getting-started.mdx

Getting Started

StatikAPI turns small route modules into static JSON endpoints.

This repo currently supports two main workflows:

• Local CLI workflow
  • build JSON into api-out/
  • preview it locally at /_ui/
• Cloudflare workflow
  • public routes as Static Assets
  • private routes behind a Worker

---

1) Scaffold a project

pnpm dlx create-statikapi my-api
cd my-api
pnpm dev

yarn create statikapi my-api
cd my-api
yarn dev

npx create-statikapi my-api
cd my-api
npm run dev

You will be prompted for a template:

• basic
• dynamic
• remote-data
• cloudflare-adapter

---

2) Local CLI mode

For basic, dynamic, and remote-data, the default layout is:

src-api/
api-out/

Run:

pnpm dev

or:

pnpm build

What dev gives you

• watches your route files
• writes JSON into api-out/
• serves a preview UI at /_ui/
• shows routes, JSON payloads, and snippets

What build gives you

• a clean api-out/
• generated JSON payloads
• .statikapi/manifest.json

---

3) Cloudflare mode

Choose the cloudflare-adapter template if you want Cloudflare deployment from day one.

This creates a project with:

• a Worker bundle
• a Static Assets directory for public routes
• a private R2 bucket for private routes
• a KV namespace for manifest data
• a Cloudflare-aware preview/dev flow

Public vs private

Public routes:

• are public by default
• are emitted under /public/...
• are served as Static Assets

Private routes:

• use config.cloudflare.public = false
• stay on their original route paths
• are served through the Worker

Rebuild model

Private routes can be refreshed at runtime with authenticated POST requests.

Public routes cannot.

Public route changes require:

1. a new build
2. a new deploy

For the full Cloudflare contract, read Cloudflare Worker + Static Assets Adapter.

---

4) Route basics

StatikAPI routes are filesystem-based.

Examples:

src-api/index.js          -> /
src-api/about.js          -> /about
src-api/users/[id].js     -> /users/:id
src-api/docs/[...slug].js -> /docs/*slug

Dynamic and catch-all routes need paths() so StatikAPI knows which concrete routes to emit.

---

5) Route module shapes

You can export:

• export default <plain value>
• export default async function () {}
• export async function data() {}

Dynamic and catch-all routes can also export:

• export async function paths() {}

Route modules must ultimately return JSON-serializable data.

---

6) Collection index routes

Dynamic and catch-all routes can also emit a parent collection route with config.listIndex.

Example:

export const config = {
  listIndex: {
    enabled: true,
    pick: ['id', 'title'],
  },
};

That can produce:

• /posts/1
• /posts/2
• /posts

The regular CLI path and the Cloudflare adapter both support this now.

---

7) If you already have a repo

Install the CLI and add src-api/ yourself:

pnpm add -D statikapi

yarn add -D statikapi

npm i -D statikapi

Add scripts:

{
  "scripts": {
    "dev": "statikapi dev",
    "build": "statikapi build"
  }
}

Then create a route:

mkdir -p src-api
printf "export default { hello: 'world' }\n" > src-api/index.js

---

8) Next steps

• Read Configuration
• Read Core CLI — statikapi
• Read Project Scaffolding — create-statikapi
• Read Routes Overview
• Read Cloudflare Worker + Static Assets Adapter if you want the Cloudflare flow