Build-Time Extraction (tastyStatic)
tastyStatic is Tasty’s framework-agnostic build-time utility for extracting CSS before rendering. It produces no client styling runtime in file mode, but it is not the only way to achieve zero-runtime delivery: server-only tasty() also ships no Tasty runtime to the browser while retaining the full React component API. Astro’s tastyIntegration({ islands: false }) is the clearest example; the same architecture applies to server-only Next.js RSC.
Choose tastyStatic specifically when styles must be generated during the build, when the consumer is not React, or when you want static class-name objects instead of components. For the broader docs map, see the Docs Hub.
- CSS that must exist before anything renders — static sites, landing pages, and HTML served from a CDN get one stylesheet generated at build time
- No React at runtime —
tastyStaticreturns class names, so plain DOM code or any templating that setsclasscan use them; the Programmatic API covers frameworks Babel does not process - Class-name objects instead of components — extend them with
tastyStatic(base, styles)and pass them wherever aclassNamegoes - Self-contained packages — inject mode embeds the CSS in the JavaScript, so consumers have no stylesheet to wire up
If the styles depend on props, keep tasty(): rendered only on the server, it also ships no styling runtime (see Server-Side Rendering).
Build-time extraction is part of the main @tenphi/tasty package but requires additional peer dependencies depending on your setup:
| Dependency | Version | Required for |
|---|---|---|
@babel/core |
7.24+ or 8 | Babel plugin (@tenphi/tasty/babel-plugin) |
@babel/helper-plugin-utils |
7.24+ or 8 | Babel plugin |
@babel/types |
7.24+ or 8 | Babel plugin |
jiti |
>= 2.6 | configFile only (Babel plugin and Next.js wrapper) |
babel-loader |
any (10+ with Babel 8) | Next.js wrapper (@tenphi/tasty/zero/next) |
Install the three Babel packages from the same major. Babel 8 itself needs Node 22.18+ or 24.11+, and babel-loader accepts it from version 10.
The Babel packages and jiti are optional peer dependencies of @tenphi/tasty; babel-loader is resolved from your project. jiti is loaded only to read a configFile, so a setup that passes config directly does not need it; without it, configFile fails with an error that says to install it. Install what your setup requires:
# Any Babel-based setup (Vite, custom Babel config, etc.)
pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types
# Next.js
pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types babel-loader
# Either, with configFile
pnpm add -D jitiimport { tastyStatic } from '@tenphi/tasty/static';
// Define styles - returns StaticStyle object
const button = tastyStatic({
display: 'inline-flex',
padding: '2x 4x',
fill: '#purple',
color: '#white',
radius: '1r',
});
// Use in JSX
<button className={button.className}>Click me</button>;
// toString() returns the class name, for template strings and plain JS
element.className = `${button} is-active`;In TSX, pass button.className: React types className as string, so passing the StaticStyle object fails type-checking even though it works at runtime.
Creates a StaticStyle object from a styles definition.
const card = tastyStatic({
padding: '4x',
fill: '#white',
border: true,
radius: true,
});Extends an existing StaticStyle with additional styles. Uses mergeStyles internally for proper nested selector handling.
const button = tastyStatic({
padding: '2x 4x',
fill: '#blue',
Icon: { color: '#white' },
});
const primaryButton = tastyStatic(button, {
fill: '#purple',
Icon: { opacity: 0.8 },
});Generates global styles for a CSS selector. The call is removed from the bundle after transformation.
tastyStatic('body', {
fill: '#surface',
color: '#text',
preset: 't3',
});The selector can be a list ('.uni-checkbox, uni-checkbox'): every item gets the states and sub-elements. Local @keyframes and @starting states work as in tastyStatic(styles).
| Property | Type | Description |
|---|---|---|
className |
string |
Space-separated class names for use in JSX |
styles |
Styles |
The original (or merged) styles object |
toString() |
() => string |
Returns className for string coercion |
// babel.config.js
module.exports = {
plugins: [
[
'@tenphi/tasty/babel-plugin',
{
output: 'public/tasty.css',
},
],
],
};These examples use data-schema="dark" as the root-state convention. If your app already uses a different root attribute such as data-theme, keep the same alias pattern and swap the attribute name consistently in your build-time config.
module.exports = {
plugins: [
[
'@tenphi/tasty/babel-plugin',
{
output: 'public/tasty.css',
config: {
states: {
'@mobile': '@media(w < 768px)',
'@tablet': '@media(w < 1024px)',
'@dark': '@root(schema=dark)',
},
devMode: true,
},
},
],
],
};| Option | Type | Default | Description |
|---|---|---|---|
output |
string |
'tasty.css' |
Path for generated CSS file |
mode |
'file' | 'inject' |
'file' |
'file' writes CSS to disk; 'inject' embeds CSS inline in JS (see Inject Mode) |
configFile |
string |
— | Absolute path to a TS/JS module that default-exports a TastyZeroConfig object. JSON-serializable alternative to config — required for Turbopack. Loaded with the optional jiti peer. |
config |
TastyZeroConfig | () => TastyZeroConfig |
{} |
Inline config object or factory function. Takes precedence over configFile. |
configDeps |
string[] |
[] |
Absolute file paths that affect config (for cache invalidation) |
injectImport |
boolean |
true |
Replace @tenphi/tasty/static imports with an import of the generated CSS file. Set to false to manage CSS imports manually. |
config.states |
Record<string, string> |
{} |
Predefined state aliases (e.g. { '@mobile': '@media(w < 768px)' }) |
config.devMode |
boolean |
false |
Add source comments to CSS |
config.tokens |
ConfigTokens |
— | Design tokens injected as CSS custom properties on :root. Values are parsed through the Tasty DSL. Supports state maps for responsive/themed tokens. |
config.replaceTokens |
Record<string, string | number> |
— | Parse-time token substitution. Keys use $name for custom properties and #name for color tokens. |
config.recipes |
Record<string, RecipeStyles> |
{} |
Predefined style recipes |
config.keyframes |
Record<string, KeyframesSteps> |
— | Global @keyframes definitions available to all tastyStatic calls |
config.fontFaces |
Record<string, FontFaceInput> |
— | Global @font-face definitions |
config.counterStyles |
Record<string, CounterStyleDescriptors> |
— | Global @counter-style definitions |
config.properties |
Record<string, PropertyDefinition> |
— | Global @property definitions, written with Tasty’s default properties |
config.units |
Record<string, string | UnitHandler> |
— | Custom units for the style parser (merged with built-ins). E.g. { u: 'var(--u)' } makes 2u compile to calc(2 * var(--u)). Native CSS units need no entry |
config.functions |
Record<string, FunctionDefinition | Function> |
— | Custom functions (merged). Bare keys → parse functions; $$name keys → declarative CSS @function definitions |
config.polyfills |
{ functions?: boolean } |
{} |
Opt-in polyfills. functions: true inlines @function calls into plain CSS at build time |
config.plugins |
TastyPlugin[] |
— | Plugins that extend tasty with custom functions, units, states, and handlers |
config.handlers |
Record<string, StyleHandlerDefinition> |
— | Custom style handlers that transform style properties into CSS declarations |
config.presets |
Record<string, TypographyPreset> |
— | Typography presets — shorthand for generateTypographyTokens(). Generated tokens merge under explicit tokens. |
config.globalStyles |
Record<string, Styles> |
— | Global Tasty styles keyed by CSS selector. Supports the full style syntax. |
config.autoPropertyTypes |
boolean |
true |
Automatically infer and register CSS @property declarations from values |
config.parserCacheSize |
number |
1000 |
Parser LRU cache size. Larger values improve performance for builds with many unique style values |
config.namePrefix |
string |
'ts' |
Prefix prepended to every generated identifier. Defaults to 'ts' so static classes never collide with runtime ('t') classes. See Configuration: Name prefix. |
When a page mixes tastyStatic with tasty, both must use different namePrefix values. The defaults handle this automatically ('t' for React rendering, 'ts' for build-time extraction). If you customize one, customize the other:
// tasty-zero.config.ts (Babel plugin)
export default { namePrefix: 'mbs' };// app entry (`tasty()` configure)
configure({ namePrefix: 'mb' });Recipes work with tastyStatic the same way as with runtime tasty:
// babel.config.js
module.exports = {
plugins: [
[
'@tenphi/tasty/babel-plugin',
{
output: 'public/tasty.css',
config: {
recipes: {
card: {
padding: '4x',
fill: '#surface',
radius: '1r',
border: true,
},
elevated: { shadow: '2x 2x 4x #shadow' },
},
},
},
],
],
};import { tastyStatic } from '@tenphi/tasty/static';
const card = tastyStatic({
recipe: 'card elevated',
color: '#text',
});
<div className={card.className}>Styled card</div>;The withTastyZero wrapper configures both webpack and Turbopack automatically. No --webpack flag is needed — it works with whichever bundler Next.js uses.
// next.config.ts
import { withTastyZero } from '@tenphi/tasty/zero/next';
export default withTastyZero({
output: 'public/tasty.css',
configFile: './app/tasty-zero.config.ts',
configDeps: ['./app/theme.ts'],
})({
reactStrictMode: true,
});| Option | Type | Default | Description |
|---|---|---|---|
output |
string |
'public/tasty.css' |
Output path for CSS relative to project root |
mode |
'file' | 'inject' |
'file' |
'file' writes CSS to disk; 'inject' embeds CSS inline in JS |
enabled |
boolean |
true |
Enable/disable the plugin |
configFile |
string |
— | Path to a TS/JS module that default-exports TastyZeroConfig. Recommended for Turbopack compatibility. |
config |
TastyZeroConfig |
— | Inline config object. For static configs that don’t change during dev. |
configDeps |
string[] |
[] |
Extra files the config depends on (for cache invalidation) |
Starting with Next.js 16, Turbopack is the default bundler. withTastyZero supports it out of the box by injecting turbopack.rules with babel-loader and JSON-serializable options.
The configFile option is key for Turbopack — it passes a file path (JSON-serializable) instead of a function, and the Babel plugin loads the config internally via jiti, which must be installed.
Requirements: babel-loader must be installed in your project (see Requirements):
pnpm add -D babel-loaderwithTastyZero automatically injects the generated CSS into your app. Every file that imports from @tenphi/tasty/static gets its import replaced with an import of the output CSS file at build time. No manual CSS import is needed.
The generated CSS file (e.g. public/tasty.css) is created as an empty stub before the first build if it doesn’t exist, so there’s no chicken-and-egg problem with fresh clones or CI builds. Add it to .gitignore:
public/tasty.css@tenphi/tasty/zero turns styles into CSS in Node without Babel or React — for build scripts, or CSS shipped to other frameworks:
import {
configure,
extractStylesForSelector,
extractStylesWithChunks,
} from '@tenphi/tasty/zero';
configure({
units: { u: 'var(--unit)' },
states: { '@dark': '@root(schema=dark)' },
});
extractStylesForSelector('.card', { padding: '2u', fill: '#surface' }).css;
// → '.card { padding: calc(2 * var(--unit)); background-color: … }'
extractStylesWithChunks({ display: 'flex', gap: '1u' });
// → [{ className: 'ts…', css: '.ts….ts… { … }' }]configure() takes the same options as the Babel plugin’s config (see Plugin Options) and replaces the previous configuration on each call; resetConfig() returns to the defaults. Options that shape the extracted rules apply — states, units, parse functions, handlers, replaceTokens, recipes, plugins, namePrefix. Definitions that become at-rules or global CSS of their own are not emitted with the rules: tokens, globalStyles, fontFaces, counterStyles, properties and $$ @function definitions. Render tokens and global styles with extractStylesForSelector(':root', tokens) and extractStylesForSelector(selector, styles).
extractConfigProperties() returns the @property rules the Babel plugin writes at the top of its output: Tasty’s default set (#border, #outline, $gap, $radius, $transition, …) overlaid with the configured properties, or with the properties map you pass it. Emit them once per stylesheet. Style handlers read several of these tokens with no fallback of their own (border: true reads #border, transition reads $transition), so without them those declarations resolve to nothing.
The configuration is process-wide and shared with the Babel plugin and the runtime configure() from @tenphi/tasty. The extractors re-apply their own configuration when the Babel plugin replaced it, but not after a runtime configure() — don’t mix the runtime and build-time configuration in one process.
extractStylesForSelector() output starts with the @keyframes its rules animate — local @keyframes and configured keyframes — under hashed names the animation declarations are rewritten to. extractStylesWithChunks() returns class rules only.
mergeStyles() merges style objects with the rules tasty(Base, { styles }) extends by — state maps with and without a '' key, null, false, '@inherit' and sub-elements (see Extending vs. Replacing State Maps) — so a build script can layer overrides onto source styles before extracting them, without React:
import { extractStylesForSelector, mergeStyles } from '@tenphi/tasty/zero';
const styles = mergeStyles(checkboxStyles, {
Indicator: { radius: '0.5r' },
});
extractStylesForSelector('.checkbox', styles).css;To write the results to a file the way the Babel plugin does, use createCSSWriter(). It deduplicates blocks by key and prepends the generated-file header:
import {
createCSSWriter,
extractConfigProperties,
extractStylesWithChunks,
} from '@tenphi/tasty/zero';
const writer = createCSSWriter('dist/tasty.css', { devMode: true });
for (const prop of extractConfigProperties()) {
writer.add(`@property:${prop.name}`, prop.css);
}
for (const chunk of extractStylesWithChunks({ display: 'flex', gap: '1u' })) {
writer.add(chunk.className, chunk.css, 'src/card.ts'); // source is a devMode comment
}
writer.write(); // also: has(key), getCSS(), clear(), getOutputPath()@vitejs/plugin-react 6 no longer runs Babel; add it with @rolldown/plugin-babel (pnpm add -D @rolldown/plugin-babel):
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import babel from '@rolldown/plugin-babel';
export default defineConfig({
plugins: [
react(),
babel({
plugins: [
[
'@tenphi/tasty/babel-plugin',
{
output: 'src/tasty.css',
config: {
states: { '@mobile': '@media(w < 768px)' },
},
},
],
],
}),
],
});With @vitejs/plugin-react 5 or older, pass the same plugins array to react({ babel: { plugins } }) instead.
Keep output outside public/: the plugin replaces each @tenphi/tasty/static import with an import of the generated file, and Vite does not let JavaScript import files from public/. Vite then bundles the CSS like any other stylesheet.
import { tastyStatic } from '@tenphi/tasty/static';
const button = tastyStatic({
padding: '2x 4x',
fill: '#purple',
color: '#white',
});
tastyStatic('.heading', { preset: 'h1' });
export const Button = () => <button className={button.className}>Click</button>;import './tasty.css';
const button = {
className: 'ts3f783b ts070801',
styles: { padding: '2x 4x', fill: '#purple', color: '#white' },
toString() {
return this.className;
},
};
export const Button = () => <button className={button.className}>Click</button>;The @tenphi/tasty/static import becomes an import of the generated file (relative to the source file), and the selector-mode call is removed.
/* Generated by @tenphi/tasty/zero - DO NOT EDIT */
@property --tasty-second-fill-color {
syntax: '<color>';
inherits: false;
initial-value: transparent;
}
@property --current-color {
syntax: '<color>';
inherits: true;
initial-value: currentcolor;
}
/* …the rest of Tasty's default @property rules (--white-color, --border-color, --gap, --transition, …), then config.properties */
.ts3f783b.ts3f783b {
color: var(--white-color);
--current-color: var(--white-color);
}
.ts3f783b.ts3f783b {
background-color: var(--purple-color);
}
.ts070801.ts070801 {
padding: 16px 32px;
}
.heading {
font-size: var(--h1-font-size, var(--default-font-size));
/* …line-height, letter-spacing, font-weight, and the rest of the h1 preset */
}The file starts with Tasty’s default @property rules and your config.properties, written once. Styles are split into chunks (here appearance and spacing), each with its own class. Color tokens compile to custom properties: #purple becomes var(--purple-color). Define it in config.tokens and the plugin writes it to :root at the top of the same file. Units are literal (2x is 16px). Selector-mode rules use the selector as written, without the doubled specificity of class rules.
By default the Babel plugin writes CSS to a file (mode: 'file'). Inject mode (mode: 'inject') embeds CSS inline in your JavaScript and injects it at runtime via a tiny injector. No CSS file is produced.
This is ideal for reusable components, extensions, and libraries where consumers shouldn’t need to manage an external CSS file.
- The Babel plugin extracts CSS at build time (same pipeline as file mode).
- Instead of writing to a
.cssfile, the CSS is embedded as string literals in the JS output. - The
@tenphi/tasty/staticimport is rewritten to@tenphi/tasty/static/inject. - Each
tastyStaticcall becomes a self-contained expression that injects its CSS and evaluates to aStaticStyleobject.
// babel.config.js
module.exports = {
plugins: [
[
'@tenphi/tasty/babel-plugin',
{
mode: 'inject',
config: {
states: { '@mobile': '@media(w < 768px)' },
},
},
],
],
};With Next.js:
// next.config.ts
import { withTastyZero } from '@tenphi/tasty/zero/next';
export default withTastyZero({
mode: 'inject',
configFile: './app/tasty-zero.config.ts',
})({
reactStrictMode: true,
});When mode is 'inject', the output and injectImport options are ignored.
Before:
import { tastyStatic } from '@tenphi/tasty/static';
const button = tastyStatic({
padding: '2x 4x',
fill: '#purple',
});
tastyStatic('.heading', { preset: 'h1' });After:
import { injectCSS as _$i } from '@tenphi/tasty/static/inject';
_$i(
'@property',
'@property --tasty-second-fill-color { … }\n@property --current-color { … }\n…',
);
const button =
(_$i(
'tsa903d6 ts070801',
'.tsa903d6.tsa903d6 { background-color: var(--purple-color); }\n.ts070801.ts070801 { padding: 16px 32px; }',
),
{
className: 'tsa903d6 ts070801',
styles: { padding: '2x 4x', fill: '#purple' },
toString() {
return this.className;
},
});
_$i('.heading', '.heading { font-size: var(--h1-font-size, …); … }');Each file that calls tastyStatic() starts by injecting Tasty’s default @property rules and your config.properties under the @property id. injectCSS() skips an id it has already injected, so the page gets them once.
Class names are content-hashed (ts + MD5). When styles change, a new hash produces a new _$i call that injects fresh CSS. The injector deduplicates by id, so unchanged styles are skipped. Old CSS stays in the DOM but is harmless since no elements reference those class names.
- Client-side only — Styles are injected via the DOM, so they are not available during SSR. For server-rendered apps, use
mode: 'file'or Reacttasty(). - Larger JS bundle — CSS is embedded in JavaScript, increasing bundle size. Best suited for components and extensions, not full-app styling.
// Base button
const button = tastyStatic({
display: 'inline-flex',
padding: '2x 4x',
radius: '1r',
fill: '#gray.20',
color: '#text',
transition: 'fill',
});
// Variants
const primaryButton = tastyStatic(button, {
fill: '#purple',
color: '#white',
});
const dangerButton = tastyStatic(button, {
fill: '#danger',
color: '#white',
});const card = tastyStatic({
padding: {
'': '4x',
'@mobile': '2x',
},
display: {
'': 'flex',
'@mobile': 'block',
},
});If you add custom style properties, use module augmentation so tastyStatic recognizes them too. See TypeScript in the configuration docs.
- Static values only — All style values must be known at build time
- No runtime props — Cannot use
stylePropsor dynamicstylesprop - No mods at runtime — Modifiers must be defined statically
- Build-time transformation required — Babel plugin must process files
For dynamic styling needs, combine with regular CSS or CSS variables:
const card = tastyStatic({
padding: '4x',
fill: '($card-bg, #white)',
});
<div
className={card.className}
style={
{
'--card-bg': isActive ? 'var(--purple-color)' : 'var(--white-color)',
} as React.CSSProperties
}
/>;- Define base styles for common patterns, then extend for variants
- Use selector mode for global/body styles
- Enable devMode in development for easier debugging
- Configure states for consistent responsive breakpoints
- No CSS file is generated: make sure the Babel plugin actually runs for files importing
@tenphi/tasty/static, and verify theoutputpath is writable. - Styles stay dynamic by mistake:
tastyStatic()only supports build-time-known values. Move dynamic values to CSS variables or switch that component to Reacttasty(). - Turbopack config behaves inconsistently: prefer
configFileover inline functions so the setup stays JSON-serializable.
- Docs Hub — Choose the right guide by task or CSS delivery model
- Style DSL — State maps, tokens, units, extending semantics (shared by runtime and static)
- React API — Client or server rendering with
tasty(): component props, variants, sub-elements, and style functions - Configuration — Global configuration: tokens, recipes, custom units, and style handlers
- Plugins & Extension Points — Which extension points work at build time (
functions,units,states,handlers,recipes) and which do not (propHandlers—tastyStatic()takes styles objects, not props)