docs: add Wrangler autoconfig documentation #28221
+1,070
−3
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| --- | ||
| pcx_content_type: concept | ||
| title: Automatic pull requests | ||
| description: Learn about the pull requests Workers Builds creates to configure your project or resolve issues. | ||
| sidebar: | ||
| order: 3 | ||
| --- | ||
|
|
||
| Workers Builds can automatically create pull requests in your repository to configure your project or resolve deployment issues. This page explains the different types of PRs you may receive and how to handle them. | ||
|
|
||
| ## Configuration PR | ||
|
|
||
| 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. | ||
|
|
||
| :::note | ||
| 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. | ||
| ::: | ||
|
|
||
| ### Why you should merge the PR | ||
|
|
||
| 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. | ||
|
|
||
| ### What the PR includes | ||
|
|
||
|  | ||
|
|
||
| The configuration PR may contain changes to the following files, depending on your framework: | ||
|
|
||
| - **`wrangler.jsonc`** - Wrangler configuration file with your Worker settings | ||
| - **Framework adapter** - Any required Cloudflare adapter for your framework (for example, `@astrojs/cloudflare` for Astro) | ||
| - **Framework configuration** - Updates to framework config files (for example, `astro.config.mjs` for Astro or `svelte.config.js` for SvelteKit) | ||
| - **`package.json`** - New scripts like `deploy`, `preview`, and `cf-typegen`, plus required dependencies | ||
| - **`package-lock.json`** / **`yarn.lock`** / **`pnpm-lock.yaml`** - Updated lock file with new dependencies | ||
| - **`.gitignore`** - Entries for `.wrangler` and `.dev.vars*` files | ||
| - **`.assetsignore`** - For frameworks that generate worker files in the output directory | ||
|
|
||
| ### PR description | ||
|
|
||
| The PR description includes: | ||
|
|
||
| - **Detected settings** - Framework, build command, deploy command, and version command | ||
| - **Preview link** - A working preview generated using the detected settings | ||
| - **Next steps** - Links to documentation for adding bindings, custom domains, and more | ||
|
|
||
| :::note | ||
| 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. | ||
| ::: | ||
|
|
||
| ## Name conflict PR | ||
|
|
||
| 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. | ||
|
|
||
| This can happen when: | ||
| - You rename your Worker in the dashboard but not in your config file | ||
| - You connect a repository that was previously used with a different Worker | ||
| - The `name` field in your config does not match the connected Worker | ||
|
|
||
| The PR will update the `name` field in your Wrangler configuration to match the Worker name in the dashboard. | ||
|
|
||
| For more details, refer to the [name conflict changelog](/changelog/2025-02-20-builds-name-conflict/). | ||
|
|
||
| ## Reviewing PRs | ||
|
|
||
| When you receive a PR from Workers Builds: | ||
|
|
||
| 1. **Review the changes** - Check that the configuration matches your project requirements | ||
| 2. **Test the preview** - Use the preview link in the PR description to verify everything works | ||
| 3. **Merge when ready** - Once satisfied, merge the PR to enable faster deployments |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,192 @@ | ||||||
| --- | ||||||
| pcx_content_type: concept | ||||||
| title: Deploy an existing project | ||||||
| sidebar: | ||||||
| order: 1 | ||||||
| description: Learn how Wrangler automatically detects and configures your project for Cloudflare Workers. | ||||||
| --- | ||||||
|
|
||||||
| import { PackageManagers, WranglerConfig } from "~/components"; | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| :::note | ||||||
| Minimum required Wrangler version: **TODO_VERSION**. Check your version by running `wrangler --version`. To update Wrangler, refer to [Install/Update Wrangler](/workers/wrangler/install-and-update/). | ||||||
| ::: | ||||||
|
|
||||||
| ## How it works | ||||||
|
|
||||||
| When you run `wrangler deploy` or `wrangler setup` in a project directory without a Wrangler configuration file, Wrangler will: | ||||||
|
|
||||||
| 1. **Detect your framework** - Analyzes your project to identify the framework you're using | ||||||
| 2. **Prompt for confirmation** - Shows the detected settings and asks you to confirm before making changes | ||||||
| 3. **Install adapters** - Installs any required Cloudflare adapters for your framework | ||||||
| 4. **Generate configuration** - Creates a `wrangler.jsonc` file with appropriate settings | ||||||
| 5. **Update package.json** - Adds helpful scripts like `deploy`, `preview`, and `cf-typegen` | ||||||
| 6. **Configure git** - Adds Wrangler-specific entries to `.gitignore` | ||||||
|
|
||||||
| ## Supported frameworks | ||||||
|
|
||||||
| Automatic configuration supports the following frameworks: | ||||||
|
|
||||||
| | Framework | Adapter/Tool | Notes | | ||||||
| | ---------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------- | | ||||||
| | [Next.js](/workers/framework-guides/web-apps/nextjs/) | `@opennextjs/cloudflare` | Runs `@opennextjs/cloudflare migrate` automatically. [R2 caching](#nextjs-caching) is configured if available. | | ||||||
| | [Astro](/workers/framework-guides/web-apps/astro/) | `@astrojs/cloudflare` | Runs `astro add cloudflare` automatically | | ||||||
| | [SvelteKit](/workers/framework-guides/web-apps/sveltekit/) | `@sveltejs/adapter-cloudflare` | Runs `sv add sveltekit-adapter` automatically | | ||||||
| | [Nuxt](/workers/framework-guides/web-apps/more-web-frameworks/nuxt/) | Built-in Cloudflare preset | | | ||||||
| | [React Router](/workers/framework-guides/web-apps/react-router/) | Cloudflare Vite plugin | | | ||||||
| | [Solid Start](/workers/framework-guides/web-apps/more-web-frameworks/solid/) | Built-in Cloudflare preset | | | ||||||
| | [Qwik](/workers/framework-guides/web-apps/more-web-frameworks/qwik/) | Built-in Cloudflare adapter | | | ||||||
| | [TanStack Start](/workers/framework-guides/web-apps/tanstack-start/) | Cloudflare Vite plugin | | | ||||||
| | [Angular](/workers/framework-guides/web-apps/more-web-frameworks/angular/) | | | | ||||||
| | [Analog](/workers/framework-guides/web-apps/more-web-frameworks/analog/) | Built-in Cloudflare preset | | | ||||||
| | [Vite](/workers/vite-plugin/) | Cloudflare Vite plugin | | | ||||||
| | [Hono](/workers/framework-guides/web-apps/more-web-frameworks/hono/) | | | | ||||||
| | [Vike](/workers/framework-guides/web-apps/vike/) | | | | ||||||
| | [Waku](/workers/framework-guides/web-apps/more-web-frameworks/waku/) | | | | ||||||
| | Static sites | None | Any directory with an `index.html` | | ||||||
|
|
||||||
| ## Files created and modified | ||||||
|
|
||||||
| When automatic configuration runs, the following files may be created or modified: | ||||||
|
|
||||||
| ### `wrangler.jsonc` | ||||||
|
|
||||||
| A new Wrangler configuration file is created with settings appropriate for your framework: | ||||||
|
|
||||||
| <WranglerConfig> | ||||||
|
|
||||||
| ```jsonc | ||||||
| { | ||||||
| "$schema": "node_modules/wrangler/config-schema.json", | ||||||
| "name": "my-project", | ||||||
| "main": "dist/_worker.js/index.js", | ||||||
| "compatibility_date": "$today", | ||||||
| "compatibility_flags": ["nodejs_compat"], | ||||||
| "assets": { | ||||||
| "binding": "ASSETS", | ||||||
| "directory": "dist", | ||||||
| }, | ||||||
| "observability": { | ||||||
| "enabled": true, | ||||||
| }, | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| </WranglerConfig> | ||||||
|
|
||||||
| The exact configuration varies based on your framework. | ||||||
|
|
||||||
| ### `package.json` | ||||||
|
|
||||||
| New scripts are added to your `package.json`: | ||||||
|
|
||||||
| ```json | ||||||
| { | ||||||
| "scripts": { | ||||||
| "deploy": "npm run build && wrangler deploy", | ||||||
| "preview": "npm run build && wrangler dev", | ||||||
| "cf-typegen": "wrangler types" | ||||||
| } | ||||||
| } | ||||||
| ``` | ||||||
|
|
||||||
| ### `.gitignore` | ||||||
|
|
||||||
| Wrangler-specific entries are added: | ||||||
|
|
||||||
| ```txt | ||||||
| # wrangler files | ||||||
| .wrangler | ||||||
| .dev.vars* | ||||||
| !.dev.vars.example | ||||||
| ``` | ||||||
|
|
||||||
| ### `.assetsignore` | ||||||
|
|
||||||
| For frameworks that generate worker files in the output directory, an `.assetsignore` file is created to exclude them from static asset uploads: | ||||||
|
|
||||||
| ```txt | ||||||
| _worker.js | ||||||
| _routes.json | ||||||
| ``` | ||||||
|
|
||||||
| ## Using automatic configuration | ||||||
|
|
||||||
| ### Deploy with automatic configuration | ||||||
|
|
||||||
| To deploy an existing project, run [`wrangler deploy`](/workers/wrangler/commands/#deploy) in your project directory: | ||||||
|
|
||||||
| <PackageManagers type="exec" pkg="wrangler" args="deploy" /> | ||||||
|
|
||||||
| Wrangler will detect your framework, show the configuration it will apply, and prompt you to confirm before making changes and deploying. | ||||||
|
|
||||||
| ### Configure without deploying | ||||||
|
|
||||||
| To configure your project without deploying, use [`wrangler setup`](/workers/wrangler/commands/#setup): | ||||||
|
|
||||||
| <PackageManagers type="exec" pkg="wrangler" args="setup" /> | ||||||
|
|
||||||
| This is useful when you want to review the generated configuration before deploying. | ||||||
|
|
||||||
| ### Preview changes with dry run | ||||||
|
|
||||||
| To see what changes would be made without actually modifying any files: | ||||||
|
|
||||||
| <PackageManagers type="exec" pkg="wrangler" args="setup --dry-run" /> | ||||||
|
|
||||||
| This outputs a summary of the configuration that would be generated. | ||||||
|
|
||||||
| ## Non-interactive mode | ||||||
|
|
||||||
| To skip the confirmation prompts, use the [`--yes` flag](/workers/wrangler/commands/#deploy): | ||||||
|
|
||||||
| <PackageManagers type="exec" pkg="wrangler" args="deploy --yes" /> | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| ## Importing a repository from the dashboard | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| For more details, refer to [Automatic pull requests](/workers/ci-cd/builds/automatic-prs/). | ||||||
|
|
||||||
| ## Skipping automatic configuration | ||||||
|
|
||||||
| 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`. | ||||||
|
|
||||||
| You can also manually configure your project by following the framework-specific guides in the [Framework guides](/workers/framework-guides/). | ||||||
|
|
||||||
| ## Next.js caching | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| - **If R2 is enabled on your account**: Automatic configuration creates an R2 bucket and configures caching automatically. | ||||||
| - **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). | ||||||
|
|
||||||
| To check if R2 is enabled or to enable it, go to **Storage & Databases** > **R2** in the [Cloudflare dashboard](https://dash.cloudflare.com/). | ||||||
|
|
||||||
| ## Troubleshooting | ||||||
|
|
||||||
| ### Multiple frameworks detected | ||||||
|
|
||||||
| 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). | ||||||
|
|
||||||
| When running `wrangler deploy` or `wrangler setup` locally, Wrangler will prompt you to select which framework to use if multiple frameworks are detected. | ||||||
|
|
||||||
| ### Framework not detected | ||||||
|
|
||||||
| If your framework is not detected, ensure your `package.json` includes the framework as a dependency. If the framework is not in the [supported list](#supported-frameworks), you'll need to manually configure your project. | ||||||
|
||||||
| If your framework is not detected, ensure your `package.json` includes the framework as a dependency. If the framework is not in the [supported list](#supported-frameworks), you'll need to manually configure your project. | |
| If your framework is not detected, ensure your `package.json` includes the framework as a dependency. If the framework is not in the [supported list](#supported-frameworks), you might need to manually configure your project. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hono is not supported 😓