---
title: "Starter templates"
description: "The starter templates are a web app (`web-app`), five small games and a server-code starter (`functions-starter`)."
url: "/docs/templates/"
lang: en
index: "/llms.txt"
---
# Starter templates

The starter templates are a web app (`web-app`), five small games and a server-code starter (`functions-starter`).
You do not need a template: in your own project folder, run `kumodeck init` or ask your AI agent to set it up.

## Web app

`web-app` is a small private notes app built the way most AI tools build apps: **React + Vite + TypeScript + Tailwind**,
with KUMODeck sign-in (guest first, then email), its own server code and database (Functions + D1: each user sees only
their own notes), and real page URLs (`/notes/123`) that can be shared and reloaded (`"web": { "spaFallback": true }`).

```sh
kumodeck create my-app --template web-app && cd my-app
kumodeck init                                    # writes your publishable keys into public/kumo-config.js
npm install && kumodeck config push
npm run build                                   # → dist/ (deployDir "dist" is saved in kumo.json)
kumodeck deploy --env development
```

Its `README.md` and `AGENTS.md` cover the server code (`kumodeck functions deploy`) and local development.

## Games

Complete, playable games you can copy, change and publish with one command. Each one uses guest sign-in, a cloud save for the
player's best score, a **Share on X** button with challenges, and keeps working offline. Want a leaderboard? Ask your AI
agent (Claude Code, Codex, Cursor, …): the leaderboard Skill that comes with each template builds one in your own database and Functions.

| Template | Engine | Game | Multiplayer |
|---|---|---|---|
| `vanilla-canvas` | none (plain `<canvas>`) | Star Catch — 30-second arcade round | — |
| `phaser` | Phaser 4.2.1 | Dune Runner — endless runner | — |
| `pixi` | PixiJS 8.21.0 | Bubble Pop — combo tapping | — |
| `three` | three.js 0.186.1 | Orb Garden — 3D rolling-ball collector | shared garden (up to 8) |
| `multiplayer-starter` | none | Cursor Party — lobby, room codes, synced positions, shared state | yes |

The game templates are **zero-build**: engines load from a pinned CDN URL, and the `public/` folder is the site.

## Use one

```sh
kumodeck create my-runner --template phaser && cd my-runner
kumodeck init                                    # writes your publishable keys into public/kumo-config.js
kumodeck config push --env development
kumodeck deploy --env development                # deployDir "public" is saved in kumo.json
kumodeck share on                                # optional: X cards + share links
```

Without `--template` you get `vanilla-canvas`. `create` copies from the templates bundled with the CLI, so it works
offline and does not touch the server; `init` is the step that creates the project. `kumodeck create my-game --init`
does both when you are signed in.

`kumo.config.json` stays **outside** `public/`, so project details are never served to
players. If you add a bundler, deploy its output folder instead (`kumodeck deploy dist`, or change `deployDir` in
`kumo.json`).

## Layout

```
my-game/
  kumo.config.json    master data (not deployed)
  README.md
  AGENTS.md           instructions for AI coding assistants (commands, rules, SDK examples; not deployed)
  CLAUDE.md           one line, `@AGENTS.md`, so Claude Code reads the same file
  GEMINI.md           one line, `@./AGENTS.md`, so Gemini CLI reads the same file
  .agents/skills/     Skills (recipes) for your AI agent: INDEX.md lists them, e.g. leaderboard/SKILL.md (not deployed)
  .claude/skills/     the same Skills, where Claude Code looks
  public/             deployed as-is
    index.html
    kumo-boot.js      finds the API, loads the SDK, signs in, never blocks play
    kumo-config.js    public: apiUrl + publishable keys
    game.js
```

`kumo-config.js` holds **one publishable key per environment**. `kumodeck init` fills it in while it still says
`REPLACE_ME`; a file you edited yourself is left alone. `kumo-boot.js` picks the development key on `<slug>--dev` URLs
and on localhost, and the production key everywhere else. A single `projectKey: 'pk_…'` (older setup) still works.

```js public/kumo-config.js
window.KUMO_CONFIG = {
  apiUrl: '',                                  // '' = the origin the page is served from (right for kumodeck deploy)
  projectKeys: {
    development: 'pk_dev_…',
    production: 'pk_live_…'                    // publishable: safe in the browser. Never put an sk_ key here.
  }
};
```

`AGENTS.md` tells an assistant (Claude Code, Codex, Cursor, …) how to work on the game: the commands to run, that the
account is created by you in the terminal (the assistant never handles your password), and that players never see the
backend's name. It also points the assistant to the Skills (the list is in `INDEX.md`): the same files are in
`.agents/skills/` (Codex, Cursor and most other agents look there) and `.claude/skills/` (Claude Code). Edit it like any other file.

## Share on X

Every template has a **Share on X** button on the result screen. It calls
`kumo.share({ kind: 'challenge', score })` with the player's score. When
someone opens the game from that post, the menu shows "Challenge: beat N!" (`kumo.share.incoming()`). Offline or with
sharing off, the button still opens X's post screen, just without a share id. **Nothing is turned on in
`kumo.config.json`** — run `kumodeck share on` when you want the card image and share links. See
[Sharing on X](/docs/guides/sharing/index.md).

URL flags every template understands: `?player=2` (a second guest in the same browser — test multiplayer against yourself), `?offline=1`, and `?api=…&key=…` to override `kumo-config.js`.

## Server code

`functions-starter` is not a game but the starting point for your own server code and SQL database, for an app or a
game: a small API that verifies the calling user (a *player* in the API), writes to its own database and runs an hourly job. See [Functions](/docs/guides/functions/index.md).