mirror of
https://github.com/cloudflare/cloudflare-docs.git
synced 2026-01-16 23:11:06 +00:00
Merge 191418df72 into daed515aa7
This commit is contained in:
Yomna Shousha
GitHub
commit
f93b70712e
1 changed files with 203 additions and 0 deletions
203
src/content/docs/workers/ci-cd/builds/autoconfig.mdx
Normal file
203
src/content/docs/workers/ci-cd/builds/autoconfig.mdx
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Reference in a new issue