# Development Setup

This page is for contributors and for anyone building Ox Content itself from source.

If you just want to use the plugin or APIs, go back to [Getting Started](./getting-started.md).

## Prerequisites

Before you begin, ensure you have the following installed:

| Requirement   | Version | Installation                                                                                   |
| ------------- | ------- | ---------------------------------------------------------------------------------------------- |
| **Rust**      | 1.95+   | Provided by `nix develop` (pinned in `rust-toolchain.toml`) or [rustup.rs](https://rustup.rs/) |
| **Node.js**   | 26+     | Provided by `nix develop` or managed via `devEngines.runtime` in `package.json`                |
| **Vite+**     | Latest  | Available as `vp` inside the dev shell                                                         |
| **wasm-pack** | Latest  | Provided by `nix develop`; needed when you run `vp run build:wasm`                             |

## Clone and Bootstrap

```bash
# Clone the repository
git clone https://github.com/ubugeeei-prod/ox-content.git
cd ox-content

# Enter the pinned development shell
nix develop

# Install JS dependencies
vp install

# Build all crates and packages
vp run build

# Run tests to verify installation
vp run test
```

## Workspace Tasks

Enter the pinned shell with `nix develop`, then run workspace tasks via `vp run <task>`.
The canonical task graph lives in `vite.config.ts`.

```bash
# Setup
vp install

# Building
vp run build
vp run build:rust
vp run build:rust-release
vp run build:napi
vp run build:npm
vp run build:wasm

# Testing
vp run test
vp run test:rust
vp run test:rust-verbose
vp run test:ts
vp run watch

# Code quality
vp run fmt
vp run fmt:check
vp run clippy
vp run lint
vp run check:panic-constructs
vp run ready

# Documentation
vp run doc:cargo
vp run doc:cargo-open
vp run deploy#docs

# Docs and examples
vp run dev
vp run dev:docs
vp run dev:playground
vp run playground
vp run integ-vue
vp run integ-react
vp run integ-svelte
vp run ssg-vite

# Benchmarks
vp run bench
vp run bench:rust
vp run bench:parse
vp run bench:bundle
```

## Project Structure

```text
ox-content/
├── Cargo.toml              # Workspace configuration
├── flake.nix               # Nix flake wiring (inputs, systems, module list)
├── tools/nix/              # Nix modules: dev shell, packages, vp wrapper, Blacksmith CLI
├── package.nix             # Nix build of the workspace binaries, via crane
├── rust-toolchain.toml     # Rust channel, components, and targets for Nix and rustup alike
├── package.json            # npm workspace metadata and devEngines runtime
├── vite.config.ts          # Vite+ workspace task graph
├── crates/                 # Rust crates
│   ├── ox_content_allocator/   # Arena allocator
│   ├── ox_content_ast/         # AST node definitions
│   ├── ox_content_parser/      # Markdown parser
│   ├── ox_content_renderer/    # HTML renderer
│   ├── ox_content_search/      # Full-text search engine
│   ├── ox_content_napi/        # Node.js N-API bindings
│   ├── ox_content_wasm/        # WebAssembly bindings
│   ├── ox_content_og_image/    # OG image generation
│   └── ox_content_lsp/         # Unified language server
├── npm/                    # npm packages
│   ├── vite-plugin-ox-content/       # @ox-content/vite-plugin
│   ├── vite-plugin-ox-content-vue/   # @ox-content/vite-plugin-vue
│   ├── vite-plugin-ox-content-react/ # @ox-content/vite-plugin-react
│   ├── vite-plugin-ox-content-svelte/# @ox-content/vite-plugin-svelte
│   ├── vite-plugin-ox-content-solid/ # @ox-content/vite-plugin-solid
│   ├── unplugin-ox-content/          # @ox-content/unplugin
│   └── vscode-ox-content/            # VS Code extension
├── editors/                # Editor integrations
│   ├── zed/                # Zed extension
│   └── neovim/             # Neovim plugin
├── examples/               # Usage examples
├── docs/                   # Documentation site
└── .github/workflows/      # CI/CD
```

## Running Tests

### All Tests

```bash
vp run test

# or
cargo test --workspace
```

### Specific Crates

```bash
cargo test -p ox_content_parser
cargo test -p ox_content_renderer
```

### With Output

```bash
cargo test --workspace -- --nocapture
```

## Running the Docs and Playground

```bash
# Start docs and playground together
vp run dev

# Only the docs site
vp run dev:docs

# Only the playground
vp run playground
```

Then open [http://127.0.0.1:4173](http://127.0.0.1:4173) for the docs site and [http://127.0.0.1:5173](http://127.0.0.1:5173) for the playground.

## Deploying the Docs to Void

Deploy the documentation site to Void with:

```bash
vp run deploy#docs
```

The task builds the Rust workspace and local npm packages before running
`void deploy`, and it uses a root base path so assets resolve correctly on
`https://ox-content.void.app`.

See [Docs Deployment](./deployment.md) for environment variables and overrides.

## Running Benchmarks

```bash
vp run bench
vp run bench:rust
vp run bench:parse
vp run bench:bundle
```

Absolute ceilings for fixture bundle gzip, rendered HTML gzip, build time,
initial requests, and runtime floors live in `tools/benchmarks/perf-budgets.json`.
After a JSON sweep, check them with:

```bash
node tools/benchmarks/bundle-size/measure.mjs --json /tmp/bundle.json
node tools/benchmarks/bundle-size/check-budgets.mjs --bundle /tmp/bundle.json
```

The PR Benchmark job runs that checker on head measurements. Raise a ceiling
in the same PR as the intentional growth, or apply the
`benchmark-regression-accepted` label. See [Performance](./performance.md).

For committed benchmark tables and charts, use the Blacksmith-backed docs
refresh workflow instead of a local machine:

```bash
gh workflow run benchmark-docs.yml --ref main -f runs=7
```

That workflow runs on `blacksmith-32vcpu-ubuntu-2404` and opens a PR with the
updated `README.md`, `docs/content/performance.md`, and benchmark SVGs. To run
the same generator locally, use:

```bash
vp run bench:docs
```

For quick remote checks against the Blacksmith testbox runner:

```bash
blacksmith auth login
TESTBOX_ID=$(blacksmith testbox warmup .github/workflows/testbox.yml --job testbox --idle-timeout 60)
blacksmith testbox run --id "$TESTBOX_ID" "vp run bench"
blacksmith testbox stop --id "$TESTBOX_ID"
```

The latest published benchmark snapshot lives on [Performance](./performance.md).

## Troubleshooting

### `cargo: command not found`

Ensure Rust is installed and in your `PATH`:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
```

### `nix: command not found`

Install Nix with the official installer, restart your shell, then re-enter the repo:

```bash
nix develop
```

### Build fails with linking errors

On Linux, you may need build essentials:

```bash
# Ubuntu / Debian
sudo apt-get install build-essential

# Fedora
sudo dnf groupinstall "Development Tools"
```

On macOS, install Xcode Command Line Tools:

```bash
xcode-select --install
```

### N-API build fails

Ensure you are on the expected Node.js version:

```bash
nix develop
node -v
vp run build:napi
```

If you manage Node.js outside Nix, match the `devEngines.runtime` version in `package.json`.

### `wasm-pack: command not found`

The WASM build task expects `wasm-pack` to be available:

```bash
nix develop
vp run build:wasm
```

If you are not using Nix, install `wasm-pack` manually and make sure `wasm32-unknown-unknown` is available through `rustup`.

## Getting Help

- [GitHub Issues](https://github.com/ubugeeei-prod/ox-content/issues)
- [Discussions](https://github.com/ubugeeei-prod/ox-content/discussions)