Cloudflare VibeSDK Templates

This repository contains the official template catalog used by the Cloudflare VibeSDK project — a modern, open source “vibe coding” starter kit where users can build apps with AI agents. The goal of VibeSDK is to let anyone run their own vibe-coding platform on a Cloudflare Workers paid account with a streamlined, one-click deployment.

These templates are the scaffolding that VibeSDK’s AI agents use to generate full applications for users. They are kept lightweight, production-minded, and type-safe.

Repository Layout

• reference/
  • Base reference templates (e.g., vite-reference/, next-reference/) used as the starting point for all generated templates.
• definitions/
  • One YAML definition per template (e.g., vite-cfagents-runner.yaml).
  • A folder per template containing overlay files that override the base reference (e.g., definitions/vite-cfagents-runner/...).
• build/
  • Output folder for generated templates. Always safe to delete and regenerate.
• originals/
  • Ground truth templates used for verification parity checks. This ensures generated templates match known-good originals.
• tools/
  • Utility scripts, notably tools/generate_templates.py for generation and verification.
• zips/
  • Where packaged zip archives are created for publishing.
• Top-level scripts and files
  • deploy_templates.sh — end-to-end generation, packaging, and upload.
  • create_zip.py — portable zip creation tool.
  • generate_template_catalog.py — creates the aggregated template_catalog.json used by the platform.
  • template_catalog.json — the published catalog of templates and metadata.

Quick Start

Prerequisites:

• Python 3.10+
• Bun (for template viability checks when verifying)
• Cloudflare Wrangler CLI (for R2 uploads during deploy)

Clone and build all templates:

python3 tools/generate_templates.py --clean

Generate the catalog from the build/ directory:

python3 generate_template_catalog.py --output template_catalog.json --pretty

Package all templates and upload them (requires R2 configuration):

# R2_BUCKET_NAME must be set in your environment
bash deploy_templates.sh

Dynamic Template Generation

Templates are generated dynamically from:

• A base reference (e.g., reference/vite-reference/)
• A template definition YAML (e.g., definitions/vite-cfagents-runner.yaml)
• Overlay files that live under definitions/<template-name>/

The generator copies the base reference into build/<template-name>/ and then applies overlays on top. Finally, it applies excludes and optional package.json patches.

Run generation for all templates:

python3 tools/generate_templates.py --clean

Generate a single template:

python3 tools/generate_templates.py -t vite-cfagents-runner

Verification and Viability Checks

Verification compares build/ to originals/ to ensure exact parity.

• Text files are compared with normalized end-of-line handling (LF vs CRLF) and a single trailing newline is ignored to reduce false diffs.
• Build artifacts, lockfiles, and platform caches are ignored by default.

Verify all templates and show diffs:

python3 tools/generate_templates.py --verify --diffs

Verify one template and skip Bun checks:

python3 tools/generate_templates.py -t vite-cfagents-runner --verify --diffs --no-bun

Notes:

• By default, generation does not verify. Add --verify to verify and run Bun install/lint/build checks.
• Add --no-bun to skip Bun during verification.

Packaging and Deployment

We ship templates as zipped archives and a JSON catalog for consumption by VibeSDK.

Create a zip for a single template:

python3 create_zip.py build/vite-cfagents-runner zips/vite-cfagents-runner.zip

create_zip.py excludes common artifacts by default:

• node_modules/, dist/, .next/, coverage output
• .wrangler/, .dev.vars*, .env.*, VCS metadata

Full deploy flow:

# Requires Cloudflare Wrangler and an R2 bucket
# Set: export R2_BUCKET_NAME=<your-bucket-name>

bash deploy_templates.sh

The deploy script:

• Generates templates into build/
• Produces template_catalog.json (scanner default points to ./build)
• Zips each valid template from build/
• Uploads the catalog and all zips to R2

Extending and Creating Templates

To create a new template, follow this overlay-first pattern.

1. Create a definition YAML in definitions/:

# definitions/my-awesome-runner.yaml
name: "my-awesome-runner"
description: "Short description of this template"
base_reference: "vite-reference"  # or "next-reference"

# Optional: shallow package.json patches (deep merge)
package_patches:
  name: "my-awesome-runner"

# Optional: files to exclude from the base reference (glob patterns)
excludes:
  - "src/pages/**"            # remove reference-only pages
  - "src/hooks/use-theme.ts"  # remove reference-only hook

# Optional: only copy a subset of overlay files (rare).
# If omitted, the entire overlay directory is applied.
# template_specific_files:
#   - "src/App.tsx"
#   - "wrangler.jsonc"

2. Add overlay files under definitions/my-awesome-runner/:

• Any file placed here will overwrite the corresponding path in the generated build/ template
• Common overlays:
  • .gitignore, .important_files.json, package.json, wrangler.jsonc, tsconfig.*.json
  • src/* files that differ from the base reference
  • worker/* files for Workers-based templates

3. Generate and verify:

python3 tools/generate_templates.py -t my-awesome-runner --verify --diffs

4. Package and publish:

python3 create_zip.py build/my-awesome-runner zips/my-awesome-runner.zip
# or run the full deploy script if uploading to Cloudflare R2
bash deploy_templates.sh

Definition YAML Reference (current generator)

Supported fields in definitions/*.yaml:

• name (string)
• description (string)
• base_reference (string: vite-reference | next-reference)
• package_patches (object)
  • Shallow/deep-merge patches applied to package.json in the build output.
• excludes (string[])
  • Glob patterns to remove files introduced by the base reference or overlays.
• template_specific_files (string[]; optional)
  • When provided, only these overlay files are applied. Otherwise, the entire overlay directory is applied.

Notes:

• Overlays are applied after copying the base reference, so overlay files always take precedence.
• Keep overlays minimal and focused. If a file matches the original reference, omit it from the overlay.

Template Catalog

The template catalog is a machine-readable JSON file used by VibeSDK. Generate from build/:

python3 generate_template_catalog.py --output template_catalog.json --pretty

This script will scan the generated templates and collate metadata and documentation suitable for display in the VibeSDK UI.

Conventions and Quality

• Keep templates small, type-safe, and production-minded.
• Favor overlays + excludes over per-file lists to stay DRY.
• Maintain parity with originals/ by running verification when templates change.
• Avoid any in TypeScript. Prefer strict typing across templates.
• Keep README content inside each template minimal; the global catalog summarizes key usage and selection guidelines.

Troubleshooting

• Missing template in build/:
  • Ensure the YAML exists in definitions/ and base_reference points to an existing reference.
• Verification failures:
  • Use --diffs to print unified diffs, adjust overlays or excludes accordingly.
• Bun checks failing:
  • Ensure Bun is installed and available in PATH. Use --no-bun to skip temporarily.
• R2 upload errors:
  • Verify Wrangler login, R2_BUCKET_NAME environment variable, and bucket permissions.

About VibeSDK

Cloudflare VibeSDK is an open source platform for building vibe coding experiences. This repository provides the curated, production-minded templates that VibeSDK’s AI agents use to scaffold applications. The full platform can be deployed to a Cloudflare Workers paid account.

If you’re building your own vibe coding platform, these templates provide a solid and extensible foundation.