Getting started with the npm package

Install one npm package, create an authenticated full-stack application, and run it locally. You do not need to clone the Clank repository or assemble a framework toolchain.

#Requirements

• Node.js 22.16 or newer.
• npm 10 or newer.
• A modern browser.

The official package is @clank.run/framework. The unscoped clank package on npm is a different project.

#1. Install Clank

Install the package globally to make the clank command available in every project:

npm install --global @clank.run/framework
clank --version

The package contains the framework runtime, TypeScript and TSX compiler, project starter, development commands, deployment client, and type declarations. It has no transitive npm dependencies.

Prefer a project-local CLI? Install the same package in an existing project and run its binary through npm:

npm install @clank.run/framework
npx clank --version

The rest of this guide uses the global clank command.

#2. Create an application

clank create my-app
cd my-app
npm install

clank create starts with a working product rather than a blank component. The generated application already has:

• email and password registration, login, logout, secure sessions, and CSRF protection;
• private per-user Todo data in SQLite;
• server rendering and node-preserving browser hydration;
• live updates across tabs and browsers;
• validated queries and mutations with inferred TypeScript types;
• Tailwind utility styling;
• an initial immutable database migration;
• health checks and deterministic deployment configuration; and
• README.md and AGENTS.md instructions for people and coding agents.

The generated package.json has one application dependency:

{
  "dependencies": {
    "@clank.run/framework": "^0.7.0"
  }
}

The scaffold uses the version of the CLI that created it. Commit the generated lockfile so every human, agent, and deployment uses the same resolved package.

#3. Run it

npm run dev

Open http://127.0.0.1:3000, register an account, and create a Todo. Open the same URL in a second browser and sign in with the same account; committed changes update both sessions.

The starter stores local data in app.sqlite. That file, generated JavaScript, and local deployment state are ignored by Git.

#Your application files

This is the structure of the app created from npm, not the structure of the Clank framework repository:

my-app/
├── src/
│   ├── backend.ts       auth, database schema, queries, and mutations
│   ├── view.tsx         accessible server/client UI
│   ├── app.tsx          hydration, live data, and browser interactions
│   └── server.tsx       routes, SSR, security headers, and static files
├── migrations/
│   └── 0001_app_metadata.sql
├── AGENTS.md            app map, invariants, and definition of done
├── README.md            human setup and deployment instructions
├── clank.deploy.json    build, database, health, and artifact contract
├── package.json         scripts and the Clank package dependency
└── tsconfig.json

Start in src/view.tsx when changing what the app looks like. Put trusted data rules in src/backend.ts, browser coordination in src/app.tsx, and HTTP or SSR behavior in src/server.tsx. Never hand-edit dist/; Clank generates it.

#Everyday commands

The generated npm scripts keep the normal workflow short:

npm run dev           # build and start the local server
npm run build         # compile src/ into dist/
npm run doctor        # check Node, config, migrations, login, and project link
npm run deploy:check  # build and verify an offline deployment artifact
npm run deploy        # build, migrate, health-check, and deploy

You can call the package CLI directly when you need more control:

clank build src dist
clank watch src dist
clank doctor --json
clank help --json

The JSON forms are stable interfaces for coding agents and automation.

#Make the first change

Components are ordinary functions that return typed TSX. Reactive values use .value, and Clank updates only the DOM bindings that read them:

/* @clankImportSource @clank.run/framework */
import { computed, signal } from "@clank.run/framework";

export function Counter() {
  const count = signal(0);
  const label = computed(() => `Count: ${count.value}`);

  return (
    <button
      class="rounded-lg bg-slate-950 px-4 py-2 font-semibold text-white"
      onClick={() => count.value++}
      agentId="increment"
      agentLabel="Increase count"
    >
      {label.value}
    </button>
  );
}

The @clankImportSource comment tells Clank's compiler where JSX primitives come from. agentId gives an important control a stable machine-readable identity, while agentLabel explains its purpose without changing the visible UI.

#Add data safely

The starter's src/backend.ts is the source of truth for data and authorization:

import { defineDatabase, defineTable, s } from "@clank.run/framework";

export const schema = defineDatabase({
  todos: defineTable({
    title: s.string({ min: 1, max: 160 }),
    done: s.boolean(),
  }).owned(),
});

.owned() scopes records to the signed-in user. Define validated queries and mutations beside the schema; the browser client infers their arguments and results without a code-generation step. Read Full-stack applications, Authentication, and Database revisions and correctness before expanding the starter's data model.

Add a new numbered SQL file for every schema change:

migrations/0002_add_due_dates.sql

Never edit or reorder an applied migration. Clank checks migration history before activation and backs up the database before production migrations. See SQLite migrations.

#Use Tailwind

The starter is already configured for Tailwind utility classes, so you can edit class values in TSX immediately. Clank does not wrap or reinterpret Tailwind; classes are emitted as normal HTML attributes. For a compiled production stylesheet, follow Tailwind CSS.

#Build with an agent

Open the generated directory in your coding agent and describe the product you want. For example:

Turn this starter into a shared meal planner. Keep authentication, make every
record user-owned, add immutable migrations, preserve live updates, and run
npm run build, npm run doctor, and npm run deploy:check when finished.

The generated AGENTS.md tells the agent where each concern belongs, which security and migration invariants it must preserve, and how to prove the app is deployable. The documentation is also available as a compact agent map, the complete Markdown corpus, and structured JSON.

#Deploy

Sign in once, check the app, and deploy:

clank login --server=https://clank.run
clank whoami
npm run doctor
npm run deploy

The first deployment creates and links an isolated project automatically. The CLI builds locally, packages the exact framework runtime and application files, verifies their digests, applies migrations, waits for the health check, and then activates the release.

Use npm run deploy:check whenever you only want to build and inspect the artifact. It does not require login or network access. Continue with the Deployment CLI for custom domains, secrets, logs, rollback, backups, organizations, and automation.

#Package imports

Import from the root for most apps:

import {
  createApp,
  defineBackend,
  renderDocument,
  signal,
} from "@clank.run/framework";

Focused public entry points are also available:

import { signal } from "@clank.run/framework/core";
import { render } from "@clank.run/framework/dom";
import { createRouter } from "@clank.run/framework/router";
import { createForm } from "@clank.run/framework/forms";
import { defineAuth } from "@clank.run/framework/auth";
import { defineBackend } from "@clank.run/framework/backend";
import { createApp } from "@clank.run/framework/server";
import { serve } from "@clank.run/framework/node";

Imports do not mutate global state. The package ships its TypeScript declarations and supports strict editor type checking with "jsx": "preserve".

#Next steps

• Application recipes: choose the right client, server, data, and deployment shape.
• Reactivity: learn signals, computed values, effects, stores, resources, and transactions.
• Rendering and components: understand TSX, keyed lists, SSR, and hydration.
• Routing: add URL-driven pages, parameters, loaders, guards, and navigation.
• Authentication: customize profiles, sessions, authorization, and the default auth UI.
• Deployment CLI: ship and operate the application.
• Contributing to Clank: clone the framework repository only when you want to change Clank itself.