Package standards

A package lives at packages/<category>/<name> and is published as @stackra/<name>. The category is only a folder (see Package categories). Every package is also a member and carries its required files.

Shape: entries first

Every library package has one shape (0126, which supersedes the archetypes of 0004). pnpm new package <name> --category <c> --entries … renders it. tooling presets keep their own shape (below).

config/<name>.config.ts   publishable deploy-time defaults (CF1), outside src
resources/                static files (lang/, stubs/, assets/), exported as ./resources/*
src/
  core/        "."           runtime-neutral; imports no host library
  contracts/   "./contracts" vocabulary only: types, as-const objects, tokens (0117)
  node/        "./node"      Node-only adapters, drivers, the module, the Explorer
  react/       "./react"     web React bindings; react is an optional peer
  native/      "./native"    React Native bindings; react-native is an optional peer
  testing/     "./testing"   fakes, builders, conformance suites for consumers' tests
  devtools/    "./devtools"  dev-only devtools, frontend and backend
  ui/                        internal logic shared by react/ and native/ (not an entry)

Rule	Detail
Declare only real entries	A folder, its `exports` key and its `tsdown.config.ts` entry are added together, with the first real code. `core` is always there.
Entries never import entries	`react` and `native` share code through the internal `src/ui/`, never through each other.
Host libraries are optional peers	A runtime-specific dependency is an optional peer (`peerDependenciesMeta`), so installing the package pulls in no host library.
Kind folders inside a feature module	`models/`, `actions/`, `queries/`, `services/`, `events/`, `listeners/`, `workflows/`, `policies/`, `permissions/`, `settings/`, `contracts/`, `resources/`; `interfaces/`, `types/`, `constants/`, `tokens/`, `errors/`, `decorators/` once there are two or more files. No `controllers/`, `dtos/`, `repositories/`, `helpers/`, `utils/`.
Decorators ship an Explorer	A package that defines decorators registers them at bootstrap through the container’s `DiscoveryService`.

Tooling

Data, not a build: JSON or JSONC presets with a files allowlist and an exports map, tag tier:config, no src/ layers. A change goes into the preset, never into each consumer. Presets keep ./x.ts specifiers because plain Node loads them.

Exports, barrels and imports

Every package builds with tsdown to ESM-only dist/*.mjs plus .d.mts. Each exports entry lists the @stackra/source condition first (pointing at ./src/**, read by typecheck, Vitest and Vite), then types and default in dist (runtimes load these). The validator checks the shape (0025).
index.ts is the only barrel name. A barrel declares nothing; it re-exports.
A consumer imports the package or a declared subpath, never another package’s src/ (@stackra/*/src/* is a lint error).
A package never imports an app, a service, or encore.dev and ~encore/*.
A shared package holds mechanisms, not product literals: no brand name, locale list, project id or process.env read. Decorators annotate code (classes, methods, fields); define* creates values other code references (defineToken, defineConfig, definePermissions, defineEvents, defineMeters, defineEntitlements); the app holds the definition. See Boundaries.
Naming, one declaration per file and specifier style: Code style.

Provenance of copied code

Code copied from another repository is copied, not depended on, and says where it came from. Next to the package, ORIGIN.md records:

the source repository, path and commit hash, and the date;
what changed on copy (renames, product values removed, dependencies swapped);
how to pull a later change: diff the source at the new commit against the recorded one, port by hand, update the file.

Port or rewrite

Decide per package before copying:

Verdict	When
Port	The design is sound and tests exist; only names, product literals and dependencies change
Shrink	Most of it is surface nobody uses; keep the core and its tests
Replace	A platform primitive (`fetch`, Intl) does the job; keep only the parts it lacks, with new tests
Rewrite	The model is wrong (strings where typed keys belong); keep the ideas, write it fresh
Drop	A few typed lines in an existing package replace it

A port that diverges from its origin does so openly: in ORIGIN.md, not silently.

What enforces this

Rule	Check	Status
Entries never import entries	planned: oxlint `boundaries.jsonc` per entry folder	No
No import of an app, service or `encore.dev` from a package	oxlint `boundaries.jsonc` + `turbo boundaries`	Yes
No deep import of `@stackra//src/`	oxlint `boundaries.jsonc`	Yes
`exports` dist + `@stackra/source` shape, `sideEffects: false`	`validate-repository.mjs`	Yes
Unused files and exports	`knip`	Yes
Entry folders match `exports` and `tsdown.config.ts`	planned: validator check	No
No product literal or `process.env` in a package	planned: validator check	No
`ORIGIN.md` present where code was copied	planned: validator check; review by `package-steward` today	No

The package-steward reviews every new package and every new exports subpath; see the agent roster.

​Shape: entries first

​Tooling

​Exports, barrels and imports

​Provenance of copied code

​Port or rewrite

​What enforces this