refactor: add sync generator for zod2md tooling setup

[BioPhoton]

preconditions:

• chore: add zod2md-nx-plugin #1162
• chore: use tsx when execution nx to have local plugins working #1242

This PR implements:

• handle zod2md dependencies if zod2md.config.js is present

---

Usage

nx sync --check # log status
nx sync # sync projets

Example project structure

Root/
├── libs/
│   └── project-name/
│       ├── zod2md.config.ts        🔎 triggers the sync generator
│       ├── project.json            👈 checks targets + build.dependsOn
│       ├── tsconfig.lib.json       👈 configures zod2md-jsdocs TS plugin
│       └── src/
│           └── index.ts
└── ...

---

Targeted behavior summary

• ✔ No zod2md.config.ts → project is ignored
• ✔ Missing TS plugin config → patched automatically
• ✔ Missing Zod2Md target → added automatically
• ✔ Missing build.dependsOn entries → updated automatically
• ✔ Fully configured project → no changes, no errors

---

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a9e4878

Command	Status	Duration	Result
nx run ci:code-pushup -- merge-diffs --files=/h...	✅ Succeeded	5s	View ↗
nx run-many --targets=code-pushup --parallel=fa...	✅ Succeeded	1m 30s	View ↗
nx run-many --targets=code-pushup --parallel=fa...	✅ Succeeded	13m 47s	View ↗
nx run-many -t unit-test,int-test	✅ Succeeded	4s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-02-08 22:27:40 UTC

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 58b3eea

---

☁️ Nx Cloud last updated this comment at 2025-12-15 14:28:22 UTC

[pkg-pr-new]

Open in StackBlitz

@code-pushup/ci

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/ci@1188

@code-pushup/cli

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/cli@1188

@code-pushup/core

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/core@1188

@code-pushup/create-cli

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/create-cli@1188

@code-pushup/models

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/models@1188

@code-pushup/nx-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/nx-plugin@1188

@code-pushup/axe-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/axe-plugin@1188

@code-pushup/coverage-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/coverage-plugin@1188

@code-pushup/eslint-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/eslint-plugin@1188

@code-pushup/js-packages-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/js-packages-plugin@1188

@code-pushup/jsdocs-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/jsdocs-plugin@1188

@code-pushup/lighthouse-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/lighthouse-plugin@1188

@code-pushup/typescript-plugin

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/typescript-plugin@1188

@code-pushup/utils

npm i https://pkg.pr.new/code-pushup/cli/@code-pushup/utils@1188

commit: a9e4878

[github-actions]

Code PushUp

🤨 Code PushUp report has both improvements and regressions – compared current commit d2b985c with previous commit 3137af7.

💼 Project plugin-typescript

😟 Code PushUp report has regressed.

🕵️ See full comparison in Code PushUp portal 🔍

🏷️ Category	⭐ Previous score	⭐ Current score	🔄 Score change
Code coverage	🟡 89	🟡 89

5 other categories are unchanged.

👎 1 group regressed, 👎 2 audits regressed

🗃️ Groups

🔌 Plugin	🗃️ Group	⭐ Previous score	⭐ Current score	🔄 Score change
Code coverage	Code coverage metrics	🟡 89	🟡 89

14 other groups are unchanged.

🛡️ Audits

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value	🔄 Value change
Code coverage	Line coverage	🟩 95.5 %	🟩 94.7 %
Code coverage	Branch coverage	🟨 81.4 %	🟨 80.8 %

442 other audits are unchanged.

💼 Project utils

🥳 Code PushUp report has improved.

🕵️ See full comparison in Code PushUp portal 🔍

🏷️ Category	⭐ Previous score	⭐ Current score	🔄 Score change
Code coverage	🟢 95	🟢 95
Documentation	🟡 61	🟡 61

4 other categories are unchanged.

👍 2 groups improved, 👍 1 audit improved

🗃️ Groups

🔌 Plugin	🗃️ Group	⭐ Previous score	⭐ Current score	🔄 Score change
Code coverage	Code coverage metrics	🟢 95	🟢 95
JSDocs coverage	Documentation coverage	🟡 61	🟡 61

13 other groups are unchanged.

🛡️ Audits

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value	🔄 Value change
Code coverage	Branch coverage	🟩 91.9 %	🟩 91.9 %

443 other audits are unchanged.

💼 Project plugin-lighthouse

🤨 Code PushUp report has both improvements and regressions.

🕵️ See full comparison in Code PushUp portal 🔍

All of 6 categories are unchanged.

1 audit changed without impacting score

🗃️ Groups

All of 15 groups are unchanged.

🛡️ Audits

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value	🔄 Value change
Code coverage	Branch coverage	🟩 98.8 %	🟩 98.8 %

443 other audits are unchanged.

---

11 other projects are unchanged.

[github-actions]

Code PushUp

🤨 Code PushUp report has both improvements and regressions – compared current commit d2b985c with previous commit 3137af7.

🕵️ See full comparison in Code PushUp portal 🔍

🏷️ Categories

🏷️ Category	⭐ Previous score	⭐ Current score	🔄 Score change
Performance	🔴 40	🔴 41
Code coverage	🟢 93	🟢 92
Bug prevention	🟡 75	🟡 75
Axe Accessibility	🟡 88	🟡 88
Code style	🟢 100	🟢 100	–
Security	🔴 47	🔴 47	–
Updates	🟡 75	🟡 75	–
Type Safety	🟡 67	🟡 67	–
Miscellaneous	🟡 67	🟡 67	–
Documentation	🟡 53	🟡 53	–
Accessibility	🟢 92	🟢 92	–
Best Practices	🟢 100	🟢 100	–
SEO	🟢 92	🟢 92	–

