polkadot-apps: Instructions file for Claude Code

CLAUDE.md

Follow the contributor guidelines in README.md.

Quick Reference

• Build: pnpm build
• Dev: pnpm dev
• Clean: pnpm clean
• Test: pnpm test
• Test with coverage: pnpm test:coverage
• Format: pnpm format
• Format check: pnpm format:check
• Generate descriptors: pnpm generate-descriptors
• Generate docs: pnpm docs

Key Conventions

• All packages live in packages/<name>/ and are scoped under @polkadot-apps/.
• Use in-source testing (if (import.meta.vitest) blocks) for unit tests. Separate tests/*.test.ts files are for integration tests only.
• Internal deps use "workspace:*", shared versions use "catalog:" from pnpm-workspace.yaml.
• Packages must be framework-agnostic pure TypeScript. No React/Vue imports in core packages.
• Biome handles formatting — do not use prettier or eslint.
• Changesets are required for any change to published packages. Run pnpm changeset and include the generated file in your commit.

Descriptors

• @polkadot-apps/descriptors provides per-chain subpath imports (e.g., @polkadot-apps/descriptors/bulletin). Each subpath is a separate papi build — no barrel import, no unnecessary chain metadata.
• Each chain lives in packages/descriptors/chains/<name>/ with its own .papi/polkadot-api.json config. pnpm generate-descriptors fetches metadata and runs papi generate per chain.
• Adding a new chain: (1) add papi add in scripts/generate.sh, (2) create chains/<name>/ with .papi/polkadot-api.json and package.json, (3) add chain to CHAINS in scripts/build.sh, (4) add subpath export in package.json.

Chain Client

• @polkadot-apps/chain-client offers two ways to connect:
  • BYOD (createChainClient): bring your own descriptors and RPCs. Zero overhead from unused chains.
  • Preset (getChainAPI): zero-config with built-in descriptors and RPCs for known environments (paseo, polkadot, kusama).
• Both return a ChainClient<T> with typed APIs per chain key, .raw for PolkadotClient access, and .destroy().
• @polkadot-api/sdk-ink is not a dependency of chain-client. Consumers who need contracts create InkSdk themselves: createInkSdk(client.raw.assetHub, { atBest: true }).
• isInsideContainerSync() is available from both @polkadot-apps/host and @polkadot-apps/chain-client for synchronous container detection in performance-critical code paths. The async isInsideContainer() (which uses product-sdk) remains the primary API.
• Bulletin RPC endpoints are imported from @polkadot-apps/host's shared chain config (BULLETIN_RPCS), not hardcoded in presets.
• Preset RPC endpoint lists in packages/chain-client/src/presets.ts are ordered live-first. @polkadot-api/ws-provider walks the array on connect and on unclean reconnects, so healthy providers belong at the top and recently-degraded ones at the bottom as fallbacks. Each dead entry at the top costs one "Unable to connect" log line per cold start; rotate rather than remove when a provider is transiently unhealthy so failover redundancy is preserved when it recovers.