--- title: "Getting started with CRUMB" --- CRUMB is the GRAIN stack's guided-tour layer: it turns a folder of markdown files into a walkthrough that highlights real, live surfaces in your app, one at a time, using GRAIN's own traveling lamp. A tour never edits your app or your data; it only reads and highlights. The same tour doubles as an AI-review walkthrough (a "here's what changed, mark it verified" mode) when you flip it to dev mode. It is live in production on this site: the "Tour" entry point on the desk runs on this exact package. The full design reasoning is in [`PLAN.md`](https://github.com/tjakoen/grain/blob/main/packages/crumb/PLAN.md); this page is the fastest path from install to a running tour. ## Install CRUMB publishes to the public npm registry, alongside the rest of the GRAIN stack. There is nothing to configure first, no `.npmrc` and no token: ```sh bun add @tjakoen/crumb # or: npm install @tjakoen/crumb ``` CRUMB depends on `@tjakoen/grain` and `@tjakoen/mill`; both need to already be installed and wired into your app (CRUMB reuses GRAIN's lamp and MILL's frontmatter parser rather than shipping its own). ## Mount it over a tours folder CRUMB's library is transport-generic: `createCrumbRoutes` returns a plain `(pathname) => Promise` handler, the same shape MILL and PROOF use. Mount it in front of your own routing and let it fall through (`null`) for anything it doesn't answer: ```ts import { createCrumbRoutes } from "@tjakoen/crumb/routes.ts"; const crumbRoutes = createCrumbRoutes({ toursDir: "./content/tours", // a folder of tour .md files // prefix: "/crumb", // optional; defaults to "/crumb" }); // inside your request handler, before your own page routes: const fromCrumb = await crumbRoutes(pathname); if (fromCrumb) return fromCrumb; ``` That's the whole server-side wiring. `toursDir` is the only required option; `prefix` defaults to `/crumb` and only needs to change if that path collides with something else your app already serves. ## Serve the client assets `createCrumbRoutes` only serves tour *data* (parsed markdown as JSON). The client that actually drives the lamp and the popover, `crumb-live.js`, plus its stylesheet `crumb.css`, are static files inside the package. Your host resolves and serves them itself, the same way it serves any other static asset: ```ts import { fileURLToPath } from "node:url"; const CRUMB_LIVE = fileURLToPath(import.meta.resolve("@tjakoen/crumb/crumb-live.js")); const CRUMB_CSS = fileURLToPath(import.meta.resolve("@tjakoen/crumb/crumb.css")); ``` Then link `crumb.css` in your page `` and load `crumb-live.js` as a native ES module (`