Docs Architecture
Distribution
Take what you need, ship what you use: installing a package, copying its styles and shipping its code are separate decisions.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Three questions
| Question | Answer |
|---|---|
| What is installed? | One package per product. |
| What is copied into the application? | Nothing by default; stylesheets when the application chooses to own them. |
| What ships to production? | The registration modules of the behaviors the markup uses and the imported stylesheets. Native-only fixture: 0 B of Svelte Lean JavaScript. |
Consumption modes
| Mode | You write | What ships |
|---|---|---|
| A. Native | Platform markup; no package needed | No runtime, no registration, no import |
| B. Package-managed behavior | Markup with a static marker; the plugin or a manual import | The matching registration modules only |
| C. Owned styles | A copied stylesheet, or CSS against the protocol | Your CSS; the behavior stays a package dependency |
Behavior code is never copied: it is accessibility-sensitive, and an upstream focus fix must
reach every project through npm. There is no slean add command yet. Setup for each
mode: Installation.
/* Mode C without any package CSS: target the protocol and the platform state directly */
[data-slean='tabs'] [role='tab'][aria-selected='true'] {
border-bottom: 2px solid currentColor;
}
[data-slean='dialog']::backdrop {
background: rgb(0 0 0 / 0.4);
}Package granularity
- One package per product, never one npm package per primitive.
- Behaviors are subpath exports: the plain entry holds types and pure helpers, the
registerentry is the one side effect, the root entry registers nothing. - Table extras (grouping, pivot, editing, clipboard, export, server data, persisted state) never load unless imported.
sideEffectslists only the register modules and the CSS.@svelte-lean/stylesships CSS only, one file per primitive plus tokens; its tests assert every export is a CSS file. The single-entry import is a convenience.
import type { TabsChangeDetail } from '@svelte-lean/primitives/tabs'; // types, pure helpers
import '@svelte-lean/primitives/tabs/register'; // the side effect: registers tabs once
import { BEHAVIORS } from '@svelte-lean/primitives'; // metadata and contracts; registers nothingimport { DataTable, createTable, createRowModel } from '@svelte-lean/table';
import { groupBy, summarize } from '@svelte-lean/table/grouping';
import { pivot } from '@svelte-lean/table/pivot';
import { createHistory, applyEdit } from '@svelte-lean/table/editing';
import { copyRange, pasteRange } from '@svelte-lean/table/clipboard';
import { toCsv, downloadText } from '@svelte-lean/table/export';
import { createDataSource } from '@svelte-lean/table/server';
import { serializeState, restoreState } from '@svelte-lean/table/state';
import '@svelte-lean/table/style.css';// packages/primitives/package.json: only the register modules are side effects
"sideEffects": ["./dist/*/register.js"]
// packages/table/package.json
"sideEffects": ["**/*.css"]Exports of @svelte-lean/primitives, read at build time: ., ./button, ./dialog, ./popover, ./popover/anchor/register, ./checkbox, ./checkbox-group, ./checkbox-group/register, ./radio-group, ./tabs, ./tabs/register, ./menu, ./menu/register, ./listbox, ./listbox/register, ./calendar, ./calendar/register, ./date-picker, ./date-picker/register, ./input, ./input/register, ./field, ./field/validation/register, ./select, ./select/register, ./select/search/register, ./select/create/register, ./rating, ./slider, ./slider/register, ./autocomplete, ./autocomplete/register, ./accordion, ./card, ./separator, ./avatar, ./badge, ./kbd, ./carousel, ./alert, ./progress, ./meter, ./skeleton, ./breadcrumb, ./nav, ./pagination, ./steps, ./toggle, ./toggle-group, ./toggle-group/register, ./toolbar, ./toolbar/register, ./tree, ./tree/register, ./toast, ./toast/register, ./button-group, ./scroll-area, ./descriptions, ./timeline, ./empty, ./splitter, ./splitter/register, ./sortable, ./sortable/register, ./menu/contextmenu/register, ./file-drop, ./file-drop/register, ./hover-card, ./hover-card/register, ./menubar, ./menubar/register, ./hint, ./hint/register, ./copy, ./copy/register, ./findable, ./findable/register, ./svelte-elements.
Exports of @svelte-lean/table: ., ./core, ./grouping, ./pivot, ./export, ./editing, ./state, ./server, ./clipboard, ./style.css.
Shipping invariants
Five release-blocking invariants, tested against real production output.
| Invariant | Where it is tested | Status in this build |
|---|---|---|
| A. Native-only pages ship no behavior runtime | fixtures/native-only; packages/primitives/scripts/size.mjs (native-only entry) | 34 assertions pass |
| B. Unused behaviors are absent from production output | fixtures/tabs-only, tabs-and-menu, manual-registration, table-basic | tabs-only: 48 assertions pass; tabs-and-menu: 46 assertions pass; manual-registration: 45 assertions pass; table-basic: 55 assertions pass |
| C. Instance count does not multiply shared listeners | apps/playground/tests/primitives/listeners.spec.ts (1 vs 1000 roots); packages/primitives/tests/tabs.test.ts | exact equality, release gate |
| D. Tier 2 state is lazy | packages/primitives/tests/autocomplete.test.ts and select.test.ts ("lazy controller": untouched roots hold no state, one entry per used root, released on close); apps/playground/tests/primitives/lazy.spec.ts (100 roots in Chrome) | exact assertion, release gate |
| E. Compatibility code is opt-in or target-selected | No test yet: no compatibility module exists. The first one adds a fixture proving the native path excludes it. | nothing to test |
| Fixture | Consumes | Svelte Lean chunk (brotli) |
|---|---|---|
| native-only | button, dialog, popover markup; the stylesheet; the plugin | 0 B |
| tabs-only | tabs markup; the plugin | 1839 B |
| manual-registration | tabs markup; the register module imported by hand; no plugin | 1839 B |
| tabs-and-menu | tabs and menu markup; one kernel | 4600 B |
| table-basic | <DataTable /> and its stylesheet; six optional modules asserted absent | 20841 B |
- Each fixture is a production Vite build in its own process, with every
@svelte-lean/*module isolated in one chunk (fixtures/README.md). - Packed tarballs are tested separately: publint, every
exportstarget, a Node import of every subpath, a server render of the table (pack-smoke.mjs).
Manifest and report
Discovery stays inspectable: the marker is in the source, the build writes a manifest and a report, and the manual import exists. This site's manifest is on Build-time discovery.
svelteLean({
// A behavior of your own, or a replacement module for a built-in one.
behaviors: {
carousel: '$lib/behaviors/carousel/register',
tabs: '@acme/primitives/tabs/register'
}
});Escape hatches
| Abstraction | Escape hatch | Documented on |
|---|---|---|
| Automatic behavior discovery by the Vite plugin | A manual import '@svelte-lean/primitives/tabs/register'; the same module, the same bytes | /docs/installation#manual-registration |
| The built-in behavior table of the plugin | The behaviors option: your own registration module for a name, or false for no runtime | /docs/architecture/build-time-discovery#options |
| The document runtime | createRuntime({ root }) for a shadow root or an iframe; register the same definitions on it | /docs/architecture/build-time-discovery#the-shared-router |
| <DataTable /> | createTable(): the engine it renders, for a renderer of your own; @svelte-lean/table/core for the pure row model | /table/api |
| Uncontrolled table state | bind:state or onStateChange: one plain object the application owns, serializes and restores | /table/state-persistence |
| The package stylesheet | Your own CSS against the protocol attributes and platform state, or a copied file you own | /styling/owned-styles |
| Native positioning of popovers | Your own anchor-name and position-anchor rules; no compatibility positioning module exists | /primitives/popover |
| The declarative tab selection | activateTab(root, value) and the cancelable slean:change event | /docs/architecture/dom-protocol#events |
import { createTable } from '@svelte-lean/table';
// Below <DataTable />: the engine it renders, for a renderer of your own.
const table = createTable({
data: () => rows,
columns,
getRowId: (row) => row.id,
state: () => tableState,
onStateChange: (next) => (tableState = next)
});
table.toggleSort('revenue');
table.model.rows;Source
- ADR 0005, Take what you need, ship what you use
- primitives package.json and table package.json
- fixtures/: the consumer builds and their assertions