@codefe/create-codefe-app

CLI tool for developers to scaffold, develop, and deploy CodeFE products.

Two entry points, shared pipeline/runtime: cca is for developers working locally. build.codefe.cn drives the same pipeline definitions through codefe-api + codefe-worker, and the worker executes runtime APIs directly.

Installation

# One-off use
npx @codefe/create-codefe-app init my-tool

# Global install (recommended)
npm install -g @codefe/create-codefe-app
cca init my-tool

Complete Development Workflow

1 — Initialize

cca init <subdomain>
# e.g. cca init color-picker

Runs 8 steps in sequence. The project directory is created as <cwd>/<subdomain>/.

| Step | What it does | |------|-------------| | check | Verifies Node, pnpm, git, SSH connectivity, and required config fields | | create-repo | Creates a GitHub repo from the template (tool or saas) under github.owner | | clone-repo | Clones the repo into <cwd>/<subdomain>/ | | add-dns | Adds a DNS A record <subdomain>.codefe.cn → deploy.host via TencentCloud API | | setup-umami | Creates an Umami analytics site and writes the tracking ID into .env.production | | gen-cca | Writes codefe.config.json in the project root with all product metadata | | update-conf | Updates src/config/site.ts, locales/en.json, locales/zh.json, public/manifest.webmanifest; writes .env.development and .env.production | | install | Runs pnpm install |

cca init my-tool -y                        # Skip all confirmation prompts
cca init my-tool --type saas               # Use saas-starter template
cca init my-tool --prd docs/PRD.md        # Pre-fill metadata from PRD file
cca init my-tool --prd-clipboard          # Read PRD from clipboard (macOS)

--prd parses a markdown PRD file and auto-fills project names, slogans, and descriptions. If the PRD contains a subdomain field, <subdomain> argument can be omitted.

After init completes the project is ready for local development. Nothing has been deployed yet.

2 — Develop

No cca command needed — open the project directory and use Claude Code or any editor directly:

cd <subdomain>
claude          # AI-assisted development with Claude Code
pnpm dev        # Local dev server at http://localhost:3000

Key files:

• codefe.config.json — product metadata
• docs/PRD.md — product requirements (write this first)
• src/app/[locale]/(marketing)/page.tsx — homepage (contains both landing and tool UI)
• src/app/[locale]/(marketing)/client.tsx — client components for the homepage
• scripts/db/index.sql — database schema (if needed)

3 — Deploy

cca deploy          # Interactive confirmation
cca deploy -y       # Skip prompts
cca deploy --skip-ssl   # Force iterative mode (skip nginx/SSL)

cca deploy auto-detects first deploy vs iterative update based on whether the product is already active in the API.

First deploy — 6 steps:

| Step | What it does | |------|-------------| | build | pnpm build → static export to out/ | | init-db | Reads local scripts/db/index.sql; dev executes it locally, prod streams the same local SQL to the production database via SSH | | upload | rsync out/ → deploy.host:deploy.targetDir/<subdomain>/ via SSH | | add-ssl | Uploads bundled setup-new-site.sh to server via SCP, then executes it via SSH to configure nginx + certbot SSL | | smoke | HTTP GET https://<subdomain>.codefe.cn — asserts 200 OK | | push | git add -A && git commit && git push origin main |

Iterative deploy — 5 steps (no nginx/SSL):

| Step | What it does | |------|-------------| | build | Same as above | | init-db | Skipped automatically if no changes to scripts/db/index.sql since last commit | | upload | Same as above | | smoke | Same as above | | push | Same as above |

On success, cca deploy calls the codefe-api to set product_status = 'active'. If the product record doesn't exist yet it creates it first.

Commands Reference

cca init <subdomain>

Scaffold a new product. See workflow above.

cca deploy

Build and deploy. See workflow above.

cca run <step-key>

Execute a single step in the current project directory:

cca run check
cca run build
cca run upload --prod
cca run init-db --prod
cca run push

All available step keys:

| Key | Pipeline | |-----|---------| | check | init | | create-repo | init | | clone-repo | init | | add-dns | init | | setup-umami | init | | gen-cca | init | | update-conf | init | | install | init | | build | deploy | | init-db | deploy | | upload | deploy | | add-ssl | first deploy | | smoke | deploy | | push | deploy | | pull | worker redeploy only | | gen-redev | worker redeploy only | | ai-dev | worker init/redeploy only | | gen-logo | deploy |

teardown is a standalone command (cca teardown <subdomain>), not a pipeline step.

cca teardown <subdomain>

Remove runtime resources for a product:

• Removes nginx config from /etc/nginx/sites-available|enabled/
• Deletes Let's Encrypt SSL certificate via certbot
• Removes /var/www/<subdomain> static files
• Removes the source directory from the execution target implied by the command mode
• Removes product-related PostgreSQL tables and matching schema_migrations records for the selected environment

cca teardown my-tool        # Prompts for confirmation (default: no)
cca teardown my-tool --yes  # Skip confirmation
cca teardown my-tool --prod --yes  # Remove prod server files + prod DB tables

Rules:

• default env (dev)
  • cleans local development code and local development database tables
• --prod
  • cleans production server files and production database tables

Shared resources such as GitHub repos, DNS, and Umami are treated as shared infrastructure and are not split by env here.

cca setup

Interactive wizard to create or update ~/.config/cca/config.json.

cca prd

