pokenav

A Pokémon route-map style navigation component for React. A trail of circular nodes connected by a dotted line, each node showing a pixelated sprite for a page or section — like walking a route on the world map.

Playground and docs → pokenav.devanshsoni.com · pokenav on npm

npm install pokenav

Want to own and edit the renderer source? Install the lightweight spriteUrl registry item:

npx shadcn@latest add https://pokenav.devanshsoni.com/r/pokenav.json

Use https://pokenav.devanshsoni.com/r/pokenav-pokemon.json when you need pokemonId; it installs the base source plus pokenav@^0.3.1 for catalogue resolution. Consumer-focused agent guidance is available at pokenav.devanshsoni.com/llms.txt.

Status: 0.3.1 is the current release. The config API is settled and everything documented is implemented — both ring styles, both trail paths, both orientations, accent-colour theming, scroll-linked trail fill, and the full 898-sprite catalogue behind the interactive picker.

The component ships from two entry points: pokenav resolves spriteUrl and is the one to reach for by default, pokenav/pokemon adds pokemonId and the bundled catalogue. The split keeps the 898 sprite chunks out of builds that never ask for a Pokémon. Since 0.2.0 the component is named Pokenav rather than Pallet; see the changelog for migration notes.

The published package is pokenav. The workspace folder is still packages/pallet, after Pallet Town where every journey starts — the internal layout doesn't have to match the published name. (pallet on npm was taken by an abandoned PureScript package manager, which is why the published name moved.)

Repo layout

packages/pallet/   pokenav — source, types, 898 bundled sprites, catalogue
apps/docs/         Next.js docs site — playground, sprite picker, written usage docs
scripts/           build-catalogue.mjs — regenerates catalogue.json from PokéAPI data

npm workspaces, no monorepo task runner. The package README and docs site are the public sources of truth for installation and component usage.

For the component's own API reference, see packages/pallet/README.md — that's the README published to npm.

Getting started

npm install          # installs all workspaces
npm run build        # builds packages/pallet (ESM + CJS + .d.ts via tsup)
npm run dev          # runs the docs site at http://localhost:3000

Other scripts:

Command	Does
npm run build:all	Builds every workspace that defines a build script.
npm run dev:pallet	Rebuilds the package on change (tsup --watch).
npm run typecheck	Typechecks every workspace.
npm run docs:check	Validates README code fences and local links.
npm test	Builds the package and runs its component/hook tests.
npm run build:docs	Builds the package, then the docs site.
npm run clean	Removes build output.

The docs app consumes pokenav from dist/, so run npm run build at least once before npm run dev. For live iteration on the component, run npm run dev:pallet alongside it.

Tests use Node's test runner through tsx, so the TypeScript suites work on the repository's Node 20 minimum as well as newer Node releases. Component and hook lifecycle tests use jsdom; no browser or global test-runner install is required.

Releasing

The package publishes from the packages/pallet workspace, and prepublishOnly runs the build so the tarball cannot contain stale dist/ output. Run the publish command from the repository root:

npm publish --workspace packages/pallet --access public --otp=<fresh-6-digit-code>

npm requires 2FA (or a granular access token with 2FA bypass) to publish. Follow the full change and release workflow for versioning, verification, commits, npm publishing, tags, and GitHub Releases.

Sprite assets and licensing

The code in this repo is MIT licensed — see LICENSE.

The Pokémon sprite assets bundled with the package are not original work and are not covered by that license. Read SPRITES-NOTICE.md for the full disclosure, the fan-tool precedent it relies on, and its limits. Every nav item accepts a spriteUrl, so you can use the component with entirely your own artwork and skip the bundled sprites completely.

Pokémon and all associated names are trademarks of Nintendo, Creatures Inc., GAME FREAK inc., and The Pokémon Company. This project is not affiliated with or endorsed by them.