Reusable TypeScript components for rapidly developing applications within the Polkadot ecosystem.
| Package | Description |
|---|---|
@polkadot-apps/address |
Substrate and EVM address utilities — SS58/H160 encoding, validation, and conversion |
@polkadot-apps/bulletin |
TypeScript SDK for uploading and retrieving data on the Polkadot Bulletin Chain |
@polkadot-apps/chain-client |
Multi-chain Polkadot API client with typed access to Asset Hub, Bulletin, and Individuality chains |
@polkadot-apps/contracts |
Typed contract interactions for Solidity and ink! contracts on Polkadot |
@polkadot-apps/crypto |
Cryptographic primitives — symmetric encryption, key derivation, and NaCl operations |
@polkadot-apps/descriptors |
Pre-generated Polkadot API descriptors for Asset Hub, Bulletin, and Individuality chains |
@polkadot-apps/host |
Host container detection, provider routing, and storage access for Polkadot Desktop and Mobile environments |
@polkadot-apps/keys |
Hierarchical key derivation and session key management for Polkadot accounts |
@polkadot-apps/logger |
Structured, namespace-filtered logging for the @polkadot-apps ecosystem |
@polkadot-apps/signer |
Multi-provider signer manager — Host API, browser extensions, and dev accounts |
@polkadot-apps/statement-store |
Publish/subscribe client for the Polkadot Statement Store with host-first transport |
@polkadot-apps/storage |
Key-value storage abstraction with automatic host/browser backend detection |
@polkadot-apps/tx |
Transaction submission, lifecycle watching, and dev signers for Polkadot chains |
@polkadot-apps/utils |
Encoding utilities and token formatting for the @polkadot-apps ecosystem |
The skills/ directory contains skills that enable AI coding assistants to build Polkadot applications end-to-end using these packages — without requiring the user to write code.
| Skill | Packages Covered | Triggers On |
|---|---|---|
polkadot-app-builder |
Orchestrator | "build a Polkadot app", project scaffolding |
polkadot-chain-connection |
chain-client, descriptors, host | "connect to chain", "query state" |
polkadot-transactions |
tx, signer, keys | "submit transaction", "sign", "dev signer" |
polkadot-bulletin |
bulletin | "upload data", "Bulletin Chain", "CID" |
polkadot-statement-store |
statement-store | "pub/sub", "statement store", "topics" |
polkadot-utilities |
address, crypto, utils, storage, logger | "SS58", "encrypt", "format token", "key-value store" |
See the examples/ directory for sample apps and E2E test packages built with these packages:
examples/multi-chain-explorer/ — CLI app that queries Paseo chain state, balances, and submits a remark transaction.examples/t3rminal-lite/ — Next.js web app demonstrating wallet connection, address display, and transaction submission.tx-demo, signer-demo, contracts-demo, statement-store-demo, bulletin-demo, host-demo, storage-demo, chain-client-demo, keys-demo) that exercise each package's Host API path end-to-end.Copy the skills into your project's .claude/skills/ directory:
# From within your project directory
cp -r /path/to/polkadot-apps/skills/* .claude/skills/
Skills are auto-discovered on session start. Invoke directly with /polkadot-app-builder or let Claude use them automatically when you describe what you want to build.
Add the skill content as project rules. In your project root, create .cursor/rules/:
mkdir -p .cursor/rules
cp /path/to/polkadot-apps/skills/polkadot-app-builder/SKILL.md .cursor/rules/polkadot-app-builder.md
cp /path/to/polkadot-apps/skills/polkadot-chain-connection/SKILL.md .cursor/rules/polkadot-chain-connection.md
# ... repeat for each skill you need
Or add the skills/ directory path to .cursorrules so Cursor indexes the content.
Add the skills as Windsurf rules. Copy SKILL.md files into .windsurfrules/ in your project:
mkdir -p .windsurfrules
cp /path/to/polkadot-apps/skills/polkadot-app-builder/SKILL.md .windsurfrules/polkadot-app-builder.md
Add skills as custom instructions in .github/copilot-instructions.md or reference them via workspace settings:
mkdir -p .github
# Concatenate the skills you need into a single instructions file
cat /path/to/polkadot-apps/skills/polkadot-app-builder/SKILL.md > .github/copilot-instructions.md
For Copilot Chat, you can also reference skill files directly in conversation: @workspace /path/to/skills/polkadot-app-builder/SKILL.md.
Skills auto-activate via the activate_skill tool when installed as plugins. Copy the skills directory:
cp -r /path/to/polkadot-apps/skills ~/.gemini/skills
The skills are standard Markdown files with YAML frontmatter. To use them with any AI tool:
SKILL.md file for the relevant skillreferences/<file>.md, load those on demand for detailed API signaturesThe polkadot-app-builder skill is the best starting point — it routes to the other skills based on what you're building.
Full API documentation is available at paritytech.github.io/polkadot-apps.
bash setup.sh
pnpm build
pnpm test
| Command | Description |
|---|---|
pnpm build |
Build all packages (turbo respects the dependency graph) |
pnpm dev |
Start dev mode with watch |
pnpm test |
Run vitest across all packages |
pnpm test:coverage |
Run tests with coverage reporting |
pnpm format |
Auto-fix formatting with Biome |
pnpm format:check |
Check formatting without writing |
pnpm clean |
Remove build artifacts |
pnpm docs |
Generate API docs with TypeDoc |
pnpm --filter @polkadot-apps/<demo> test:e2e |
Run E2E tests for a specific demo package |
packages/<name>/src/.pnpm build (turbo respects the dependency graph).pnpm test (runs vitest across all packages).pnpm format (biome).Unit tests live alongside the code they test using vitest's in-source testing. Ex:
export function add(a: number, b: number): number {
return a + b;
}
if (import.meta.vitest) {
const { test, expect } = import.meta.vitest;
test("add", () => {
expect(add(1, 2)).toBe(3);
});
}
The if (import.meta.vitest) block is tree-shaken out of production builds. No separate test files needed for unit tests, though tests/*.test.ts files are also supported for integration tests.
E2E tests use Playwright with @parity/host-api-test-sdk to run each demo app inside a simulated Host container (Polkadot Desktop/Mobile). This tests the real Host API path — signing, chain connections, storage, preimages, and statement store — without requiring actual Polkadot Desktop.
# Run a single demo's tests
pnpm --filter @polkadot-apps/tx-demo test:e2e
# Run with headed browser (useful for debugging)
pnpm --filter @polkadot-apps/tx-demo test:e2e:headed
Each demo lives in examples/<name>-demo/ and follows the same structure: src/main.ts (app), e2e/*.spec.ts (tests), e2e/fixtures.ts (test host setup). All 9 demos run in CI via .github/workflows/e2e.yml.
packages/<name>/ with package.json, tsconfig.json, and src/index.ts.package.json must include:
"name": "@polkadot-apps/<name>""type": "module""publishConfig": { "access": "public" }"files": ["dist"]tsconfig.json must extend ../../tsconfig.json with outDir: "./dist" and rootDir: "./src"."workspace:*" for internal dependencies and "catalog:" for shared versions.This repo uses changesets for versioning.
To prepare a release:
pnpm changeset
Select the packages you changed, choose the semver bump level, and write a summary. This creates a changeset file in .changeset/. Commit it with your PR.
When the changeset lands on main, the release workflow consumes it, bumps versions, and publishes to npm.
.vscode/settings.json (install the Biome extension).pnpm format:check to verify locally, or pnpm format to auto-fix.react/ or vue/ packages (not yet created).