Generate a prompt template for writing a product PRD.

cca ls

cca ls          # Table output
cca ls --json   # JSON output

Configuration

Global config — ~/.config/cca/config.json

Created once per machine via cca setup. Stores all infrastructure credentials.

{
  "apiProdUrl": "https://api.codefe.cn",
  "apiDevUrl": "http://localhost:4000",
  "cookieDomain": ".codefe.cn",
  "template": {
    "tool": "https://github.com/code-fe/static-starter",
    "saas": "https://github.com/code-fe/saas-starter"
  },
  "github": {
    "token": "ghp_xxxxxxxx",
    "owner": "code-fe"
  },
  "deploy": {
    "mode": "ip",
    "host": "1.2.3.4",
    "user": "ubuntu",
    "targetDir": "/var/www",
    "nginxScript": "~/scripts/setup-new-site.sh"
  },
  "dns": {
    "provider": "tencentcloud",
    "domain": "codefe.cn",
    "tencentcloud": {
      "secretId": "AKIDxxxxxxxx",
      "secretKey": "xxxxxxxx"
    }
  },
  "analytics": {
    "umamiUrl": "https://analytics.codefe.cn",
    "username": "admin",
    "password": "xxxx"
  },
  "database": {
    "devUrl": "postgresql://user:pass@localhost:5432/codefe_dev",
    "prodUrl": "postgresql://user:pass@host:5432/codefe"
  },
  "supabase": {
    "devUrl": "http://localhost:54321",
    "devAnonKey": "eyJ...",
    "prodUrl": "https://xxxx.supabase.co",
    "prodAnonKey": "eyJ...",
    "adminEmail": "[email protected]",
    "adminPassword": "xxxx"
  },
  "resend": {
    "apiKey": "re_xxxx",
    "emailFrom": "[email protected]",
    "supportEmail": "[email protected]"
  }
}

Sensitive fields can also be provided via environment variables:

_CCA_GITHUB_TOKEN          _CCA_GITHUB_OWNER
_CCA_DEPLOY_HOST           _CCA_DEPLOY_USER
_CCA_TENCENTCLOUD_SECRET_ID  _CCA_TENCENTCLOUD_SECRET_KEY
_CCA_DATABASE_PROD_URL

Config loading priority:

Defaults → ~/.config/cca/config.json → _CCA_* env vars → CLI flags

Project config — codefe.config.json

Auto-generated by cca init in the project root. Checked into git.

{
  "type": "tool",
  "subdomain": "my-tool",
  "url": "https://my-tool.codefe.cn",
  "project": {
    "name_en": "MyTool",
    "name_zh": "我的工具",
    "slogan_en": "Do one thing well",
    "slogan_zh": "专注做好一件事",
    "desc_en": "A concise tool description",
    "desc_zh": "简洁的工具描述",
    "tags": ["tool"]
  }
}

Production Server Setup

The production server runs codefe-worker directly. It does not need a global cca install and does not need ~/.config/cca/config.json.

Server-side runtime configuration belongs to codefe-worker and codefe-api environment files. The worker imports @codefe/create-codefe-app/runtime directly and constructs a server runtime context in-process.

Typical server-side settings include:

• DATABASE_URL
• CODEFE_PROJECT_ROOT
• LOGS_DIR
• CODEFE_API_URL / _CCA_API_PROD_URL
• production deploy/dns/database credentials used by runtime steps

The supabase.adminEmail + adminPassword are still used by runtime API calls to codefe-api (for example gen-cca and gen-redev when the worker needs product metadata).

Bundled server scripts

cca packages two bash scripts that are uploaded to the server as needed:

| Script | Uploaded by | Purpose | |--------|------------|---------| | scripts/setup-new-site.sh | add-ssl step | Configure nginx vhost + certbot SSL | | scripts/teardown-site.sh | cca teardown command | Remove nginx config, SSL cert, webroot, source dir |

Both scripts are uploaded to the path configured in deploy.nginxScript (with setup-new-site.sh → teardown-site.sh substitution for teardown).

Worker / Server Integration

When codefe-worker picks up a pipeline task (init or redevelop), it iterates through the workflow step array and calls @codefe/create-codefe-app/runtime APIs directly. Step success/failure is determined by structured return values; the worker updates product_runs.steps in DB directly after each step.

Runtime context injected by the worker for each step includes:

| Field | Effect | |-------|--------| | executionMode = "server" | Use server-native execution semantics | | targetEnv = "prod" | Use production resources | | subdomain | Product subdomain | | projectDir/serverProjectDir | Canonical server-side project location | | changeRequest | Change description for ai-dev / gen-redev | | contextMode = "fast" | Context mode for redevelop |

Steps only used by the worker (not in cca init or cca deploy):

• pull — git pull --ff-only origin main + pnpm install (before AI redevelop)
• gen-redev — fetches product data from API, reads docs/PRD.md, generates docs/redevelop-context.json with smart file selection based on the runtime changeRequest
• ai-dev — runs Claude CLI with a structured prompt for AI-driven init or redevelop using runtime runType, contextMode, and changeRequest

Developing cca itself

git clone <repo>
cd create-codefe-app
pnpm install
pnpm dev -- --help            # Run via tsx
pnpm dev -- init test-tool    # Test a command
pnpm build                    # Compile to dist/
pnpm tsc --noEmit             # Type check only

Publishing

pnpm build
npm publish --access public