@hrbrmstr/notebooks-create

A CLI tool for scaffolding Observable Notebooks 2.0 projects with customizable themes.

Installation

npm install -g @hrbrmstr/notebooks-create

Usage

create-notebooks <project-name> [--theme <theme>] [--use-db <db1,db2,...>]

Examples

# Create a project with the default "air" theme
create-notebooks my-notebook-project

# Create a project with a specific theme
create-notebooks my-notebook-project --theme dark
create-notebooks data-viz-project --theme observablehq
create-notebooks --theme slate analytics-dashboard

# Create a project with database support
create-notebooks my-data-project --use-db duckdb
create-notebooks analytics-project --use-db duckdb,postgres
create-notebooks full-stack-project --theme midnight --use-db duckdb,sqlite,postgres,snowflake,databricks,bigquery

Parameters

• <project-name> - Required. The name of your project (lowercase letters, numbers, hyphens, and underscores only)
• --theme <theme> - Optional. The Observable theme to use (defaults to "air")
• --use-db <db1,db2,...> - Optional. Comma-separated list of database drivers to include (duckdb, sqlite, postgres, snowflake, databricks, bigquery)

Available Themes

• air (default) - Clean, airy theme with lots of whitespace
• coffee - Warm brown tones for a cozy feel
• cotton - Soft, light theme with subtle colors
• deep-space - Ultra-dark theme with cosmic accents
• glacier - Cool blues and whites
• ink - High contrast black and white
• midnight - Dark theme with deep blue tones
• near-midnight - Very dark theme with blue accents
• ocean-floor - Deep ocean-inspired dark theme
• parchment - Warm, paper-like theme
• slate - Professional gray theme
• stark - Minimalist high-contrast theme
• sun-faded - Vintage, washed-out colors

Available Databases

When using --use-db, you can include support for the following databases:

• duckdb - DuckDB embedded analytical database
• sqlite - SQLite embedded database (bundled with Notebook Kit)
• postgres - PostgreSQL database connector
• snowflake - Snowflake cloud data warehouse connector
• databricks - Databricks lakehouse platform connector
• bigquery - Google BigQuery data warehouse connector

What Gets Created

When you run the command, it creates a new directory with the following structure:

my-project/
├── package.json         # Project configuration with Observable dependencies
├── README.md            # Project-specific documentation
├── .gitignore           # Git ignore rules
├── databases.json       # Database configurations (if --use-db specified)
├── data/                # Data directory for file-based databases (if applicable)
│   └── .gitkeep
└── docs/
    └── index.html       # Main notebook file with your chosen theme

Generated Files

package.json

• Configured with Observable Notebook Kit dependency
• Includes preview and build scripts
• Pre-configured with sensible defaults

docs/index.html

• Basic Observable notebook template
• Uses your specified theme
• Includes sample markdown and Plot.js visualization
• Ready to edit and expand

README.md

• Project-specific documentation
• Instructions for development workflow
• Links to Observable documentation
• Database configuration notes (if databases included)

databases.json (if --use-db specified)

• Pre-configured database connection settings
• Example configurations for each selected database type
• Requires updating with actual credentials before use

Development Workflow

After creating your project:

# Navigate to your project
cd my-project

# Install dependencies
npm install

# Start development server with live reload
npm run docs:preview

# Build for production
npm run docs:build

Requirements

• Node.js >= 18.0.0
• npm or yarn

Features

• Quick scaffolding - Get started with Observable Notebooks 2.0 in seconds
• Theme selection - Choose from 13 built-in Observable themes
• Database support - Optional integration with DuckDB, SQLite, PostgreSQL, and Snowflake
• Validation - Ensures valid project names, theme choices, and database types
• Best practices - Follows Observable project structure conventions
• Ready to use - Includes sample content and development scripts

Project Structure Details

Scripts

The generated package.json includes these npm scripts:

• docs:preview - Start a development server with live reload
• docs:build - Build your notebooks for production deployment

Dependencies

Projects are created with:

• @observablehq/notebook-kit - The core Observable Notebooks 2.0 runtime

When using --use-db, the following packages are added as needed:

