Skip to content

Commit cdc18d7

Browse files
henkisdabroclaude
henkisdabro
and
claude
committed
feat: add /setup-cloudflare onboarding command and improve CI/CD pipeline
- Add new /setup-cloudflare slash command for guided Cloudflare credentials setup - Enhance GitHub Actions workflow with Node.js setup, lint, test, and build steps - Update landing page with new onboarding flow and command documentation - Fix binding syntax in CLAUDE.md and AGENTS.md (TOML to JSON format) - Update all documentation to reflect new two-step onboarding process 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 99fdd76 commit cdc18d7

8 files changed

Lines changed: 512 additions & 268 deletions

File tree

‎.claude/README.md‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,22 @@ Interactive setup assistant that guides you through:
2121
/new-project
2222
```
2323

24+
### `/setup-cloudflare`
25+
26+
**Use this when:** You need help setting up Cloudflare credentials and GitHub secrets for deployment.
27+
28+
Step-by-step guide for:
29+
- Finding your Cloudflare Account ID
30+
- Creating an API token with correct permissions
31+
- Adding secrets to GitHub Actions
32+
- Local Wrangler authentication
33+
- Verifying your setup works
34+
35+
**Usage:**
36+
```
37+
/setup-cloudflare
38+
```
39+
2440
### `/generate-prp <feature-description>`
2541

2642
**Use this when:** You want to create a comprehensive Product Requirement Plan for a new feature.
@@ -122,6 +138,7 @@ Configure additional bindings:
122138
.claude/
123139
├── commands/ # Slash command definitions
124140
│ ├── new-project.md
141+
│ ├── setup-cloudflare.md
125142
│ ├── generate-prp.md
126143
│ ├── execute-prp.md
127144
│ ├── add-ai-feature.md
@@ -143,11 +160,12 @@ PRPs/ # Product Requirement Plans
143160

144161
## Workflow
145162

146-
1. **Initial Setup:** Run `/new-project` after forking this template
147-
2. **Add Features:** Use `/add-ai-feature`, `/setup-database`, or `/setup-sandbox`
148-
3. **Plan Complex Features:** Use `/generate-prp` to create implementation plans
149-
4. **Build Features:** Use `/execute-prp` to implement the plans
150-
5. **Add Bindings:** Use `/add-binding` for additional Cloudflare services
163+
1. **Cloudflare Setup:** Run `/setup-cloudflare` to configure credentials and secrets
164+
2. **Project Setup:** Run `/new-project` to configure project name and metadata
165+
3. **Add Features:** Use `/add-ai-feature`, `/setup-database`, or `/setup-sandbox`
166+
4. **Plan Complex Features:** Use `/generate-prp` to create implementation plans
167+
5. **Build Features:** Use `/execute-prp` to implement the plans
168+
6. **Add Bindings:** Use `/add-binding` for additional Cloudflare services
151169

152170
## Templates
153171

‎.claude/commands/setup-cloudflare.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Cloudflare Account Setup
2+
3+
This command helps you configure your Cloudflare account credentials and GitHub secrets for deployment. Run this before your first deployment.
4+
5+
## Prerequisites Check
6+
7+
Before we begin, let me verify your environment is ready:
8+
9+
1. **Check Node.js version** - Run `node --version` (should be v22+)
10+
2. **Check npm is available** - Run `npm --version`
11+
3. **Verify dependencies** - Run `npm install` if `node_modules` doesn't exist
12+
4. **Test the build** - Run `npm run build` to ensure compilation works
13+
14+
## Step 1: Get Your Cloudflare Account ID
15+
16+
Your Account ID uniquely identifies your Cloudflare account.
17+
18+
**How to find it:**
19+
20+
1. Log in to [Cloudflare Dashboard](https://dash.cloudflare.com)
21+
2. In the left sidebar, click **Workers & Pages**
22+
3. Look at the **right sidebar** - you'll see "Account details"
23+
4. Copy the **Account ID** (a 32-character hexadecimal string)
24+
25+
**Example:** `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6`
26+
27+
**Store it safely** - you'll need this for GitHub Secrets.
28+
29+
## Step 2: Create a Cloudflare API Token
30+
31+
The API token allows GitHub Actions (or Wrangler) to deploy to your account.
32+
33+
**How to create it:**
34+
35+
1. Go to [Cloudflare API Tokens](https://dash.cloudflare.com/profile/api-tokens)
36+
2. Click **Create Token**
37+
3. Find **"Edit Cloudflare Workers"** template
38+
4. Click **Use Template**
39+
40+
**Token permissions (pre-filled by template):**
41+
42+
| Permission | Access |
43+
|------------|--------|
44+
| Account - Workers Scripts | Edit |
45+
| Account - Workers KV Storage | Edit |
46+
| Account - Workers R2 Storage | Edit |
47+
| Account - Workers Tail | Read |
48+
| Account - D1 | Edit |
49+
| Zone - Workers Routes | Edit |
50+
51+
5. Under **Account Resources**, select your account (or "All accounts" if you have multiple)
52+
6. Under **Zone Resources**, select "All zones" (or specific zones if preferred)
53+
7. Click **Continue to summary**
54+
8. Click **Create Token**
55+
9. **IMPORTANT:** Copy the token immediately - it's only shown once!
56+
57+
**Example token format:** `abcDEF123ghiJKL456mno...` (long string)
58+
59+
## Step 3: Add Secrets to GitHub
60+
61+
GitHub Secrets store your credentials securely and make them available to GitHub Actions.
62+
63+
**How to add them:**
64+
65+
1. Go to your GitHub repository
66+
2. Click **Settings** (tab at the top)
67+
3. In the left sidebar, click **Secrets and variables** → **Actions**
68+
4. Click **New repository secret**
69+
70+
**Add these two secrets:**
71+
72+
| Secret Name | Value |
73+
|-------------|-------|
74+
| `CLOUDFLARE_ACCOUNT_ID` | Your 32-character Account ID |
75+
| `CLOUDFLARE_API_TOKEN` | Your API token from Step 2 |
76+
77+
**Verification:**
78+
- After adding, you should see both secrets listed (values are hidden)
79+
- The names must match exactly (case-sensitive)
80+
81+
## Step 4: Local Development Setup (Optional)
82+
83+
For local Wrangler commands (like `wrangler secret put`), authenticate:
84+
85+
```bash
86+
# Interactive browser login
87+
npx wrangler login
88+
89+
# Verify authentication
90+
npx wrangler whoami
91+
```
92+
93+
This creates a local auth token so you can run Wrangler commands directly.
94+
95+
## Step 5: Verify Setup
96+
97+
Let's test everything works:
98+
99+
1. **Local development:**
100+
```bash
101+
npm run dev
102+
# Should start at http://localhost:5173
103+
```
104+
105+
2. **Manual deployment test:**
106+
```bash
107+
npm run deploy
108+
# Should deploy to *.workers.dev
109+
```
110+
111+
3. **GitHub Actions test:**
112+
- Make a small change (e.g., add a comment to a file)
113+
- Commit and push to `main` branch
114+
- Go to your repo → Actions tab
115+
- Watch the deployment workflow run
116+
- Check for green checkmark (success)
117+
118+
## Troubleshooting
119+
120+
### "Authentication error" in GitHub Actions
121+
122+
- Verify `CLOUDFLARE_API_TOKEN` is correct (re-create if unsure)
123+
- Ensure the token hasn't expired
124+
- Check token has "Edit Cloudflare Workers" permissions
125+
126+
### "Account not found" error
127+
128+
- Verify `CLOUDFLARE_ACCOUNT_ID` is correct
129+
- Ensure your token has access to that account
130+
131+
### "Worker not found" when using custom domain
132+
133+
- The Worker must be deployed before adding a custom domain
134+
- Ensure the name in `wrangler.jsonc` matches your Worker name
135+
136+
### Local `wrangler` commands fail
137+
138+
- Run `npx wrangler login` to re-authenticate
139+
- Ensure you're in the project directory
140+
- Check `wrangler.jsonc` exists and is valid JSON
141+
142+
## Quick Reference
143+
144+
| Item | Location |
145+
|------|----------|
146+
| Account ID | Dashboard → Workers & Pages → Right sidebar |
147+
| API Tokens | Dashboard → Profile → API Tokens |
148+
| GitHub Secrets | Repo → Settings → Secrets → Actions |
149+
| Wrangler Login | `npx wrangler login` |
150+
| Deploy Command | `npm run deploy` |
151+
152+
## Next Steps
153+
154+
Once setup is complete:
155+
156+
1. Run `/new-project` to configure your project name and metadata
157+
2. Start building your application!
158+
3. Use `/add-ai-feature`, `/setup-database`, or other commands as needed
159+
160+
## Links
161+
162+
- [Cloudflare Dashboard](https://dash.cloudflare.com)
163+
- [API Tokens](https://dash.cloudflare.com/profile/api-tokens)
164+
- [Workers Documentation](https://developers.cloudflare.com/workers/)
165+
- [Wrangler Configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)

‎.github/workflows/deploy.yml‎

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,42 @@ on:
1010
jobs:
1111
deploy:
1212
runs-on: ubuntu-latest
13-
name: Deploy
13+
name: Build and Deploy
1414
steps:
1515
- name: Checkout
1616
uses: actions/checkout@v4
1717

18+
# Use Node.js 22 to match local development and Cloudflare's default build image
19+
- name: Setup Node.js
20+
uses: actions/setup-node@v4
21+
with:
22+
node-version: '22'
23+
cache: 'npm'
24+
25+
- name: Install dependencies
26+
run: npm ci
27+
28+
- name: Run linter
29+
run: npm run lint
30+
31+
- name: Run tests
32+
run: npm run test
33+
34+
- name: Build application
35+
run: npm run build
36+
1837
- name: Deploy to Cloudflare Workers
38+
id: deploy
1939
# Use the official Cloudflare Wrangler action
2040
uses: cloudflare/wrangler-action@v3
2141
with:
2242
# These secrets must be configured in the repository settings of the new project
2343
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
2444
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
45+
# Skip the build step since we've already built above
46+
command: deploy --minify
47+
48+
- name: Show deployment URL
49+
env:
50+
DEPLOY_URL: ${{ steps.deploy.outputs.deployment-url }}
51+
run: echo "Deployed to ${DEPLOY_URL}"

‎AGENTS.md‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ For complete spelling/punctuation guidelines, see **[docs/CONVENTIONS.md](docs/C
7272
`.claude/settings.json` includes pre-approved permissions for common operations (git, file editing, testing).
7373

7474
### Slash Commands (Claude Code)
75+
- `/setup-cloudflare` - Configure Cloudflare credentials and GitHub secrets (run first!)
7576
- `/new-project` - Complete project setup with domain configuration
7677
- `/add-ai-feature` - Add AI capabilities (Claude API, Workers AI, AI Gateway)
7778
- `/setup-database` - Configure D1 or KV storage
@@ -88,19 +89,21 @@ See `.claude/README.md` for complete slash command documentation.
8889
Use for: relational data, structured queries, transactions, ACID guarantees.
8990

9091
```jsonc
91-
[[d1_databases]]
92-
binding = "DB"
93-
database_name = "my-database"
94-
database_id = "uuid-from-wrangler-create"
92+
"d1_databases": [{
93+
"binding": "DB",
94+
"database_name": "my-database",
95+
"database_id": "uuid-from-wrangler-create"
96+
}]
9597
```
9698

9799
### KV (Key-Value)
98100
Use for: caching, sessions, config, high-read/low-write workloads.
99101

100102
```jsonc
101-
[[kv_namespaces]]
102-
binding = "KV"
103-
id = "namespace-id-from-wrangler-create"
103+
"kv_namespaces": [{
104+
"binding": "KV",
105+
"id": "namespace-id-from-wrangler-create"
106+
}]
104107
```
105108

106109
### Sandbox SDK (Beta)
@@ -146,8 +149,13 @@ See **[AI_INTEGRATION.md](AI_INTEGRATION.md)** for detailed integration guides.
146149

147150
Automated on push to `main`:
148151
1. GitHub Actions workflow triggers
149-
2. Builds Vite app and Worker
150-
3. Deploys to Cloudflare's global edge network
152+
2. Installs dependencies (`npm ci`)
153+
3. Runs linter (`npm run lint`)
154+
4. Runs tests (`npm run test`)
155+
5. Builds Vite app and Worker (`npm run build`)
156+
6. Deploys to Cloudflare's global edge network
157+
158+
Run `/setup-cloudflare` (Claude Code) to configure the required GitHub secrets.
151159

152160
## Important Notes
153161

‎CLAUDE.md‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ For complete spelling/punctuation guidelines, see **[docs/CONVENTIONS.md](docs/C
7272
`.claude/settings.json` includes pre-approved permissions for common operations (git, file editing, testing).
7373

7474
### Slash Commands
75+
- `/setup-cloudflare` - Configure Cloudflare credentials and GitHub secrets (run first!)
7576
- `/new-project` - Complete project setup with domain configuration
7677
- `/add-ai-feature` - Add AI capabilities (Claude API, Workers AI, AI Gateway)
7778
- `/setup-database` - Configure D1 or KV storage
@@ -88,19 +89,21 @@ See `.claude/README.md` for complete slash command documentation.
8889
Use for: relational data, structured queries, transactions, ACID guarantees.
8990

9091
```jsonc
91-
[[d1_databases]]
92-
binding = "DB"
93-
database_name = "my-database"
94-
database_id = "uuid-from-wrangler-create"
92+
"d1_databases": [{
93+
"binding": "DB",
94+
"database_name": "my-database",
95+
"database_id": "uuid-from-wrangler-create"
96+
}]
9597
```
9698

9799
### KV (Key-Value)
98100
Use for: caching, sessions, config, high-read/low-write workloads.
99101

100102
```jsonc
101-
[[kv_namespaces]]
102-
binding = "KV"
103-
id = "namespace-id-from-wrangler-create"
103+
"kv_namespaces": [{
104+
"binding": "KV",
105+
"id": "namespace-id-from-wrangler-create"
106+
}]
104107
```
105108

106109
### Sandbox SDK (Beta)
@@ -146,8 +149,13 @@ Use `/add-ai-feature` for guided setup. See **[AI_INTEGRATION.md](AI_INTEGRATION
146149

147150
Automated on push to `main`:
148151
1. GitHub Actions workflow triggers
149-
2. Builds Vite app and Worker
150-
3. Deploys to Cloudflare's global edge network
152+
2. Installs dependencies (`npm ci`)
153+
3. Runs linter (`npm run lint`)
154+
4. Runs tests (`npm run test`)
155+
5. Builds Vite app and Worker (`npm run build`)
156+
6. Deploys to Cloudflare's global edge network
157+
158+
Run `/setup-cloudflare` to configure the required GitHub secrets.
151159

152160
## Important Notes
153161

0 commit comments

Comments
 (0)