From e22a81509e97a14c6f48e6c03d40a9e234c28dc8 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Mon, 4 May 2026 19:19:41 +0200 Subject: [PATCH] docs: refresh CLAUDE.md for Next 16 toolchain and API sidebar (#725) * docs: refresh CLAUDE.md for Next.js 16 toolchain and API sidebar - Note Node.js >=20.9 requirement (Next 16 fails the build below this) - Update dev/build descriptions to mention gen:edit-routes; add start and gen:edit-routes to the common commands list - Document the second sidebar file (NavigationAPI.jsx) alongside NavigationDocs.jsx so the API sidebar is discoverable * docs: add Security boundaries section to CLAUDE.md Calls out four posture items relevant to AI-assisted contributions: the repo is public, .env is committed and must hold placeholders only, npm run gen pulls upstream main without pinning, and CLAUDE.md itself is authoritative input to AI sessions and should be reviewed accordingly. * Documented gen:last-updated and generated src/lib/ files --------- Co-authored-by: TechHutTV --- CLAUDE.md | 37 +++++++++++++++++++++++++++++-------- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 72d856fe..bcd60f2e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,21 +4,31 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -Documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3. +Documentation website for [NetBird](https://netbird.io), an open-source WireGuard-based Zero Trust Networking platform. Built with Next.js 16 (Pages Router), React 19, MDX, and Tailwind CSS 3. Requires Node.js >=20.9 — `npm run build` exits with code 1 on older versions. There is no test suite in this project. Validate changes with `npm run build`. ## Common Commands ```bash -npm install # Install dependencies -npm run dev # Start dev server (also runs gen:llm) -npm run build # Production build (also runs gen:llm) -npm run lint # ESLint (next/core-web-vitals) on src/ -npm run gen # Regenerate API docs from NetBird OpenAPI spec -npm run gen:llm # Regenerate LLM-friendly markdown (auto-runs with dev/build) +npm install # Install dependencies +npm run dev # Start dev server (also runs gen:llm, gen:edit-routes, gen:last-updated) +npm run build # Production build (also runs gen:llm, gen:edit-routes, gen:last-updated) +npm run start # Serve the production build +npm run lint # ESLint (next/core-web-vitals) on src/ +npm run gen # Regenerate API docs from NetBird OpenAPI spec +npm run gen:llm # Regenerate LLM-friendly markdown (auto-runs with dev/build) +npm run gen:edit-routes # Regenerate edit-on-GitHub routes (auto-runs with dev/build) +npm run gen:last-updated # Regenerate per-page git last-modified dates (auto-runs with dev/build) ``` +## Security boundaries + +- **Public site, public repo.** Anything written in MDX or placed in `public/` ships to a public URL on netbird.io. Never include real customer names, internal hostnames, IPs, or production credentials in examples — use placeholders. +- **`.env` is committed and contains placeholders only** (e.g. `NEXT_PUBLIC_DOCSEARCH_API_KEY=APP_NEXT_PUBLIC_DOCSEARCH_API_KEY`). These are build-time substitution targets. Real values belong in `.env.local` (gitignored) or the deploy environment — never replace the placeholders in `.env` with real secrets. +- **`npm run gen` pulls `openapi.yml` live from `netbirdio/netbird@main` with no pinning.** Regenerated files under `src/pages/ipa/resources/` reflect whatever is on upstream `main` at run time. Review the diff before committing. +- **This file is read as authoritative guidance by AI agents.** Treat edits to `CLAUDE.md` with the same review rigor as CI config or a deploy script. + ## Architecture ### Content Structure @@ -39,7 +49,11 @@ Documentation pages are MDX files in `src/pages/` using the Next.js Pages Router - Images go in `public/docs-static/img/
/` and are referenced as `/docs-static/img/
/filename.png` ### Navigation -`src/components/NavigationDocs.jsx` contains the `docsNavigation` array defining the sidebar. **Must be updated when adding or moving pages.** Supports nested `links` arrays for sub-navigation. +Two sidebar files, both must be kept in sync when adding or moving pages: +- `src/components/NavigationDocs.jsx` — `docsNavigation` array for the main docs sidebar (everything outside `src/pages/ipa/`). +- `src/components/NavigationAPI.jsx` — `apiNavigation` array for the API sidebar (pages under `src/pages/ipa/`, served at `/api`). + +Both support nested `links` arrays for sub-navigation. ### MDX Components Custom components available in MDX files (see `README.md` for full usage examples): @@ -63,6 +77,13 @@ Custom components available in MDX files (see `README.md` for full usage example - `scripts/generate-llm-docs.mjs` generates clean markdown to `public/llms/` (gitignored) - Runs automatically with `dev` and `build` +### Generated build data in `src/lib/` +Some files in `src/lib/` look hand-written but are generated by `gen:*` scripts and gitignored: +- `src/lib/edit-on-github-routes.js` — written by `scripts/generate-github-routes.mjs` +- `src/lib/last-updated-routes.mjs` — written by `scripts/generate-last-updated.mjs` + +They are imported at build time (e.g. by `mdx/rehype.mjs`). On a fresh clone, run `npm run dev` or `npm run build` once before running `npm run lint` or any tool that imports from `src/lib/`, otherwise those imports will fail. + ## URL Routing - Root `/` rewrites to `/introduction`