chore(agent): configure AI agents and tools
Add configuration for BMad, Claude, OpenCode, and other AI agent tools and workflows.
This commit is contained in:
@@ -0,0 +1,407 @@
|
||||
# Configuration Guide
|
||||
|
||||
Complete reference for all configuration options when deploying Astro to Cloudflare Workers.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [wrangler.jsonc Reference](#wranglerjsonc-reference)
|
||||
2. [Astro Configuration](#astro-configuration)
|
||||
3. [Environment-Specific Configuration](#environment-specific-configuration)
|
||||
4. [Bindings Configuration](#bindings-configuration)
|
||||
5. [Advanced Options](#advanced-options)
|
||||
|
||||
---
|
||||
|
||||
## wrangler.jsonc Reference
|
||||
|
||||
### Core Fields
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Worker/Project name |
|
||||
| `compatibility_date` | string (YYYY-MM-DD) | Yes | Runtime API version |
|
||||
| `$schema` | string | No | Path to JSON schema for validation |
|
||||
| `main` | string | No | Entry point file (auto-detected for Astro) |
|
||||
| `account_id` | string | No | Cloudflare account ID |
|
||||
|
||||
### Assets Configuration
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"assets": {
|
||||
"directory": "./dist",
|
||||
"binding": "ASSETS",
|
||||
"html_handling": "force-trailing-slash",
|
||||
"not_found_handling": "404-page"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Option | Values | Default | Description |
|
||||
|--------|--------|---------|-------------|
|
||||
| `directory` | path | `"./dist"` | Build output directory |
|
||||
| `binding` | string | `"ASSETS"` | Name to access assets in code |
|
||||
| `html_handling` | `"none"`, `"force-trailing-slash"`, `"strip-trailing-slash"` | `"none"` | URL handling behavior |
|
||||
| `not_found_handling` | `"none"`, `"404-page"`, `"spa-fallback"` | `"none"` | 404 error behavior |
|
||||
|
||||
### Compatibility Flags
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"compatibility_flags": ["nodejs_compat", "disable_nodejs_process_v2"]
|
||||
}
|
||||
```
|
||||
|
||||
| Flag | Purpose |
|
||||
|------|---------|
|
||||
| `nodejs_compat` | Enable Node.js APIs in Workers |
|
||||
| `disable_nodejs_process_v2` | Use legacy process global (for some packages) |
|
||||
|
||||
---
|
||||
|
||||
## Astro Configuration
|
||||
|
||||
### Adapter Options
|
||||
|
||||
```javascript
|
||||
// astro.config.mjs
|
||||
import cloudflare from '@astrojs/cloudflare';
|
||||
|
||||
export default defineConfig({
|
||||
adapter: cloudflare({
|
||||
// Mode: how routes are deployed
|
||||
mode: 'directory', // 'directory' (default) or 'standalone'
|
||||
|
||||
// Image service handling
|
||||
imageService: 'passthrough', // 'passthrough' (default) or 'compile'
|
||||
|
||||
// Platform proxy for local development
|
||||
platformProxy: {
|
||||
enabled: true,
|
||||
configPath: './wrangler.jsonc',
|
||||
persist: {
|
||||
path: './.cache/wrangler/v3',
|
||||
},
|
||||
},
|
||||
}),
|
||||
});
|
||||
```
|
||||
|
||||
### Mode Comparison
|
||||
|
||||
| Mode | Description | Use Case |
|
||||
|------|-------------|----------|
|
||||
| `directory` | Separate function per route | Most projects, better caching |
|
||||
| `standalone` | Single worker for all routes | Simple apps, shared state |
|
||||
|
||||
### Image Service Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `passthrough` | Images pass through unchanged (default) |
|
||||
| `compile` | Images optimized at build time using Sharp |
|
||||
|
||||
---
|
||||
|
||||
## Environment-Specific Configuration
|
||||
|
||||
### Multiple Environments
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"name": "my-app",
|
||||
"vars": {
|
||||
"ENVIRONMENT": "production",
|
||||
"API_URL": "https://api.example.com"
|
||||
},
|
||||
|
||||
"env": {
|
||||
"staging": {
|
||||
"name": "my-app-staging",
|
||||
"vars": {
|
||||
"ENVIRONMENT": "staging",
|
||||
"API_URL": "https://staging-api.example.com"
|
||||
}
|
||||
},
|
||||
|
||||
"production": {
|
||||
"name": "my-app-production",
|
||||
"vars": {
|
||||
"ENVIRONMENT": "production",
|
||||
"API_URL": "https://api.example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Deploying to Environment
|
||||
|
||||
```bash
|
||||
# Deploy to staging
|
||||
npx wrangler deploy --env staging
|
||||
|
||||
# Deploy to production
|
||||
npx wrangler deploy --env production
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bindings Configuration
|
||||
|
||||
### KV Namespace
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"kv_namespaces": [
|
||||
{
|
||||
"binding": "MY_KV",
|
||||
"id": "your-kv-namespace-id",
|
||||
"preview_id": "your-preview-kv-id"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage in Astro:**
|
||||
```javascript
|
||||
const kv = Astro.locals.runtime.env.MY_KV;
|
||||
const value = await kv.get("key");
|
||||
await kv.put("key", "value", { expirationTtl: 3600 });
|
||||
```
|
||||
|
||||
**Creating KV:**
|
||||
```bash
|
||||
npx wrangler kv:namespace create MY_KV
|
||||
```
|
||||
|
||||
### D1 Database
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"d1_databases": [
|
||||
{
|
||||
"binding": "DB",
|
||||
"database_name": "my-database",
|
||||
"database_id": "your-d1-database-id"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage in Astro:**
|
||||
```javascript
|
||||
const db = Astro.locals.runtime.env.DB;
|
||||
const result = await db.prepare("SELECT * FROM users").all();
|
||||
```
|
||||
|
||||
**Creating D1:**
|
||||
```bash
|
||||
npx wrangler d1 create my-database
|
||||
npx wrangler d1 execute my-database --file=./schema.sql
|
||||
```
|
||||
|
||||
### R2 Storage
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"r2_buckets": [
|
||||
{
|
||||
"binding": "BUCKET",
|
||||
"bucket_name": "my-bucket"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Usage in Astro:**
|
||||
```javascript
|
||||
const bucket = Astro.locals.runtime.env.BUCKET;
|
||||
await bucket.put("file.txt", "Hello World");
|
||||
const object = await bucket.get("file.txt");
|
||||
```
|
||||
|
||||
**Creating R2:**
|
||||
```bash
|
||||
npx wrangler r2 bucket create my-bucket
|
||||
```
|
||||
|
||||
### Durable Objects
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"durable_objects": {
|
||||
"bindings": [
|
||||
{
|
||||
"name": "MY_DURABLE_OBJECT",
|
||||
"class_name": "MyDurableObject",
|
||||
"script_name": "durable-object-worker"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Options
|
||||
|
||||
### Custom Routing
|
||||
|
||||
Create `_routes.json` in project root for advanced routing control:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"include": ["/*"],
|
||||
"exclude": ["/api/*", "/admin/*"]
|
||||
}
|
||||
```
|
||||
|
||||
- **include**: Patterns to route to Worker
|
||||
- **exclude**: Patterns to serve as static assets
|
||||
|
||||
### Scheduled Tasks (Cron Triggers)
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"triggers": {
|
||||
"crons": [
|
||||
{ "cron": "0 * * * *", "path": "/api/hourly" },
|
||||
{ "cron": "0 0 * * *", "path": "/api/daily" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Create corresponding API routes:
|
||||
|
||||
```javascript
|
||||
// src/pages/api/hourly.js
|
||||
export async function GET({ locals }) {
|
||||
// Runs every hour
|
||||
return new Response("Hourly task complete");
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"routes": [
|
||||
{
|
||||
"pattern": "api.example.com/*",
|
||||
"zone_name": "example.com"
|
||||
}
|
||||
],
|
||||
"limits": {
|
||||
"cpu_ms": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Logging and Monitoring
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"logpush": true,
|
||||
"placement": {
|
||||
"mode": "smart"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**View logs in real-time:**
|
||||
```bash
|
||||
npx wrangler tail
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TypeScript Configuration
|
||||
|
||||
### Complete tsconfig.json
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2022",
|
||||
"module": "ESNext",
|
||||
"moduleResolution": "bundler",
|
||||
"resolveJsonModule": true,
|
||||
"allowJs": true,
|
||||
"strict": true,
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"types": ["@cloudflare/workers-types"],
|
||||
"jsx": "react-jsx",
|
||||
"jsxImportSource": "react"
|
||||
},
|
||||
"include": ["src"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Type Definition
|
||||
|
||||
```typescript
|
||||
// src/env.d.ts
|
||||
/// <reference path="../.astro/types.d.ts" />
|
||||
|
||||
interface Env {
|
||||
// Cloudflare bindings
|
||||
MY_KV: KVNamespace;
|
||||
DB: D1Database;
|
||||
BUCKET: R2Bucket;
|
||||
|
||||
// Environment variables
|
||||
API_URL: string;
|
||||
ENVIRONMENT: string;
|
||||
SECRET_VALUE?: string;
|
||||
}
|
||||
|
||||
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
|
||||
|
||||
declare namespace App {
|
||||
interface Locals extends Runtime {}
|
||||
}
|
||||
|
||||
declare namespace Astro {
|
||||
interface Locals extends Runtime {}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Configuration
|
||||
|
||||
### package.json Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "astro dev",
|
||||
"build": "astro build",
|
||||
"preview": "wrangler dev",
|
||||
"deploy": "npm run build && wrangler deploy",
|
||||
"deploy:staging": "npm run build && wrangler deploy --env staging",
|
||||
"cf:dev": "wrangler dev",
|
||||
"cf:dev:remote": "wrangler dev --remote",
|
||||
"cf:tail": "wrangler tail"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Vite Configuration
|
||||
|
||||
```javascript
|
||||
// vite.config.js (if needed)
|
||||
import { defineConfig } from 'vite';
|
||||
|
||||
export default defineConfig({
|
||||
build: {
|
||||
// Adjust chunk size warnings
|
||||
chunkSizeWarningLimit: 1000,
|
||||
},
|
||||
});
|
||||
```
|
||||
@@ -0,0 +1,376 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide covers common issues when deploying Astro 6 to Cloudflare Workers.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Build Errors](#build-errors)
|
||||
2. [Runtime Errors](#runtime-errors)
|
||||
3. [Deployment Issues](#deployment-issues)
|
||||
4. [Performance Issues](#performance-issues)
|
||||
5. [Development Server Issues](#development-server-issues)
|
||||
|
||||
---
|
||||
|
||||
## Build Errors
|
||||
|
||||
### "MessageChannel is not defined"
|
||||
|
||||
**Symptoms:**
|
||||
- Build fails with reference to `MessageChannel`
|
||||
- Occurs when using React 19 with Cloudflare adapter
|
||||
|
||||
**Cause:**
|
||||
React 19 uses `MessageChannel` which is not available in the Cloudflare Workers runtime by default.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Add compatibility flag** in `wrangler.jsonc`:
|
||||
```jsonc
|
||||
{
|
||||
"compatibility_flags": ["nodejs_compat"]
|
||||
}
|
||||
```
|
||||
|
||||
2. **Use React 18** temporarily if the issue persists:
|
||||
```bash
|
||||
npm install react@18 react-dom@18
|
||||
```
|
||||
|
||||
3. **Check for related GitHub issues:**
|
||||
- [Astro Issue #12824](https://github.com/withastro/astro/issues/12824)
|
||||
|
||||
### "Cannot find module '@astrojs/cloudflare'"
|
||||
|
||||
**Symptoms:**
|
||||
- Import error in `astro.config.mjs`
|
||||
- Type errors in TypeScript
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Install the adapter:**
|
||||
```bash
|
||||
npm install @astrojs/cloudflare
|
||||
```
|
||||
|
||||
2. **Verify installation:**
|
||||
```bash
|
||||
npm list @astrojs/cloudflare
|
||||
```
|
||||
|
||||
3. **For Astro 6, ensure v13+:**
|
||||
```bash
|
||||
npm install @astrojs/cloudflare@beta
|
||||
```
|
||||
|
||||
### "Too many files for webpack"
|
||||
|
||||
**Symptoms:**
|
||||
- Build fails with file limit error
|
||||
- Occurs in large projects
|
||||
|
||||
**Solution:**
|
||||
|
||||
The Cloudflare adapter uses Vite, not webpack. If you see this error, check:
|
||||
|
||||
1. **Ensure adapter is properly configured:**
|
||||
```javascript
|
||||
// astro.config.mjs
|
||||
import cloudflare from '@astrojs/cloudflare';
|
||||
export default defineConfig({
|
||||
adapter: cloudflare(),
|
||||
});
|
||||
```
|
||||
|
||||
2. **Check for legacy configuration:**
|
||||
- Remove any `@astrojs/vercel` or other adapter references
|
||||
- Ensure `output` mode is set correctly
|
||||
|
||||
---
|
||||
|
||||
## Runtime Errors
|
||||
|
||||
### 404 Errors on Specific Routes
|
||||
|
||||
**Symptoms:**
|
||||
- Some routes return 404 after deployment
|
||||
- Static assets not found
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check `_routes.json` configuration** (for advanced routing):
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"include": ["/*"],
|
||||
"exclude": ["/api/*"]
|
||||
}
|
||||
```
|
||||
|
||||
2. **Verify build output:**
|
||||
```bash
|
||||
npm run build
|
||||
ls -la dist/
|
||||
```
|
||||
|
||||
3. **Check wrangler.jsonc assets directory:**
|
||||
```jsonc
|
||||
{
|
||||
"assets": {
|
||||
"directory": "./dist",
|
||||
"binding": "ASSETS"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### "env is not defined" or "runtime is not defined"
|
||||
|
||||
**Symptoms:**
|
||||
- Cannot access Cloudflare bindings in Astro code
|
||||
- Runtime errors in server components
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Ensure TypeScript types are configured:**
|
||||
```typescript
|
||||
// src/env.d.ts
|
||||
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
|
||||
|
||||
declare namespace App {
|
||||
interface Locals extends Runtime {}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Access bindings correctly:**
|
||||
```astro
|
||||
---
|
||||
// Correct
|
||||
const env = Astro.locals.runtime.env;
|
||||
const kv = env.MY_KV_NAMESPACE;
|
||||
|
||||
// Incorrect
|
||||
const kv = Astro.locals.env.MY_KV_NAMESPACE;
|
||||
---
|
||||
```
|
||||
|
||||
3. **Verify platformProxy is enabled:**
|
||||
```javascript
|
||||
// astro.config.mjs
|
||||
adapter: cloudflare({
|
||||
platformProxy: {
|
||||
enabled: true,
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Issues
|
||||
|
||||
### "Authentication required" or "Not logged in"
|
||||
|
||||
**Symptoms:**
|
||||
- `wrangler deploy` fails with authentication error
|
||||
- CI/CD deployment fails
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Authenticate locally:**
|
||||
```bash
|
||||
npx wrangler login
|
||||
```
|
||||
|
||||
2. **For CI/CD, create API token:**
|
||||
- Go to Cloudflare Dashboard → My Profile → API Tokens
|
||||
- Create token with "Edit Cloudflare Workers" template
|
||||
- Set as `CLOUDFLARE_API_TOKEN` in GitHub/GitLab secrets
|
||||
|
||||
3. **Set account ID:**
|
||||
```bash
|
||||
# Get account ID
|
||||
npx wrangler whoami
|
||||
|
||||
# Add to wrangler.jsonc or environment
|
||||
export CLOUDFLARE_ACCOUNT_ID=your-account-id
|
||||
```
|
||||
|
||||
### "Project name already exists"
|
||||
|
||||
**Symptoms:**
|
||||
- Deployment fails due to naming conflict
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Change project name in wrangler.jsonc:**
|
||||
```jsonc
|
||||
{
|
||||
"name": "my-app-production"
|
||||
}
|
||||
```
|
||||
|
||||
2. **Or use environments:**
|
||||
```jsonc
|
||||
{
|
||||
"env": {
|
||||
"staging": {
|
||||
"name": "my-app-staging"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Deployment succeeds but site doesn't update
|
||||
|
||||
**Symptoms:**
|
||||
- `wrangler deploy` reports success
|
||||
- Old version still served
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Clear browser cache** (Ctrl+Shift+R or Cmd+Shift+R)
|
||||
|
||||
2. **Verify deployment:**
|
||||
```bash
|
||||
npx wrangler deployments list
|
||||
```
|
||||
|
||||
3. **Check for cached versions:**
|
||||
```bash
|
||||
npx wrangler versions list
|
||||
```
|
||||
|
||||
4. **Force deployment:**
|
||||
```bash
|
||||
npx wrangler deploy --compatibility-date 2025-01-19
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow initial page load
|
||||
|
||||
**Symptoms:**
|
||||
- First Contentful Paint (FCP) > 2 seconds
|
||||
- Large Time to First Byte (TTFB)
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use hybrid or static output:**
|
||||
```javascript
|
||||
// Pre-render static pages where possible
|
||||
export const prerender = true;
|
||||
```
|
||||
|
||||
2. **Enable image optimization:**
|
||||
```javascript
|
||||
adapter: cloudflare({
|
||||
imageService: 'compile',
|
||||
})
|
||||
```
|
||||
|
||||
3. **Cache at edge:**
|
||||
```javascript
|
||||
export async function getStaticPaths() {
|
||||
return [{
|
||||
params: { id: '1' },
|
||||
props: { data: await fetchData() },
|
||||
}];
|
||||
}
|
||||
```
|
||||
|
||||
### High cold start latency
|
||||
|
||||
**Symptoms:**
|
||||
- First request after inactivity is slow
|
||||
- Subsequent requests are fast
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use mode: 'directory'** for better caching:
|
||||
```javascript
|
||||
adapter: cloudflare({
|
||||
mode: 'directory',
|
||||
})
|
||||
```
|
||||
|
||||
2. **Keep bundle size small** - avoid heavy dependencies
|
||||
|
||||
3. **Use Cloudflare KV** for frequently accessed data:
|
||||
```javascript
|
||||
const cached = await env.KV.get('key');
|
||||
if (!cached) {
|
||||
const data = await fetch();
|
||||
await env.KV.put('key', data, { expirationTtl: 3600 });
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Server Issues
|
||||
|
||||
### Styling not applied in dev mode (Astro 6 Beta)
|
||||
|
||||
**Symptoms:**
|
||||
- CSS not loading in `astro dev`
|
||||
- Works in production but not locally
|
||||
|
||||
**Status:** Known bug in Astro 6 beta
|
||||
|
||||
**Workarounds:**
|
||||
|
||||
1. **Use production build locally:**
|
||||
```bash
|
||||
npm run build
|
||||
npx wrangler dev --local
|
||||
```
|
||||
|
||||
2. **Check GitHub issue for updates:**
|
||||
- [Astro Issue #15194](https://github.com/withastro/astro/issues/15194)
|
||||
|
||||
### Cannot test bindings locally
|
||||
|
||||
**Symptoms:**
|
||||
- `Astro.locals.runtime.env` is undefined locally
|
||||
- Cloudflare bindings don't work in dev
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Ensure platformProxy is enabled:**
|
||||
```javascript
|
||||
adapter: cloudflare({
|
||||
platformProxy: {
|
||||
enabled: true,
|
||||
configPath: './wrangler.jsonc',
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
2. **Create .dev.vars for local secrets:**
|
||||
```bash
|
||||
API_KEY=local_key
|
||||
DATABASE_URL=postgresql://localhost:5432/db
|
||||
```
|
||||
|
||||
3. **Use remote development:**
|
||||
```bash
|
||||
npx wrangler dev --remote
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If issues persist:
|
||||
|
||||
1. **Check official documentation:**
|
||||
- [Astro Cloudflare Guide](https://docs.astro.build/en/guides/deploy/cloudflare/)
|
||||
- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
|
||||
|
||||
2. **Search existing issues:**
|
||||
- [Astro GitHub Issues](https://github.com/withastro/astro/issues)
|
||||
- [Cloudflare Workers Discussions](https://github.com/cloudflare/workers-sdk/discussions)
|
||||
|
||||
3. **Join community:**
|
||||
- [Astro Discord](https://astro.build/chat)
|
||||
- [Cloudflare Discord](https://discord.gg/cloudflaredev)
|
||||
@@ -0,0 +1,329 @@
|
||||
# Upgrade Guide
|
||||
|
||||
Migrating existing Astro projects to deploy on Cloudflare Workers.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [From Astro 5 to Astro 6](#from-astro-5-to-astro-6)
|
||||
2. [From Other Platforms to Cloudflare](#from-other-platforms-to-cloudflare)
|
||||
3. [Adapter Migration](#adapter-migration)
|
||||
4. [Breaking Changes](#breaking-changes)
|
||||
|
||||
---
|
||||
|
||||
## From Astro 5 to Astro 6
|
||||
|
||||
### Prerequisites Check
|
||||
|
||||
Astro 6 requires:
|
||||
|
||||
| Requirement | Minimum Version | Check Command |
|
||||
|-------------|-----------------|---------------|
|
||||
| Node.js | 22.12.0+ | `node --version` |
|
||||
| Astro | 6.0.0 | `npm list astro` |
|
||||
| Cloudflare Adapter | 13.0.0+ | `npm list @astrojs/cloudflare` |
|
||||
|
||||
### Upgrade Steps
|
||||
|
||||
1. **Backup current state:**
|
||||
```bash
|
||||
git commit -am "Pre-upgrade commit"
|
||||
```
|
||||
|
||||
2. **Run automated upgrade:**
|
||||
```bash
|
||||
npx @astrojs/upgrade@beta
|
||||
```
|
||||
|
||||
3. **Update adapter:**
|
||||
```bash
|
||||
npm install @astrojs/cloudflare@beta
|
||||
```
|
||||
|
||||
4. **Update Node.js** if needed:
|
||||
```bash
|
||||
# Using nvm
|
||||
nvm install 22
|
||||
nvm use 22
|
||||
|
||||
# Or download from nodejs.org
|
||||
```
|
||||
|
||||
5. **Update CI/CD Node.js version:**
|
||||
```yaml
|
||||
# .github/workflows/deploy.yml
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '22'
|
||||
```
|
||||
|
||||
6. **Test locally:**
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
npm run build
|
||||
npx wrangler dev
|
||||
```
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
#### 1. Vite 7.0
|
||||
|
||||
Vite has been upgraded to Vite 7.0. Check plugin compatibility:
|
||||
|
||||
```bash
|
||||
# Check for outdated plugins
|
||||
npm outdated
|
||||
|
||||
# Update Vite-specific plugins
|
||||
npm update @vitejs/plugin-react
|
||||
```
|
||||
|
||||
#### 2. Hybrid Output Behavior
|
||||
|
||||
The `hybrid` output mode behavior has changed:
|
||||
|
||||
```javascript
|
||||
// Old (Astro 5)
|
||||
export const prerender = true; // Static
|
||||
|
||||
// New (Astro 6) - same, but default behavior changed
|
||||
// Static is now the default for all pages in hybrid mode
|
||||
```
|
||||
|
||||
#### 3. Development Server
|
||||
|
||||
The new dev server runs on the production runtime:
|
||||
|
||||
```javascript
|
||||
// Old: Vite dev server
|
||||
// New: workerd runtime (same as production)
|
||||
|
||||
// Update your code if it relied on Vite-specific behavior
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## From Other Platforms to Cloudflare
|
||||
|
||||
### From Vercel
|
||||
|
||||
**Remove Vercel adapter:**
|
||||
```bash
|
||||
npm uninstall @astrojs/vercel
|
||||
```
|
||||
|
||||
**Install Cloudflare adapter:**
|
||||
```bash
|
||||
npm install @astrojs/cloudflare wrangler --save-dev
|
||||
```
|
||||
|
||||
**Update astro.config.mjs:**
|
||||
```javascript
|
||||
// Before
|
||||
import vercel from '@astrojs/vercel';
|
||||
export default defineConfig({
|
||||
adapter: vercel(),
|
||||
});
|
||||
|
||||
// After
|
||||
import cloudflare from '@astrojs/cloudflare';
|
||||
export default defineConfig({
|
||||
adapter: cloudflare(),
|
||||
});
|
||||
```
|
||||
|
||||
**Update environment variables:**
|
||||
- Vercel: `process.env.VARIABLE`
|
||||
- Cloudflare: `Astro.locals.runtime.env.VARIABLE` or `env.VARIABLE` in endpoints
|
||||
|
||||
### From Netlify
|
||||
|
||||
**Remove Netlify adapter:**
|
||||
```bash
|
||||
npm uninstall @astrojs/netlify
|
||||
```
|
||||
|
||||
**Install Cloudflare adapter:**
|
||||
```bash
|
||||
npm install @astrojs/cloudflare wrangler --save-dev
|
||||
```
|
||||
|
||||
**Update netlify.toml to wrangler.jsonc:**
|
||||
|
||||
```toml
|
||||
# netlify.toml (old)
|
||||
[build]
|
||||
command = "astro build"
|
||||
publish = "dist"
|
||||
|
||||
[functions]
|
||||
node_bundler = "esbuild"
|
||||
```
|
||||
|
||||
```jsonc
|
||||
// wrangler.jsonc (new)
|
||||
{
|
||||
"name": "my-app",
|
||||
"compatibility_date": "2025-01-19",
|
||||
"assets": {
|
||||
"directory": "./dist"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### From Node.js Server
|
||||
|
||||
**Before (Express/Fastify server):**
|
||||
```javascript
|
||||
// server.js
|
||||
import express from 'express';
|
||||
app.use(express.static('dist'));
|
||||
app.listen(3000);
|
||||
```
|
||||
|
||||
**After (Cloudflare Workers):**
|
||||
```javascript
|
||||
// astro.config.mjs
|
||||
export default defineConfig({
|
||||
output: 'server',
|
||||
adapter: cloudflare(),
|
||||
});
|
||||
|
||||
// Deploy
|
||||
npx wrangler deploy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adapter Migration
|
||||
|
||||
### From Astro 4 to 5/6
|
||||
|
||||
**Old adapter syntax:**
|
||||
```javascript
|
||||
// Astro 4
|
||||
adapter: cloudflare({
|
||||
functionPerRoute: true,
|
||||
})
|
||||
```
|
||||
|
||||
**New adapter syntax:**
|
||||
```javascript
|
||||
// Astro 5/6
|
||||
adapter: cloudflare({
|
||||
mode: 'directory', // equivalent to functionPerRoute: true
|
||||
})
|
||||
```
|
||||
|
||||
### Mode Migration Guide
|
||||
|
||||
| Old Option | New Option | Notes |
|
||||
|------------|------------|-------|
|
||||
| `functionPerRoute: true` | `mode: 'directory'` | Recommended |
|
||||
| `functionPerRoute: false` | `mode: 'standalone'` | Single worker |
|
||||
|
||||
---
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
### Removed APIs
|
||||
|
||||
1. **`Astro.locals` changes:**
|
||||
```javascript
|
||||
// Old
|
||||
const env = Astro.locals.env;
|
||||
|
||||
// New
|
||||
const env = Astro.locals.runtime.env;
|
||||
```
|
||||
|
||||
2. **Endpoint API changes:**
|
||||
```javascript
|
||||
// Old
|
||||
export async function get({ locals }) {
|
||||
const { env } = locals;
|
||||
}
|
||||
|
||||
// New
|
||||
export async function GET({ locals }) {
|
||||
const env = locals.runtime.env;
|
||||
}
|
||||
```
|
||||
|
||||
### TypeScript Changes
|
||||
|
||||
```typescript
|
||||
// Old type imports
|
||||
import type { Runtime } from '@astrojs/cloudflare';
|
||||
|
||||
// New type imports
|
||||
import type { Runtime } from '@astrojs/cloudflare/virtual';
|
||||
|
||||
// Or use the adapter export
|
||||
import cloudflare from '@astrojs/cloudflare';
|
||||
type Runtime = typeof cloudflare.Runtime;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rollback Procedures
|
||||
|
||||
### If Deployment Fails
|
||||
|
||||
1. **Keep old version deployed:**
|
||||
```bash
|
||||
npx wrangler versions list
|
||||
npx wrangler versions rollback <version-id>
|
||||
```
|
||||
|
||||
2. **Or rollback git changes:**
|
||||
```bash
|
||||
git revert HEAD
|
||||
npx wrangler deploy
|
||||
```
|
||||
|
||||
### If Build Fails
|
||||
|
||||
1. **Clear cache:**
|
||||
```bash
|
||||
rm -rf node_modules .astro dist
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
2. **Check for incompatible dependencies:**
|
||||
```bash
|
||||
npm ls
|
||||
```
|
||||
|
||||
3. **Temporarily pin to previous version:**
|
||||
```bash
|
||||
npm install astro@5
|
||||
npm install @astrojs/cloudflare@12
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After upgrading, verify:
|
||||
|
||||
- [ ] Local dev server starts without errors
|
||||
- [ ] Build completes successfully
|
||||
- [ ] `wrangler dev` works locally
|
||||
- [ ] Static assets load correctly
|
||||
- [ ] SSR routes render properly
|
||||
- [ ] Environment variables are accessible
|
||||
- [ ] Cloudflare bindings (KV/D1/R2) work
|
||||
- [ ] TypeScript types are correct
|
||||
- [ ] CI/CD pipeline succeeds
|
||||
- [ ] Production deployment works
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- [Astro Discord](https://astro.build/chat)
|
||||
- [Cloudflare Discord](https://discord.gg/cloudflaredev)
|
||||
- [Astro GitHub Issues](https://github.com/withastro/astro/issues)
|
||||
Reference in New Issue
Block a user