npm package: @hrbrmstr/notebooks-create
Description: Create Observable Notebooks 2.0 projects
Author: boB Rudis
Latest version: 0.3.0

# @hrbrmstr/notebooks-create

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

## Installation

```bash
npm install -g @hrbrmstr/notebooks-create
```

## Usage

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

### Examples

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

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

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

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

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

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

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

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

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

```json
{
  "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

```bash
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](https://github.com/casey/just) to use these commands:

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

```bash
# 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](./LICENSE) file for details.

## Links

- [Repository](https://codeberg.org/hrbrmstr/notebooks-create)
- [Issues](https://codeberg.org/hrbrmstr/notebooks-create/issues)
- [Observable Notebooks 2.0 Documentation](https://observablehq.com/documentation)
- [Observable Runtime](https://github.com/observablehq/runtime)

## Author

**boB Rudis** - [bob@rud.is](mailto:bob@rud.is) - [https://rud.is/](https://rud.is/)