@codefe/create-codefe-app

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

Two entry points, same pipeline: cca is for developers who work locally. build.codefe.cn is the Web UI for non-technical users — it drives the same pipeline via codefe-api + worker.

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 | |------|-------------| | preflight-check | Verifies Node, pnpm, git, SSH connectivity, and required config fields | | create-remote-repo | Creates a GitHub repo from the template (tool or saas) under github.owner | | clone-repo | Clones the repo into <cwd>/<subdomain>/ | | add-dns-record | 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-env-config | Updates src/config/site.ts, locales/en.json, locales/zh.json, public/manifest.webmanifest; writes .env.development and .env.production | | pnpm-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/setup.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-frontend | pnpm build → static export to out/ | | init-db | SSHes to server, runs pnpm db:init (injects DATABASE_URL); fallback: pipes scripts/db/setup.sql via psql | | sync-frontend | rsync out/ → deploy.host:deploy.targetDir/<subdomain>/ via SSH | | setup-nginx-ssl | Uploads bundled setup-new-site.sh to server via SCP, then executes it via SSH to configure nginx + certbot SSL | | smoke-check | HTTP GET https://<subdomain>.codefe.cn — asserts 200 OK | | push-frontend | git add -A && git commit && git push origin main |

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

| Step | What it does | |------|-------------| | build-frontend | Same as above | | init-db | Skipped automatically if no changes to scripts/db/setup.sql since last commit | | sync-frontend | Same as above | | smoke-check | Same as above | | push-frontend | 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 preflight-check
cca run build-frontend
cca run sync-frontend --prod
cca run init-db --prod
cca run push-frontend

All available step keys:

| Key | Pipeline | |-----|---------| | preflight-check | init | | create-remote-repo | init | | clone-repo | init | | add-dns-record | init | | setup-umami | init | | gen-cca | init | | update-env-config | init | | pnpm-install | init | | build-frontend | deploy | | init-db | deploy | | sync-frontend | deploy | | setup-nginx-ssl | first deploy | | smoke-check | deploy | | push-frontend | deploy | | git-pull | worker redeploy only | | gen-redevelop-context | worker redeploy only | | claude-develop | worker init/redeploy only |

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

cca teardown <subdomain>

Permanently remove a deployed product from the server:

• Removes nginx config from /etc/nginx/sites-available|enabled/
• Deletes Let's Encrypt SSL certificate via certbot
• Removes /var/www/<subdomain> static files
• Removes ~/code/codefe/<subdomain> source directory

cca teardown my-tool        # Prompts for confirmation (default: no)
cca teardown my-tool --yes  # Skip confirmation

Local mode: uploads teardown-site.sh to server via SCP then executes it via SSH.
ON_SERVER=true: executes the script directly with sudo (no SSH).

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 (where codefe-worker runs) needs cca installed globally:

npm install -g @codefe/create-codefe-app

The server config at ~/.config/cca/config.json needs only production fields — devUrl / devAnonKey fields are never used because the worker always invokes cca with --prod:

{
  "apiProdUrl": "https://api.codefe.cn",
  "template": {
    "tool": "https://github.com/code-fe/static-starter",
    "saas": "https://github.com/code-fe/saas-starter"
  },
  "github": { "token": "...", "owner": "code-fe" },
  "deploy": {
    "mode": "ip",
    "host": "127.0.0.1",
    "user": "ubuntu",
    "targetDir": "/var/www",
    "nginxScript": "~/scripts/setup-new-site.sh"
  },
  "dns": {
    "provider": "tencentcloud",
    "domain": "codefe.cn",
    "tencentcloud": { "secretId": "...", "secretKey": "..." }
  },
  "analytics": { "umamiUrl": "...", "username": "...", "password": "..." },
  "database": { "prodUrl": "postgresql://..." },
  "supabase": {
    "prodUrl": "https://xxxx.supabase.co",
    "prodAnonKey": "eyJ...",
    "adminEmail": "...",
    "adminPassword": "..."
  }
}

The supabase.adminEmail + adminPassword are used by cca to authenticate API calls to codefe-api (e.g., fetching product data in gen-cca and gen-redevelop-context steps).

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 | setup-nginx-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 cca run <step> --prod for each step sequentially. Step success/failure is determined by exit code; the worker updates product_runs.steps in DB directly after each step.

Env vars injected by the worker for each step:

| Variable | Effect | |----------|--------| | ON_SERVER=true | Local rsync + local nginx script execution (no SSH) | | API_URL | codefe-api base URL | | CCA_SUBDOMAIN | Product subdomain (worker calls cca run from WORK_DIR) | | CCA_PRODUCT_TYPE | tool or saas (for early init steps before codefe.config.json exists) | | CHANGE_REQUEST | Change description for claude-develop (redevelop only) | | CONTEXT_MODE=fast\|full | Context mode for gen-redevelop-context (redevelop only) |

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

• git-pull — git pull --ff-only origin main + pnpm install (before AI redevelop)
• gen-redevelop-context — fetches product data from API, reads docs/PRD.md, generates docs/redevelop-context.json with smart file selection based on CHANGE_REQUEST
• claude-develop — runs Claude CLI with a structured prompt for AI-driven init or redevelop (PIPELINE_MODE, CONTEXT_MODE, CHANGE_REQUEST)

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