CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

enterprise-submodule

Set up, update and change the enterprise submodule (`.source/`) and the enterprise packages (`enterprise/packages/*`), including the matching packages-enterprise PR. Use when touching enterprise code or when the submodule needs to be initialized or updated.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Critical

Do not install without reviewing

SKILL.md
Quality
Evals
Security

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

    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 using the same Conventional Commits name (e.g., feat/scope-description-fixes-NOV-123). 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 the submodule branch from inside .source/: git push
  6. Create the enterprise PR from the workspace root (do NOT cd into the submodule):
    gh pr create --repo novuhq/packages-enterprise --head <branch-name> --base next --title "..." --body "..."
    If this fails due to permissions, give the user this link instead:
    https://github.com/novuhq/packages-enterprise/compare/next...<branch-name>
  7. Push the main repo branch and create its PR with gh pr create.
  8. Cross-link both PRs: each PR body links the other (monorepo ↔ enterprise); gh pr edit the earlier one once the second URL exists.
  9. 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).
Repository

novuhq/novu

Path

.agents/skills/enterprise-submodule/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.