<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->

# Cloudflare C3 (create-cloudflare) Skill

Expert guidance for C3, Cloudflare's CLI for scaffolding Workers, Pages, and full-stack apps with templates, TypeScript, and instant deployment.

## Installation & Usage

```bash
npm create cloudflare@latest                    # interactive
npm create cloudflare@latest my-app             # named project
npm create cloudflare@latest -- --template=...  # from template
```

Also works with `yarn create cloudflare` and `pnpm create cloudflare@latest`.

## Templates

All templates use: `npm create cloudflare@latest -- --template=<name>`

| Category | Template | Description |
|----------|----------|-------------|
| **Workers** | `worker` | Basic Worker |
| | `worker-typescript` | TypeScript Worker |
| | `hello-world-do-template` | Durable Objects |
| **Full-Stack** | `next-starter-template` | Next.js |
| | `react-router-starter-template` | React Router |
| | `remix-starter-template` | Remix |
| | `astro-blog-starter-template` | Astro |
| **Database & Storage** | `d1-template` | D1 SQLite |
| | `r2-explorer-template` | R2 Explorer |
| | `postgres-hyperdrive-template` | Postgres + Hyperdrive |
| **AI & ML** | `llm-chat-app-template` | Workers AI Chat |
| | `text-to-image-template` | Text-to-Image |
| **Real-time** | `durable-chat-template` | Chat with Durable Objects |
| | `multiplayer-globe-template` | Multiplayer Globe |

Custom templates: `--template=user/repo`, `--template=../local-path`, or `--template=cloudflare/templates/<name>`.

## Interactive vs Non-Interactive

**Interactive** (`npm create cloudflare@latest my-app`) prompts for: application type, framework choice, TypeScript preference, git initialization, deployment option.

**Non-interactive** — pass flags directly:

```bash
npm create cloudflare@latest my-worker \
  --type=web-app \
  --framework=next \
  --ts \
  --git \
  --deploy
```

### Flags

| Flag | Description |
|------|-------------|
| `--type` | `web-app`, `hello-world`, `pre-existing`, `remote-template` |
| `--framework` | `next`, `remix`, `astro`, `react-router`, `solid`, `svelte`, etc. |
| `--template` | GitHub template URL or path |
| `--ts` / `--no-ts` | TypeScript |
| `--git` / `--no-git` | Initialize git repo |
| `--deploy` / `--no-deploy` | Deploy after creation |
| `--open` | Open in browser after deploy |
| `--existing-script` | Path to existing Worker script |

## CI/CD Usage

```yaml
# GitHub Actions
- name: Create Cloudflare Project
  run: |
    npm create cloudflare@latest my-app -- \
      --type=web-app \
      --framework=next \
      --ts \
      --no-git \
      --no-deploy
```

## Project Structure

```text
my-app/
├── src/
│   └── index.ts       # Worker entry point
├── wrangler.toml      # Configuration
├── package.json
├── tsconfig.json
└── README.md
```

## Post-Creation

```bash
cd my-app
npm run dev          # local development
npm run deploy       # deploy
npm run cf-typegen   # type check
```

## wrangler.toml Configuration

C3 generates bindings based on template:

```toml
name = "my-app"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "MY_KV"
id = "..."

[[d1_databases]]
binding = "DB"
database_id = "..."
```

## Common Workflows

### Quick Worker with Deploy

```bash
npm create cloudflare@latest my-worker -- --type=hello-world --ts --deploy
```

### Full-Stack App with D1

```bash
npm create cloudflare@latest my-app -- \
  --template=react-router-starter-template \
  --ts \
  --git
cd my-app
npx wrangler d1 create my-db
# Add to wrangler.toml, then:
npm run deploy
```

### Convert Existing Project

```bash
cd existing-project
npm create cloudflare@latest . -- --existing-script=./dist/index.js
```

## Best Practices

1. Always use `@latest` for the most recent templates
2. Choose TypeScript for type safety
3. Review generated `wrangler.toml` before first deploy
4. Update dependencies post-creation: `npm update`

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `npm create cloudflare` failed | Ensure Node.js 16.13+. Clear cache: `npm cache clean --force`. Try `npx create-cloudflare@latest` |
| Template not found | Verify name/path. Check network. Use full GitHub URL: `https://github.com/user/repo` |
| Deployment fails | Run `wrangler login`. Verify `wrangler.toml`. Check for naming conflicts in dashboard |

## Reference

- [C3 GitHub](https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare)
- [Templates Repository](https://github.com/cloudflare/templates)
- [Workers Docs](https://developers.cloudflare.com/workers/)

---

This skill focuses exclusively on C3 CLI tool usage. For Workers development, see `cloudflare-workers` skill.