👍 1 group improved, 👎 1 group regressed, 👍 4 audits improved, 👎 4 audits regressed, 13 audits changed without impacting score

🗃️ Groups

🔌 Plugin	🗃️ Group	⭐ Previous score	⭐ Current score	🔄 Score change
Lighthouse	Performance	🔴 40	🔴 41
Code coverage	Code coverage metrics	🟢 93	🟢 92

32 other groups are unchanged.

🛡️ Audits

🔌 Plugin	🛡️ Audit	📏 Previous value	📏 Current value	🔄 Value change
Lighthouse	Initial server response time was short	🟥 Root document took 660 ms	🟩 Root document took 470 ms
Lighthouse	Speed Index	🟥 6.8 s	🟥 6.0 s
Lighthouse	First Contentful Paint	🟥 3.3 s	🟥 3.3 s
Lighthouse	Time to Interactive	🟥 13.1 s	🟥 12.9 s
Lighthouse	Total Blocking Time	🟥 1,040 ms	🟥 1,100 ms
Code coverage	Line coverage	🟩 92.8 %	🟩 92.5 %
Code coverage	Branch coverage	🟨 89.2 %	🟨 89 %
Code coverage	Function coverage	🟩 94.4 %	🟩 94.2 %
Lighthouse	Avoids enormous network payloads	🟩 Total size was 2,089 KiB	🟩 Total size was 2,098 KiB
Lighthouse	Minimizes main-thread work	🟥 8.1 s	🟥 7.2 s
Lighthouse	Uses efficient cache policy on static assets	🟨 31 resources found	🟨 31 resources found
Lighthouse	Server Backend Latencies	🟩 300 ms	🟩 970 ms
Lighthouse	Largest Contentful Paint	🟥 11.7 s	🟥 11.9 s
Lighthouse	Metrics	🟩 100%	🟩 100%
Lighthouse	Reduce unused JavaScript	🟥 Potential savings of 225 KiB	🟥 Potential savings of 202 KiB
Lighthouse	Remove duplicate modules in JavaScript bundles	🟥 Potential savings of 65 KiB	🟥 Potential savings of 72 KiB
Lighthouse	JavaScript execution time	🟥 2.1 s	🟥 2.0 s
Lighthouse	Max Potential First Input Delay	🟥 620 ms	🟥 610 ms
TypeScript	Semantic errors	🟥 44 errors	🟥 48 errors
Lighthouse	Network Round Trip Times	🟩 70 ms	🟩 70 ms
Lighthouse	Cumulative Layout Shift	🟩 0.003	🟩 0

658 other audits are unchanged.

[BioPhoton]

@matejchalk to be able to use uncompiled Nx tooling code we can't have .js extensions present. The reason is, Nx uses SWC under the hood and can't be configured.

Here we see the existing plugin does not have any import to local files: https://github.com/code-pushup/cli/blob/main/tools/zod2md-jsdocs/src/nx-plugin.ts otherwise it fails.

Any other ideas? 💡 how should we progress here other than avoiding extensions?

[matejchalk]

how should we progress here other than avoiding extensions?

Removing import extensions would break our package builds. That's not worth it for a nice-to-have local tool.

If there's no way to tell Nx to look up a matching .ts file for .js imports, then I guess the next best option is build the plugin and run it from dist.

[matejchalk]

... no way to tell Nx to look up a matching .ts file for .js imports ...

💡 Actually, I think I've found a way. We can set a custom Node loader using environment variables. I've tested it locally by adding a constants.ts that's imported as ./constants.js, then running nx graph. This gave me a Cannot find module './constants.js' error, until the .env.local, which fixed it. (See #1238) 🙂

[BioPhoton]

... no way to tell Nx to look up a matching .ts file for .js imports ...

💡 Actually, I think I've found a way. We can set a custom Node loader using environment variables. I've tested it locally by adding a constants.ts that's imported as ./constants.js, then running nx graph. This gave me a Cannot find module './constants.js' error, until the .env.local, which fixed it. (See #1238) 🙂

I digged into this also. I did not use this in the current PR as suggested solution (sry to not mention it here!).

Nx has tsx detection and disables its local bundling with SWC if --import tsx is used...

---

Why SWC is skipped when running Nx with NODE_OPTIONS="--import tsx"

Nx has hardcoded transpiler-selection logic for local TS/TSX execution (plugins, executors, generators).
When running with a Node loader like tsx, Nx does not register SWC, even if SWC is available.

Relevant source:
https://github.com/nrwl/nx/blob/81c157d0631927b3d1891453aa45652f3b5a7988/packages/nx/src/plugins/js/utils/register.ts

Key logic:

export function registerTranspiler(
  compilerOptions: CompilerOptions,
  tsConfigRaw?: unknown
): () => void {
  const transpiler = getTranspiler(compilerOptions, tsConfigRaw);

  if (!transpiler) {
    warnNoTranspiler();
    return () => {};
  }

  return transpiler();
}

If getTranspiler(...) returns undefined, Nx intentionally does not register SWC or ts-node.

getTranspiler(...) only detects:

• @swc-node/register
• ts-node

Node loaders like tsx are not detected, so:

• getTranspiler(...) === undefined
• registerTranspiler becomes a no-op
• SWC is effectively disabled by design for this execution path

This is not in @nx/js:swc, but in Nx’s runtime TS/TSX plugin execution pipeline.
Running with NODE_OPTIONS="--import tsx" therefore bypasses SWC via hardcoded logic.

[BioPhoton]

I opened #1242 to address the local plugin problem in a separate PR.