Pattern packages
Share a design system as an npm package with Pattern Dump: the patternDump field in package.json, package order, overrides, and a package of your own.
"patternDump": {
"patterns": "src/patterns",
"styles": {
"dir": "src/styles",
"documentBase": [
"base"
]
},
"themes": {
"dir": "themes",
"default": "light",
"switch": "attribute"
},
"scripts": "src/scripts",
"assets": [
"assets"
]
}
A pattern package is an npm package with a patternDump field in its package.json: a style guide another project uses. The field says where its patterns, styles, themes, scripts and assets are, as the one above, which pd init writes into every design system it makes. A project names the packages it uses in packages in its config, installs them with npm, and renders their components beside its own.
Using a package
export default defineConfig({
packages: ["@acme/styleguide"],
});
packages- A list of package names, or of
{ name, exclude?, styles? }. Anything else:"packages" must be a list of package names or { name, exclude, styles } objects. exclude- Globs, relative to the package's patterns folder, of templates to leave out, on top of the package's own
exclude. styles: false- Leaves out the package's styles, its
documentBaseincluded. Its templates, data, themes, scripts and assets stay.
A package is found at node_modules/<name>/package.json, looking from the project's root upward, so a hoisted install works. Its peerDependencies that have a patternDump field are used too, and theirs, at any depth; a peer that isn't installed, or has no field, is skipped without a word. Each package is used once, even when it is named and a peer, and its options apply however it is reached.
- A package that isn't installed
- Stops startup:
pattern package "<name>" is not installed. Run: npm install --save-dev <name>. - A package without the field
- Stops startup:
"<name>" has no "patternDump" field in its package.json, so Pattern Dump cannot tell where its patterns, styles and themes are. See PackageManifest in @pattern-dump/contracts.
At startup
pd dev prints a line per package, [dev-server] pattern package <name>@<version>, with (peer) for a peer, and : an installed copy, not watched or : linked, nothing in it to watch where that applies; the version defaults to 0.0.0. A package is used from its real folder, links resolved, and counts as linked when that folder isn't inside a node_modules. A linked package is watched like the project's own files; an installed copy is not. Installing, updating or adding a package needs a restart of pd dev.
The patternDump field
Every field is optional. Paths are relative to the package's folder, except styles.entry, relative to styles.dir, the exclude globs, relative to patterns, and styles.documentBase, relative to styles.dir.
patterns- The patterns folder.
data- The global data folder.
helpers- The helpers: compiled JavaScript. A
.tsfile stops startup,pattern package "<name>": its helpers are TypeScript (<path>), which Node does not load from an installed package. Ship compiled helpers: …, and so does a folder with TypeScript and no.js; with both, the.jsloads and a warning names the TypeScript it skipped. assets- A list of asset folders.
styles{ dir, entry?, documentBase? }: the styles folder, the files to compile (else every.scssunderdirthat isn't a partial), and the base layer's files.themes{ dir, default?, switch? }: the themes folder, the default theme and the switch mode.scripts,globalScripts- The scripts folder, and the scripts every preview loads.
exclude- Globs of the package's own templates to leave out.
The field is read as written, not validated. Unknown fields are ignored without a message; only helpers is checked.
How sources combine
The project comes first, then the packages, in the order the config names them, each followed directly by its peers, depth first.
- Components
- The same handle in the project and a package: the project's wins. Between two packages, the earlier one's. Both are logged,
[dev-server] <id> overrides <package>'s component of the same handle ("<handle>"). Two components with one handle in the same source are a collision. "Hide packages" in the Nav Rail hides the packages' components from the tree and the galleries; they stay usable, and reachable by address. The control shows only when the tree has package components. - Classes
- A class belongs to the first stylesheet that defines it, the project's first. The base layer is written packages first, so the project's own base rules come last and win.
- Global data and helpers
- Packages first, in package order, the project last: later data merges deeply over earlier, and a later helper of the same name replaces an earlier one.
- Scripts
- Looked up in the project's scripts folder first, then the packages'.
globalScriptslists the packages' first. - Assets
- A package's asset folders are served under
/assets/<folder name>/. A project folder, or an earlier package's, of the same name hides it. - Themes
- Theme folders are the project's first, then each package's, in package order, and a theme name found first hides a later one. See Themes.
A package of your own
A design system that pd init makes is a pattern package from the start: its package.json gets a patternDump field naming the same folders as its config. A project whose own root package.json has the field takes from it every folder its config leaves out:
| Field | Config key |
|---|---|
patterns |
patternsDir |
data |
dataDir |
helpers |
helpers |
scripts |
scriptsDir |
globalScripts |
globalScripts |
exclude |
exclude |
assets |
assets.dir |
styles.dir, styles.entry |
styles.dir, styles.entry |
styles.documentBase |
documentBase |
themes.dir, themes.default, themes.switch |
the same under themes |
The field is merged before the config is validated and before the folders' defaults, so a folder it names is never mistaken for a default. A root package.json that is missing, isn't valid JSON or has no field leaves the config as it is.
A key set in both must have the same value. Paths are compared normalised, so ./patterns is patterns, and one path equals a list of one; globalScripts, exclude, themes.default and themes.switch are compared as values. A difference stops with:
<config file>: the config and the project's own package manifest disagree
- "<config key>" is <value> in <config file>, but "patternDump.<field>" is <value> in package.json: name it in one of them, or give both the same value
Since themes is merged before validation, a field with themes.dir but no themes.default, and a config without themes.default, fail with missing required "themes.default".
A site on a style guide in a folder of its own, made with pd init --site, uses it as a package: A site on a style guide shows the setup.