sveltelean
Version v0.18.0

Requirements

ToolRangeNotes
Node^20.19.0 || >=22.12.0For the build (the engines of @svelte-lean/vite). The repository needs >=22.18.0 and develops on 22.23.4.
Svelte^5.20.0Peer of @svelte-lean/table; the primitives have no framework dependency. Tested with 5.57.1.
Vite^6.0.0 || ^7.0.0 || ^8.0.0Peer of @svelte-lean/vite. Tested with 7.3.6 and, nightly, the latest release; Vite 6 is in the range and not tested.
TypeScript5moduleResolution bundler or node16. SvelteKit is optional.

Read from the package files at build time; the full matrix is on Compatibility.

Packages

npm install @svelte-lean/primitives
npm install @svelte-lean/styles
npm install --save-dev @svelte-lean/vite
npm install @svelte-lean/table
npm install @svelte-lean/query
  • Every primitive is a subpath export of @svelte-lean/primitives.
  • @svelte-lean/styles is optional and ships CSS only.
  • @svelte-lean/core comes with the primitives package.
  • @svelte-lean/query (server state) is independent of the others and versioned on its own: Client setup.
  • All packages are ESM-only with strict exports maps.

Vite plugin

vite.config.ts
// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { svelteLean } from '@svelte-lean/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [svelteLean(), sveltekit()]
});
vite.config.ts
// vite.config.ts, plain Vite without SvelteKit
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { svelteLean } from '@svelte-lean/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [svelteLean(), svelte()]
});
  • Place svelteLean() before sveltekit(), so the scanner reads the source before any preprocessor.
  • In development it keeps @svelte-lean/primitives and @svelte-lean/core out of dependency pre-bundling, so the first page with a behavior does not force a reload.
  • Server transforms are skipped (ssr: 'skip'); registration modules touch neither document nor window at evaluation. Every route of this site is prerendered with this configuration.

Styles

+layout.svelte
// src/routes/+layout.svelte
import '@svelte-lean/styles/tokens.css'; // required by every primitive file
import '@svelte-lean/styles/base.css'; // required by every primitive file
import '@svelte-lean/styles/dialog.css';
import '@svelte-lean/styles/tabs.css';
import '@svelte-lean/styles/menu.css'; // imports popover.css itself
TypeScript
// Convenience only: every stylesheet, for prototypes
import '@svelte-lean/styles';
  • Every file declares the same cascade layer order, so the order between primitive files does not matter.
  • Dependencies: menu.css and menubar.css need popover.css; button-group.css needs button.css. Each primitive page lists its stylesheets in order.
  • Selectors are wrapped in :where(): any unlayered rule of the application wins.
  • Dark values apply under prefers-color-scheme: dark or data-theme="dark" on the root.

First component

Native markup

A Tier 0 primitive is platform markup: nothing is imported, the browser owns the behavior, and the data-slean attributes are hooks for the stylesheet and development validation.

settings.svelte
<button type="button" commandfor="settings" command="show-modal">Settings</button>

<dialog id="settings" data-slean="dialog" aria-labelledby="settings-title">
	<header>
		<h2 id="settings-title">Settings</h2>
	</header>
	<div>…</div>
	<footer>
		<button type="button" commandfor="settings" command="close">Close</button>
	</footer>
</dialog>

The native-only fixture ships 0 B of Svelte Lean JavaScript. Missing platform features are covered on Browser support.

Behavior markup

Tabs need JavaScript the browser does not provide. Write the contract markup with a static marker; the plugin appends the registration import to the compiled module.

+page.svelte
<!-- src/routes/settings/+page.svelte -->
<div data-slean="tabs" data-slean-value="account">
	<div role="tablist" aria-label="Settings" data-slean-part="list">
		<button
			type="button"
			id="tab-account"
			role="tab"
			aria-controls="panel-account"
			aria-selected="true"
			tabindex="0"
			data-slean-part="trigger"
			data-slean-value="account"
		>
			Account
		</button>
		<button
			type="button"
			id="tab-security"
			role="tab"
			aria-controls="panel-security"
			aria-selected="false"
			tabindex="-1"
			data-slean-part="trigger"
			data-slean-value="security"
		>
			Security
		</button>
	</div>
	<div
		id="panel-account"
		role="tabpanel"
		aria-labelledby="tab-account"
		data-slean-part="panel"
		data-slean-value="account"
	>
		…
	</div>
	<div
		id="panel-security"
		role="tabpanel"
		aria-labelledby="tab-security"
		data-slean-part="panel"
		data-slean-value="security"
		hidden
	>
		…
	</div>
