Skip to content

Commit c6af4b6

Browse files
yomna-shoushaask-bonk[bot]dario-piotrowiczkodster28
authored
docs: add Wrangler autoconfig documentation (#28221)
* docs: add Wrangler autoconfig documentation - Add new page: Deploy an existing project (automatic-configuration.mdx) - Add new page: Automatic pull requests (automatic-prs.mdx) - Update Workers Builds pages with autoconfig integration - Add tip callouts to 13 framework guides linking to autoconfig - Update wrangler commands page with autoconfig and --yes flag - Add automatic PR screenshot image * docs: add changelog for autoconfig GA release * docs: address style guide feedback from Bonk review - Remove unused imports (Details, Render) from autoconfig.mdx - Fix contractions: don't → do not, doesn't → does not - Use WranglerConfig component with $today for compatibility_date - Replace em dash with period in changelog * remove changelog (moved to separate PR) and rename autoconfig.mdx to automatic-configuration.mdx * remove changelog image (moved to separate PR) * Replace sh code blocks with PackageManagers component in autoconfig docs * clarify that the multiple frameworks error only happens in CI * add troublshooting section regarding workspaces * docs: use PackageManagers component in framework guide tips and restore image - Replace inline `npx wrangler deploy` with PackageManagers component in 13 framework guide tip callouts - Restore automatic-pr.png image that was accidentally removed * docs: clarify troubleshooting sections for multiple frameworks and workspaces - Clarify that multiple frameworks error only occurs in Workers Builds dashboard - Add links to root directory and monorepo setup documentation - Simplify workspaces section wording * docs: add Next.js R2 caching information to autoconfig docs - Add Next.js caching section explaining automatic R2 cache setup - Update frameworks table to reference R2 caching for Next.js - Update Next.js guide tip to mention automatic R2 caching * Remove Hono from autoconfig - not supported * Clarify autoconfig may work with other projects like React/Vue SPAs * Add AutoconfigDiagram component and update framework guide pages - Create AutoconfigDiagram.astro component with auto-play looping animation - Add diagram and 'Automatic configuration' callouts to all 12 framework pages - Export component from src/components/index.ts * Trigger preview rebuild * Remove Qwik from autoconfig docs Co-authored-by: yomna-shousha <yomna-shousha@users.noreply.github.com> * Retrigger CI + remove unneeded sentence * [Workers] Replace TODO_VERSION with 4.68.0 in autoconfig docs * chore: retrigger CI --------- Co-authored-by: ask-bonk[bot] <ask-bonk[bot]@users.noreply.github.com> Co-authored-by: Dario Piotrowicz <dario@cloudflare.com> Co-authored-by: yomna-shousha <yomna-shousha@users.noreply.github.com> Co-authored-by: Kody Jackson <kody@cloudflare.com>
1 parent 156405d commit c6af4b6

20 files changed

Lines changed: 1050 additions & 3 deletions

File tree

‎src/assets/images/workers/ci-cd/builds/automatic-pr.png‎

888 KB
Loading

‎src/components/AutoconfigDiagram.astro‎

Lines changed: 535 additions & 0 deletions
Large diffs are not rendered by default.

‎src/components/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ export { Icon as AstroIcon } from "astro-icon/components";
77
export { default as AnchorHeading } from "./AnchorHeading.astro";
88
export { default as AnimatedWorkflowDiagram } from "./AnimatedWorkflowDiagram.astro";
99
export { default as APIRequest } from "./APIRequest.astro";
10+
export { default as AutoconfigDiagram } from "./AutoconfigDiagram.astro";
1011
export { default as AvailableNotifications } from "./AvailableNotifications.astro";
1112
export { default as Checkbox } from "./Checkbox.astro";
1213
export { default as CompatibilityFlag } from "./CompatibilityFlag.astro";

‎src/content/docs/workers/ci-cd/builds/automatic-prs.mdx‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
pcx_content_type: concept
3+
title: Automatic pull requests
4+
description: Learn about the pull requests Workers Builds creates to configure your project or resolve issues.
5+
sidebar:
6+
order: 3
7+
---
8+
9+
Workers Builds can automatically create pull requests in your repository to configure your project or resolve deployment issues.
10+
11+
## Configuration PR
12+
13+
When you connect a repository that does not have a Wrangler configuration file, Workers Builds runs `wrangler deploy` which triggers [automatic project configuration](/workers/framework-guides/automatic-configuration/). Instead of failing, it creates a pull request with the necessary configuration for your detected framework.
14+
15+
:::note
16+
A configuration PR is only created when your deploy command is `npx wrangler deploy`. If you have a custom deploy command, autoconfig will still run and configure your project, but no PR will be created.
17+
:::
18+
19+
### Why you should merge the PR
20+
21+
Without the configuration in your repository, every build has to run autoconfig first, which means your project gets built twice - once during autoconfig to generate the configuration, and again for the actual deployment. Merging the PR commits the configuration to your repository, so future builds skip autoconfig and go straight to building and deploying. This results in faster deployments and version-controlled settings.
22+
23+
### What the PR includes
24+
25+
![Example of an automatic configuration pull request created by Workers Builds](~/assets/images/workers/ci-cd/builds/automatic-pr.png)
26+
27+
The configuration PR may contain changes to the following files, depending on your framework:
28+
29+
- **`wrangler.jsonc`** - Wrangler configuration file with your Worker settings
30+
- **Framework adapter** - Any required Cloudflare adapter for your framework (for example, `@astrojs/cloudflare` for Astro)
31+
- **Framework configuration** - Updates to framework config files (for example, `astro.config.mjs` for Astro or `svelte.config.js` for SvelteKit)
32+
- **`package.json`** - New scripts like `deploy`, `preview`, and `cf-typegen`, plus required dependencies
33+
- **`package-lock.json`** / **`yarn.lock`** / **`pnpm-lock.yaml`** - Updated lock file with new dependencies
34+
- **`.gitignore`** - Entries for `.wrangler` and `.dev.vars*` files
35+
- **`.assetsignore`** - For frameworks that generate worker files in the output directory
36+
37+
### PR description
38+
39+
The PR description includes:
40+
41+
- **Detected settings** - Framework, build command, deploy command, and version command
42+
- **Preview link** - A working preview generated using the detected settings
43+
- **Next steps** - Links to documentation for adding bindings, custom domains, and more
44+
45+
:::note
46+
When you merge the PR, Workers Builds will update your build and deploy commands if they do not match the detected settings, ensuring successful deployments.
47+
:::
48+
49+
## Name conflict PR
50+
51+
If Workers Builds detects a mismatch between your Worker name in the Cloudflare dashboard and the `name` field in your Wrangler configuration file, it will create a pull request to fix the conflict.
52+
53+
This can happen when:
54+
- You rename your Worker in the dashboard but not in your config file
55+
- You connect a repository that was previously used with a different Worker
56+
- The `name` field in your config does not match the connected Worker
57+
58+
The PR will update the `name` field in your Wrangler configuration to match the Worker name in the dashboard.
59+
60+
For more details, refer to the [name conflict changelog](/changelog/2025-02-20-builds-name-conflict/).
61+
62+
## Reviewing PRs
63+
64+
When you receive a PR from Workers Builds:
65+
66+
1. **Review the changes** - Check that the configuration matches your project requirements
67+
2. **Test the preview** - Use the preview link in the PR description to verify everything works
68+
3. **Merge when ready** - Once satisfied, merge the PR to enable faster deployments

‎src/content/docs/workers/ci-cd/builds/configuration.mdx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,15 @@ import { DirectoryListing, Render, Tabs, TabItem, DashButton } from "~/component
1010

1111
When connecting your Git repository to your Worker, you can customize the configurations needed to build and deploy your Worker.
1212

13+
## How Workers Builds works
14+
15+
When a commit is pushed to your connected repository, Workers Builds runs a two-step process:
16+
17+
1. **Build command** _(optional)_ - Compiles your project (for example, `npm run build` for frameworks like Next.js or Astro)
18+
2. **Deploy command** - Deploys your Worker to Cloudflare (defaults to `npx wrangler deploy`)
19+
20+
For preview builds (commits to branches other than your production branch), the deploy command is replaced with a **preview deploy command** (defaults to `npx wrangler versions upload`), which creates a preview version without promoting it to production.
21+
1322
## Build settings
1423

1524
Build settings can be found by navigating to **Settings** > **Build** within your Worker.
@@ -60,6 +69,10 @@ Examples of other non-production branch deploy commands you can set include:
6069
| `yarn exec wrangler versions upload` | You can customize the package manager used to run Wrangler. |
6170
| `npx wrangler versions upload --env staging` | If you have a [Wrangler environment](/workers/ci-cd/builds/advanced-setups/#wrangler-environments) Worker, you should set your non-production branch deploy command with the environment flag. For more details, see [Advanced Setups](/workers/ci-cd/builds/advanced-setups/#wrangler-environments). |
6271

72+
### Automatic configuration for new projects
73+
74+
If your repository does not have a Wrangler configuration file, the deploy command (`wrangler deploy`) will trigger [automatic project configuration](/workers/framework-guides/automatic-configuration/). This detects your framework, creates the necessary configuration, and opens a [pull request](/workers/ci-cd/builds/automatic-prs/) for you to review. Once you merge the PR, your project is configured and future builds will deploy normally.
75+
6376
### API token
6477

6578
The API token in Workers Builds defines the access granted to Workers Builds for interacting with your account's resources. Currently, only user tokens are supported, with account-owned token support coming soon.

‎src/content/docs/workers/ci-cd/builds/index.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,17 @@ When connecting a repository to a Workers project, the Worker name in the Cloudf
4343

4444
:::
4545

46+
## Automatic project configuration
47+
48+
When you connect a repository that does not have a Wrangler configuration file, [autoconfig](/workers/framework-guides/automatic-configuration/) runs to detect your framework and create a [pull request](/workers/ci-cd/builds/automatic-prs/) to configure your project for Cloudflare Workers.
49+
50+
1. Autoconfig detects your framework and generates the necessary configuration
51+
2. A pull request is created in your repository with the necessary configuration changes
52+
3. A preview deployment is generated so you can test before merging
53+
4. Once you merge the PR, your project is ready for deployment
54+
55+
For details about supported frameworks and what files are created, refer to [Deploy an existing project](/workers/framework-guides/automatic-configuration/). For details about the PRs created, refer to [Automatic pull requests](/workers/ci-cd/builds/automatic-prs/).
56+
4657
## View build and preview URL
4758

4859
You can monitor a build's status and its build logs by navigating to **View build history** at the bottom of the **Deployments** tab of your Worker.

‎src/content/docs/workers/framework-guides/automatic-configuration.mdx‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
pcx_content_type: concept
3+
title: Deploy an existing project
4+
sidebar:
5+
order: 1
6+
description: Learn how Wrangler automatically detects and configures your project for Cloudflare Workers.
7+
---
8+
9+
import { PackageManagers, WranglerConfig } from "~/components";
10+
11+
Wrangler can automatically detect your framework and configure your project for Cloudflare Workers. This allows you to deploy existing projects with a single command, without manually setting up configuration files or installing adapters.
12+
13+
:::note
14+
Minimum required Wrangler version: **4.68.0**. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/).
15+
:::
16+
17+
## How it works
18+
19+
When you run `wrangler deploy` or `wrangler setup` in a project directory without a Wrangler configuration file, Wrangler will:
20+
21+
1. **Detect your framework** - Analyzes your project to identify the framework you're using
22+
2. **Prompt for confirmation** - Shows the detected settings and asks you to confirm before making changes
23+
3. **Install adapters** - Installs any required Cloudflare adapters for your framework
24+
4. **Generate configuration** - Creates a `wrangler.jsonc` file with appropriate settings
25+
5. **Update package.json** - Adds helpful scripts like `deploy`, `preview`, and `cf-typegen`
26+
6. **Configure git** - Adds Wrangler-specific entries to `.gitignore`
27+
28+
## Supported frameworks
29+
30+
Automatic configuration supports the following frameworks:
31+
32+
| Framework | Adapter/Tool | Notes |
33+
| ---------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
34+
| [Next.js](/workers/framework-guides/web-apps/nextjs/) | `@opennextjs/cloudflare` | Runs `@opennextjs/cloudflare migrate` automatically. [R2 caching](#nextjs-caching) is configured if available. |
35+
| [Astro](/workers/framework-guides/web-apps/astro/) | `@astrojs/cloudflare` | Runs `astro add cloudflare` automatically |
36+
| [SvelteKit](/workers/framework-guides/web-apps/sveltekit/) | `@sveltejs/adapter-cloudflare` | Runs `sv add sveltekit-adapter` automatically |
37+
| [Nuxt](/workers/framework-guides/web-apps/more-web-frameworks/nuxt/) | Built-in Cloudflare preset | |
38+
| [React Router](/workers/framework-guides/web-apps/react-router/) | Cloudflare Vite plugin | |
39+
| [Solid Start](/workers/framework-guides/web-apps/more-web-frameworks/solid/) | Built-in Cloudflare preset | |
40+
| [TanStack Start](/workers/framework-guides/web-apps/tanstack-start/) | Cloudflare Vite plugin | |
41+
| [Angular](/workers/framework-guides/web-apps/more-web-frameworks/angular/) | | |
42+
| [Analog](/workers/framework-guides/web-apps/more-web-frameworks/analog/) | Built-in Cloudflare preset | |
43+
| [Vite](/workers/vite-plugin/) | Cloudflare Vite plugin | |
44+
| [Vike](/workers/framework-guides/web-apps/vike/) | | |
45+
| [Waku](/workers/framework-guides/web-apps/more-web-frameworks/waku/) | | |
46+
| Static sites | None | Any directory with an `index.html` |
47+
48+
Automatic configuration may also work with other projects, such as React or Vue SPAs. Try running `wrangler deploy` or `wrangler setup` to see if your project is detected.
49+
50+
## Files created and modified
51+
52+
When automatic configuration runs, the following files may be created or modified:
53+
54+
### `wrangler.jsonc`
55+
56+
A new Wrangler configuration file is created with settings appropriate for your framework:
57+
58+
<WranglerConfig>
59+
60+
```jsonc
61+
{
62+
"$schema": "node_modules/wrangler/config-schema.json",
63+
"name": "my-project",
64+
"main": "dist/_worker.js/index.js",
65+
"compatibility_date": "$today",
66+
"compatibility_flags": ["nodejs_compat"],
67+
"assets": {
68+
"binding": "ASSETS",
69+
"directory": "dist",
70+
},
71+
"observability": {
72+
"enabled": true,
73+
},
74+
}
75+
```
76+
77+
</WranglerConfig>
78+
79+
The exact configuration varies based on your framework.
80+
81+
### `package.json`
82+
83+
New scripts are added to your `package.json`:
84+
85+
```json
86+
{
87+
"scripts": {
88+
"deploy": "npm run build && wrangler deploy",
89+
"preview": "npm run build && wrangler dev",
90+
"cf-typegen": "wrangler types"
91+
}
92+
}
93+
```
94+
95+
### `.gitignore`
96+
97+
Wrangler-specific entries are added:
98+
99+
```txt
100+
# wrangler files
101+
.wrangler
102+
.dev.vars*
103+
!.dev.vars.example
104+
```
105+
106+
### `.assetsignore`
107+
108+
For frameworks that generate worker files in the output directory, an `.assetsignore` file is created to exclude them from static asset uploads:
109+
110+
```txt
111+
_worker.js
112+
_routes.json
113+
```
114+
115+
## Using automatic configuration
116+
117+
### Deploy with automatic configuration
118+
119+
To deploy an existing project, run [`wrangler deploy`](/workers/wrangler/commands/#deploy) in your project directory:
120+
121+
<PackageManagers type="exec" pkg="wrangler" args="deploy" />
122+
123+
Wrangler will detect your framework, show the configuration it will apply, and prompt you to confirm before making changes and deploying.
124+
125+
### Configure without deploying
126+
127+
To configure your project without deploying, use [`wrangler setup`](/workers/wrangler/commands/#setup):
128+
129+
<PackageManagers type="exec" pkg="wrangler" args="setup" />
130+
131+
This is useful when you want to review the generated configuration before deploying.
132+
133+
### Preview changes with dry run
134+
135+
To see what changes would be made without actually modifying any files:
136+
137+
<PackageManagers type="exec" pkg="wrangler" args="setup --dry-run" />
138+
139+
This outputs a summary of the configuration that would be generated.
140+
141+
## Non-interactive mode
142+
143+
To skip the confirmation prompts, use the [`--yes` flag](/workers/wrangler/commands/#deploy):
144+
145+
<PackageManagers type="exec" pkg="wrangler" args="deploy --yes" />
146+
147+
This applies the configuration automatically using sensible defaults. This is useful in CI/CD environments or when you want to accept the detected settings without reviewing them.
148+
149+
## Importing a repository from the dashboard
150+
151+
When you import a GitHub or GitLab repository via the Cloudflare dashboard, autoconfig runs non-interactively. If your repository does not have a Wrangler configuration file, [Workers Builds](/workers/ci-cd/builds/) will create a pull request with the necessary configuration.
152+
153+
The PR includes all the configuration changes described above. A preview deployment is generated so you can test the changes before merging. Once merged, your project is ready for deployment.
154+
155+
For more details, refer to [Automatic pull requests](/workers/ci-cd/builds/automatic-prs/).
156+
157+
## Skipping automatic configuration
158+
159+
If you do not want automatic configuration to run, ensure you have a valid Wrangler configuration file (`wrangler.toml`, `wrangler.json`, or `wrangler.jsonc`) in your project before running `wrangler deploy`.
160+
161+
You can also manually configure your project by following the framework-specific guides in the [Framework guides](/workers/framework-guides/).
162+
163+
## Next.js caching
164+
165+
For Next.js projects, automatic configuration will set up [R2](/r2/) for caching if your Cloudflare account has R2 enabled. R2 caching improves performance for [Incremental Static Regeneration (ISR)](https://opennext.js.org/cloudflare/caching) and other Next.js caching features.
166+
167+
- **If R2 is enabled on your account**: Automatic configuration creates an R2 bucket and configures caching automatically.
168+
- **If R2 is not enabled**: Your project will be configured without caching. You can [enable R2](/r2/get-started/) later and manually configure caching by following the [OpenNext caching documentation](https://opennext.js.org/cloudflare/caching).
169+
170+
To check if R2 is enabled or to enable it, go to **Storage & Databases** > **R2** in the [Cloudflare dashboard](https://dash.cloudflare.com/).
171+
172+
## Troubleshooting
173+
174+
### Multiple frameworks detected
175+
176+
When you import a repository via [Workers Builds](/workers/ci-cd/builds/) in the Cloudflare dashboard, automatic configuration will fail if your project contains multiple frameworks. To resolve this, set the [root directory](/workers/ci-cd/builds/configuration/#build-settings) to the path containing only one framework. For monorepos, refer to [monorepo setup](/workers/ci-cd/builds/advanced-setups/#monorepos).
177+
178+
When running `wrangler deploy` or `wrangler setup` locally, Wrangler will prompt you to select which framework to use if multiple frameworks are detected.
179+
180+
### Framework not detected
181+
182+
If your framework is not detected, ensure your `package.json` includes the framework as a dependency.
183+
184+
### Configuration already exists
185+
186+
If a Wrangler configuration file already exists, automatic configuration will not run. To reconfigure your project, delete the existing configuration file and run `wrangler deploy` or `wrangler setup` again.
187+
188+
### Workspaces
189+
190+
Support for monorepos and npm/yarn/pnpm workspaces is currently limited. Wrangler analyzes the project directory where you run the command, but does not detect dependencies installed at the workspace root. This can cause framework detection to fail if the framework is listed as a dependency in the workspace's root `package.json` rather than in the individual project's `package.json`.
191+
192+
If you encounter issues, report them in the [Wrangler GitHub repository](https://github.com/cloudflare/workers-sdk/issues/new/choose).

0 commit comments

Comments
 (0)