---
title: "Contributing"
image: "https://adonia.pages.dev/og.png"
version: "next"
---

> Documentation Index
> Fetch the complete documentation index at: https://adonia.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

Adonia is a pnpm monorepo containing the server runtime, React renderer, developer tools,
adapters, reference plugins, a VitePress site, and a complete AdonisJS example. This guide
covers the repository workflow and the checks expected for each kind of change.

Adonia is currently pre-release. Public APIs are being reviewed for 1.0, while descriptor
protocol v1 is already closed to breaking changes. Changes to protocol behavior, package
exports, authorization, persistence, or generated application code need corresponding
contract evidence rather than only an implementation patch.

## Prerequisites

Use the same baseline as CI and the example application:

- Node.js 24 or newer
- pnpm 10.13.1 through Corepack
- Git
- SQLite for the default local example path
- PostgreSQL 17, MySQL 8.4, Redis, or Meilisearch only when working on the integration that needs it

Set up the workspace:

```sh
corepack enable
pnpm install
pnpm build
```

`pnpm install` includes every package, `examples/blog-admin`, and `docs/site` through
`pnpm-workspace.yaml`. Do not install dependencies separately inside a workspace.

## Repository map

| Path | Responsibility |
| --- | --- |
| `packages/core` | Panel/resource authoring APIs, HTTP runtime, query and validation pipelines, serialization, authorization, testing helpers |
| `packages/ui` | Generic Inertia pages, React renderer and registry, hooks, theme, styles |
| `packages/devtools` | Configure hook, Ace commands, code generators, stubs, doctor checks |
| `packages/queue-bullmq` | BullMQ adapter for queued actions |
| `packages/meilisearch` | Meilisearch search driver |
| `packages/activity-log` | Activity log reference plugin, published as `adonia-activity-log` |
| `packages/import-export` | Import/export reference plugin, published as `adonia-import-export` |
| `examples/blog-admin` | Tutorial source, functional fixture, and end-to-end application |
| `templates/adonia-starter` | Reusable starter content and installation smoke-test input |
| `docs` | Guides, generated reference, specification, protocol, ADRs, security and release evidence |
| `docs/site` | VitePress configuration and documentation generators |
| `fixtures/protocol` | Versioned descriptor fixtures |
| `scripts` | Fresh-install, release, bundle, performance, and documentation gates |

## Design contracts

Before changing a subsystem, read its guide and the linked normative section. The following
invariants shape most reviews:

1. **The server owns behavior.** React renders descriptors; it does not recreate resource,
   visibility, authorization, or validation decisions.
2. **Descriptors are data.** Functions do not cross the wire. Dynamic behavior is exposed
   through named capabilities and URLs.
3. **One tree drives all write contracts.** Projection, state keys, VineJS validation, and
   the persistence allowlist must remain aligned.
4. **Unauthorized means absent.** A forbidden node and its value must not survive in a
   descriptor, initial state, validator, fill set, search result, action, or export.
5. **Protocol v1 does not break.** Additive component and capability registration is valid;
   changing existing node meaning or wire shape requires the protocol/RFC process.
6. **AdonisJS owns framework instances.** Host integrations stay peer dependencies so the
   application owns AdonisJS, Lucid, VineJS, React, and Inertia instances.
7. **Installation is idempotent.** Re-running `node ace configure @adonia/core` must not
   duplicate edits or overwrite application-owned files.

Relevant starting points: [protocol v1](/protocol/v1),
[authorization](/authorization), and [security conformance](/security-conformance).
When prose and implementation disagree, establish current behavior from source and tests,
then update the affected documentation in the same change.

## Working on a change

1. Create a focused branch from `main`.
2. Locate the existing public contract, implementation, test, and documentation for the
   subsystem. Extend the existing pattern instead of creating a parallel abstraction.
3. Make the smallest complete change. Update every package or example caller in the same
   pull request; compatibility shims are not the default.
4. Add or update tests for new observable behavior and plausible regressions.
5. Update authored docs, generated reference, fixtures, and release evidence when affected.
6. Run focused checks while iterating, then the applicable repository gates before opening
   the pull request.
7. Add a Changeset for a publishable package change.

### Focused commands

Use pnpm filtering to keep the feedback loop small:

```sh
pnpm --filter @adonia/core test
pnpm --filter @adonia/core typecheck
pnpm --filter @adonia/ui test
pnpm --filter @adonia/devtools test
pnpm --filter blog-admin test
pnpm --filter blog-admin test:e2e
```

Replace the filter with the package being changed. Package names are defined in their
`package.json`; the two reference plugins are `adonia-activity-log` and
`adonia-import-export`.

For the example application:

