NodeBooks

NodeBooks (nbks) is a JS/TS notebook environment. It supports editing Markdown and code cells, executing TypeScript/JavaScript, and streaming outputs to the browser in real time.

Features

📝 Edit Markdown and code cells
⚡ Run TypeScript/JavaScript in a sandboxed runtime
💻 Run collaborative terminal cells and commands
🌐 Execute HTTP requests
🗄️ Query databases with SQL
🤖 Conversational AI assistants
📈 Create interactive plots
📡 Stream outputs to the browser in real time
📦 Install and use npm dependencies per notebook
🔐 Notebook-scoped environment variables
🧩 Rich display components (tables, charts, images, alerts)
💾 Persistence: SQLite (bundled) and PostgreSQL
🌍 Multi-user collaboration

CLI (nbks)

The @nodebooks/cli workspace exposes an nbks binary for configuring and running the server locally.

npx @nodebooks/cli

or install it with:

npm install -g @nodebooks/cli

Configuration lives at ~/.config/nodebooks/nodebooks.toml (respects XDG_CONFIG_HOME on Linux).
The default SQLite database path resolves to:
- ~/Library/Application Support/nodebooks/nodebooks.sqlite on macOS
- %APPDATA%\nodebooks\data\nodebooks.sqlite on Windows
- $XDG_DATA_HOME/nodebooks/nodebooks.sqlite (or ~/.local/share/nodebooks/nodebooks.sqlite) on Linux

Project Layout

nodebooks/
├── apps/
│   ├── backend/              # @nodebooks/server – Fastify API with bundled Next.js client
│   ├── client/               # @nodebooks/client – Next.js 15 UI (Monaco-powered editor)
│   └── cli/                  # @nodebooks/cli – nbks command-line interface
├── packages/
│   ├── config/               # Shared config loaders and CLI helpers (builds to dist/)
│   ├── notebook-schema/      # Shared Zod models and notebook definitions (builds to dist/)
│   ├── runtime-host/         # Host utilities for coordinating runtimes (builds to dist/)
│   ├── runtime-node/         # Sandboxed Node.js runtime harness (builds to dist/)
│   ├── runtime-node-worker/  # Worker entrypoint for executing notebook cells (builds to dist/)
│   ├── runtime-protocol/     # Shared protocol definitions for runtime messaging (builds to dist/)
│   └── ui/                   # Reusable React UI components and styles

Requirements

Node 22.6+
pnpm 10 (Corepack-enabled Node images work out of the box)

Install dependencies

pnpm install

Development

Single-port dev (Fastify serves the Next.js UI):
- pnpm dev
- App: http://localhost:4000
API-only + separate Next.js dev (two terminals):
- Terminal 1 (API): pnpm api:dev (Fastify on http://localhost:4000)
- Terminal 2 (UI): pnpm ui:dev (Next.js on http://localhost:3000)
- The UI dev script is preconfigured with NEXT_PUBLIC_API_BASE_URL=http://localhost:4000/api.

Production

Build all workspaces, then start the server in production mode:

pnpm -w build
pnpm start

Server listens on HOST (default 0.0.0.0) and PORT (default 4000).
The backend serves the built Next.js UI by default.

Environment Variables

PORT – Port to bind (default 4000).
HOST – Host to bind (default 0.0.0.0).
NODEBOOKS_TERMINALS_ENABLED – Enable terminal cells (default 0). Supported values:
- 1 – Enable terminal cells.
- 0 – Disable terminal cells.
NODEBOOKS_KERNEL_TIMEOUT_MS – Kernel execution timeout in ms (default 10000).
NODEBOOKS_KERNEL_WS_HEARTBEAT_MS – Server→client WebSocket ping interval in ms to keep connections alive behind proxies with idle timeouts (default 25000).
NODEBOOKS_THEME – Theme to use for the UI (default light). Supported values:
- light – Light theme.
- dark – Dark theme.
NODEBOOKS_PERSISTENCE – Notebook persistence driver (sqlite default). Supported values:
- sqlite – Persist notebooks to the bundled sql.js database file.
- postgres – Use PostgreSQL via DATABASE_URL.
- in-memory – Ephemeral storage useful for local smoke tests.
DATABASE_URL – PostgreSQL connection string used when NODEBOOKS_PERSISTENCE=postgres.
NODEBOOKS_SQLITE_PATH – Path to the SQLite file for notebooks storage.

Docker

Build image: docker build -t nodebooks:latest .
Run (SQLite, ephemeral): docker run --rm -p 4000:4000 nodebooks:latest
Run (SQLite, persistent): docker run --rm -p 4000:4000 -v nodebooks_data:/app/apps/backend/data nodebooks:latest
Run (PostgreSQL): docker run --rm -p 4000:4000 -e NODEBOOKS_PERSISTENCE=postgres -e DATABASE_URL=postgres://user:pass@host:5432/db nodebooks:latest
Health check: curl http://localhost:4000/health returns { "status": "ok" }

Deploy to Heroku

One-click deployment:
Or manually:
- Create an app: heroku create
- Add PostgreSQL addon: heroku addons:create heroku-postgresql:essential-0
- Set env:
  - heroku config:set NODEBOOKS_PERSISTENCE=postgres
- Push: git push heroku HEAD:main (or your default branch)
- Open: heroku open

The repo includes app.json and Procfile for Heroku. The Node.js buildpack installs PNPM via Corepack, runs the monorepo build, and starts the Fastify server (pnpm start).

Testing & Quality

pnpm lint           # ESLint across workspaces
pnpm test           # Vitest across workspaces
pnpm format         # Prettier write
pnpm format:check   # Prettier verify only

License

MIT

License

julianduque/nodebooks

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Contributors 2

Uh oh!

Languages