Development Setup
Install and build
Use a supported Node 24 release matching the package's engine range. The repository includes .nvmrc with major version 24.
git clone https://github.com/rafaself/neko-search.git
cd neko-search
nvm use
npm ci
npm run buildThe npm workspaces include the documentation engine, indexer, and private website. Keep package-lock.json as the dependency lockfile.
The root build compiles the engine, indexer, and production CLI, and prepares the builder runtime needed by CLI commands. It does not download NestJS documentation or build the website.
npm run start:nekosearch -- --help
npm testThe Jest suite builds the application through its global setup. It includes unit, integration, and stdio end-to-end coverage. See Contributing for the required completion checks.
Documentation website
npm run docs:site:devOpen the local URL printed by VitePress. Production build and preview are separate:
npm run docs:site:build
npm run docs:site:check
npm run docs:site:previewThe source is Markdown under apps/docs-site/docs, with VitePress configuration and a small theme extension in the app's .vitepress directory. Static assets live in the app's public directory. Output is apps/docs-site/.vitepress/dist and is ignored by Git.
docs:site:check checks the generated HTML's local navigation, fragment targets, and asset references. Run it after building. Browser checks are still needed for search, mobile menus, and appearance.
VitePress and Vue are development dependencies of the private site workspace. They are not CLI runtime dependencies. The site uses VitePress's built-in local search; no search account, API key, backend, or database service is needed.
Deployment configuration
| Environment variable | Default | Purpose |
|---|---|---|
DOCS_SITE_BASE | / | Absolute deployment path, with leading and trailing slashes |
DOCS_SITE_URL | https://nekosearch.pages.dev | HTTP(S) deployment origin, without a path, credentials, query, or fragment |
For a local build targeting a project site under a subpath, override both values:
DOCS_SITE_URL=https://docs.example.com DOCS_SITE_BASE=/nekosearch/ npm run docs:site:build
DOCS_SITE_BASE=/nekosearch/ npm run docs:site:check
DOCS_SITE_BASE=/nekosearch/ npm run docs:site:previewThe production build emits canonical URLs, absolute sharing-image URLs, and a sitemap for https://nekosearch.pages.dev/. DOCS_SITE_URL can override that origin for a preview deployment.
Keep the same base when building, checking, and previewing. The output uses .html page files so static hosts can serve clean routes without rewrite rules.
Publish with Cloudflare Pages
The Publish documentation GitHub Actions workflow is manual. It builds and checks the site, creates the Cloudflare Pages Direct Upload project named nekosearch on the first run if needed, then uploads the static output with Wrangler. It only publishes the main branch and never deploys on a push.
Before the first deployment:
- Create a Cloudflare API token with Account → Cloudflare Pages → Edit permission.
- In the GitHub repository, add Actions secrets named
CLOUDFLARE_ACCOUNT_IDandCLOUDFLARE_API_TOKENwith the matching Cloudflare values.
Then open Actions → Publish documentation → Run workflow, choose main, and start the run. Cloudflare must have the nekosearch project name available for the site to receive the nekosearch.pages.dev address. Cloudflare Direct Upload projects cannot later be switched to Git integration, so keep this project on Direct Upload for manual workflow publishing. See Cloudflare's Direct Upload guide and GitHub Actions setup.
Existing snapshot scripts
The existing root commands docs:build, docs:ingest, docs:build:mcp, and search:index operate on indexed documentation. They are separate from the docs:site:* website scripts.
Use the public CLI's build for portable local snapshots. Contributor-level indexer commands expose the specialized ingestion/build pipeline; inspect their command handlers and configuration schemas before changing them. Product website development does not require rebuilding external documentation snapshots.
