mirror of
https://github.com/ksyasuda/dotfiles.git
synced 2026-03-21 18:11:27 -07:00
update skills
This commit is contained in:
111
.agents/skills/cloudflare-deploy/references/c3/README.md
Normal file
111
.agents/skills/cloudflare-deploy/references/c3/README.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# C3 (create-cloudflare)
|
||||
|
||||
Official CLI for scaffolding Cloudflare Workers and Pages projects with templates, TypeScript, and instant deployment.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Interactive (recommended for first-time)
|
||||
npm create cloudflare@latest my-app
|
||||
|
||||
# Worker (API/WebSocket/Cron)
|
||||
npm create cloudflare@latest my-api -- --type=hello-world --ts
|
||||
|
||||
# Pages (static/SSG/full-stack)
|
||||
npm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages
|
||||
```
|
||||
|
||||
## Platform Decision Tree
|
||||
|
||||
```
|
||||
What are you building?
|
||||
|
||||
├─ API / WebSocket / Cron / Email handler
|
||||
│ └─ Workers (default) - no --platform flag needed
|
||||
│ npm create cloudflare@latest my-api -- --type=hello-world
|
||||
|
||||
├─ Static site / SSG / Documentation
|
||||
│ └─ Pages - requires --platform=pages
|
||||
│ npm create cloudflare@latest my-site -- --type=web-app --framework=astro --platform=pages
|
||||
|
||||
├─ Full-stack app (Next.js/Remix/SvelteKit)
|
||||
│ ├─ Need Durable Objects, Queues, or Workers-only features?
|
||||
│ │ └─ Workers (default)
|
||||
│ └─ Otherwise use Pages for git integration and branch previews
|
||||
│ └─ Add --platform=pages
|
||||
|
||||
└─ Convert existing project
|
||||
└─ npm create cloudflare@latest . -- --type=pre-existing --existing-script=./src/worker.ts
|
||||
```
|
||||
|
||||
**Critical:** Pages projects require `--platform=pages` flag. Without it, C3 defaults to Workers.
|
||||
|
||||
## Interactive Flow
|
||||
|
||||
When run without flags, C3 prompts in this order:
|
||||
|
||||
1. **Project name** - Directory to create (defaults to current dir with `.`)
|
||||
2. **Application type** - `hello-world`, `web-app`, `demo`, `pre-existing`, `remote-template`
|
||||
3. **Platform** - `workers` (default) or `pages` (for web apps only)
|
||||
4. **Framework** - If web-app: `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, etc.
|
||||
5. **TypeScript** - `yes` (recommended) or `no`
|
||||
6. **Git** - Initialize repository? `yes` or `no`
|
||||
7. **Deploy** - Deploy now? `yes` or `no` (requires `wrangler login`)
|
||||
|
||||
## Installation Methods
|
||||
|
||||
```bash
|
||||
# NPM
|
||||
npm create cloudflare@latest
|
||||
|
||||
# Yarn
|
||||
yarn create cloudflare
|
||||
|
||||
# PNPM
|
||||
pnpm create cloudflare@latest
|
||||
```
|
||||
|
||||
## In This Reference
|
||||
|
||||
| File | Purpose | Use When |
|
||||
|------|---------|----------|
|
||||
| **api.md** | Complete CLI flag reference | Scripting, CI/CD, advanced usage |
|
||||
| **configuration.md** | Generated files, bindings, types | Understanding output, customization |
|
||||
| **patterns.md** | Workflows, CI/CD, monorepos | Real-world integration |
|
||||
| **gotchas.md** | Troubleshooting failures | Deployment blocked, errors |
|
||||
|
||||
## Reading Order
|
||||
|
||||
| Task | Read |
|
||||
|------|------|
|
||||
| Create first project | README only |
|
||||
| Set up CI/CD | README → api → patterns |
|
||||
| Debug failed deploy | gotchas |
|
||||
| Understand generated files | configuration |
|
||||
| Full CLI reference | api |
|
||||
| Create custom template | patterns → configuration |
|
||||
| Convert existing project | README → patterns |
|
||||
|
||||
## Post-Creation
|
||||
|
||||
```bash
|
||||
cd my-app
|
||||
|
||||
# Local dev with hot reload
|
||||
npm run dev
|
||||
|
||||
# Generate TypeScript types for bindings
|
||||
npm run cf-typegen
|
||||
|
||||
# Deploy to Cloudflare
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- **workers/README.md** - Workers runtime, bindings, APIs
|
||||
- **workers-ai/README.md** - AI/ML models
|
||||
- **pages/README.md** - Pages-specific features
|
||||
- **wrangler/README.md** - Wrangler CLI beyond initial setup
|
||||
- **d1/README.md** - SQLite database
|
||||
- **r2/README.md** - Object storage
|
||||
71
.agents/skills/cloudflare-deploy/references/c3/api.md
Normal file
71
.agents/skills/cloudflare-deploy/references/c3/api.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# C3 CLI Reference
|
||||
|
||||
## Invocation
|
||||
|
||||
```bash
|
||||
npm create cloudflare@latest [name] [-- flags] # NPM requires --
|
||||
yarn create cloudflare [name] [flags]
|
||||
pnpm create cloudflare@latest [name] [-- flags]
|
||||
```
|
||||
|
||||
## Core Flags
|
||||
|
||||
| Flag | Values | Description |
|
||||
|------|--------|-------------|
|
||||
| `--type` | `hello-world`, `web-app`, `demo`, `pre-existing`, `remote-template` | Application type |
|
||||
| `--platform` | `workers` (default), `pages` | Target platform |
|
||||
| `--framework` | `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, `qwik`, `vue`, `angular`, `hono` | Web framework (requires `--type=web-app`) |
|
||||
| `--lang` | `ts`, `js`, `python` | Language (for `--type=hello-world`) |
|
||||
| `--ts` / `--no-ts` | - | TypeScript for web apps |
|
||||
|
||||
## Deployment Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--deploy` / `--no-deploy` | Deploy immediately (prompts interactive, skips in CI) |
|
||||
| `--git` / `--no-git` | Initialize git (default: yes) |
|
||||
| `--open` | Open browser after deploy |
|
||||
|
||||
## Advanced Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--template=user/repo` | GitHub template or local path |
|
||||
| `--existing-script=./src/worker.ts` | Existing script (requires `--type=pre-existing`) |
|
||||
| `--category=ai\|database\|realtime` | Demo filter (requires `--type=demo`) |
|
||||
| `--experimental` | Enable experimental features |
|
||||
| `--wrangler-defaults` | Skip wrangler prompts |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
CLOUDFLARE_API_TOKEN=xxx # For deployment
|
||||
CLOUDFLARE_ACCOUNT_ID=xxx # Account ID
|
||||
CF_TELEMETRY_DISABLED=1 # Disable telemetry
|
||||
```
|
||||
|
||||
## Exit Codes
|
||||
|
||||
`0` success, `1` user abort, `2` error
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# TypeScript Worker
|
||||
npm create cloudflare@latest my-api -- --type=hello-world --lang=ts --no-deploy
|
||||
|
||||
# Next.js on Pages
|
||||
npm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts
|
||||
|
||||
# Astro blog
|
||||
npm create cloudflare@latest my-blog -- --type=web-app --framework=astro --ts --deploy
|
||||
|
||||
# CI: non-interactive
|
||||
npm create cloudflare@latest my-app -- --type=web-app --framework=next --ts --no-git --no-deploy
|
||||
|
||||
# GitHub template
|
||||
npm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi
|
||||
|
||||
# Convert existing project
|
||||
npm create cloudflare@latest . -- --type=pre-existing --existing-script=./build/worker.js
|
||||
```
|
||||
@@ -0,0 +1,81 @@
|
||||
# C3 Generated Configuration
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
my-app/
|
||||
├── src/index.ts # Worker entry point
|
||||
├── wrangler.jsonc # Cloudflare config
|
||||
├── package.json # Scripts
|
||||
├── tsconfig.json
|
||||
└── .gitignore
|
||||
```
|
||||
|
||||
## wrangler.jsonc
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/cloudflare/workers-sdk/main/packages/wrangler/config-schema.json",
|
||||
"name": "my-app",
|
||||
"main": "src/index.ts",
|
||||
"compatibility_date": "2026-01-27"
|
||||
}
|
||||
```
|
||||
|
||||
## Binding Placeholders
|
||||
|
||||
C3 generates **placeholder IDs** that must be replaced before deploy:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"kv_namespaces": [{ "binding": "MY_KV", "id": "placeholder_kv_id" }],
|
||||
"d1_databases": [{ "binding": "DB", "database_id": "00000000-..." }]
|
||||
}
|
||||
```
|
||||
|
||||
**Replace with real IDs:**
|
||||
```bash
|
||||
npx wrangler kv namespace create MY_KV # Returns real ID
|
||||
npx wrangler d1 create my-database # Returns real database_id
|
||||
```
|
||||
|
||||
**Deployment error if not replaced:**
|
||||
```
|
||||
Error: Invalid KV namespace ID "placeholder_kv_id"
|
||||
```
|
||||
|
||||
## Scripts
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "wrangler dev",
|
||||
"deploy": "wrangler deploy",
|
||||
"cf-typegen": "wrangler types"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Type Generation
|
||||
|
||||
Run after adding bindings:
|
||||
```bash
|
||||
npm run cf-typegen
|
||||
```
|
||||
|
||||
Generates `.wrangler/types/runtime.d.ts`:
|
||||
```typescript
|
||||
interface Env {
|
||||
MY_KV: KVNamespace;
|
||||
DB: D1Database;
|
||||
}
|
||||
```
|
||||
|
||||
## Post-Creation Checklist
|
||||
|
||||
1. Review `wrangler.jsonc` - check name, compatibility_date
|
||||
2. Replace placeholder binding IDs with real resource IDs
|
||||
3. Run `npm run cf-typegen`
|
||||
4. Test: `npm run dev`
|
||||
5. Deploy: `npm run deploy`
|
||||
6. Add secrets: `npx wrangler secret put SECRET_NAME`
|
||||
92
.agents/skills/cloudflare-deploy/references/c3/gotchas.md
Normal file
92
.agents/skills/cloudflare-deploy/references/c3/gotchas.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# C3 Troubleshooting
|
||||
|
||||
## Deployment Issues
|
||||
|
||||
### Placeholder IDs
|
||||
|
||||
**Error:** "Invalid namespace ID"
|
||||
**Fix:** Replace placeholders in wrangler.jsonc with real IDs:
|
||||
```bash
|
||||
npx wrangler kv namespace create MY_KV # Get real ID
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
**Error:** "Not authenticated"
|
||||
**Fix:** `npx wrangler login` or set `CLOUDFLARE_API_TOKEN`
|
||||
|
||||
### Name Conflict
|
||||
|
||||
**Error:** "Worker already exists"
|
||||
**Fix:** Change `name` in wrangler.jsonc
|
||||
|
||||
## Platform Selection
|
||||
|
||||
| Need | Platform |
|
||||
|------|----------|
|
||||
| Git integration, branch previews | `--platform=pages` |
|
||||
| Durable Objects, D1, Queues | Workers (default) |
|
||||
|
||||
Wrong platform? Recreate with correct `--platform` flag.
|
||||
|
||||
## TypeScript Issues
|
||||
|
||||
**"Cannot find name 'KVNamespace'"**
|
||||
```bash
|
||||
npm run cf-typegen # Regenerate types
|
||||
# Restart TS server in editor
|
||||
```
|
||||
|
||||
**Missing types after config change:** Re-run `npm run cf-typegen`
|
||||
|
||||
## Package Manager
|
||||
|
||||
**Multiple lockfiles causing issues:**
|
||||
```bash
|
||||
rm pnpm-lock.yaml # If using npm
|
||||
rm package-lock.json # If using pnpm
|
||||
```
|
||||
|
||||
## CI/CD
|
||||
|
||||
**CI hangs on prompts:**
|
||||
```bash
|
||||
npm create cloudflare@latest my-app -- \
|
||||
--type=hello-world --lang=ts --no-git --no-deploy
|
||||
```
|
||||
|
||||
**Auth in CI:**
|
||||
```yaml
|
||||
env:
|
||||
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
||||
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
|
||||
```
|
||||
|
||||
## Framework-Specific
|
||||
|
||||
| Framework | Issue | Fix |
|
||||
|-----------|-------|-----|
|
||||
| Next.js | create-next-app failed | `npm cache clean --force`, retry |
|
||||
| Astro | Adapter missing | Install `@astrojs/cloudflare` |
|
||||
| Remix | Module errors | Update `@remix-run/cloudflare*` |
|
||||
|
||||
## Compatibility Date
|
||||
|
||||
**"Feature X requires compatibility_date >= ..."**
|
||||
**Fix:** Update `compatibility_date` in wrangler.jsonc to today's date
|
||||
|
||||
## Node.js Version
|
||||
|
||||
**"Node.js version not supported"**
|
||||
**Fix:** Install Node.js 18+ (`nvm install 20`)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| Invalid namespace ID | Placeholder binding | Create resource, update config |
|
||||
| Not authenticated | No login | `npx wrangler login` |
|
||||
| Cannot find KVNamespace | Missing types | `npm run cf-typegen` |
|
||||
| Worker already exists | Name conflict | Change `name` |
|
||||
| CI hangs | Missing flags | Add --type, --lang, --no-deploy |
|
||||
| Template not found | Bad name | Check cloudflare/templates |
|
||||
82
.agents/skills/cloudflare-deploy/references/c3/patterns.md
Normal file
82
.agents/skills/cloudflare-deploy/references/c3/patterns.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# C3 Usage Patterns
|
||||
|
||||
## Quick Workflows
|
||||
|
||||
```bash
|
||||
# TypeScript API Worker
|
||||
npm create cloudflare@latest my-api -- --type=hello-world --lang=ts --deploy
|
||||
|
||||
# Next.js on Pages
|
||||
npm create cloudflare@latest my-app -- --type=web-app --framework=next --platform=pages --ts --deploy
|
||||
|
||||
# Astro static site
|
||||
npm create cloudflare@latest my-blog -- --type=web-app --framework=astro --platform=pages --ts
|
||||
```
|
||||
|
||||
## CI/CD (GitHub Actions)
|
||||
|
||||
```yaml
|
||||
- name: Deploy
|
||||
run: npm run deploy
|
||||
env:
|
||||
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
|
||||
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
|
||||
```
|
||||
|
||||
**Non-interactive requires:**
|
||||
```bash
|
||||
--type=<value> # Required
|
||||
--no-git # Recommended (CI already in git)
|
||||
--no-deploy # Deploy separately with secrets
|
||||
--framework=<value> # For web-app
|
||||
--ts / --no-ts # Required
|
||||
```
|
||||
|
||||
## Monorepo
|
||||
|
||||
C3 detects workspace config (`package.json` workspaces or `pnpm-workspace.yaml`).
|
||||
|
||||
```bash
|
||||
cd packages/
|
||||
npm create cloudflare@latest my-worker -- --type=hello-world --lang=ts --no-deploy
|
||||
```
|
||||
|
||||
## Custom Templates
|
||||
|
||||
```bash
|
||||
# GitHub repo
|
||||
npm create cloudflare@latest -- --template=username/repo
|
||||
npm create cloudflare@latest -- --template=cloudflare/templates/worker-openapi
|
||||
|
||||
# Local path
|
||||
npm create cloudflare@latest my-app -- --template=../my-template
|
||||
```
|
||||
|
||||
**Template requires `c3.config.json`:**
|
||||
```json
|
||||
{
|
||||
"name": "my-template",
|
||||
"category": "hello-world",
|
||||
"copies": [{ "path": "src/" }, { "path": "wrangler.jsonc" }],
|
||||
"transforms": [{ "path": "package.json", "jsonc": { "name": "{{projectName}}" }}]
|
||||
}
|
||||
```
|
||||
|
||||
## Existing Projects
|
||||
|
||||
```bash
|
||||
# Add Cloudflare to existing Worker
|
||||
npm create cloudflare@latest . -- --type=pre-existing --existing-script=./dist/index.js
|
||||
|
||||
# Add to existing framework app
|
||||
npm create cloudflare@latest . -- --type=web-app --framework=next --platform=pages --ts
|
||||
```
|
||||
|
||||
## Post-Creation Checklist
|
||||
|
||||
1. Review `wrangler.jsonc` - set `compatibility_date`, verify `name`
|
||||
2. Create bindings: `wrangler kv namespace create`, `wrangler d1 create`, `wrangler r2 bucket create`
|
||||
3. Generate types: `npm run cf-typegen`
|
||||
4. Test: `npm run dev`
|
||||
5. Deploy: `npm run deploy`
|
||||
6. Set secrets: `wrangler secret put SECRET_NAME`
|
||||
Reference in New Issue
Block a user