✨ Static Kit CLI

Compile, scaffold, and install static assets. WordPress, Shopify, and static sites are hosts: they differ in .staticrc paths, not in this CLI.

A lean toolbelt, not a UI kit. lib/ is primitives. components/ is the host’s. Starter Sass/JS come from the host (pass bodies into create), not from a catalog in this package.

Requires Node.js 20+.

npm install -g @wndrfl/static-kit-cli
static install --dir ./static
static compile --dir ./static

A global install is for authors stamping a tree. After that, the CLI is optional. Pin it as a host devDependency if you want npx static compile without a global binary — or leave it. The stamp is Dart Sass + ESM; see Leaving the CLI.

Commands

• static install — stamp the framework. Already installed iff a config file exists (.staticrc, .static, statickit.json), not merely a folder.
• static compile [all|css|js|images] — compile. --watch / -w rebuilds and turns the browser Logger on. --debug does the same for a one-shot JS build (and verbose CLI logs). Default command when none is given (static -w).
• static template create --name <page> — per-page JS + SCSS entries.
• static component create --name <slug> [--js] [--scss-from <file>] [--js-from <file>] [--force] — component stubs or host-supplied bodies.
• static component remove --name <slug>
• static version
• static help

--format json prints { ok, data, error } on stdout. Logs go to stderr.

Shopify

Point every dist path at the theme assets/ folder. Compile from a source subfolder. Image cleanup never deletes hand-authored files.

{
  "paths": {
    "src": { "js": "src/js", "scss": "src/scss", "images": "src/images" },
    "dist": { "js": "../assets", "css": "../assets", "images": "../assets" }
  },
  "overwrite": false
}

Programmatic API

import { compile, component, core, template } from '@wndrfl/static-kit-cli';

const installed = await core.installKit(dir, { deps: true, compile: false });
const created = await component.create(dir, 'hero', { script: true });
// or pass host bodies: { overwrite: true, scss, js }
// created.data.wrote → [{ kind: 'style'|'script', path }]
await compile.all({ dir });

Every function returns { ok, data, error }. See ARCHITECTURE.md.

Leaving the CLI

The stamped tree does not require this package. Install is the CLI. Compile can be Dart Sass and any JS bundler. The inheritor copy of this contract is the README inside the stamp (framework/README.md).

Read paths from .staticrc. Compile only root entries (src/scss/*.scss, src/js/*.{js,ts}). Files under components/ and lib/ are imported, not emitted.

# CSS — Dart Sass (not LibSass)
npx sass --style=compressed --source-map src/scss:dist/css

# JS — same shape as `static compile js`
npx esbuild src/js/*.js --bundle --minify --format=esm --target=es2020 --sourcemap --define:__SK_DEBUG__=false --outdir=dist/js

Point src/dist at whatever .staticrc says (Shopify often uses ../assets for all three dist keys). Load bundled JS as a module, or wrap it in your bundler.

Images: copy src/images to the dist images path (nested folders included). The CLI also compresses JPEG (mozjpeg, quality 80) and PNG, writes sibling .webp (lossless when the source has alpha), skips outputs newer than their source, and tracks names in .static-images-manifest.json so cleanup does not empty a shared assets/ folder. Skip that pipeline if you want; do not glob-delete a mixed Shopify assets/ directory.

Pages and components are files. Add src/scss/<page>.scss + src/js/<page>.js, or src/scss/components/_<slug>.scss + optional src/js/components/<Pascal>.js, then @use / import from the page entry.

Do not add compile behavior that cannot be expressed with stock Sass/esbuild (or the image steps above). That would lock inheritors back in.

License

Copyright (c) 2026 Wonderful. MIT.