Contributing

Contribute code, modules, templates, or documentation to 86d. Setup, the development loop, the bar for pull requests, and how to publish modules.

86d welcomes contributions. The codebase is intentionally shaped so it is easy to make small focused changes, and we try hard to give every contributor a fast review.

The main repositories you can contribute to are 86d-app/86d, which contains the framework (including the store app, modules, CLI, and packages), and 86d-app/docs, which hosts the documentation (this site).

Setting up the framework repo

git clone https://github.com/86d-app/86d
cd 86d
bun install
86d init

Run 86d doctor to verify the project is healthy before you make changes.

Development loop

Five health gates have to pass before a pull request can merge:

bun run typecheck   # TypeScript
bun run check       # Biome lint + format
bun run test        # Vitest unit tests
bun run test:e2e    # Playwright + visual snapshots
bun run build       # Production build

Run them locally and fix everything they flag. CI runs the same five.

What good pull requests look like

• One coherent change per PR. A bug fix, a new endpoint, a new module, a docs improvement. Not all four at once.
• Tests for every code change. New endpoint -> add Vitest tests. UI change -> update Playwright snapshots. Bug fix -> add a regression test.
• A real description. What problem the PR solves, why this approach, what alternatives you considered, what is not yet covered.
• Changesets entry. For changes that affect a published package, run bunx changeset and commit the generated file. CI will reject PRs without one when one is needed.

Coding standards

• No any, @ts-expect-error, @ts-ignore, or biome-ignore. Fix the underlying type or code.
• No edits to tsconfig.json, biome.json, or other config files to silence errors. If a rule does not fit, raise it; do not bypass it.
• Primitive components are sacred. shadcn/ui, Base UI, Radix UI, React Aria. Wrap or compose, never modify.
• Never delete or weaken a passing test to make a new change pass.
• Biome handles formatting. bun biome check --write src/ to auto-fix.

Writing a module

Scaffold and iterate:

86d module create my-feature
86d module enable my-feature
86d generate
bun test --filter @86d-app/my-feature

For a module to be considered complete:

• Real schema with proper types and relations
• Storefront and admin endpoints, fully implemented (no TODO bodies)
• Loading, error, and empty states in any UI components
• Vitest tests for critical paths with realistic fixtures
• For external API integrations: real HTTP calls, retries, error mapping, webhook signature verification
• Playwright visual snapshots for any new admin or storefront screen, in light + dark mode, desktop + mobile

See Build a custom module.

Publishing community modules

You do not need to upstream a module to publish it. Follow the standard pattern:

1. Build with bun run build.
2. Set "private": false and a stable version in package.json.
3. Add "86d-app" plus the relevant category to keywords so it surfaces in registry search.
4. Publish: npm publish --access public.

Anyone can then install your module:

86d module add npm:@your-scope/your-module

If you want to propose your module for inclusion in the official registry, open an issue describing the module, its category, and its API surface.

Documentation contributions

Docs live in their own repo at 86d-app/docs. Every page is an .mdx file with YAML frontmatter. Clone the repo and run a local Mintlify preview:

git clone https://github.com/86d-app/docs
cd docs
npm i -g mint
mint dev

The bar for docs PRs:

• Active voice. “Run the command” not “the command should be run.”
• Sentence case for headings.
• No em dashes. Use a comma, a colon, a semicolon, parentheses, or a sentence break instead.
• Include working examples. If you reference a CLI command or an API endpoint, paste the exact form and verify it runs.

Releasing the framework

Maintainers cut releases by merging an aggregated Changesets PR generated by CI. See release in package.json. Module publishes use --provenance so consumers can verify package integrity.

Code of conduct

Be kind. Assume good faith. Disagree about ideas, not people. We follow the Contributor Covenant 2.1.

Reporting security issues

Use GitHub Security Advisories rather than public issues for any security-relevant report.

Where to get help

• Discussions: github.com/86d-app/86d/discussions for design proposals and open questions.
• Issues: github.com/86d-app/86d/issues for bugs and feature requests.

We try to triage every new issue or discussion within a few business days.