Class prefix

Sépale's classes are plain: btn, chip, title. In a project that already has a .title or a .chip of its own, the kit styles it by name. A Vite plugin shipped in @sepale/components renames the kit's classes while the project builds, so the two never meet.

Turn it on

One line in the Vite config. The prefix is yours to choose, which is why it is applied while you build rather than shipped: nothing published carries it, and without the option nothing changes.

// vite.config.ts
import { sepale } from '@sepale/components/vite';
import { sveltekit } from '@sveltejs/kit/vite';

export default {
  plugins: [
    sepale({ prefix: 'sp', family: '@sepale/style/peony.css' }),
    sveltekit()
  ]
};

The project keeps importing the same stylesheet and the same components. The plugin renames both on their way through the build.

<script>
  import '@sepale/style/peony.css';            // still the unprefixed file: the plugin renames it
  import '@sepale/style/peony/themes/iris.css';
  import { Button, Chip } from '@sepale/components';
</script>

<Button color="primary">Save</Button>          <!-- renders <button class="sp-btn sp-btn-primary"> -->
<Chip>Draft</Chip>                             <!-- your own .chip is no longer the kit's -->

Options

prefix string
Lowercase letters and digits, without the dash: sp writes sp-btn. Left out, the plugin does nothing and the kit stays unprefixed.
family string | string[]
The family stylesheet(s) the project imports, by package path or relative to the project. Required with a prefix: the classes to rename are the ones it ships. Themes carry no class and are not listed.
components RegExp
Where the package's build is, tested on a file's path. Default: @sepale/components/dist in node_modules. Only worth setting for a build kept somewhere else.

What is renamed

Classes, and only classes. The stylesheet and the components are renamed from the same list, the classes the family ships, so they cannot disagree.

  • The family stylesheet, token by token. Comments, strings and url() are left alone.
  • The components of @sepale/components: class attributes and directives, the classes a component builds from its name (checkbox and checkbox-primary), classes it tests or toggles, classes in the selectors it queries.
  • Not renamed: custom properties (--btn-bg), keyframes, element selectors, attributes, and the classes of a library the kit only reaches into (air-datepicker).
.btn { … }                .sp-btn { … }
.btn-primary { … }   →    .sp-btn-primary { … }
.toast.toast-top { … }    .sp-toast.sp-toast-top { … }
--btn-bg: #fff;           --btn-bg: #fff;              /* a custom property is never renamed */

So a theme, a background prop or a reset needs no change: they never named a class.

Your own markup

A class you write on an element, or hand to a component through class, chipClass or field, is the kit's own: it takes the prefix too. The types do not know the prefix. They narrow what a family draws (color, size), not how a class is spelled.

<!-- Your own markup takes the prefixed names too -->
<p class="sp-text-s2 sp-text-b1">Fixed price</p>

<!-- and so does a class you give a component -->
<Input class="sp-input-ghost" />

A family that is not in @sepale/style

family takes any stylesheet that follows the family contract, so a private family or one made on the family page is prefixed like the published ones. It is the plugin that reads it: the prefix is never part of its build.

// A family that is not in @sepale/style: a private one, one built from a theme editor,
// one written by hand. Same option, any path.
sepale({ prefix: 'sp', family: '@acme/ui/acme.css' })
sepale({ prefix: 'sp', family: './src/styles/acme.css' })

Another bundler

Only Vite has a plugin. The two functions behind it are exported, so any build step can do the same.

// Any other build tool: the plugin is a thin layer over two functions.
import { classesIn, prefixCss, prefixComponent } from '@sepale/components/prefix';

const css = readFileSync('peony.css', 'utf8');
const classes = classesIn(css);                    // what the family ships

writeFileSync('peony.sp.css', prefixCss(css, 'sp'));
// on every .svelte of @sepale/components, before Svelte compiles it:
const { code } = prefixComponent(source, 'sp', classes);

Limits

  • A rename is made on the syntax tree, so a class has to be written where it can be seen: a string in a class attribute, or in what the attribute reads. A class assembled elsewhere would be missed.
  • That is checked on what ships: pnpm run check:prefix renders every component, every axis value and every flag through the plugin and fails on any class of a family that comes out unprefixed.
  • No source map for the renamed files: a rename moves columns on a line, never lines.
  • The decisions are written down in ADR 0007 and ADR 0017.
Sponsor