```sh
pnpm --filter blog-admin dev
```

The default panel is available at `/admin`. The functional suite uses the database selected
by `DB_CONNECTION`; CI exercises PostgreSQL, MySQL, and SQLite.

## Tests

Tests must defend observable contracts: descriptor shape, query behavior, authorization,
validation, persistence boundaries, HTTP responses, UI behavior, or installation output.
Avoid tests that assert source text or private plumbing when the same regression can be
observed at a public boundary.

| Change | Minimum evidence |
| --- | --- |
| Resource, field, table, validation, action, widget | Focused `@adonia/core` tests and typecheck |
| React component, registry, hooks, accessibility | Focused `@adonia/ui` tests and browser-facing example/e2e path when behavior changes |
| Installer, generator, codegen, doctor | `@adonia/devtools` tests; fresh-install or template smoke path when generated applications change |
| Authorization, persistence, upload, serialization | Mapped security test and the relevant functional path |
| Protocol descriptor | Core contract test, `fixtures/protocol`, protocol impact review |
| Adapter or reference plugin | That workspace's unit tests plus its core integration boundary |
| Tutorial or example behavior | `blog-admin` functional test; Playwright when browser interaction changes |
| Documentation only | `pnpm docs:check` and `pnpm docs:build` |

The full repository suite is:

```sh
pnpm test
pnpm typecheck
pnpm lint
pnpm build
```

Performance or UI-bundle changes also require:

```sh
pnpm perf
pnpm size
```

The [CI guide](/ci) documents every job, database matrix, security gate, bundle budget,
and performance artifact.

## Documentation workflow

The VitePress content root is the entire `docs` directory. Edit subsystem pages where they
already live; do not create a second documentation tree under `docs/site`.

Run the site locally:

```sh
pnpm docs:dev
```

TypeScript and TSX fences are executable documentation. `pnpm docs:check` extracts them and
compiles them against package source. Use a nearby `<!-- @sample-preamble ... -->` only for
imports and declarations needed to make a deliberately partial sample type-check.

Field and public API references are generated from source:

- `docs/reference/fields/**` comes from field classes and their TSDoc.
- `docs/reference/api/**` comes from package export maps and public TSDoc.

Do not hand-edit generated pages. Update source/TSDoc and regenerate:

```sh
pnpm docs:generate
pnpm docs:check
pnpm docs:build
```

Generated reference is committed. `docs:check` fails if checked-in output is stale;
`docs:build` additionally rejects dead links. Add a new authored page to
`docs/site/.vitepress/nav_data.ts` when its position should be curated; otherwise the
sidebar sweep makes it reachable automatically.

Documentation changes should:

- state prerequisites and defaults explicitly;
- distinguish required and optional peers;
- use application-relative paths and complete commands;
- document failure behavior and security consequences, not only the happy path;
- link to the normative spec instead of copying large contracts;
- call out implementation deltas honestly when source and an earlier design differ.

## Changesets and releases

All seven publishable packages are in one fixed Changesets group, so a release versions them
together. Add a Changeset when a pull request changes behavior, types, exports, generated
application output, adapters, plugins, or another package-facing contract:

```sh
pnpm exec changeset
```

Choose the semver impact based on the public contract and write a user-facing summary. A
Changeset is normally unnecessary for tests, internal refactors, or documentation-only
changes that do not alter published package behavior.

Do not manually edit package versions. The release process consumes Changesets and validates
launch evidence first. Maintainer release checks are:

```sh
pnpm launch:check
pnpm release:dry-run
```

The repository remains pre-release until every required item in
[`docs/launch/checklist.json`](/launch/checklist.json) has evidence and an attestation.

## Pull request checklist

Before requesting review, verify all applicable items:

- [ ] The change is complete across server, client, generated output, and callers.
- [ ] Public behavior has a regression test at the narrowest stable boundary.
- [ ] Authorization and persistence behavior is covered by the security map when affected.
- [ ] Exported symbols have TSDoc and the generated API reference is current.
- [ ] Documentation samples compile and relative links build.
- [ ] Protocol fixtures and impact records are updated when descriptor behavior changes.
- [ ] A Changeset describes any publishable package change.
- [ ] Focused tests pass, followed by the applicable full gates.
- [ ] No public demo, compatibility, performance, or release claim is made without recorded evidence.

## Reporting documentation defects

A broken link, stale sample, unclear requirement, or mismatch with current source is a bug.
Open an issue or pull request with the affected page, the observed behavior, and the source
or test establishing the correct contract. Do not weaken a failing generated-reference,
sample, security, or launch gate to make documentation pass; repair the source of the drift.

Source: https://adonia.pages.dev/guide/contributing/index.mdx