{"protocol":"clank-doc/1","frameworkVersion":"0.8.0","slug":"getting-started","title":"Getting started with the npm package","description":"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.","group":{"id":"start","title":"Start with npm"},"url":"https://docs.clank.run/docs/getting-started","source":"docs/getting-started.md","headings":["Requirements","1. Install Clank","2. Create an application","3. Run it","Your application files","Everyday commands","Make the first change","Add data safely","Use Tailwind","Build with an agent","Deploy","Package imports","Next steps"],"tableOfContents":[{"id":"requirements","title":"Requirements","level":2},{"id":"1-install-clank","title":"1. Install Clank","level":2},{"id":"2-create-an-application","title":"2. Create an application","level":2},{"id":"3-run-it","title":"3. Run it","level":2},{"id":"your-application-files","title":"Your application files","level":2},{"id":"everyday-commands","title":"Everyday commands","level":2},{"id":"make-the-first-change","title":"Make the first change","level":2},{"id":"add-data-safely","title":"Add data safely","level":2},{"id":"use-tailwind","title":"Use Tailwind","level":2},{"id":"build-with-an-agent","title":"Build with an agent","level":2},{"id":"deploy","title":"Deploy","level":2},{"id":"package-imports","title":"Package imports","level":2},{"id":"next-steps","title":"Next steps","level":2}],"markdown":"# Getting started with the npm package\n\nInstall 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.\n\n## Requirements\n\n- Node.js 22.16 or newer.\n- npm 10 or newer.\n- A modern browser.\n\nThe official package is `@clank.run/framework`. The unscoped `clank` package on npm is a different project.\n\n## 1. Install Clank\n\nInstall the package globally to make the `clank` command available in every project:\n\n```sh\nnpm install --global @clank.run/framework\nclank --version\n```\n\nThe package contains the framework runtime, TypeScript and TSX compiler, project starter, development commands, deployment client, and type declarations. It has no transitive npm dependencies.\n\nRun `clank` by itself in an interactive terminal to choose a template and follow a guided create, login, check, or deploy workflow:\n\n```sh\nclank\n```\n\nBare `clank` prints the full command reference when standard input is not interactive, so it never blocks an agent or CI job waiting for a prompt.\n\nPrefer a project-local CLI? Install the same package in an existing project and run its binary through npm:\n\n```sh\nnpm install @clank.run/framework\nnpx clank --version\n```\n\nThe rest of this guide uses the global `clank` command.\n\n## 2. Create an application\n\n```sh\nclank create my-app\ncd my-app\nnpm install\n```\n\n`clank create` starts with a working product rather than a blank component. The generated application already has:\n\n- email and password registration, login, logout, secure sessions, and CSRF protection;\n- private per-user Todo data in SQLite;\n- server rendering and node-preserving browser hydration;\n- live updates across tabs and browsers;\n- validated queries and mutations with inferred TypeScript types;\n- Tailwind utility styling;\n- an initial immutable database migration;\n- health checks and deterministic deployment configuration; and\n- `README.md` and `AGENTS.md` instructions for people and coding agents.\n\nThe generated `package.json` has one application dependency:\n\n```json\n{\n  \"dependencies\": {\n    \"@clank.run/framework\": \"^0.8.0\"\n  }\n}\n```\n\nThe 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.\n\n## 3. Run it\n\n```sh\nnpm run dev\n```\n\nOpen `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.\n\nThe starter stores local data in `app.sqlite`. That file, generated JavaScript, and local deployment state are ignored by Git.\n\n## Your application files\n\nThis is the structure of the app created from npm, not the structure of the Clank framework repository:\n\n```text\nmy-app/\n├── src/\n│   ├── backend.ts       auth, database schema, queries, and mutations\n│   ├── view.tsx         accessible server/client UI\n│   ├── app.tsx          hydration, live data, and browser interactions\n│   └── server.tsx       routes, SSR, security headers, and static files\n├── migrations/\n│   └── 0001_app_metadata.sql\n├── AGENTS.md            app map, invariants, and definition of done\n├── README.md            human setup and deployment instructions\n├── clank.deploy.json    build, database, health, and artifact contract\n├── package.json         scripts and the Clank package dependency\n└── tsconfig.json\n```\n\nStart 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.\n\n## Everyday commands\n\nThe generated npm scripts keep the normal workflow short:\n\n```sh\nnpm run dev           # build and start the local server\nnpm run build         # compile src/ into dist/\nnpm run doctor        # check Node, config, migrations, login, and project link\nnpm run deploy:check  # build and verify an offline deployment artifact\nnpm run deploy        # build, migrate, health-check, and deploy\n```\n\nYou can call the package CLI directly when you need more control:\n\n```sh\nclank build src dist\nclank watch src dist\nclank doctor --json\nclank help --json\n```\n\nThe JSON forms are stable interfaces for coding agents and automation.\n\n## Make the first change\n\nComponents are ordinary functions that return typed TSX. Reactive values use `.value`, and Clank updates only the DOM bindings that read them:\n\n```tsx\n/* @clankImportSource @clank.run/framework */\nimport { computed, signal } from \"@clank.run/framework\";\n\nexport function Counter() {\n  const count = signal(0);\n  const label = computed(() => `Count: ${count.value}`);\n\n  return (\n    <button\n      class=\"rounded-lg bg-slate-950 px-4 py-2 font-semibold text-white\"\n      onClick={() => count.value++}\n      agentId=\"increment\"\n      agentLabel=\"Increase count\"\n    >\n      {label.value}\n    </button>\n  );\n}\n```\n\nThe `@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.\n\n## Add data safely\n\nThe starter's `src/backend.ts` is the source of truth for data and authorization:\n\n```ts\nimport { defineDatabase, defineTable, s } from \"@clank.run/framework\";\n\nexport const schema = defineDatabase({\n  todos: defineTable({\n    title: s.string({ min: 1, max: 160 }),\n    done: s.boolean(),\n  }).owned(),\n});\n```\n\n`.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](full-stack.md), [Authentication](auth.md), and [Database revisions and correctness](database.md) before expanding the starter's data model.\n\nAdd a new numbered SQL file for every schema change:\n\n```text\nmigrations/0002_add_due_dates.sql\n```\n\nNever edit or reorder an applied migration. Clank checks migration history before activation and backs up the database before production migrations. See [SQLite migrations](migrations.md).\n\n## Use Tailwind\n\nThe 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](tailwind.md).\n\n## Build with an agent\n\nOpen the generated directory in your coding agent and describe the product you want. For example:\n\n```text\nTurn this starter into a shared meal planner. Keep authentication, make every\nrecord user-owned, add immutable migrations, preserve live updates, and run\nnpm run build, npm run doctor, and npm run deploy:check when finished.\n```\n\nThe 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](https://docs.clank.run/llms.txt), [the complete Markdown corpus](https://docs.clank.run/llms-full.txt), and [structured JSON](https://docs.clank.run/api/docs.json).\n\n## Deploy\n\nSign in once, check the app, and deploy:\n\n```sh\nclank login\nclank whoami\nnpm run doctor\nnpm run deploy\n```\n\nLogin uses `https://clank.run` by default. Pass `--server` only when using a self-hosted Clank control plane. 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.\n\nUse `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](cli.md) for custom domains, secrets, logs, rollback, backups, organizations, and automation.\n\n## Package imports\n\nImport from the root for most apps:\n\n```ts\nimport {\n  createApp,\n  defineBackend,\n  renderDocument,\n  signal,\n} from \"@clank.run/framework\";\n```\n\nFocused public entry points are also available:\n\n```ts\nimport { signal } from \"@clank.run/framework/core\";\nimport { render } from \"@clank.run/framework/dom\";\nimport { createRouter } from \"@clank.run/framework/router\";\nimport { createForm } from \"@clank.run/framework/forms\";\nimport { defineAuth } from \"@clank.run/framework/auth\";\nimport { defineBackend } from \"@clank.run/framework/backend\";\nimport { createApp } from \"@clank.run/framework/server\";\nimport { serve } from \"@clank.run/framework/node\";\n```\n\nImports do not mutate global state. The package ships its TypeScript declarations and supports strict editor type checking with `\"jsx\": \"preserve\"`.\n\n## Next steps\n\n- [Application recipes](application-recipes.md): choose the right client, server, data, and deployment shape.\n- [Reactivity](reactivity.md): learn signals, computed values, effects, stores, resources, and transactions.\n- [Rendering and components](rendering.md): understand TSX, keyed lists, SSR, and hydration.\n- [Routing](routing.md): add URL-driven pages, parameters, loaders, guards, and navigation.\n- [Authentication](auth.md): customize profiles, sessions, authorization, and the default auth UI.\n- [Deployment CLI](cli.md): ship and operate the application.\n- [Contributing to Clank](../CONTRIBUTING.md): clone the framework repository only when you want to change Clank itself.\n"}