Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/native-vite-fallback.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
"cf": minor
---

Run the project's own Vite or Vite+ commands

`cf dev`, `cf build` and `cf deploy` now run the project's installed `vite` or `vp` (Vite+) instead of the internal `cf-vite` executable from `@cloudflare/vite-plugin` when autoconfig identifies it as a Vite project. If you were running `cf dev -- --local`, set `remoteBindings: false` in `cloudflare()` to turn off remote bindings.

Stopping cf now also stops tools that launchers such as `vp` start, and on macOS and Linux a second Ctrl+C force-stops the command.
35 changes: 35 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -391,6 +391,41 @@ delegated build, recording `--mode` and Preview context, before the command
continues through the normal Build Output upload path. Without `[directory]`,
these commands consume Build Output from a delegated build or `--prebuilt`.

Autoconfig owns the dev/build command choice, including Vite versus Vite+.
Autoconfig reports command-readiness problems as data so inspection can recognize
configured projects before dependencies are installed. cf raises those problems
before executing a development or build command. Autoconfig owns the minimum
Vite plugin version for auth-profile support (`>=2.0.0-beta.v.13 <3`).
Pages detection and migration checks take precedence over native fallbacks.
Other unsupported frameworks can use a native fallback after the project has
been configured for cf; their automatic setup restrictions still apply.
Autoconfig validates plugin compatibility for eligible cf projects that declare
the plugin. When neither framework command is detected, it returns the installed
native executable in `devCommand` / `buildCommand`. cf executes those commands using the same
argument forwarding, environment, signals, and exit handling as other framework
commands. Vite evaluates its own configuration, including dynamic plugin arrays
and custom config files. If a Vite build succeeds without Build Output, cf hints
that the Vite config should include `cloudflare()`. On POSIX, framework commands
run in a separate process group so
shutdown signals also reach tools started by launchers such as `vp`. Windows
keeps console Ctrl+C delivery and terminates the command tree for SIGTERM.
On POSIX, a second interrupt forces termination, and terminal closure forwards
SIGHUP. With inherited terminal streams, global-to-local cf delegation relies
on the terminal's SIGINT delivery to both CLIs, so one Ctrl+C does not trigger
escalation. Non-interactive delegation relays SIGINT, and SIGTERM is always relayed.
A synchronous exit hook makes a best-effort attempt to stop an active
command tree if cf exits before shutdown completes. SIGKILL of cf itself cannot
run cleanup; cf does not start a supervisor process.
Bare commands prepend autoconfig's ordered `nodeModulesPaths`, from the
application's `node_modules/.bin` through its validated workspace root, and retain
the inherited PATH. This supports hoisted workspace toolchains without adding
unrelated parent installations. The shared build
path supplies `CLOUDFLARE_PREVIEW_BUILD` for Preview deployments. Delegate discovery
is reserved for Wrangler, Python, and Rust implementations. Binding defaults
remain unchanged. To explicitly disable remote bindings, configure
`cloudflare({ remoteBindings: false })` in the Vite configuration; the internal
Vite delegate's `--local` flag is no longer available.

This keeps Worker-definition validation lazy: `cf dns records list` cannot fail
merely because a binding field in the configured Worker is invalid. Loading
account settings still evaluates the TypeScript module and default config
Expand Down
6 changes: 3 additions & 3 deletions fixtures/vite-plugin-project/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ No automated test currently starts this fixture.

## Layout

- `package.json` declares the Vite plugin, Vite, Wrangler, and Workers types, and provides the `vp dev` script.
- `package.json` declares the Vite plugin, Vite, Vite+, Wrangler, and Workers types, and provides the `vp dev` script.
- `vite.config.ts` registers `cloudflare()` and disables inspector-port and persisted-state behavior for the smoke session.
- `cloudflare.config.ts`'s default export contains the Worker entrypoint, compatibility date, name, and `MY_VAR` text binding. Mode `test` produces `Test var`; other modes produce `Default var`.
- `src/worker.ts` returns `MY_VAR` from `/var` and a JSON fixture description from Worker-handled paths.
Expand All @@ -19,7 +19,7 @@ cf supplies `CLOUDFLARE_VITE_FORCE_BUILD_OUTPUT=true` to the detected Vite comma

The fixture is included by the root `fixtures/*` workspace glob. Its committed dependencies are registry semver ranges, not environment-specific `link:` targets. A root `pnpm install` resolves them and creates the fixture-local package links expected by the tools.

The workspace aliases `vite` to Vite+ core, which provides no `vite` CLI. The root `vite-plus` dependency supplies the `vp` CLI used by the fixture script.
The workspace aliases `vite` to Vite+ core, which provides no `vite` CLI. The fixture declares `vite-plus` directly so autoconfig selects its `vp` CLI for `cf dev` as well as the fixture script.

## Running the dev script

