diff --git a/src/content/docs/workers/ci-cd/builds/autoconfig.mdx b/src/content/docs/workers/ci-cd/builds/autoconfig.mdx new file mode 100644 index 000000000000000..27cddb31f44b9b9 --- /dev/null +++ b/src/content/docs/workers/ci-cd/builds/autoconfig.mdx @@ -0,0 +1,203 @@ +--- +pcx_content_type: autoconfig +title: Project Auto-configuration +description: Learn how Workers Builds Configures your project to run on Workers +sidebar: + order: 11 +--- + +### Automatic Configuration + +Workers Builds includes automatic configuration to streamline your deployment process. When you deploy a project without a Wrangler configuration file, Workers Builds automatically detects your framework, configures your project, and creates a pull request with the necessary configuration files. + +#### Overview + +When you connect a repository to Workers Builds and your project doesn't have a `wrangler.toml` or `wrangler.jsonc` file, automatic configuration will: + +- Detect your framework (Astro, SvelteKit, or static sites) +- Identify your build settings from `package.json` +- Create the necessary Wrangler configuration files +- Deploy your Worker successfully +- Create a pull request with the configuration changes + +After you merge the pull request, future deployments will be faster since the configuration step can be skipped. + +### How It Works + +#### First Deployment + +On your first deployment, Workers Builds will: + +1. **Configure your project** - Automatically detect your framework and create configuration files +2. **Build your project** - Run your build command to prepare your Worker +3. **Deploy your Worker** - Publish your Worker to Cloudflare's network +4. **Create a pull request** - Open a PR in your repository with the configuration files + + +##### After Merging the PR + +Once you merge the configuration pull request: + +- Future deployments will use your committed configuration +- Builds will be faster (no configuration step needed) +- You can customize the configuration as needed + +### Supported Frameworks + +Automatic configuration currently supports: + +| Framework | Support Level | +|-----------|--------------| +| **Astro** | Full SSR support with Cloudflare adapter | +| **SvelteKit** | Full SSR support with Cloudflare adapter | +| **Static sites** | Any project with static HTML/assets | +| + more | | + + +### Configuration Pull Request + +#### What's Included + +The pull request will contain only the files needed to configure your Worker: + +- **`wrangler.jsonc`** - Your Worker configuration (compatibility settings, build command, output directory) +- **`package.json`** - Updated with Wrangler dependency and deployment scripts +- **`.gitignore`** - Appended with Wrangler-specific ignore patterns (`.wrangler/`, `.dev.vars`, `.env`) +- **Framework configs** (if applicable) - For example, `astro.config.mjs` or `svelte.config.js` +- **`.assetsignore`** files (if applicable) - Asset handling configuration for your framework +- can have a better list here when we get more data + +#### Why Merge the PR + +Merging the configuration PR provides several benefits: + +1. ** Faster builds** - Skip the configuration step on every deployment +2. ** Transparency** - See exactly what configuration was applied to your project +3. ** Customizable** - Modify the configuration to fit your specific needs +4. ** Version controlled** - Track your Worker configuration alongside your code + +#### If You Don't Merge + +If you choose not to merge the PR: + +- Automatic configuration will run on every deployment +- Builds will take longer due to the additional configuration step +- The PR will remain open for you to review and merge later + + +### Customizing Your Configuration + +After merging the PR, you can customize your Worker configuration by editing `wrangler.jsonc`: + +```jsonc +{ + "name": "my-worker", + "main": "dist/_worker.js", + "compatibility_date": "2025-01-01", + "compatibility_flags": ["nodejs_compat"], + "assets": { + "directory": "dist/" + } +} +``` + +Common customizations include: + +- **Environment variables** - Add [vars](/workers/configuration/environment-variables/) or [secrets](/workers/configuration/secrets/) +- **Custom domains** - Configure [routes](/workers/configuration/routing/routes/) +- **Bindings** - Add [KV](/kv/), [R2](/r2/), [D1](/d1/), or other [service bindings](/workers/runtime-apis/bindings/) +- **Compatibility settings** - Adjust [compatibility dates](/workers/configuration/compatibility-dates/) and [flags](/workers/configuration/compatibility-dates/#compatibility-flags) + +See the [configuration reference](/workers/wrangler/configuration/) for all available options. + +### Manual Configuration + +If you prefer to configure your Worker manually instead of using automatic configuration: + +1. **Run setup locally**: + ```bash + npx wrangler setup + ``` + +2. **Review the generated files**: + - Check `wrangler.jsonc` for accuracy + - Verify framework-specific configurations + +3. **Customize as needed**: + - Edit configurations to match your requirements + - Add environment variables, bindings, etc. + +4. **Commit and push**: + ```bash + git add wrangler.jsonc package.json .gitignore + git commit -m "Add Wrangler configuration" + git push + ``` + +Once a Wrangler configuration file exists in your repository, automatic configuration will not run on subsequent deployments. + +### Troubleshooting + +#### Build Fails After Merging PR + +If your deployment fails after merging the configuration PR: + +**Possible causes:** +- Specified build command may not match the proper configuration +- Missing environment variables or bindings +- Framework-specific requirements not met + +**Solutions:** +1. Review your build logs for specific error messages +2. Check that `wrangler.jsonc` settings match your project: + - Verify the `main` entry point exists + - Confirm the output directory is correct + - Ensure compatibility flags are appropriate +3. Consult the [framework guides](/workers/framework-guides/) for framework-specific setup + + +#### Need to Reconfigure + +If you want to regenerate your configuration: + +1. **Delete the configuration file**: + ```bash + git rm wrangler.jsonc + git commit -m "Remove Wrangler config for regeneration" + git push + ``` + +2. **Trigger a new deployment** - Automatic configuration will run again and create a new PR + + +## FAQ + +**Q: Will automatic configuration run on every deployment?** + +A: No. Once you have a `wrangler.jsonc` file in your repository (either from merging the PR or committing manually), automatic configuration will be skipped on future deployments. + +--- + +**Q: Is my code or data committed in the PR?** + +A: No. The PR only contains configuration files that automatic configuration created or modified. Your source code, build outputs, and environment variables are never included. + +--- + +**Q: Can I disable automatic configuration?** + +A: Yes. Create and commit a `wrangler.jsonc` file in your repository before deploying. Once a configuration file exists, automatic configuration will not run. + +--- + +**Q: How long does automatic configuration add to my build time?** + +A: The first deployment with automatic configuration takes an additional x seconds for the configuration step. After merging the PR, this overhead is eliminated entirely. + +### Related Resources + +- [Configuration Reference](/workers/wrangler/configuration/) - Complete guide to `wrangler.jsonc` options (add wrangler docs) +- [Framework Guides](/workers/framework-guides/) - Framework-specific setup instructions +- [Build Configuration](/workers/ci-cd/builds/configuration/) - Customize your build and deploy commands +- [Git Integration](/workers/ci-cd/builds/git-integration/) - Manage your repository connection +- [Wrangler Commands](/workers/wrangler/commands/) - CLI reference for local development \ No newline at end of file