Skip to content
Screenbook

Quick Start

This guide will walk you through creating your first screen definition and viewing it in the Screenbook UI.

  1. Create a screen.meta.ts file

    Create a screen.meta.ts file alongside your route/page file:

    src/pages/dashboard/screen.meta.ts
    import { defineScreen } from "screenbook"
    

    export const screen = defineScreen({
      id: "dashboard",
      title: "Dashboard",
      route: "/dashboard",
      owner: ["platform-team"],
      tags: ["core"],
    })

  2. Build the screen catalog

    Run the build command to generate the screen metadata:

    Terminal window
    npx screenbook build

    This creates:

    • .screenbook/screens.json - All screen metadata
    • .screenbook/graph.mmd - Navigation graph in Mermaid format
    • .screenbook/coverage.json - Coverage statistics

  3. Start the development server

    View your screens in the Screenbook UI:

    Terminal window
    npx screenbook dev

    Open http://localhost:4321 to see your screen catalog.

  4. Add navigation relationships

    Define how screens connect to each other:

    src/pages/dashboard/screen.meta.ts
    export const screen = defineScreen({
      id: "dashboard",
      title: "Dashboard",
      route: "/dashboard",
      owner: ["platform-team"],
      tags: ["core"],
      next: ["settings", "profile"],  // Screens this page links to
    })
    src/pages/settings/screen.meta.ts
    export const screen = defineScreen({
      id: "settings",
      title: "Settings",
      route: "/settings",
      owner: ["platform-team"],
      tags: ["core"],
      entryPoints: ["dashboard"],  // Screens that link here
    })

  5. View the navigation graph

    Rebuild and refresh the UI to see the navigation graph:

    Terminal window
    npx screenbook build
    npx screenbook dev

    Navigate to the Graph view to see how your screens connect.

Auto-generate screen.meta.ts files

Section titled “Auto-generate screen.meta.ts files”

If you have many routes, you can auto-generate screen.meta.ts files:

Terminal window
npx screenbook generate

This scans your route files and creates skeleton screen.meta.ts files that you can customize.

Next Steps

Section titled “Next Steps”