Publishable Package Dependency Rules

Use this guidance before changing dependencies in any publishable MoltNet package, especially packages managed by release-please or published under @themoltnet/*.

Rules

1. Public in-repo @themoltnet/* packages should use pnpm workspace protocol in repository manifests, for example workspace:*.

   Why: pnpm links the local workspace package during development and rewrites the dependency to the published package version during pnpm publish. A plain npm semver range lets release-please edit the package manifest without regenerating pnpm-lock.yaml, which can break pnpm install --frozen-lockfile.

2. Private @moltnet/* packages must not ship in dependencies.

   If a publishable package imports private @moltnet/* code and Vite SSR bundles it into dist, keep that private package in devDependencies. The published tarball must not reference private workspace packages that npm cannot install.

3. Bundle only private implementation packages by default.

   In a publishable Node package, bundle private @moltnet/* implementation packages. Externalize every installable dependency: public in-repo @themoltnet/* packages and third-party npm packages. Keep those external packages in dependencies or peerDependencies as appropriate.

   A public or third-party package may be bundled only for a documented loader or artifact constraint and needs a focused regression check.

4. Runtime external public packages belong in dependencies.

   If consumers need a public package at runtime, keep it in dependencies, but still use workspace:* inside the monorepo when that package is part of this workspace.

5. Enforce externalization in the active build configuration.

   Vite SSR normally externalizes registry packages, but source-direct workspace exports may still be inlined. With Vite 8/Rolldown, use the repository externalizeInstallableDependencies predicate in build.rolldownOptions.external (or the active build.rollupOptions.external). It derives externals from the package's installable dependency and peer fields, excluding private @moltnet/*, without duplicating manifest names. If bundled private code reaches an undeclared third-party import, the predicate fails the build: promote that dependency to the published manifest. ssr.external alone is not sufficient. Inspect emitted JS for retained imports and for asset paths detached from their owning package.

6. Check package manifests, emitted output, and a clean packed install.

   Before publishing or merging release-please changes, run the package's check:pack, verify pnpm install --frozen-lockfile, and inspect whether release-please changed dependency specifiers without a lockfile update. For asset-owning or chained workspace packages, pack and install the local dependency set in a clean temporary consumer so tests resolve published dist exports rather than workspace source exports.

Failure Patterns

• Node-RED release drift: libs/node-red-contrib-core used @themoltnet/sdk as a plain semver dependency. Release-please changed the range from ^0.112.0 to ^0.113.0, but the lockfile still recorded ^0.112.0, so release CI failed before build or publish. The fix was to use workspace:* and regenerate the lockfile with pnpm.

• Private workspace dependency leak: @themoltnet/pi-extension and @themoltnet/legreffier previously shipped private @moltnet/* workspace packages in dependencies. npm installs then failed with E404 or check:pack blocked the release. The fix pattern is to bundle private code with Vite SSR and keep those private imports in devDependencies.

• Check-pack false positives: tools/src/check-pack.ts once flagged workspace imports that only appeared in comments/JSDoc. Detection must match actual module specifiers, not prose.

• Vite SSR externalization drift: Vite 8/Rolldown rejected regex entries in ssr.external; externalization rules should be retested when Vite changes.

Provenance

• Node-RED SDK lockfile drift incident: 8fe07443-036c-4e5c-9e13-0fa8e069ea7c
• Pi-extension private dependency leak: b7751f1d-8aff-4ddf-96e1-785a13a4576a
• Legreffier unpublished workspace dependency incident: 2e99af04-6793-4fe3-89b5-1378c899bd67
• Pi-extension Vite publishing pattern: c8d117f6-c05a-41be-9851-1bfac9c450eb
• Agent-runtime standalone publish decision: a4eefe9a-f565-416b-ac1a-e06e6c17c876
• check:pack false-positive fix: 034af63b-d3a8-4d83-982d-e0edad380b59
• Vite 8 SSR externalization incident: f04f21ba-2760-4310-811e-4590f30ce81f
• Pi-runtime analyzer WASM boundary and clean packed smoke: b2a136dd-002c-4a32-8287-ba8ab90fda0a