</div>
+page.svelte, compiled
// What the compiled module of that page receives from the plugin, appended after the
// compiled code (imports are hoisted, so it evaluates first):
import '@svelte-lean/primitives/tabs/register';

A hundred files with tabs still bundle one registration module. Tabs-only fixture: 1839 B brotli.

Manual registration

Without the plugin, with a dynamic marker such as data-slean={kind}, or outside Vite, import the registration module once on the client.

+layout.svelte
// src/routes/+layout.svelte (or any module that runs once on the client)
import '@svelte-lean/primitives/tabs/register';

It is the module the plugin injects, and registration is idempotent, so mixing both is safe. Manual-registration fixture: 1839 B brotli, plugin path: 1839 B brotli, with the same module set asserted by both fixtures.

Events in Svelte

Behaviors emit cancelable DOM events on their root (slean:change, slean:select, slean:toggle, and the others each contract lists). In Svelte 5, onslean:change={…} is a listener on that element, removed with it.

+page.svelte
<!-- src/routes/settings/+page.svelte -->
<script lang="ts">
	let subscribed = $state(false);
</script>

<div
	data-slean="tabs"
	data-slean-value="account"
	onslean:change={(event) => {
		// detail is the union of every change detail; behavior narrows it.
		if (event.detail.behavior !== 'tabs') return;
		if (event.detail.value === 'billing' && !subscribed) event.preventDefault();
	}}
>
	…
</div>

Two one-time settings:

  • The types-only entry @svelte-lean/primitives/svelte-elements types event.detail (narrowed by its behavior field) and fails svelte-check on a misspelled event. It also types data-slean where attributes are checked as props, such as rest props forwarded to an element.
  • The compiler warns on every attribute name with a colon (attribute_illegal_colon). @svelte-lean/vite drops it for onslean: in builds and the dev server; svelte-check reads svelte.config.js, so compose the same filter there.
src/app.d.ts
// src/app.d.ts
/// <reference types="@svelte-lean/primitives/svelte-elements" />

declare global {
	namespace App {}
}

export {};
svelte.config.js
// svelte.config.js
import { withSleanWarningFilter } from '@svelte-lean/vite';

export default {
	compilerOptions: {
		// onslean:change listens to slean:change; the compiler warns about every attribute name
		// with a colon. The Vite plugin drops the warning for onslean: in builds; svelte-check
		// reads this file. Pass your own filter to compose it.
		warningFilter: withSleanWarningFilter()
	}
};

Table

A Svelte component with three required props and a stylesheet; no runtime, no plugin.

members.svelte
<script lang="ts">
	import { DataTable, type Column } from '@svelte-lean/table';
	import '@svelte-lean/table/style.css';

	type Member = { id: number; name: string; revenue: number };
	const data: Member[] = [
		{ id: 1, name: 'Amara Okafor', revenue: 1200 },
		{ id: 2, name: 'Jonas Lindqvist', revenue: 9119 }
	];
	const columns: Column<Member>[] = [
		{ id: 'name', header: 'Member' },
		{ id: 'revenue', header: 'Revenue', align: 'end' }
	];
</script>

<DataTable {data} {columns} getRowId={(row) => row.id} />

Grouping, pivot, clipboard, CSV export, server data and persisted state are separate entry points. Next: Getting started.

Owned styles

Copy a primitive's stylesheet into the application and edit it; the behavior stays in the package, so runtime accessibility fixes still arrive through npm (ADR 0005). There is no slean add command yet.

Terminal
# Mode C today: copy the file and own it. The behavior stays in the package.
cp node_modules/@svelte-lean/styles/css/tabs.css src/lib/styles/tabs.css
+layout.svelte
// The copied file keeps depending on the tokens; the behavior is still registered
// by the plugin (or by the manual import), not copied.
import '@svelte-lean/styles/tokens.css';
import '@svelte-lean/styles/base.css';
import '$lib/styles/tabs.css';

Modes, layers and variants: Styling.

Build verification

A production build writes node_modules/.svelte-lean/manifest.json: each behavior found, its module and the files that use it. report: true prints a summary.

vite.config.ts
// vite.config.ts
export default defineConfig({
	plugins: [svelteLean({ report: true }), sveltekit()]
});
Build output
svelte-lean build report
  native-only  button, dialog
  runtime      tabs -> @svelte-lean/primitives/tabs/register
                 src/routes/settings/+page.svelte
  unknown      none
  dynamic      none
  manifest     node_modules/.svelte-lean/manifest.json

The report lists what the scan saw; sizes and listener counts come from the consumer fixtures. The proof page shows this site's manifest.