From 3fd4a6e7449cb2673d77f0230cbd03b7029a6598 Mon Sep 17 00:00:00 2001 From: Caio Pizzol Date: Fri, 15 May 2026 21:37:13 -0300 Subject: [PATCH] feat: install superdoc from wrapper packages --- .github/package-impact-map.md | 8 ++++---- packages/esign/.releaserc.cjs | 8 ++++---- packages/esign/package.json | 6 ++++-- packages/esign/src/types.ts | 4 ++-- packages/template-builder/.releaserc.cjs | 9 +++++---- packages/template-builder/package.json | 6 ++++-- pnpm-lock.yaml | 14 ++++++++------ 7 files changed, 31 insertions(+), 24 deletions(-) diff --git a/.github/package-impact-map.md b/.github/package-impact-map.md index 303c8f330b..1a55f0427a 100644 --- a/.github/package-impact-map.md +++ b/.github/package-impact-map.md @@ -9,7 +9,7 @@ Source of truth for which repo paths should trigger CI and release workflows for - **CI gates compatibility.** A change to SuperDoc core should run the CI of every dependent package — that's how breakage in `@superdoc-dev/react` or `@superdoc-dev/sdk` gets caught before it ships. CI paths follow *compatibility* impact. - **Release gates artifact changes.** A package should only publish a new version when its own published artifact actually changes. Release paths follow *artifact* impact. -These two are not the same. `template-builder` and `esign` externalize `superdoc` in their builds and declare it as a `peerDependency`, so a core change doesn't change their tarballs → CI broad, release narrow. CLI bundles core into platform binaries, so a core change does change the CLI tarball → both broad. +These two are not the same. `template-builder` and `esign` externalize `superdoc` in their builds and declare it as both a dependency and peer dependency, so a core change inside the declared range doesn't change their tarballs → CI broad, release narrow. CLI bundles core into platform binaries, so a core change does change the CLI tarball → both broad. ## Surfaces @@ -49,7 +49,7 @@ These two are not the same. `template-builder` and `esign` externalize `superdoc ## Why each classification -- **`template-builder` and `esign`** externalize `superdoc` in their Vite build (`rollupOptions.external`) and declare it as a `peerDependency`. A SuperDoc core change does not change the wrapper's published bundle — consumers receive the new core through their own `npm install`. Release-on-core is pure version noise; CI-on-core remains necessary to catch breaking API changes. +- **`template-builder` and `esign`** externalize `superdoc` in their Vite build (`rollupOptions.external`) and declare it in **both** `dependencies` and `peerDependencies`. The `dependencies` entry preserves auto-install for customers who use the wrapper as their SuperDoc entrypoint; the `peerDependencies` entry signals the singleton contract for apps that also install SuperDoc directly. A SuperDoc core change inside the declared range does not change the wrapper's published bundle or manifest, so release-on-core is pure version noise; CI-on-core remains necessary to catch breaking API changes. - **`react`** externalizes `superdoc` in its Vite build the same way, and declares `superdoc` in **both** `dependencies` and `peerDependencies`. The `dependencies` entry preserves auto-install for every consumer (zero-break regardless of package manager); the `peerDependencies` entry signals the singleton contract and aligns the manifest with template-builder/esign. Because the `dependencies` entry still pins via lockfiles, existing consumers only pick up a new core version when react republishes, so release-on-core stays correct *today*. The unlock for release-narrow is to remove `superdoc` from `dependencies` entirely — that is a breaking change and tracked as a separate decision. - **CLI / SDK** bundle engine behavior into platform-specific native binaries (see `apps/cli/.releaserc.cjs` and `packages/sdk/.releaserc.cjs` — both use `patch-commit-filter.cjs` to expand release analysis into core paths). The published artifact genuinely changes when core changes. - **MCP** depends on SDK via `workspace:*` and imports engine/session code directly. Its current release trigger (`apps/mcp/**` only) causes it to lag SDK releases. Expand to match SDK's release paths. @@ -61,6 +61,6 @@ These two are not the same. `template-builder` and `esign` externalize `superdoc ## Notes - `packages/ai/**` has been removed from all release and CI triggers. `@superdoc-dev/ai` is being deprecated; npm-side deprecation is a separate operational step. -- When SuperDoc core ships a breaking API change, `template-builder` and `esign` must be manually updated and released. Their `peerDependencies` version bump is the signal; semantic-release won't auto-trigger on upstream changes for them. -- `@superdoc-dev/react` declares `superdoc` in both `dependencies` and `peerDependencies` to preserve zero-break install semantics while still signaling the singleton contract. Removing `superdoc` from `dependencies` is the unlock for release-narrow and is tracked as a separate decision. +- When SuperDoc core ships a breaking API change, `template-builder` and `esign` must be manually updated and released. Their dependency and peer-dependency floor bump is the signal; semantic-release won't auto-trigger on upstream changes for them. +- `@superdoc-dev/react`, `@superdoc-dev/template-builder`, and `@superdoc-dev/esign` declare `superdoc` in both `dependencies` and `peerDependencies` to preserve automatic install semantics while still signaling the singleton contract. Removing `superdoc` from `dependencies` is the unlock for release-narrow and is tracked as a separate decision. - When editing a release or CI workflow, its `paths:` filter must match the corresponding row in this map. Workflow-lint rules should enforce this. diff --git a/packages/esign/.releaserc.cjs b/packages/esign/.releaserc.cjs index 0a2637b43b..49a4aa1aa3 100644 --- a/packages/esign/.releaserc.cjs +++ b/packages/esign/.releaserc.cjs @@ -6,10 +6,10 @@ const { /* * Release narrow: esign externalizes `superdoc` in its build, so a core - * change does not alter the published esign tarball (consumers get the new - * core via their own peerDependencies install). Only commits touching - * packages/esign/** should trigger a release. See - * .github/package-impact-map.md. + * change inside the declared dependency/peer range does not alter the + * published esign tarball. Consumers pick up eligible core versions through + * package manager resolution. Only commits touching packages/esign/** should + * trigger a release. See .github/package-impact-map.md. */ const branch = process.env.GITHUB_REF_NAME || process.env.CI_COMMIT_BRANCH; diff --git a/packages/esign/package.json b/packages/esign/package.json index 98fd1b79f1..91d23478af 100644 --- a/packages/esign/package.json +++ b/packages/esign/package.json @@ -46,6 +46,9 @@ ], "author": "SuperDoc Team", "license": "AGPL-3.0", + "dependencies": { + "superdoc": "^1.33.1" + }, "bugs": { "url": "https://github.com/superdoc-dev/superdoc/issues" }, @@ -53,7 +56,7 @@ "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", - "superdoc": "^1.28.0" + "superdoc": "^1.33.1" }, "devDependencies": { "@testing-library/jest-dom": "catalog:", @@ -66,7 +69,6 @@ "eslint-plugin-react-hooks": "catalog:", "react": "catalog:", "react-dom": "catalog:", - "superdoc": "workspace:*", "typescript": "catalog:", "vite": "catalog:", "vite-plugin-dts": "catalog:", diff --git a/packages/esign/src/types.ts b/packages/esign/src/types.ts index 565c96d1b0..a7da617caa 100644 --- a/packages/esign/src/types.ts +++ b/packages/esign/src/types.ts @@ -56,8 +56,8 @@ export interface SubmitConfig { component?: React.ComponentType; } -export interface PdfModuleConfig { - pdfLib: any; +export interface PdfModuleConfig extends Record { + pdfLib: object; workerSrc?: string; setWorker?: boolean; textLayer?: boolean; diff --git a/packages/template-builder/.releaserc.cjs b/packages/template-builder/.releaserc.cjs index c48172cb4a..9483401fa1 100644 --- a/packages/template-builder/.releaserc.cjs +++ b/packages/template-builder/.releaserc.cjs @@ -6,10 +6,11 @@ const { /* * Release narrow: template-builder externalizes `superdoc` in its build, so a - * core change does not alter the published template-builder tarball - * (consumers get the new core via their own peerDependencies install). Only - * commits touching packages/template-builder/** should trigger a release. - * See .github/package-impact-map.md. + * core change inside the declared dependency/peer range does not alter the + * published template-builder tarball. Consumers pick up eligible core versions + * through package manager resolution. Only commits touching + * packages/template-builder/** should trigger a release. See + * .github/package-impact-map.md. */ const branch = process.env.GITHUB_REF_NAME || process.env.CI_COMMIT_BRANCH; diff --git a/packages/template-builder/package.json b/packages/template-builder/package.json index 8686683bd9..8693f6e966 100644 --- a/packages/template-builder/package.json +++ b/packages/template-builder/package.json @@ -46,6 +46,9 @@ ], "author": "SuperDoc Team", "license": "AGPL-3.0", + "dependencies": { + "superdoc": "^1.33.1" + }, "bugs": { "url": "https://github.com/superdoc-dev/superdoc/issues" }, @@ -53,7 +56,7 @@ "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", - "superdoc": "^1.31.1" + "superdoc": "^1.33.1" }, "devDependencies": { "@testing-library/jest-dom": "catalog:", @@ -66,7 +69,6 @@ "eslint-plugin-react-hooks": "catalog:", "react": "catalog:", "react-dom": "catalog:", - "superdoc": "workspace:*", "typescript": "catalog:", "vite": "catalog:", "vite-plugin-dts": "catalog:", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 46da9e526a..39dcca66b6 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -2398,6 +2398,10 @@ importers: version: 3.2.4(@emnapi/core@1.9.1)(@emnapi/runtime@1.9.1)(@types/debug@4.1.13)(@types/node@25.6.0)(esbuild@0.27.7)(happy-dom@20.4.0)(jiti@2.6.1)(jsdom@27.3.0(canvas@3.2.3))(less@4.4.2)(sass@1.97.3)(terser@5.46.1)(tsx@4.21.0)(yaml@2.8.3) packages/esign: + dependencies: + superdoc: + specifier: workspace:* + version: link:../superdoc devDependencies: '@testing-library/jest-dom': specifier: 'catalog:' @@ -2432,9 +2436,6 @@ importers: react-dom: specifier: 'catalog:' version: 19.2.4(react@19.2.4) - superdoc: - specifier: workspace:* - version: link:../superdoc typescript: specifier: 'catalog:' version: 5.9.3 @@ -3161,6 +3162,10 @@ importers: version: 14.2.6 packages/template-builder: + dependencies: + superdoc: + specifier: workspace:* + version: link:../superdoc devDependencies: '@testing-library/jest-dom': specifier: 'catalog:' @@ -3195,9 +3200,6 @@ importers: react-dom: specifier: 'catalog:' version: 19.2.4(react@19.2.4) - superdoc: - specifier: workspace:* - version: link:../superdoc typescript: specifier: 'catalog:' version: 5.9.3