Enterprise Submodule Setup

Use this skill when making changes to the enterprise submodule (.source/) or enterprise packages (enterprise/packages/*), or when the enterprise submodule needs to be initialized/updated.

Overview

Novu uses a git submodule at .source pointing to git@github.com:novuhq/packages-enterprise.git. The enterprise packages in enterprise/packages/ have their src directories symlinked to .source/<package>/src.

Initial Setup

1. Configure git for submodule recursion:

   git config --global submodule.recurse true

2. Initialize the submodule:

   git submodule update --init --recursive

   If SSH is unavailable (e.g., in cloud environments), configure HTTPS fallback:

   git config --global url."https://github.com/".insteadOf "git@github.com:"
   gh auth setup-git

3. Add enterprise env vars to apps/api/src/.env and apps/worker/src/.env:

   NOVU_ENTERPRISE=true

4. Install and build with enterprise:

   pnpm install:with-ee
   pnpm build:with-ee

   install:with-ee runs pnpm install then pnpm symlink:submodules which symlinks src dirs from .source/ into enterprise/packages/.

Pulling Changes

1. git pull in the main repository (with submodule.recurse=true, submodule changes are fetched but NOT merged).
2. For development in the submodule: cd .source && git checkout <branch> && git pull

Making Changes in the Submodule

1. Pull latest from both repos.
2. Create branches in both the main repo and submodule. Start from a branch in the submodule, not a detached HEAD.
3. Implement changes.
4. Commit in the submodule first, then the main repo.
5. Push both repos: git push --recurse-submodules=on-demand or push each manually.
6. Create PRs in both repos with links to each other.
7. Merge the submodule PR first, then the main repo PR (to avoid broken builds for teammates).

Troubleshooting

• fatal: could not get a repository handle for submodule '.source':

  • Delete .git/modules/ contents
  • Run git submodule update --init --recursive

• Untracked working tree files error on checkout:

  • git submodule deinit -f enterprise
  • Checkout to branch and pull
  • git submodule update --init --recursive

• Nuclear option:

  pnpm run clean
  rm -rf node_modules
  pnpm i
  pnpm run symlink:submodules
  pnpm nx run-many --target=build --all --skip-nx-cache

Key Points

• The .source directory contains the actual enterprise source code (private repo).
• enterprise/packages/*/src are symlinks to .source/*/src.
• Enterprise packages: @novu/ee-auth, @novu/ee-api, @novu/ee-dal, @novu/ee-billing, @novu/ee-translation, @novu/ee-shared-services.
• The check-ee.mjs script in each enterprise package only builds if the src folder exists (graceful degradation for OSS contributors).