feat(nx-cloudflare): add configuration generator for existing apps (#135)

[NachoVazquez]

TL;DR

There was no first-class way to put an existing Nx app on Cloudflare — create-cloudflare (C3) only scaffolds brand-new apps and binding only edits a Worker that already has a wrangler.jsonc. This adds a configuration generator that authors a wrangler.jsonc, installs wrangler + @cloudflare/workers-types, and registers the inference plugin onto a project you already have, so the serve/deploy/typegen/version/tail targets light up.

Files to review (20):

File	Why
packages/nx-cloudflare/src/generators/configuration/generator.ts (start here)	The generator — project resolution, don't-clobber guard, dep install, plugin registration, template authoring, gitignore, misconfig warnings.
packages/nx-cloudflare/src/generators/configuration/schema.json	Options + interactive prompts (project, template, name, main, assetsDir, compatibilityDate, nodejsCompat).
packages/nx-cloudflare/src/generators/configuration/files/{worker,spa,fullstack}/wrangler.jsonc.template	The three authored config shapes.
packages/nx-cloudflare/src/utils/{project,gitignore,wrangler-config}.ts	Shared helpers (resolveProjectRootOrThrow, ensureGitignored + WORKER_CONFIGURATION_DTS, wranglerSchemaPath) now reused by binding and create-cloudflare.
packages/nx-cloudflare/src/generators/{binding,create-cloudflare}/generator.ts	Refactored to consume those shared helpers instead of local copies.
packages/nx-cloudflare/src/generators/configuration/generator.spec.ts (new)	14 tests: each template, name sanitization, plugin + deps, gitignore (incl. idempotency), nodejsCompat for all three templates, entry-missing warning, both guards.
packages/nx-cloudflare/generators.json / src/index.ts	Manifest entry (alias config) + programmatic export.
packages/gonx/generators.json	Un-hides the existing init generator (see Reviewer notes).
docs/{nx-cloudflare-docs,gonx-docs}/...	How-to pages for each.

Why

Most frameworks (Astro, React Router, SvelteKit, Nuxt, Angular) deploy to Workers via their own adapters and already ship Nx generators. The plugin's durable value is the Cloudflare deploy/serve/types layer — the createNodes inference plugin keyed off wrangler.{toml,jsonc,json} — not re-scaffolding frameworks. This generator wires exactly that layer onto an app that already exists, and stays deliberately framework-agnostic: you bring your framework's Cloudflare adapter, it brings the config and targets.

Closes #135 (part of the #115 modernization epic).

How

The generator resolves the target project (Tree first, project-graph fallback so inference-only Workers resolve — the shared resolveProjectRootOrThrow), then:

1. Guards against an existing wrangler.{toml,jsonc,json} and throws loudly rather than clobbering hand-tuned config.
2. Installs wrangler + @cloudflare/workers-types and registers @naxodev/nx-cloudflare/plugin in nx.json — directly, not via the init generator, which would also force vitest + @cloudflare/vitest-pool-workers onto an app that owns its own test setup.
3. Authors wrangler.jsonc from one of three templates, with the $schema written as an offsetFromRoot-relative path so editors validate it. The default Worker name is sanitized to Cloudflare's lowercase-alphanumeric-plus-hyphens rule, so a scoped/cased Nx project name (@org/My_App → org-my-app) still yields a valid config.
4. Gitignores worker-configuration.d.ts (the typegen output).
5. Warns when the config is technically valid but won't work yet — the main entry doesn't exist, or the project root has no project.json/package.json for the inference plugin to attach targets to.

Template	Shape
worker (default)	plain Worker — main points at your entry, no assets
spa	static assets only — assets.directory + not_found_handling: "single-page-application", no main
fullstack	assets + API Worker — main and assets with an ASSETS binding

Reviewer notes

• Framework-agnostic by design. No framework detection, no adapter install, no entry-file scaffolding — main just points at whatever the app already builds. This matches nx-cloudflare: add an "add Cloudflare to an existing app" generator #135's premise and keeps the generator from rotting against per-framework adapter churn.
• Shared utils, not copies. resolveProjectRootOrThrow, ensureGitignored/WORKER_CONFIGURATION_DTS, and wranglerSchemaPath are extracted to src/utils and now consumed by binding and create-cloudflare too, replacing the previously duplicated blocks.
• gonx rides along as a one-line discoverability tweak. gonx already covered "add Go to an existing workspace" via its init generator; this only removes "hidden": true and sharpens the description so nx g/Nx Console surface it. It's intentionally minor and introduces no new gonx behavior — hence the single feat(nx-cloudflare) scope rather than a separate gonx release. Flag if you'd prefer it split out for its own changelog entry.
• assetsDir default is a starting point, not a guarantee. wrangler resolves it relative to the project root; Nx's default build output lives at the workspace root, so the schema/doc call out overriding it (e.g. ../../dist/apps/web) unless your framework builds into the project.
• Name follows Nx convention. configuration (alias config) mirrors @nx/vite:configuration — the configuration form is used when the plugin is the tool being configured; setup-* is for when the noun differs.
• No migration. Purely additive — no ! change, nothing for existing consumers to migrate.

Tests

14 bun:test cases in generator.spec.ts covering all three templates, Worker-name sanitization, the nodejsCompat flag on each template (proving the JSONC stays valid with the conditional comma), plugin + dependency wiring, gitignore presence and idempotency, the missing-entry warning, and both the already-configured and unknown-project guards. Run with bunx nx test nx-cloudflare. Lint, build, and both docs-site builds pass.

Links

• Issue: nx-cloudflare: add an "add Cloudflare to an existing app" generator #135
• Epic: nx-cloudflare: modernization epic (Nx 22 + Wrangler v4) #115

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	nx-cloudflare	c6c53ac	Commit Preview URL Branch Preview URL	Jun 28 2026, 08:36 PM

[nx-cloud]

View your CI Pipeline Execution ↗ for commit c6c53ac

Command	Status	Duration	Result
nx affected -t e2e --parallel=1	✅ Succeeded	4m 22s	View ↗
nx affected -t build --yes	✅ Succeeded	25s	View ↗
nx affected -t lint test	✅ Succeeded	41s	View ↗
nx-cloud record -- nx format:check	✅ Succeeded	1s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-28 20:41:32 UTC

[nx-cloud]

View your CI Pipeline Execution ↗ for commit a1b16e7

Command	Status	Duration	Result
nx affected -t e2e --parallel=1	✅ Succeeded	3m 56s	View ↗
nx affected -t build --yes	✅ Succeeded	24s	View ↗
nx affected -t lint test	✅ Succeeded	41s	View ↗
nx-cloud record -- nx format:check	✅ Succeeded	1s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-27 23:30:10 UTC

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gonx-docs	c6c53ac	Commit Preview URL Branch Preview URL	Jun 28 2026, 08:36 PM