Srcbook Documentation

Srcbooks are interactive programming notebooks based on the Node.js runtime. They are composed of two types of cells:

1. markdown cell: Used for literate programming to express ideas with rich markup.
2. code cell: Function as JS or TS files. You can execute them or export objects to be used in other cells.

Code cells can be run by clicking 'Run' or using the keyboard shortcut cmd + enter.

A srcbook is not a single document, but a real npm project stored on disk in ~/.srcbook/srcbooks/<randomid>/.

Each notebook directory contains:

• A package.json and tsconfig.json.
• A node_modules/ directory.
• Individual files for each code cell located under src/.
• A README.md in the .src.md format, which serves as the canonical source by linking to the cell files rather than inlining them.

Because it is a standard npm project, you can cd into the notebook directory and run code using standard node or npm commands.

Srcbook runs code within a Node.js process rather than a browser environment. This allows you to perform backend-oriented tasks that are typically restricted in browser-based notebooks (like Observable).

Key capabilities include:

• Opening database connections
• Spawning web servers
• Working directly with the file system
• Testing HTTP endpoints (similar to a scripting version of Postman)
• Exploring npm libraries and testing code logic

Because it is an execution environment, Srcbook can serve as an AI playground where AI-generated code can be immediately executed (with your explicit consent).

The .src.md format is a markdown-based structure designed for easy version control (diffing) and readability.

Key Characteristics & Limitations:

• Cell Boundaries: Cells are currently delimited using ###### (h6) headers. Note that any h6 used in standard prose will be interpreted as a cell boundary.
• Execution Model: srcbook uses a stateless execution model. Each cell runs in its own fresh process (using tsx). This means variables defined in one cell are not available in the next cell by default.
• Structure: The format expects a specific order for certain elements during encoding: the first cell is treated as the title, and the second cell is treated as the package.json position. Deviating from this order (e.g., adding a paragraph before the package.json marker) may cause errors during export.

To avoid hardcoding sensitive information, use the Srcbook secrets mechanism. Secrets are stored securely and accessed at runtime as environment variables via process.env.

const secret = process.env.SECRET_API_KEY
console.log(secret ? `The secret is: ${secret}` : 'SECRET_API_KEY not set')

You can quickly import pre-made example Srcbooks from the Srcbook hub using the npx command.

npx srcbook@latest import web-scraping-with-puppeteer

Tasks follow a linear lifecycle: TODO $\rightarrow$ IN_PROGRESS $\rightarrow$ DONE.

To update a task, edit the status field directly within the existing file. Do not move or rename the file, as the id serves as a stable reference for the task's history in git.

Srcbooks use the .src.md file extension.

• Exporting: Click the Export link in the top-level left menu to save your Srcbook as a Markdown file.
• Importing: You can import .src.md files directly into the application to run, modify, or re-export them.

Tasks are managed as individual Markdown files. Each task must follow a specific naming convention and include a YAML frontmatter block for metadata.

Naming Convention: Use the format NNNN-short-slug.md, where NNNN is a zero-padded, monotonically increasing ID.

Frontmatter Schema: Every task file must start with a YAML block containing the following keys:

• id: The zero-padded numeric ID.
• title: A short imperative title.
• status: The current state (TODO, IN_PROGRESS, or DONE).
• created: The creation date.
• area: The functional area (api, web, shared, cli, ci, docs, or format).

---
id: 0001
title: Short imperative title
status: TODO # TODO | IN_PROGRESS | DONE
created: 2026-07-29
area: api # api | web | shared | cli | ci | docs | format
---

The recommended way to run Srcbook is using npx (or your package manager's equivalent) to ensure you are always using the latest version without a permanent global installation.

To start the Srcbook server immediately, use the start command.

# Using npm
npx srcbook@latest start

# Using pnpm
pnpm dlx srcbook@latest start