Project Scaffolding — create-statikapi

create-statikapi scaffolds a new project with one of the templates currently supported in this repo.

Use it when you want:

• a regular local statikapi project
• a dynamic-route example project
• a build-time remote-data example
• a Cloudflare Worker + Static Assets project

pnpm dlx create-statikapi

Supported templates

• basic
  • small starter with a root route
• dynamic
  • dynamic and catch-all route examples
• remote-data
  • build-time fetch examples
• cloudflare-adapter
  • Cloudflare Worker + Static Assets for public routes + private R2 + KV + preview UI + private rebuild webhooks

Global flags

• --template basic|dynamic|remote-data|cloudflare-adapter
• --yes, -y
• --no-install
• --no-gitignore
• --package-manager pnpm|npm|yarn
• --src-dir <dir>
• --out-dir <dir>
• --assets-dir <dir>
  • Cloudflare template only
• --deploy cloudflare,netlify,github
  • non-Cloudflare templates only
• --help, -h

Examples

create-statikapi my-api --template dynamic --no-install

create-statikapi my-api --src-dir api --out-dir public/api --deploy cloudflare,github

create-statikapi my-worker --template cloudflare-adapter --assets-dir public

Normal templates

For basic, dynamic, and remote-data, the scaffold can ask about:

• source directory
• output directory
• JavaScript or TypeScript example routes
• ESLint
• deploy presets

Defaults:

• source directory: src-api
• output directory: api-out

If you customize the directories, the scaffold writes statikapi.config.js for you.

Cloudflare template

The Cloudflare template is intentionally different from the normal templates.

It scaffolds a project for:

• one Worker
• one Static Assets directory for public output
• one private R2 bucket
• one KV namespace
• one preview UI flow

What it writes

• wrangler.toml
• statikapi.config.js
• .dev.vars
• src-api/
• package scripts for dev, build, and deploy

What it asks for

• Static Assets directory
  • defaults to public
• private R2 bucket binding name
• private R2 bucket name
• KV binding name
• KV namespace id
• STATIK_BUILD_TOKEN
• STATIK_SRC
  • usually matches src-api
• STATIK_USE_INDEX_JSON
• private auth header name
• private auth header value
• Cloudflare account id
• Cloudflare API token placeholder
• optional Worker / R2 limit values

Cloudflare output model

Public routes:

• are public by default
• are emitted under /public/...
• are generated into the configured Static Assets directory
• are served by Cloudflare Static Assets

Private routes:

• use config.cloudflare.public = false
• keep their original route paths
• are stored in a private R2 bucket
• are served through the Worker

Cloudflare route config

Generated routes can override project defaults with:

export const config = {
  cloudflare: {
    public: false,
    webhook: true,
  },
};

Important limitation

Public routes are not webhook-refreshable in this version.

That means:

• POST / refreshes private outputs only
• POST <private-route> refreshes that private route only
• public output changes require a new build + deploy

For full Cloudflare behavior, see Cloudflare Worker + Static Assets Adapter.

Cloudflare template commands after scaffolding

Typical flow:

cd my-worker
pnpm install
pnpm dev

What pnpm dev does in the scaffolded Cloudflare app:

• builds the Worker bundle
• builds public Static Assets
• starts local wrangler dev
• starts the preview UI
• opens the preview UI when possible
• rebuilds on src-api/ changes

The preview UI shows:

• public routes
• private routes
• grouped visibility
• preview JSON
• copy-ready snippets

Deploy notes for the scaffolded Cloudflare project:

• pnpm deploy now runs the StatikAPI build before wrangler deploy
• deployed Worker secrets still must be set in Cloudflare separately; local .dev.vars does not upload them by itself
• if you need to seed private outputs after deploy, send a manual POST to YOUR_WORKER_URL/ with Authorization: Bearer YOUR_STATIK_BUILD_TOKEN
• if you connect the repo to Cloudflare Git-based deployments, keep the same split between deployment credentials, build-time values, and deployed Worker secrets
• the Cloudflare manifest also carries srcRoute, webhookAvailable, and webhookRoute for each entry

Cloudflare setup guidance

The scaffold asks for values that come from your Cloudflare account.

Account ID

Official Cloudflare doc:

• Find account and zone IDs

Practical place to copy it:

• Workers & Pages -> Overview -> Account details

KV namespace id

Official doc:

• KV namespaces

Practical place to get it:

• Workers & Pages -> KV

Private R2 bucket name

Official doc:

• Create new buckets

Practical place to get it:

• R2 -> Buckets

Cloudflare deploy token

Official docs:

• Create API token
• API token permissions reference

Recommended permissions for this template:

• Workers Scripts Edit
• Workers KV Storage Edit
• Workers R2 Storage Edit

Optional:

• Workers Tail Read

STATIK_BUILD_TOKEN

This is not the Cloudflare API token.

It is the application-level secret used to authorize:

• POST /
• POST <private-route-path>

Use a long random string.

Node and install behavior

The scaffold currently writes:

• .nvmrc
• .node-version
• package.json engines

to keep the generated project aligned with the repo’s current Node expectations.

By default the scaffold installs dependencies immediately, unless you pass:

create-statikapi my-api --no-install

When to choose which template

Choose basic when:

• you want the smallest possible starter

Choose dynamic when:

• you want to learn dynamic and catch-all routes quickly

Choose remote-data when:

• your routes fetch remote APIs at build time

Choose cloudflare-adapter when:

• you want public Static Assets plus authenticated private routes
• you want local preview UI for a Cloudflare project
• you want private route rebuilds via authenticated HTTP POSTs