開発環境のセットアップ#
このページは、コントリビューターと、Ox Content 自体をソースからビルドする人向けです。
プラグインや API を使うだけなら、はじめる に戻ってください。
前提条件#
始める前に、次がインストールされていることを確認してください。
| 要件 | バージョン | インストール |
|---|---|---|
| Rust | 1.95+ | nix develop が提供します（rust-toolchain.toml で固定）。または rustup.rs |
| Node.js | 26+ | nix develop が提供するか、package.json の devEngines.runtime で管理します |
| Vite+ | 最新 | 開発シェル内では vp として使えます |
| wasm-pack | 最新 | nix develop が提供します。vp run build:wasm を回すときに必要です |
クローンとブートストラップ#
# 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
ワークスペースタスク#
nix develop で固定シェルに入り、vp run <task> でワークスペースタスクを実行します。
正規のタスクグラフは vite.config.ts にあります。
# 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
プロジェクト構成#
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
テストを実行する#
すべてのテスト#
vp run test
# or
cargo test --workspace
特定の crate#
cargo test -p ox_content_parser
cargo test -p ox_content_renderer
出力付き#
cargo test --workspace -- --nocapture
ドキュメントとプレイグラウンドを動かす#
# Start docs and playground together
vp run dev
# Only the docs site
vp run dev:docs
# Only the playground
vp run playground
ドキュメントサイトは http://127.0.0.1:4173、プレイグラウンドは http://127.0.0.1:5173 を開いてください。
ドキュメントを Void へデプロイする#
ドキュメントサイトを Void へデプロイするには:
vp run deploy#docs
このタスクは void deploy の前に Rust ワークスペースとローカル npm パッケージをビルドし、https://ox-content.void.app でアセットが正しく解決されるようルートの base パスを使います。
環境変数と上書きは ドキュメントのデプロイ を見てください。
ベンチマークを実行する#
vp run bench
vp run bench:rust
vp run bench:parse
vp run bench:bundle
フィクスチャのバンドル gzip、描画 HTML gzip、ビルド時間、初期リクエスト、実行時下限の絶対天井は tools/benchmarks/perf-budgets.json にあります。JSON 掃引のあとに次で確認します。
node tools/benchmarks/bundle-size/measure.mjs --json /tmp/bundle.json
node tools/benchmarks/bundle-size/check-budgets.mjs --bundle /tmp/bundle.json
PR Benchmark ジョブは head の測定に対してこの検査を走らせます。意図した増大は同じ PR で天井を上げるか、benchmark-regression-accepted ラベルを付けます。パフォーマンス を見てください。
コミットするベンチマーク表とチャートには、手元のマシンではなく Blacksmith ベースの docs 更新ワークフローを使ってください。
gh workflow run benchmark-docs.yml --ref main -f runs=7
このワークフローは blacksmith-32vcpu-ubuntu-2404 で動き、更新した README.md、docs/content/performance.md、ベンチマーク SVG を含む PR を開きます。同じ生成器をローカルで回すには:
vp run bench:docs
Blacksmith の testbox ランナーに対する素早いリモート確認には:
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"
最新の公開ベンチマークスナップショットは パフォーマンス にあります。
トラブルシューティング#
cargo: command not found#
Rust がインストールされ、PATH に入っていることを確認してください。
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
nix: command not found#
公式インストーラーで Nix を入れ、シェルを再起動してからリポジトリへ入り直してください。
nix develop
リンクエラーでビルドが失敗する#
Linux ではビルド必須パッケージが必要になることがあります。
# Ubuntu / Debian
sudo apt-get install build-essential
# Fedora
sudo dnf groupinstall "Development Tools"
macOS では Xcode Command Line Tools を入れてください。
xcode-select --install
N-API ビルドが失敗する#
想定している Node.js バージョンであることを確認してください。
nix develop
node -v
vp run build:napi
Nix の外で Node.js を管理している場合は、package.json の devEngines.runtime のバージョンに合わせてください。
wasm-pack: command not found#
WASM ビルドタスクは wasm-pack が使えることを期待しています。
nix develop
vp run build:wasm
Nix を使っていない場合は、wasm-pack を手動で入れ、rustup 経由で wasm32-unknown-unknown が使えるようにしてください。