KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

nodebooks

★ 31 Open GitHub ↗

Interactive Node.js Notebooks

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# NodeBooks

![NodeBooks Logo](https://raw.githubusercontent.com/julianduque/nodebooks/main/apps/client/public/assets/nodebooks-logo-64x64.png)

NodeBooks ([nbks](https://nbks.dev)) 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.

```bash
npx @nodebooks/cli
```

or install it with:

```bash
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

```bash
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:

```bash
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:

[![Deploy to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/julianduque/nodebooks)

- 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

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

## License

MIT

nodebooks

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README