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:

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

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, authorization, and 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:

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:

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.

The full repository suite is:

pnpm test
pnpm typecheck
pnpm lint
pnpm build

Performance or UI-bundle changes also require:

pnpm perf
pnpm size

The CI guide 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:

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:

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:

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:

pnpm launch:check
pnpm release:dry-run

The repository remains pre-release until every required item in docs/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.