Getting started

Starting a product on Graview takes one command, npm create graview, which writes a running app for your own domain. Everything on this page below the command is read out of the generator that writes it, so it is what you will actually get.

npm create graview@latest my-app

Or pnpm create graview my-app, or npx graview create my-app. Node 22 or later.

What it asks

The directory is the only thing it needs; the rest has a default it says out loud. Give it the product's name and the first kind of thing your domain has — --kind shift, --kind work-order — and it writes chapter one for that domain rather than for a placeholder.

graview create <dir> [--name "Field Notes"] [--kind note] [--plural notes]

      --name <text>      the product's name (default: from <dir>)
      --kind <slug>      the first node kind (default: item)
      --plural <slug>    its plural (default: <kind>s)
      --link <path>      consume the framework from a sibling checkout by
                         path rather than from a registry
      --pm pnpm|npm      the package manager (default: whichever ran this)
      --port <n>         the dev server port (default: 5170)
      --accent <#hex>    the brand accent (default: a worked green)
      --no-install       write the files and stop
      --no-skills        do not install the authoring skills
      --no-git           do not initialize a git repository
      --workspace        the layout every real product ends up with: a
                         workspace root with the app under app/ and the
                         harness scripts at the root
      --merge            write only the files that do not exist yet, and
                         name every collision without touching it
      --force            write into a directory that is not empty
      --template <file|url>
                         start from a template made anywhere (Graview
                         Cloud's graview-template shape): the project keeps
                         its document as src/domain/app.json and the
                         template as template.json, for `graview apply
                         --template` to set a store up from. Named after
                         the template unless --name says otherwise. The
                         views it comes with are written to views/ from
                         views/<template id>/<name>.js (or .html) beside it.

What it writes (22 files)

The declaration split into domain and UI, so the domain has no React in it and graview check can read it headless. src/domain/ is the whole surface you will work in; the shell in src/ui/ is eighty lines made of framework parts, and every one of them can be replaced.

  • package.json
  • tsconfig.json
  • tsconfig.build.json
  • vite.config.ts
  • index.html
  • embed.html
  • .gitignore
  • README.md
  • AGENTS.md
  • CLAUDE.md
  • src/domain/schema.ts
  • src/domain/mutations.ts
  • src/domain/invariants.ts
  • src/domain/brand.ts
  • src/domain/app.ts
  • src/ui/views.tsx
  • src/ui/app.tsx
  • src/ui/pages.tsx
  • src/main.tsx
  • src/embed.tsx
  • tests/domain.test.ts
  • .github/workflows/ci.yml

Dependencies: @graview/core, @graview/layout, @graview/tools, @graview/render, @graview/react, @graview/primitives, @graview/pages, @graview/ship, @graview/embed, @graview/studio, @graview/guest, react, react-dom. Dev: graview, @types/node, @types/react, @types/react-dom, typescript, vite, vitest. No zod of your own — @graview/core re-exports z, so a kind's fields are built with exactly the copy the framework was built with.

The scripts it gives you

ScriptRuns
npm run devvite
npm run typechecktsc -p tsconfig.json
npm run testvitest run
npm run build:domaintsc -p tsconfig.build.json
npm run buildnpm run build:domain && vite build
npm run checknpm run build:domain && graview check ./dist/domain/app.js
npm run docsnpm run build:domain && graview docs ./dist/domain/app.js --out docs
npm run servenpm run build:domain && graview serve ./dist/domain/app.js --data data
npm run mcpnpm run build:domain && graview mcp ./dist/domain/app.js --data data
npm run skillsgraview skills install .
npm run verifynpm run typecheck && npm run test && npm run build && npm run check && graview docs ./dist/domain/app.js --out docs

Start with verify — typecheck, tests, build and graview check, in that order — and then dev: the scene at the root, the routed face at /pages.

The loop from there

Open a session beside the declaration. The skills are already installed where Claude Code and Codex look for them, and the first one to read is graview-node-kind. Describe a kind; let the model draft its fields, its edges, its acts and its rule; run graview check; look at the picture; declare more. The checker tells you both when a shape is wrong, in words, before a page does.

One release, run from the project

Every @graview/* package and graview are one release: pin them all to the same version, and run graview doctor when something will not start — it says a pin, a lockfile, an install or a document that is on another release, and a react beside a react-dom of another version, which React refuses at startup with a blank page.

Run the project's own graview (node_modules/.bin/graview, pnpm exec graview) rather than npx -y graview@<version>: inside a pnpm workspace that already holds that release in its hidden hoist, npx skips the install, finds no bin and says sh: graview: command not found.

Holding only a document and a snapshot, graview preview app.json --seed seed.json draws the scene and Pages over them with nothing built, and graview shots photographs its places.

Working on the framework itself

A product can consume a checkout of the framework by path instead of a registry, the way the first-party examples do: build the framework, then pnpm graview create ../my-app --link .. The project resolves every @graview/* import into the checkout's dist/, and its dev server rebuilds when the framework does.

$git clone https://github.com/en-dash-consulting/graview && cd graview
$pnpm install && pnpm buildevery package
$pnpm graview create ../my-app --link . --name "My App" --kind thing
$pnpm dev:seedbedthe garden — ?chapter=N opens any chapter