• @duckdb/node-api - DuckDB driver (if duckdb selected)
• postgres - PostgreSQL driver (if postgres selected)
• snowflake-sdk - Snowflake driver (if snowflake selected)
• @databricks/sql - Databricks driver (if databricks selected)
• @google-cloud/bigquery - BigQuery driver (if bigquery selected)

Examples

Creating a Data Science Project

create-notebooks data-science-project --theme observablehq --use-db duckdb
cd data-science-project
npm install
npm run docs:preview

Creating a Dark-Themed Dashboard

create-notebooks analytics-dashboard --theme midnight
cd analytics-dashboard
npm install
# Edit docs/index.html to add your visualizations
npm run docs:preview

Creating a Full-Stack Data Project

create-notebooks full-data-project --use-db duckdb,postgres,snowflake,databricks,bigquery
cd full-data-project
npm install
# Update databases.json with your actual credentials
npm run docs:preview

Troubleshooting

Invalid Project Name

Project names must contain only lowercase letters, numbers, hyphens, and underscores:

# Valid names
create-notebooks my-project
create-notebooks data_viz_2024
create-notebooks user-analytics

# Invalid names
create-notebooks My-Project        # uppercase letters
create-notebooks data viz          # spaces
create-notebooks my@project        # special characters

Invalid Theme

If you specify an invalid theme, the tool will warn you and fall back to the default "air" theme:

create-notebooks my-project --theme invalidtheme
# Warning: "invalidtheme" is not a valid theme. Using "air" instead.
# Available themes: air, coffee, cotton, deep-space, glacier, ink, midnight, near-midnight, ocean-floor, parchment, slate, stark, sun-faded

Invalid Database Type

If you specify an invalid database type, the tool will warn you and skip it:

create-notebooks my-project --use-db mysql,duckdb
# Warning: "mysql" is not a valid database type. Skipping.
# Including database support for: duckdb

Directory Already Exists

The tool will not overwrite existing directories:

create-notebooks existing-project
# Directory existing-project already exists

Database Configuration

When using --use-db, a databases.json file is created with example configurations. You must update this file with your actual database credentials before using the database connections in your notebooks:

{
  "demo-postgres": {
    "type": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "your-username",
    "password": "your-password",
    "database": "your-database"
  },
  "demo-databricks": {
    "type": "databricks",
    "hostname": "your-workspace.cloud.databricks.com",
    "path": "/sql/1.0/warehouses/your-warehouse-id",
    "token": "your-access-token",
    "catalog": "demo",
    "schema": "default"
  },
  "demo-bigquery": {
    "type": "bigquery",
    "projectId": "your-project-id",
    "dataset": "demo_dataset",
    "keyFilename": "path/to/service-account-key.json",
    "location": "US"
  }
}

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Development Setup

git clone https://codeberg.org/hrbrmstr/notebooks-create.git
cd notebooks-create
npm install

Development Tasks

This project includes a justfile for common development tasks. Install just to use these commands:

# List all available tasks
just

# Test project creation locally (creates and cleans up automatically)
just test-local

# Test with a custom project name
just test-local my-test-project

# Publish to npm (assumes version is already bumped)
just publish

# Run a quick minimal test
just test-minimal

# Debug test (creates project without cleanup)
just test-debug

# Clean up any test projects
just clean

# Verify package.json is valid
just verify

Available Just Tasks

• default - Lists all available tasks
• test-local [project-name] - Tests project creation with theme and database options, then cleans up
• publish - Publishes the package to npm (checks npm login, uses --access public for scoped packages)
• test-debug [project-name] - Creates a test project without auto-cleanup for debugging
• clean - Removes any leftover test projects
• test-minimal - Quick smoke test with minimal options
• verify - Validates package.json structure

Testing Local Changes

# Make the script executable locally
chmod +x create.js

# Test it manually
./create.js test-project --theme dark

# Or use the justfile for automated testing
just test-local

Publishing a New Version

1. Bump the version in package.json
2. Update CHANGELOG.md with release notes
3. Run just publish to publish to npm
4. Create and push a git tag: git tag v0.2.0 && git push --tags

License

MIT License - see the LICENSE file for details.

Links

• Repository
• Issues
• Observable Notebooks 2.0 Documentation
• Observable Runtime

Author

boB Rudis - [email protected] - https://rud.is/