Skip to content

Add Wrangler configuration to an existing project

The configuration generator adds a wrangler.jsonc and Cloudflare deploy/serve/types targets to an existing Nx project. It is framework-agnostic — bring your own framework’s Cloudflare adapter; this generator only wires the deploy, serve, and types layer.

Alias: config

Where this fits

Section titled “Where this fits”

Adopting Cloudflare in an existing workspace has two layers:

  1. Onboard the workspace — nx add @naxodev/nx-cloudflare installs Wrangler + Workers types and registers the inference plugin (see Installation). This runs once per workspace.
  2. Wire an app — this configuration generator writes the wrangler.jsonc and inferred targets onto one project. Run it per app you want to deploy.

nx add can’t do step 2 for you: it runs the workspace-level init generator, which has no notion of a target project. This generator is also self-bootstrapping — it installs the deps and registers the plugin itself — so you can run it directly without nx add first.

Usage

Section titled “Usage”
bunx nx g @naxodev/nx-cloudflare:configuration --project=<project>

What it does

Section titled “What it does”

Running the generator:

  1. Writes wrangler.jsonc into the project root (shape depends on template).
  2. Installs wrangler and @cloudflare/workers-types into the workspace root package.json devDependencies.
  3. Registers @naxodev/nx-cloudflare/plugin in nx.json if not already present, so that serve, deploy, typegen, version-upload, version-deploy, and tail targets are inferred from the Wrangler config.
  4. Gitignores worker-configuration.d.ts — the file generated by wrangler types.

Templates

Section titled “Templates”
TemplateDescription
workerPlain Worker. Points main at your entry file. (default)
spaStatic assets only. No Worker entry; assets served directly by Cloudflare.
fullstackStatic assets and an API Worker, with an ASSETS binding wired up.

Options

Section titled “Options”
Option Type Default Description
project string (required) The existing Nx project to add Cloudflare configuration to. Defaults to the project inferred from the current working directory.
template worker | spa | fullstack worker Shape of the generated wrangler.jsonc.
name string - The Worker name written to wrangler.jsonc. Defaults to a sanitized form of the project name (lowercase alphanumeric + hyphens, as Cloudflare requires).
main string src/index.ts Worker entry point (project-relative). Ignored for the 'spa' template.
assetsDir string dist Static assets directory wrangler serves, relative to the project root. Must point at your build output — Nx's default output lives at the workspace root (e.g. '../../dist/apps/web'), so override this unless your framework builds into the project. Used by 'spa' and 'fullstack'.
compatibilityDate string - Wrangler compatibility_date (YYYY-MM-DD). Defaults to today.
nodejsCompat boolean false Add compatibility_flags: ["nodejs_compat"].
skipFormat boolean false Skip formatting files.

Framework-agnostic note

Section titled “Framework-agnostic note”

The configuration generator does not install or configure a framework. If you are using React, Vue, Svelte, Astro, or another framework, install and configure the framework’s Cloudflare adapter separately — the generator only writes the Wrangler config and registers the plugin so that serve, deploy, and typegen targets become available in your Nx graph.

Example

Section titled “Example”

Add SPA (static-only) Cloudflare deployment to an existing web project whose build output lands in dist/web:

bunx nx g @naxodev/nx-cloudflare:configuration --project=web --template=spa --assetsDir=dist/web

After the generator runs:

bunx nx show project web

The project now has inferred serve, deploy, typegen, version-upload, version-deploy, and tail targets.

Next steps

Section titled “Next steps”