use-reset-atom.mdx Documentation

1. Project Overview & Quickstart (pmndrs/use-reset-atom.mdx) Copy Chapter

use-reset-atom.mdx

Open-source repository pmndrs/use-reset-atom.mdx

Repository Details Copy Section

• Repository: pmndrs/use-reset-atom.mdx
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (pmndrs/docs) Copy Chapter

File: docs/getting-started/introduction.mdx Copy Chapter

title: pmndrs/docs nav: 0 Copy Chapter

@pmndrs/docs
storybook
storybook
playwright

A static MDX documentation generator, with a GitHub reusable workflow. It is primarily used for some pmndrs/* projects, but will work for anyone.

Those projects are known to be using this generator.

INSTALL Copy Chapter

$ git clone https://github.com/pmndrs/docs.git
$ cd docs

$ nvm install
$ nvm use
$ node -v # make sure your version satisfies package.json#engines.node

$ pnpm install

Configuration Copy Chapter

Environment variables configure the website. For MDX extensions, add docs.config.ts in the current working directory: components registers React components and scope exposes named data. Both fields are optional. See Custom components and data for the typed configuration and a live example.

[!IMPORTANT]

Variables default to "" (empty) unless a fallback is documented below.

* Required

Readers can re-seed THEME_PRIMARY, THEME_SCHEME, THEME_CONTRAST and THEME_COLOR_MATCH from the theme controls in the sidebar. An overridden control is outlined, and a double-click (or Delete) brings the site's value back.

MDX_BASEURL

Given a advanced/introduction.mdx file in the MDX folder:

![](dog.png)

becomes (for a MDX_BASEURL=http://localhost:60141 value):

![](http://localhost:60141/advanced/dog.png)

http://localhost:60141 being the MDX folder served.

[!TIP]
When deployed on GitHub Pages, MDX_BASEURL will typically value something like https://github.com/pmndrs/uikit/raw/main/docs, thanks to build.yml rule.

THEME_*

We implement m3 design system, using material-theme-builder.

This is an embed iframe of material-theme-builder's <Mtb> story.

[!NOTE]

• Material Color for more information
• The defaults are pmndrs/design-system's palette: the lime #CAF543 under color match, a warm grey neutral, and seven colors every site gets as custom colors, lime, teal, cyan, purple, red, orange and yellow (<Color role="teal" />).
• THEME_PRIMARY is the seed: the secondary and tertiary colors are derived from it, unless the site gives its own (THEME_SECONDARY, THEME_TERTIARY). The neutral, neutral variant and error colors are the pmndrs ones, unless the site gives its own (THEME_NEUTRAL, THEME_NEUTRAL_VARIANT, THEME_ERROR).
• THEME_COLOR_MATCH (on unless "false") is Material Theme Builder's "Color match - Stay true to my color inputs": each core and custom color keeps its input's chroma instead of being toned down to the scheme's, so THEME_SCHEME is ignored and the scheme toggle is hidden while color match is on. Readers can toggle color match from the sidebar. A custom color with :blend is still harmonized first.

VERSION_*, LIB_VERSION, TAG_MATCH

• Label: git describe --tags (eg. v10.7.9, v10.7.9-3-ga1b2c3d), or @<shortsha> without tags. LIB_VERSION overrides it.
• TAG_MATCH narrows the tags:

• VERSION_URL_TEMPLATE enables the switcher: the label lists the branches, each leading to the same page on its deployment. Full public URL (base path included), with a placeholder:

• A hostname label holds 63 characters at most. When a long branch would overflow it, {branch:vercel} follows Vercel's own truncation, and {branch} keeps its slug's first 63 - (rest of the label) - 7 characters, drops a trailing -, and appends - and the first 6 hex characters of the branch name's SHA-256 (printf %s "$branch" | sha256sum | cut -c1-6): eg. claude/pages-shadcn-tailwind-prep-98d23c in https://design-system-git-{branch}-pmndrs.vercel.app becomes design-system-git-claude-pages-shadcn-tailwind-pr-2675d4-pmndrs. Outside the hostname, {branch} is never cut. To alias a deployment there, pmndrs-docs version-url prints the URL (--hostname: the hostname alone), or see the reusable workflow's version_hostname output.

• VERSION_PRODUCTION_BRANCH leads to VERSION_PRODUCTION_URL; every other branch shows a banner linking to production.

• Branches: the remote's, minus dependabot/, renovate/, changeset-release/. VERSION_BRANCHES replaces that filter, VERSION_BRANCHES_LIST the whole list. Read at build time.

[!IMPORTANT]

• The per-branch URLs are yours to create: Vercel's Git integration does, vercel deploy does not (vercel alias set, see ci.yml).
• Git needs full history and tags (fetch-depth: 0).

Usage Copy Chapter

dev Copy Section

This is dev.sh. The site listens on PORT (default 3000), the MDX folder on any free port, so several checkouts can run side by side:

$ (
  trap 'kill -9 0' SIGINT

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="docs"
  export NEXT_PUBLIC_LIBNAME_SHORT="docs"
  export BASE_PATH=
  export DIST_DIR=
  export OUTPUT=
  export HOME_REDIRECT=
  export MDX_BASEURL=http://localhost:$_PORT
  export SOURCECODE_BASEURL="vscode://file$(pwd)"
  export EDIT_BASEURL="vscode://file$(pwd)/docs"
  export NEXT_PUBLIC_URL=
  export ICON=
  export LOGO=gutenberg.jpg
  export GITHUB=https://github.com/pmndrs/docs
  export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
  export CONTRIBUTORS_PAT=

  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  pnpm run dev &

  wait
)

Then go to: http://localhost:3000

When running the engine against another repository, set both MDX and DOCS_CONFIG; the configuration is discovered from the working directory, not the MDX folder:

MDX=/path/to/library/docs DOCS_CONFIG=/path/to/library/docs.config.ts pnpm dev

[!TIP]
If HOME_REDIRECT= empty, / will not redirect, and instead displays an index of libraries.

build Copy Section

This is start.sh, same ports:

$ (
  trap 'kill -9 0' SIGINT

  # `next dev` leaves types pointing at `src/app/api`, which the export build moves aside
  rm -rf out .next/dev/types

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export MDX=docs
  export NEXT_PUBLIC_LIBNAME="docs"
  export NEXT_PUBLIC_LIBNAME_SHORT="docs"
  export BASE_PATH=
  export DIST_DIR=
  export OUTPUT=export
  export HOME_REDIRECT=
  export MDX_BASEURL=http://localhost:$_PORT
  export SOURCECODE_BASEURL=
  export EDIT_BASEURL=
  export NEXT_PUBLIC_URL=
  export ICON=
  export LOGO=gutenberg.jpg
  export GITHUB=https://github.com/pmndrs/docs
  export DISCORD=https://discord.com/channels/740090768164651008/1264328004172255393
  export CONTRIBUTORS_PAT=

  pnpm run build

  npx serve $MDX -p $_PORT --no-port-switching --no-clipboard &

  npx serve out -p $PORT &

  wait
)

http://localhost:3000

CLI Copy Section

The published CLI builds without cloning the engine. If your custom components import packages, install those dependencies in your repository first:

$ cd ~/code/pmndrs/react-three-fiber
$ (
  trap 'kill -9 0' SIGINT

  export PORT=${PORT:-3000}
  export _PORT=$(node -e 'const s = require("net").createServer().listen(0, () => { console.log(String(s.address().port)); s.close() })')

  export NEXT_PUBLIC_LIBNAME="React Three Fiber"
  export NEXT_PUBLIC_LIBNAME_SHORT="r3f"
  export BASE_PATH=/toto
  export HOME_REDIRECT=/getting-started/introduction
  export MDX_BASEURL=http://localhost:$_PORT
  export ICON=🇨🇭
  export GITHUB=https://github.com/pmndrs/react-three-fiber

  npx -y @pmndrs/docs@latest build docs docs/out --format website

  npx serve docs -p $_PORT --no-port-switching --no-clipboard &

  npx -y serve docs/out -p $PORT &

  wait
)

Then go to: http://localhost:3000

npx @pmndrs/docs@latest build --help lists the CLI flags, including --config for a configuration outside the repository root.

Both --format website and --format fragment use the same Next.js build and static export.
Fragments contain only the compiled document: no layout, stylesheet or script. The CLI
copies assets alongside folder fragments and preserves static Mermaid and Sandpack content.

$ npx @pmndrs/docs@latest build page.mdx
$ cat page.mdx | npx @pmndrs/docs@latest build

A single file or stdin writes HTML to stdout and build logs to stderr. These inputs also
run a full Next.js build. Consumer components and data use the same docs.config.ts as
the website.

Agents Copy Chapter

llms.txt dumps and the pmndrs MCP server moved to their own page: Agents.