website-enchun-mgr/.opencode/skills/astro-cloudflare-deploy/references/upgrade-guide.md

Upgrade Guide

Migrating existing Astro projects to deploy on Cloudflare Workers.

Table of Contents

1. From Astro 5 to Astro 6
2. From Other Platforms to Cloudflare
3. Adapter Migration
4. 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:

   git commit -am "Pre-upgrade commit"
   

2. Run automated upgrade:

   npx @astrojs/upgrade@beta
   

3. Update adapter:

   npm install @astrojs/cloudflare@beta
   

4. Update Node.js if needed:

   # Using nvm
   nvm install 22
   nvm use 22
   
   # Or download from nodejs.org
   

5. Update CI/CD Node.js version:

   # .github/workflows/deploy.yml
   - uses: actions/setup-node@v4
     with:
       node-version: '22'
   

6. Test locally:

   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:

# 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:

// 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:

// 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:

npm uninstall @astrojs/vercel

Install Cloudflare adapter:

npm install @astrojs/cloudflare wrangler --save-dev

Update astro.config.mjs:

// 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:

npm uninstall @astrojs/netlify

Install Cloudflare adapter:

npm install @astrojs/cloudflare wrangler --save-dev

Update netlify.toml to wrangler.jsonc:

# netlify.toml (old)
[build]
  command = "astro build"
  publish = "dist"

[functions]
  node_bundler = "esbuild"

// wrangler.jsonc (new)
{
  "name": "my-app",
  "compatibility_date": "2025-01-19",
  "assets": {
    "directory": "./dist"
  }
}

From Node.js Server

Before (Express/Fastify server):

// server.js
import express from 'express';
app.use(express.static('dist'));
app.listen(3000);

After (Cloudflare Workers):

// 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:

// Astro 4
adapter: cloudflare({
  functionPerRoute: true,
})

New adapter syntax:

// 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:

   // Old
   const env = Astro.locals.env;
   
   // New
   const env = Astro.locals.runtime.env;
   

2. Endpoint API changes:

   // Old
   export async function get({ locals }) {
     const { env } = locals;
   }
   
   // New
   export async function GET({ locals }) {
     const env = locals.runtime.env;
   }
   

TypeScript Changes

// 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:

   npx wrangler versions list
   npx wrangler versions rollback <version-id>
   

2. Or rollback git changes:

   git revert HEAD
   npx wrangler deploy
   

If Build Fails

1. Clear cache:

   rm -rf node_modules .astro dist
   npm install
   npm run build
   

2. Check for incompatible dependencies:

   npm ls
   

3. Temporarily pin to previous version:

   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
• Cloudflare Discord
• Astro GitHub Issues