Guide

Installation

1 npm install @xpulse/theme --registry=https://npm.xpulse.one

Usage

When @xpulse/theme is installed and started by @xpulse/app, a single minified CSS bundle is served at /_theme/css/xpulse.css. All themes (dark, light, and any app overrides) are included in that one file.

Recommended — use template methods in your layout:

1 {% themeAssets() %}

This renders the bundle link, the anti-FOUC inline script, and the browser runtime script. Add the switcher separately if needed:

1 {% themeSwitcher() %}

JavaScript

@xpulse/theme works without any required runtime JavaScript. Most use cases rely only on:

HTML structure
CSS classes (xpulse-*)
--xpulse-* custom properties

JavaScript is only needed as an optional behavior layer, for example:

Theme switching via /_theme/theme.js
Live :root token demos via themeTokenEditor()
Active TOC highlighting on scroll
Copy-to-clipboard for code blocks

What The Package Provides

Built-in themes at public/css/themes/ (dark, light)
Base CSS at public/css/base.css
Component CSS at public/css/components/
A single HTTP bundle: GET /_theme/css/xpulse.css
Browser runtime: GET /_theme/theme.js
No manual theme registration required

Using A Custom App Theme

Create a file in your app under src/themes/:

1 /* src/themes/app.css */
2 .xpulse-shell {
3   width: min(1100px, calc(100% - 32px));
4   margin: 32px auto;
5 }

Important:

Do not @import the base theme — app.css contains only local overrides
The file is appended to the end of the bundle
themeAssets() also injects app.css as a separate <link> so that changes take effect in development without a cache rebuild

Theme Switcher

1 {% themeAssets() %}
2 {% themeSwitcher() %}

theme.allow and theme.default in xpulse.json control the switcher:

1 {
2   "theme": {
3     "default": "dark",
4     "allow": ["dark", "light"]
5   }
6 }

`allow`	Result
`[]` or not set	All discovered themes are allowed
`["dark", "light"]`	Compact moon/sun toggle button
`["dark", "light", "high-contrast"]`	Select dropdown
`["dark"]`	No switcher rendered

Caching

The CSS bundle is cached at var/cache/theme/xpulse.css on first start and read directly from there on subsequent starts.

In dev mode (NODE_ENV !== 'production') the cache is always skipped
Use theme.init({ force: true }) to bypass the cache manually
TTL and enabled state are configurable via xpulse.json:

1 {
2   "theme": {
3     "cache": {
4       "enabled": true,
5       "ttl": 0
6     }
7   }
8 }

ttl: 0 means no expiry. ttl: 3600 invalidates the cache after 1 hour.

Component Class Naming

CSS classes from @xpulse/theme follow the xpulse-* prefix and BEM:

.xpulse-box / .xpulse-box--header / .xpulse-box--content
.xpulse-brand / .xpulse-brand__title
.xpulse-nav__item--depth-1
.xpulse-button--primary / .xpulse-button--secondary

Related CSS variables use the --xpulse-* prefix.

1	/* src/themes/app.css */
2	.xpulse-shell {
3	width: min(1100px, calc(100% - 32px));
4	margin: 32px auto;
5	}

1	{
2	"theme": {
3	"default": "dark",
4	"allow": ["dark", "light"]
5	}
6	}