|
| 1 | +# Backend dynamic plugin export |
| 2 | + |
| 3 | +Walkthrough of [`backend.ts`](../../src/commands/export-dynamic-plugin/backend.ts): **`backend-plugin`** and **`backend-plugin-module`** packages. The result is a self-contained tree under **`dist-dynamic/`** suitable for loading as a Node dynamic plugin. |
| 4 | + |
| 5 | +← [Back to index](./README.md) · Shared packaging: [shared-packaging.md](./shared-packaging.md) |
| 6 | + |
| 7 | +## 1. Inputs and guards |
| 8 | + |
| 9 | +- Parse the plugin **`package.json`**; reject if **`bundled: true`** (dynamic backend plugins must not be bundled in this sense). |
| 10 | +- Resolve CLI lists: **`--embed-package`**, **`--shared-package`**, **`--allow-native-package`**, **`--suppress-native-package`**, **`--ignore-version-check`**. |
| 11 | +- Load monorepo layout with **`@manypkg/get-packages`** from **`paths.targetDir`**. |
| 12 | +- **`searchEmbedded`** ([`backend.ts`](../../src/commands/export-dynamic-plugin/backend.ts) + [`backend-utils`](../../src/commands/export-dynamic-plugin/backend-utils.ts)) resolves which packages to embed from the dependency graph and optional **`--embed-package`** names; may auto-include related **`-common`** / **`-node`** packages depending on role. |
| 13 | + |
| 14 | +## 2. Shared dependency rules |
| 15 | + |
| 16 | +- **`sharedPackagesRules`**: by default, **`@backstage/*`** dependencies are treated as **shared** (moved to **`peerDependencies`** during [`customizeForDynamicUse`](./shared-packaging.md)). |
| 17 | +- **`--shared-package`** adds patterns (string or `/regex/`); entries prefixed with **`!`** go to **`exclude`** (do not force to peer). |
| 18 | +- **Embedded package names** are always excluded from the “move to peer” rule so they stay private/embedded as intended. |
| 19 | + |
| 20 | +## 3. Prepare `dist-dynamic` |
| 21 | + |
| 22 | +- Optional **`--clean`**: remove **`dist-dynamic`** entirely. |
| 23 | +- Recreate directory and write **`.gitignore`** (ignore all by default). |
| 24 | +- With **`--track-dynamic-manifest-and-lock-file`**, whitelist **`package.json`**, **`yarn.lock`**, **`.yarnrc.yml`** so they can be committed (productization). |
| 25 | + |
| 26 | +## 4. Suppress native (`--suppress-native-package`) |
| 27 | + |
| 28 | +For each suppressed name, materialize a stub under **`embedded/<name>/`** (minimal **`package.json`** + **`index.js`** that throws) so resolutions can point at a non-native placeholder. |
| 29 | + |
| 30 | +## 5. Embedded packages loop |
| 31 | + |
| 32 | +For each resolved embedded package: |
| 33 | + |
| 34 | +- Optional **`yarn build`** in the embedded package dir when **`--build`** (default install path uses `opts.build`). |
| 35 | +- **`productionPack`** into **`dist-dynamic/embedded/<normalized-name>/`**, or **recursive copy** if already packed. |
| 36 | +- Remove **`node_modules`** under the embedded copy if present. |
| 37 | +- **`customizeForDynamicUse`** on the embedded **`package.json`** (private, version suffix `+embedded`, shared/peer rules, workspace resolution, Yarn v1 **`file:`** for embedded deps when applicable), including [lockfile-adjacent workspace **`resolutions`**](./shared-packaging.md#workspace-resolutions-inheritance) merged before backend-only **`additionalResolutions`**. |
| 38 | +- Collect **peer dependencies** from embedded packages for later hoisting onto the main package. |
| 39 | + |
| 40 | +## 6. Main package |
| 41 | + |
| 42 | +- Optional **`yarn build`** at **`paths.targetDir`** when **`--build`**. |
| 43 | +- **`productionPack`** with **`packageDir: ''`** so file resolution uses the **Backstage CLI target directory** (plugin root) as the pack root, output into **`dist-dynamic`**. |
| 44 | +- Remove nested **`dist-dynamic/dist-dynamic`** if **`files`** accidentally included it. |
| 45 | +- **`customizeForDynamicUse`** on the main **`package.json`** (same [workspace \*\*`resolutions` inheritance](./shared-packaging.md#workspace-resolutions-inheritance); embedded **`file:`** resolutions still win on conflicts): |
| 46 | + - Rename to **`<original-name>-dynamic`** |
| 47 | + - **`bundleDependencies: true`** |
| 48 | + - Clear **`scripts`** |
| 49 | + - **`resolutions`** / **`yarn`** resolutions wiring **`file:./embedded/...`** for embedded packages (and suppressed native stubs) |
| 50 | + - Hoist collected embedded **peer** requirements onto the main **`peerDependencies`** when non-empty |
| 51 | + |
| 52 | +Details of manifest rewriting: [shared-packaging.md](./shared-packaging.md). |
| 53 | + |
| 54 | +## 7. Yarn project metadata (`initializeYarnProject`) |
| 55 | + |
| 56 | +See [shared-packaging.md](./shared-packaging.md). Summaries: copy **`yarn.lock`** if missing, **generate** a minimal Berry **`.yarnrc.yml`** in **`dist-dynamic`** (**`httpTimeout`** + **`nodeLinker: node-modules`**; see shared doc), set **`packageManager`**. |
| 57 | + |
| 58 | +## 8. `yarn install` |
| 59 | + |
| 60 | +- Skipped when **`--no-install`**; user is warned the lockfile may be stale until they install manually. |
| 61 | +- Otherwise run **`yarn install`** in **`dist-dynamic`** with Yarn **1.x** vs **Berry**-appropriate flags; log to a temp file on backend, then remove **`.yarn`** under **`dist-dynamic`** after success. |
| 62 | + |
| 63 | +## 9. Post-install validation (install path only) |
| 64 | + |
| 65 | +1. **Shared vs private**: scan **`yarn.lock`** so no **shared** package (per rules) appears as a private dependency; on failure, suggest **`--shared-package !...`** or **`--embed-package`** with a derived hint list. |
| 66 | +2. **Native modules**: **`gatherNativeModules`**; fail unless listed in **`--allow-native-package`**. |
| 67 | +3. **Entry points**: **`validatePluginEntryPoints`** ([`backend-utils.ts`](../../src/commands/export-dynamic-plugin/backend-utils.ts)) — ensures expected backend plugin entry surface. |
| 68 | + |
| 69 | +On success, the yarn install log is removed (see **`logFile`** / **`fs.remove`** usage at the end of the install block in **`backend.ts`**). |
| 70 | + |
| 71 | +## 10. Return value |
| 72 | + |
| 73 | +Returns the absolute **`dist-dynamic`** path for **`command.ts`** to append config schema and dev steps. |
| 74 | + |
| 75 | +← [Back to index](./README.md) |
0 commit comments