Expand All @@ -32,7 +32,7 @@ cd fixtures/vite-plugin-project
pnpm dev
```

Pass custom Vite arguments to the script, for example `pnpm dev --mode test`. The current autoconfig route used by `cf dev` delegates to `npx vite`; it does not yet use this fixture's `vp dev` script.
Pass custom Vite arguments to the script, for example `pnpm dev --mode test`. Alternatively, `cf dev` runs the project command selected by autoconfig and forwards the mode and server arguments, for example `cf dev --mode test`.
Comment thread
petebacondarwin marked this conversation as resolved.
Resolved

The server prints its URL. Representative checks are:

Expand Down
1 change: 1 addition & 0 deletions fixtures/vite-plugin-project/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
"@cloudflare/workers-types": "5.20261116.1",
"cf": "workspace:*",
"vite": "catalog:",
"vite-plus": "catalog:",
"wrangler": "4.163.0"
}
}
2 changes: 1 addition & 1 deletion fixtures/wrangler-bundler-project/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The current `cf-wrangler` delegate uses Wrangler's TypeScript configuration load

The fixture is included by the root `fixtures/*` workspace glob. There are no environment-specific `link:` targets.

cf requires Wrangler 4.161.0 or newer for this delegate, shared authentication profile selection, and output contract. For an unpublished workers-sdk worktree, a temporary fixture-local link may be used instead, but no such link belongs to the committed fixture. The relevant upstream executable is `packages/wrangler/bin/cf-wrangler.js`.
cf requires Wrangler 4.163.0 or newer for this delegate, shared authentication profile selection, and output contract. For an unpublished workers-sdk worktree, a temporary fixture-local link may be used instead, but no such link belongs to the committed fixture. The relevant upstream executable is `packages/wrangler/bin/cf-wrangler.js`.

## Running through cf

Expand Down
2 changes: 1 addition & 1 deletion packages/cli/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ public AI Search endpoint, outside the platform API/SDK, and returns ranked
JSON page metadata without authentication. Agents fetch returned URLs with
`Accept: text/markdown` to read complete pages.

`auth`, `complete`, `dev`, `build`, `deploy`, `migrate`, `cli`, `schema`, and `tools` are root entries in `src/commands/hand-written.ts`, registered lazily by `src/index.ts`. `cf cli telemetry` is the telemetry-settings path. `cf migrate` uses `@cloudflare/codemods` to convert a Wrangler configuration to `cloudflare.config.ts` and report manual follow-up work. `cf dev` analyzes and, when needed, configures a project before running its canonical framework command, with an installed Cloudflare implementation as fallback. `cf build` follows the same routing and validates the resulting Build Output. `cf deploy`, `cf previews deploy`, and `cf workers versions create` accept an optional `[directory]` containing already-built, assets-only content and write it into Build Output without delegation; Preview output is marked with Preview context. The directory form reuses an optional source Worker config but rejects configured entrypoints and Containers, so server-side projects omit it and use the normal build path. Without the positional argument, these commands build first unless `--prebuilt` is passed, then read Build Output and call `@cloudflare/deploy-helpers`; Preview names use `--preview-name`, and version creation uploads without deploying. `cf workers triggers deploy` likewise builds by default or consumes `--prebuilt` Build Output, but only applies the configured triggers and does not accept an assets directory. Deploy-helper provisioning is enabled for supported bindings.
`auth`, `complete`, `dev`, `build`, `deploy`, `migrate`, `cli`, `schema`, and `tools` are root entries in `src/commands/hand-written.ts`, registered lazily by `src/index.ts`. `cf cli telemetry` is the telemetry-settings path. `cf migrate` uses `@cloudflare/codemods` to convert a Wrangler configuration to `cloudflare.config.ts` and report manual follow-up work. `cf dev` analyzes and, when needed, configures a project before running its canonical framework command, with an installed Cloudflare implementation as fallback. Autoconfig owns Vite/Vite+ command selection and plugin compatibility checks, including the minimum version for cf profiles and projects without a detected framework command. Until autoconfig raises its beta compatibility floor, cf additionally requires `@cloudflare/vite-plugin >=2.0.0-rc.0 <3` for Vite-based Build Output v1 producers, recording the failure during analysis and validating it after setup. Vite evaluates its own configuration; cf adds a `cloudflare()` hint when a successful Vite build produces no Build Output. Execute its returned dev/build commands through the project command runner; reserve delegate discovery for Wrangler, Python, and Rust. Bare commands prepend autoconfig's ordered `nodeModulesPaths`: the application's `node_modules/.bin` and ancestor directories up to its validated workspace root. Inherited PATH remains available for ordinary project commands. `cf build` follows the same routing and validates the resulting Build Output. `cf deploy`, `cf previews deploy`, and `cf workers versions create` accept an optional `[directory]` containing already-built, assets-only content and write it into Build Output without delegation; Preview output is marked with Preview context. The directory form reuses an optional source Worker config but rejects configured entrypoints and Containers, so server-side projects omit it and use the normal build path. Without the positional argument, these commands build first unless `--prebuilt` is passed, then read Build Output and call `@cloudflare/deploy-helpers`; Preview names use `--preview-name`, and version creation uploads without deploying. `cf workers triggers deploy` likewise builds by default or consumes `--prebuilt` Build Output, but only applies the configured triggers and does not accept an assets directory. Deploy-helper provisioning is enabled for supported bindings.

`previews` uses a generated group containing the hand-written `previews deploy` workflow. Its parent override opts into `createIfMissing`, so generation creates an empty API parent when the pinned schema has no Preview CLI operations. Future schema operations join the same group without colliding with a hand-written root.

Expand Down
5 changes: 3 additions & 2 deletions packages/cli/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,9 @@ named profiles. `cf auth login` and `cf auth logout` manage the default profile.
commands and Cloudflare dev-server implementations through
`CLOUDFLARE_AUTH_PROFILE`, overriding any inherited value. The development
server needs `@cloudflare/workers-auth` 0.17.0 or newer to use the selected
credentials. Cloudflare delegates require Wrangler 4.163.0 or newer, or Vite
plugin v2 starting at 2.0.0-rc.0; older delegates fail with an upgrade hint.
credentials. Wrangler delegates require Wrangler 4.163.0 or newer. For Vite
projects, use `@cloudflare/vite-plugin` 2.0.0-rc.0 or newer to produce compatible
Build Output.
Comment thread
petebacondarwin marked this conversation as resolved.
Resolved

Use `cf auth login --use-keyring` to encrypt OAuth credentials with a key stored
in your OS keychain. The choice is saved across invocations and applies to all
Expand Down
Loading
Loading