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,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)
|
||||
Reference in New Issue
Block a user