From 00fed2dbff5130fba9736d0ce073c40eb57b0e0d Mon Sep 17 00:00:00 2001 From: Chi-Hsuan Huang Date: Wed, 27 May 2026 15:23:32 +0800 Subject: [PATCH 1/6] feat(premium-analytics): add tsconfig paths and typecheck for internal packages --- pnpm-lock.yaml | 3 ++ projects/packages/premium-analytics/README.md | 29 +++++++++++++++---- .../changelog/add-internal-package-resolution | 4 +++ .../packages/premium-analytics/package.json | 2 ++ .../packages/premium-analytics/tsconfig.json | 9 ++++++ 5 files changed, 42 insertions(+), 5 deletions(-) create mode 100644 projects/packages/premium-analytics/changelog/add-internal-package-resolution diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 526dabd96ca4..85e3d1751a8d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -3849,6 +3849,9 @@ importers: '@babel/core': specifier: 7.29.0 version: 7.29.0 + '@typescript/native-preview': + specifier: 7.0.0-dev.20260225.1 + version: 7.0.0-dev.20260225.1 '@wordpress/build': specifier: 0.13.0 version: 0.13.0(@babel/core@7.29.0)(@wordpress/boot@0.13.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(@wordpress/route@0.12.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1))(browserslist@4.28.2) diff --git a/projects/packages/premium-analytics/README.md b/projects/packages/premium-analytics/README.md index e3f361a44074..5b26b1fbcaa5 100644 --- a/projects/packages/premium-analytics/README.md +++ b/projects/packages/premium-analytics/README.md @@ -42,17 +42,19 @@ jetpack build packages/premium-analytics # via Jetpack CLI ### Adding a route 1. Create `routes//package.json`: + ```json { - "name": "-route", - "route": { - "path": "/", - "page": "jetpack-premium-analytics" - } + "name": "-route", + "route": { + "path": "/", + "page": "jetpack-premium-analytics" + } } ``` 2. Create `routes//stage.tsx` exporting `stage()`: + ```tsx export const stage = () =>
My new page
; ``` @@ -74,11 +76,28 @@ fixes the template or the minimum WordPress version is 7.0+. ### Init module (`packages/init/`) Serves two purposes: + 1. Sets the dashboard menu icon via `@wordpress/boot` store 2. Forces `@wordpress/build` to track `@wordpress/boot` as a module dependency — without an init module that imports boot, the build skips it +## Internal packages (`packages/*`) + +App-internal modules discovered by `@wordpress/build`. Types/IDE resolve +`@jetpack-premium-analytics/` imports via the `tsconfig.json` `paths` alias +(`pnpm typecheck`). + +To import one from a route/another package, the build also needs it symlinked in +`node_modules` under that specifier. Name the package +`@automattic/jetpack-premium-analytics-` (a bare `@jetpack-premium-analytics/*` +name fails the repo name lint and `_@…` is invalid to pnpm), then add a `link:` +dep on the top-level `package.json` (routes aren't workspace members): + +```jsonc +"dependencies": { "@jetpack-premium-analytics/": "link:packages/" } +``` + ## File structure ``` diff --git a/projects/packages/premium-analytics/changelog/add-internal-package-resolution b/projects/packages/premium-analytics/changelog/add-internal-package-resolution new file mode 100644 index 000000000000..d35865145ec1 --- /dev/null +++ b/projects/packages/premium-analytics/changelog/add-internal-package-resolution @@ -0,0 +1,4 @@ +Significance: patch +Type: added + +Add a tsconfig paths alias and typecheck script so internal packages/* resolve for types/IDE, and document how to wire cross-package imports for the build. diff --git a/projects/packages/premium-analytics/package.json b/projects/packages/premium-analytics/package.json index ada5924f05de..e30e5e144b49 100644 --- a/projects/packages/premium-analytics/package.json +++ b/projects/packages/premium-analytics/package.json @@ -6,6 +6,7 @@ "scripts": { "build": "wp-build && mkdir -p build/modules/boot && cp shims/boot-asset.php build/modules/boot/index.min.asset.php", "build-production": "NODE_ENV=production wp-build && mkdir -p build/modules/boot && cp shims/boot-asset.php build/modules/boot/index.min.asset.php", + "typecheck": "tsgo --noEmit", "watch": "wp-build --watch" }, "wpPlugin": { @@ -38,6 +39,7 @@ }, "devDependencies": { "@babel/core": "7.29.0", + "@typescript/native-preview": "7.0.0-dev.20260225.1", "@wordpress/build": "0.13.0", "browserslist": "4.28.2" } diff --git a/projects/packages/premium-analytics/tsconfig.json b/projects/packages/premium-analytics/tsconfig.json index 1e36ba0293d3..f018f27578e3 100644 --- a/projects/packages/premium-analytics/tsconfig.json +++ b/projects/packages/premium-analytics/tsconfig.json @@ -1,4 +1,13 @@ { "extends": "jetpack-js-tools/tsconfig.base.json", + "compilerOptions": { + // Resolve cross-package imports between internal `packages/*` modules + // (`@jetpack-premium-analytics/`) to their TypeScript source for + // type-checking + IDE. The build resolves the same specifier separately (see + // README → "Internal packages"); this keeps tsc/esbuild and `tsgo` in sync. + "paths": { + "@jetpack-premium-analytics/*": [ "./packages/*/src" ] + } + }, "include": [ "routes/**/*", "packages/**/*" ] } From 20e62414b3a35c1ef8cfb65f271e5bebf95d8134 Mon Sep 17 00:00:00 2001 From: Chi-Hsuan Huang Date: Wed, 27 May 2026 16:16:30 +0800 Subject: [PATCH 2/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- projects/packages/premium-analytics/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/projects/packages/premium-analytics/README.md b/projects/packages/premium-analytics/README.md index 5b26b1fbcaa5..5abfb8f0e512 100644 --- a/projects/packages/premium-analytics/README.md +++ b/projects/packages/premium-analytics/README.md @@ -45,11 +45,11 @@ jetpack build packages/premium-analytics # via Jetpack CLI ```json { - "name": "-route", - "route": { - "path": "/", - "page": "jetpack-premium-analytics" - } + "name": "-route", + "route": { + "path": "/", + "page": "jetpack-premium-analytics" + } } ``` From 662c887ff7538d3ea7aa57a8026f301a11d2ae0e Mon Sep 17 00:00:00 2001 From: Chi-Hsuan Huang Date: Wed, 27 May 2026 16:16:40 +0800 Subject: [PATCH 3/6] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- projects/packages/premium-analytics/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/projects/packages/premium-analytics/README.md b/projects/packages/premium-analytics/README.md index 5abfb8f0e512..2785620dabee 100644 --- a/projects/packages/premium-analytics/README.md +++ b/projects/packages/premium-analytics/README.md @@ -92,7 +92,8 @@ To import one from a route/another package, the build also needs it symlinked in `node_modules` under that specifier. Name the package `@automattic/jetpack-premium-analytics-` (a bare `@jetpack-premium-analytics/*` name fails the repo name lint and `_@…` is invalid to pnpm), then add a `link:` -dep on the top-level `package.json` (routes aren't workspace members): +dep in this package's `projects/packages/premium-analytics/package.json` +(not the repo root `package.json`; routes aren't workspace members): ```jsonc "dependencies": { "@jetpack-premium-analytics/": "link:packages/" } From d4da9cad4304fe48243f8c8250e76a72f483e7de Mon Sep 17 00:00:00 2001 From: Chi-Hsuan Huang Date: Thu, 28 May 2026 14:07:06 +0800 Subject: [PATCH 4/6] docs(premium-analytics): clarify internal-package naming and rename init Address PR review feedback on the "Internal packages" section: - Lead with scope intent: internal-only, never published, in-tree symlink-only resolution (answers the npm-squatting concern) - Explicitly explain the structural dual naming between the package name field and the wp-build-derived import specifier - Rename packages/init from `_@jetpack-premium-analytics/init` to `@automattic/jetpack-premium-analytics-init` so the codebase matches the documented pattern (the old placeholder is invalid to pnpm) --- projects/packages/premium-analytics/README.md | 40 ++++++++++++------- .../packages/init/package.json | 2 +- 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/projects/packages/premium-analytics/README.md b/projects/packages/premium-analytics/README.md index 2785620dabee..bf7ad81a5191 100644 --- a/projects/packages/premium-analytics/README.md +++ b/projects/packages/premium-analytics/README.md @@ -45,11 +45,11 @@ jetpack build packages/premium-analytics # via Jetpack CLI ```json { - "name": "-route", - "route": { - "path": "/", - "page": "jetpack-premium-analytics" - } + "name": "-route", + "route": { + "path": "/", + "page": "jetpack-premium-analytics" + } } ``` @@ -84,16 +84,26 @@ Serves two purposes: ## Internal packages (`packages/*`) -App-internal modules discovered by `@wordpress/build`. Types/IDE resolve -`@jetpack-premium-analytics/` imports via the `tsconfig.json` `paths` alias -(`pnpm typecheck`). - -To import one from a route/another package, the build also needs it symlinked in -`node_modules` under that specifier. Name the package -`@automattic/jetpack-premium-analytics-` (a bare `@jetpack-premium-analytics/*` -name fails the repo name lint and `_@…` is invalid to pnpm), then add a `link:` -dep in this package's `projects/packages/premium-analytics/package.json` -(not the repo root `package.json`; routes aren't workspace members): +App-internal modules used only by this package — never published to npm, never +shared across the monorepo. Resolution is entirely in-tree (the local symlink); +the `@jetpack-premium-analytics/*` scope is never looked up against any registry. + +**The dual naming is structural.** `@wordpress/build` derives the import +specifier as `@/`, so the specifier here is +always `@jetpack-premium-analytics/`. The package's own `name` field has +to be different (`@automattic/jetpack-premium-analytics-`) because pnpm +rejects the `_@…` escape and the repo name lint (`lint-project-structure.sh`) +rejects the bare `@jetpack-premium-analytics/*` scope. They don't need to +match: pnpm symlinks under the **dep key**, so the import resolves regardless +of the linked package's `name`. + +Types/IDE: the `tsconfig.json` `paths` alias maps the specifier to +`./packages//src` (covered by `pnpm typecheck`). + +Build: to import one from a route or another package, add a `link:` dep on +**this package's `package.json`** (`projects/packages/premium-analytics/package.json` — +routes aren't workspace members, so the dep belongs here, not in the route's +`package.json`): ```jsonc "dependencies": { "@jetpack-premium-analytics/": "link:packages/" } diff --git a/projects/packages/premium-analytics/packages/init/package.json b/projects/packages/premium-analytics/packages/init/package.json index 6ee2ce1e4470..70de0aea9d5b 100644 --- a/projects/packages/premium-analytics/packages/init/package.json +++ b/projects/packages/premium-analytics/packages/init/package.json @@ -1,6 +1,6 @@ { "private": true, - "name": "_@jetpack-premium-analytics/init", + "name": "@automattic/jetpack-premium-analytics-init", "version": "0.1.0", "type": "module", "wpScript": true, From feeb212fd34ef003d5e873ad87c6b33ec013f733 Mon Sep 17 00:00:00 2001 From: Chi-Hsuan Huang Date: Wed, 3 Jun 2026 10:15:02 +0800 Subject: [PATCH 5/6] docs(premium-analytics): revert internal-packages README section Defer the internal-packages naming docs until the upstream wp-build identity change (gutenberg#78822 / #48089) lands; restore README to trunk. --- projects/packages/premium-analytics/README.md | 40 +++---------------- 1 file changed, 5 insertions(+), 35 deletions(-) diff --git a/projects/packages/premium-analytics/README.md b/projects/packages/premium-analytics/README.md index bf7ad81a5191..e3f361a44074 100644 --- a/projects/packages/premium-analytics/README.md +++ b/projects/packages/premium-analytics/README.md @@ -42,19 +42,17 @@ jetpack build packages/premium-analytics # via Jetpack CLI ### Adding a route 1. Create `routes//package.json`: - ```json { - "name": "-route", - "route": { - "path": "/", - "page": "jetpack-premium-analytics" - } + "name": "-route", + "route": { + "path": "/", + "page": "jetpack-premium-analytics" + } } ``` 2. Create `routes//stage.tsx` exporting `stage()`: - ```tsx export const stage = () =>
My new page
; ``` @@ -76,39 +74,11 @@ fixes the template or the minimum WordPress version is 7.0+. ### Init module (`packages/init/`) Serves two purposes: - 1. Sets the dashboard menu icon via `@wordpress/boot` store 2. Forces `@wordpress/build` to track `@wordpress/boot` as a module dependency — without an init module that imports boot, the build skips it -## Internal packages (`packages/*`) - -App-internal modules used only by this package — never published to npm, never -shared across the monorepo. Resolution is entirely in-tree (the local symlink); -the `@jetpack-premium-analytics/*` scope is never looked up against any registry. - -**The dual naming is structural.** `@wordpress/build` derives the import -specifier as `@/`, so the specifier here is -always `@jetpack-premium-analytics/`. The package's own `name` field has -to be different (`@automattic/jetpack-premium-analytics-`) because pnpm -rejects the `_@…` escape and the repo name lint (`lint-project-structure.sh`) -rejects the bare `@jetpack-premium-analytics/*` scope. They don't need to -match: pnpm symlinks under the **dep key**, so the import resolves regardless -of the linked package's `name`. - -Types/IDE: the `tsconfig.json` `paths` alias maps the specifier to -`./packages//src` (covered by `pnpm typecheck`). - -Build: to import one from a route or another package, add a `link:` dep on -**this package's `package.json`** (`projects/packages/premium-analytics/package.json` — -routes aren't workspace members, so the dep belongs here, not in the route's -`package.json`): - -```jsonc -"dependencies": { "@jetpack-premium-analytics/": "link:packages/" } -``` - ## File structure ``` From 2beeaa9a2c6ac17b2d050597d09229f1254bd49e Mon Sep 17 00:00:00 2001 From: Chi-Hsuan Huang Date: Wed, 3 Jun 2026 10:35:23 +0800 Subject: [PATCH 6/6] fix(premium-analytics): align route name with internal-package convention Rename routes/dashboard to @automattic/jetpack-premium-analytics-dashboard-route to match the packages/* naming (per review), and drop the stale changelog line about README build docs that were reverted. Build output is unchanged (routes key off the directory name). --- .../premium-analytics/changelog/add-internal-package-resolution | 2 +- .../packages/premium-analytics/routes/dashboard/package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/projects/packages/premium-analytics/changelog/add-internal-package-resolution b/projects/packages/premium-analytics/changelog/add-internal-package-resolution index d35865145ec1..f4343aa091ea 100644 --- a/projects/packages/premium-analytics/changelog/add-internal-package-resolution +++ b/projects/packages/premium-analytics/changelog/add-internal-package-resolution @@ -1,4 +1,4 @@ Significance: patch Type: added -Add a tsconfig paths alias and typecheck script so internal packages/* resolve for types/IDE, and document how to wire cross-package imports for the build. +Add a tsconfig paths alias and typecheck script so internal packages/* resolve for types/IDE. diff --git a/projects/packages/premium-analytics/routes/dashboard/package.json b/projects/packages/premium-analytics/routes/dashboard/package.json index e71390452278..b0139ff6987b 100644 --- a/projects/packages/premium-analytics/routes/dashboard/package.json +++ b/projects/packages/premium-analytics/routes/dashboard/package.json @@ -1,6 +1,6 @@ { "private": true, - "name": "_@jetpack-premium-analytics/dashboard-route", + "name": "@automattic/jetpack-premium-analytics-dashboard-route", "route": { "path": "/", "page": "jetpack-premium-analytics"