Loading...
Loading...
Scaffold and build a complete Caffeine app (caffeine.ai) from scratch — the project layout, the caffeine.toml workspace + canister manifests, the mops.toml for the single Motoko `backend` canister, the React/Vite frontend, and the caffeine CLI build loop (auth login, doctor, install, check --fix, preview --build). Use whenever the user wants to create, scaffold, set up, or build a Caffeine app or a caffeine.ai project, asks about caffeine.toml or mops.toml structure, or needs the caffeine CLI workflow — even if they do not say the words 'from scratch'. Always pair it with the `writing-motoko` skill for the backend code. Do NOT use it for Motoko language syntax or compiler errors (use the `writing-motoko` skill), and do NOT use it for generic Internet Computer / dfx / icp deployment (use the `icp-cli` skill).
npx skill4agent add dfinity/icskills caffeine-appwriting-motokomo:corecaffeine.tomlmops.tomlauth logindoctorinstallcheckpreviewwriting-motokodfxicpicp-clicaffeinedfxcaffeine initcaffeine newcaffeine projects clone <id>caffeine projects import <zip>caffeine exportbackendmops.toml[canisters.backend]src/frontend/src/backend.tssrc/frontend/src/declarations/caffeine-bindgencaffeine preview --buildproject.idcaffeine deploypublish# Install the CLI (public npm package). The binary is `caffeine`.
npm install -g @caffeineai/cli
# Authenticate against caffeine.ai. Opens a browser; without one (or with --device) it
# uses the device flow. On a host with no OS keychain (headless Linux, containers), add
# --insecure-storage to keep the token in ~/.caffeine/tokens.json (mode 0600) instead.
caffeine auth login
caffeine auth status
# Check the environment: Node, pnpm, mops, caffeine-bindgen, that you are logged in,
# and that the Caffeine API is reachable (installs what it can).
caffeine doctor --fixcaffeinenpx -y @caffeineai/cli@latestnpx -y @caffeineai/cli@latest auth statuscaffeine doctorengines>=20.19.0caffeine-bindgen--fixic-mopscaffeine-bindgen@caffeineai/bindgennpm install -gmoclintoko[toolchain]mops.tomldfxmy-app/
├── .old/src/backend/dist/
│ └── backend.most # stable-signature baseline — seed with an empty actor (see below)
├── caffeine.toml # root workspace manifest — MUST contain [workspace]
├── mops.toml # Motoko build config — ONE per project, at the root
├── package.json # pnpm workspace root + the `bindgen` script
├── pnpm-workspace.yaml # declares src/**/* as workspace packages
├── tsconfig.json # root TS config
└── src/
├── backend/ # the single Motoko canister, named "backend"
│ ├── caffeine.toml # canister manifest: type = "motoko"
│ ├── main.mo # actor entry point (write with the `writing-motoko` skill)
│ └── migrations/ # enhanced-migration chain (see the `mops.toml` notes)
│ └── 00000000_000000.mo # first migration: initializes the actor's stable state
└── frontend/ # the assets canister (React + Vite)
├── caffeine.toml # canister manifest: type = "assets"
├── package.json # frontend deps + scripts (see references/frontend-template.md)
├── vite.config.js # (see references/frontend-template.md)
├── tsconfig.json # (see references/frontend-template.md)
├── biome.json # (see references/frontend-template.md)
├── tailwind.config.js # (see references/frontend-template.md)
├── postcss.config.js # (see references/frontend-template.md)
├── index.html
├── env.json # runtime config — copied into dist/ on build
├── public/ # static files served as-is (for example favicon.ico)
└── src/
├── main.tsx # React entry (providers)
├── App.tsx
├── index.css
├── backend.ts # GENERATED by caffeine-bindgen — do NOT edit
└── declarations/ # GENERATED by caffeine-bindgen — do NOT editmops.tomlmain.mopackage.jsonvite.config.jsindex.htmlenv.jsonmain.tsxApp.tsxreferences/frontend-template.mdcaffeine.toml[workspace]manifest_version = "0.1.0"
[project]
name = "My App"
# id is the cloud project id, a UUID. Omit it for a brand-new local project; once
# `caffeine projects create` reports one, set it here (or pass --project-id to preview).
# A placeholder such as "my-app" makes `caffeine preview` refuse to upload.
[workspace]
include = [ "src/**" ]
# Build the backend before the frontend, because the frontend imports generated
# bindings produced from the backend's Candid interface.
[canisters.frontend]
depends_on = [ "backend" ][workspace].includesrc/**src/backend/caffeine.tomlsrc/frontend/caffeine.tomlsrc/backend/caffeine.tomlmanifest_version = "0.1.0"
[project]
name = "backend"
type = "motoko"
main = "main.mo"
[build]
commands = ["mops build", "pnpm bindgen"]
out = "dist"
[check]
commands = ["mops check"]
[check.fix]
commands = ["mops check --fix"][build].commandsmops buildmain.mopnpm bindgenpackage.jsoncaffeine check --fix[check.fix].commandssrc/frontend/caffeine.tomlmanifest_version = "0.1.0"
[project]
name = "frontend"
type = "assets"
[build]
commands = ["pnpm build"]
out = "dist"
[check]
commands = ["pnpm typecheck", "pnpm check"]
[check.fix]
commands = ["pnpm typecheck", "pnpm fix"]mops.toml[canisters.backend]caffeine preview[canisters.backend][canisters.backend.check-stable]skipIfMissing[build] outputDir = "src/backend/dist"[moc]-E-W-A[package]
name = "backend"
version = "0.1.0"
[build]
outputDir = "src/backend/dist"
args = ["--release"]
check-wasm = true
[canisters.backend]
main = "src/backend/main.mo"
[canisters.backend.check-stable]
path = ".old/src/backend/dist/backend.most"
[toolchain]
moc = "2.1.0"
lintoko = "0.12.0"
[lint]
extends = true
[moc]
args = [
"--implicit-package=core",
"-no-check-ir",
"-E=M0254",
"-W=M0235,M0223,M0236,M0237",
"-A=M0241"
]
[dependencies]
core = "2.6.1"
ic = "5.0.0"
caffeineai-authorization = "1.0.0"
caffeineai-lints = "0.1.0"
caffeineai-oql = "0.8.0"
[canisters.backend.migrations]
chain = "src/backend/migrations"
check-limit = 1actorpersistent--default-persistent-actors--generate-view-queries[moc] argsunknown optionmoc = "1.16.0"--default-persistent-actors[moc] argsmigrating-to-moc-2check-stable.old/src/backend/dist/backend.mostcaffeine checkcaffeine projects clone.old/caffeine checkDeployed file not found: .old/src/backend/dist/backend.most// Version: 1.0.0
actor {};skipIfMissing = truecaffeine preview[canisters.backend.migrations]--enhanced-migration[moc] args.mosrc/backend/migrations/00000000_000000.momain.moYYYYMMDD_HHMMSS.moimport AccessControl "mo:caffeineai-authorization/access-control";
module {
public type OldActor = {};
public type NewActor = { accessControlState : AccessControl.AccessControlState };
public func migration(_ : OldActor) : NewActor {
{ accessControlState = AccessControl.initState() };
};
};check-limit = 100000000_000000.mocaffeine checktoo many pending migrations for check-limit=1migrating-motoko-actorscoremo:coremo:coremo:basewriting-motokocaffeineai-oqlExposemain.mocaffeineai-authorizationMixinAuthorizationAccessControlcaffeine checkmain.moMixinAuthorizationmops remove caffeineai-authorizationextension-authorizationMixinAuthorization[lint] extends = truelintoko[toolchain]mops checkicmo:ic/Typesmo:ic/Callimport ... "ic:aaaaa-aa"--actor-idlmops add <name>[dependencies]mops.lockmops-cliVersions and dependencies drift. Theversions, the[toolchain][moc]/-E/-Wcodes, and the frontend dependency set are template-managed and change over time (e.g. the-A→@dfinity/*migration, moc/core bumps). Treat the exact values here as a snapshot — for current ones,@icp-sdk/*a recent project and copy itscaffeine projects clone+mops.toml. Stable across versions: the file layout, the singlesrc/frontend/package.jsoncanister,backendwith the seeded baseline,check-stable,[build] outputDir, andmo:core.useActor(createActor)
package.jsonbindgenbindgen[build]pnpm bindgen{
"name": "@caffeine/template-app",
"type": "module",
"engines": {
"node": ">=20.19.0",
"pnpm": ">=7.0.0",
"npm": "please use pnpm"
},
"scripts": {
"build": "pnpm -r --if-present run build",
"typecheck": "pnpm -r --if-present run typecheck",
"check": "pnpm -r --if-present run check",
"fix": "pnpm -r --if-present run fix",
"bindgen": "caffeine-bindgen --did-file ./src/backend/dist/backend.did --out-dir ./src/frontend/src --actor-interface-file --force"
},
"devDependencies": {
"@icp-sdk/core": "^5.3.0",
"sharp": "^0.34.4"
}
}packageManager@dfinity/picpnpm-workspace.yamlonlyBuiltDependenciesallowBuildspackages:
- src/**/*
allowBuilds:
'@biomejs/biome': true
esbuild: true
sharp: true
onlyBuiltDependencies:
- '@biomejs/biome'
- esbuild
- sharptsconfig.json{
"compilerOptions": {
"strict": true,
"target": "ES2020",
"experimentalDecorators": true,
"strictPropertyInitialization": false,
"module": "esnext",
"moduleResolution": "bundler",
"allowJs": true,
"outDir": "HACK_BECAUSE_OF_ALLOW_JS"
}
}src/backend/main.momain.moMixinAuthorizationcaffeineai-authorizationExposecaffeineai-oqlaccessControlState00000000_000000.mowriting-motokoimport AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";
import Expose "mo:caffeineai-oql/Expose";
actor {
let accessControlState : AccessControl.AccessControlState;
include MixinAuthorization(accessControlState, null);
include Expose({ entities = [] });
};extension-authorizationwriting-motokomo:corereferences/frontend-template.mdSKILL.md…/skills/caffeine-app/references/frontend-template.mdpackage.jsonmain.tsxuseActor(createActor)src/frontend/src/main.tsxInternetIdentityProvider@caffeineai/core-infrastructureQueryClientProvidersrc/frontend/src/backend.tssrc/frontend/src/declarations/createActor(...)createActoruseActor(createActor)@caffeineai/core-infrastructuremain.tsxreferences/frontend-template.mduseInternetIdentity()login()onClickclear()isAuthenticateduseActorextension-core-infrastructureenv.jsonbackend_hostbackend_canister_idproject_idii_derivation_originstorage_gateway_url"undefined"builddist/cp env.json dist/@caffeineai/core-infrastructureenv.jsoncopy:env# 1. Install dependencies. On a brand-new project, generate the pnpm lockfile FIRST
# (first run only — see Common Pitfalls), then install the rest (pnpm + mops).
pnpm install
caffeine install
# 2. Write your backend in src/backend/main.mo using the `writing-motoko` skill, and your
# frontend in src/frontend/src/.
# 3. Build: compiles the backend, then `pnpm bindgen` regenerates the frontend client
# (src/frontend/src/backend.ts + declarations/), then the frontend `pnpm build` runs.
# Run this BEFORE check, so the frontend has the generated ./backend to typecheck
# against. Artifacts land in src/backend/dist + src/frontend/dist (no cloud / no id).
caffeine build
# 4. Lint + typecheck + auto-fix (runs each canister's [check.fix] commands:
# backend `mops check --fix`, frontend `pnpm typecheck` + `pnpm fix`).
caffeine check --fix
# 5. Upload a built draft (needs a cloud project id). For a brand-new app, create the
# cloud project once to obtain an id, then preview:
caffeine projects create # reports a new project id
# put that id in caffeine.toml [project] id = "...", OR pass --project-id:
caffeine preview --build --project-id <id>caffeine previewcaffeine build--buildmops.tomlsrc/backend/dist/backend.wasmsrc/frontend/dist/index.htmlcaffeine projects cloneNo committed draft foundCAFFEINE_VERBOSE=1caffeine installcaffeine buildcaffeine check--verbose--json--json{ "ok": true, "data": ... }{ "ok": false, "error": ... }src/frontend/src/backend.tspnpm bindgen./backendcaffeine buildcaffeine checkApp.tsx./backendcaffeine preview --buildproject.idcaffeine chat opencaffeine_go_livecaffeine projects show <id>caffeine projects createcaffeine chat send --project-id <id> "<prompt>"chat send--detachcaffeineai-*@caffeineai/*skills-lock.json.agents/skills/npx skills experimental_install -yskills/<name>/SKILL.mdhttps://mcp.internetcomputer.org/mcp[workspace]caffeine.toml[workspace]backendmops.toml[canisters.backend]bindgen./src/backend/dist/backend.didsrc/frontend/src/backend.tsdeclarations/caffeine-bindgenmain.mo./backendpnpm bindgencaffeine preview --buildcaffeine buildimport { createActor } from "./backend"dfx deploycaffeine deploycaffeinedfxmops.toml[canisters.backend][canisters.backend.check-stable][build] outputDir[toolchain] moc.old/env.jsoncopy:env.old/check-stableenv.jsondist/writing-motokomo:corenpmyarnpnpmpnpm-workspace.yamlpnpm -rcaffeine installcaffeine installbuildERR_PNPM_NO_LOCKFILEpnpm install --frozen-lockfilepnpm-lock.yamlpnpm installcaffeine checkDeployed file not found: …/backend.most.old/src/backend/dist/backend.mostmops.tomlcaffeine buildcaffeine preview --buildNo project.id in caffeine.tomlcaffeine projects create[project] id--project-id <id>caffeine buildtoo many pending migrations for check-limit=100000000_000000.moinclude-authorizationM0169accessControlStatemain.moMixinAuthorizationaccessControlStatemain.moextension-authorizationwriting-motokosrc/backend/main.momigrating-motoko-actorssrc/backend/migrations/extension-core-infrastructureInternetIdentityProvideruseInternetIdentityuseActorextension-authorizationcaffeineai-authorizationmops-climops addmops checkmigrating-to-moc-2icp-clidfxicpreferences/frontend-template.mdpackage.jsonvite.config.jstsconfig.jsonindex.htmlenv.jsonmain.tsxApp.tsxsrc/frontend/