--- author: [Teemu Lahjalahti](https://www.linkedin.com/in/teemulahjalahti/) index: https://salty-css.dev/llms.txt --- # Runtime styles Salty is a build-time library, and runtime styles don't change that. `defineRuntime` is a small, deliberate opening in the wall: a request-time helper that takes a style object and hands back a `{ className, css }` pair you render into the page. The difference from everything else in Salty is that the input doesn't have to exist when the project compiles — it can come from a database row, a CMS field, or whatever a person saved in a settings panel three minutes ago. Worth being straight about what this is *not* for, because the name invites the wrong idea: it isn't a way to move style generation off the build and into your requests. The static stylesheet stays the fast path, and anything you can express at build time should stay there. What runtime styles buy you is the ability to ship customization that genuinely depends on the request — that's a product feature you either can or can't offer, not a performance decision. One warning up front, since it's the kind that gets skipped: styles that arrive as data are untrusted input, and CSS is less harmless than it looks. Salty does not sanitize what you hand the parser — that's a deliberate choice, covered in [Security](#security-a-note-before-you-ship-it) near the bottom. Read it before you wire this to a public text field. --- ## When you reach for it Most of the time you don't, and that's the intended outcome. Four rungs, and you should stop climbing at the first one that fits: 1. **The styles are known when the project compiles.** [`styled`](/astro/docs/basics/styled-components) or [`className`](/astro/docs/basics/class-names). This is the everyday choice and it covers almost everything. 2. **The shape is known, one value isn't** — a tint, a progress width, a stagger index. That's a prop token: `{props.X}` in the style, `css-x` at the call site, one static rule and a CSS variable carrying the value. See [Dynamic Values](/astro/docs/basics/dynamic-values). 3. **The style object itself doesn't exist until the request runs** — a CMS block author dropped in a custom payload, a profile row carries a layout, a tenant config supplies brand overrides. There's nothing for the compiler to extract, because the rule doesn't exist yet. That's this page. 4. **It changes per frame in the browser** — a cursor-following gradient, a drag offset. Use a plain `style` prop. `defineRuntime` is a request-time helper, not a per-frame one. The two cases that actually drove this feature, so you can pattern-match against your own: **Profile customization.** You want to give people real control over their own corner of your product — a profile, a portfolio page, a small site inside your site. Named looks you designed are one thing (that's [theming](/astro/docs/basics/theming)), but "pick your own colors and spacing and let it be yours" isn't enumerable at build time. Runtime styles are how the module components on that page get styled per person. **One-off overrides in a systematic layout.** You've built a page out of six block components, everything is consistent, and then the client or the designer wants *this one section* to be different. Not a new variant anybody will use twice — one deliberate deviation, in one place. Runtime styles let you make it without polluting the component with a variant that exists for a single URL. ### Why not just an inline style Because an inline style is a flat list of declarations, and that's all it will ever be. It can't hover. It has one job, in one place, and no chance to hit that Sacred Flame to help the party (sorry Shadowheart). No breakpoints, no reaching a child element, no reacting to a `data-` attribute. `defineRuntime` runs the *same parser* as the build-time compiler, so what you hand it is a real Salty style object: nested selectors, `&:hover`, media queries, tokens, templates. And it produces a real scoped rule with a real class, not a `style` attribute — so it participates in the cascade like CSS instead of sitting on top of it. That's the entire argument for this API over `style={{ … }}`, and it's most of what makes the profile case workable. --- ## Example 1 — The loop Set up a runtime once, resolve a style object per request, render the class and the CSS together. ### How you define it ```ts // a regular .ts file, not .css.ts import { defineRuntime } from "@salty-css/astro/runtime"; import config from "../salty.config"; export const runtime = defineRuntime(config); ``` Two things are load-bearing here. **It's a plain `.ts` file.** `defineRuntime` isn't a `define*` factory the compiler collects — there's nothing to extract, since the CSS is generated when your server code runs. Calling it from a `.css.ts` file doesn't error; it just quietly does nothing useful, which is worse. Keep it out of there. **Passing `config` is what connects this to your design system.** The runtime reads `variables`, `templates`, `mediaQueries` and `modifiers` from whatever you hand it, so an incoming `{colors.brand.main}` resolves to the exact same CSS variable your `styled` components already reference, and `@tabletUp` resolves to the same breakpoint they use — same names, same values, one source of truth. Skip the config and `{colors.brand.main}` still compiles to `var(--colors-brand-main)`; it just points at a variable nothing declared, which renders as nothing at all. `defineRuntime()` with no argument is fine when the incoming styles reference nothing from your system. ### How you use it `resolve` gives you the pair. Render the CSS in a ` {children} ); } ``` Notice what's mixed in: `{colors.grey.light}` is your token, sitting in the same object as the person's chosen accent color. The parts of the design you still own stay owned. ### How you use it ```tsx const profile = await getProfile(handle); // your data layer

{profile.title}

{profile.bio}

; ``` ### The habit worth copying **Don't pass a raw object from your database straight to `resolve`.** Map it, field by field, into a shape you wrote. It costs you a type and a few lines, and it buys three things: a much smaller security surface (see below), the freedom to redesign later without every saved profile turning into a broken layout, and an actual answer when someone asks what a "profile style" can contain. **Dedupe when a page renders many of these.** Because the class is a hash of the object, a hundred modules sharing one look are a hundred identical `} {/* …block content, rendered by the same components as every other section */} ); } ``` ### How you use it The override lives with the content, in whatever shape your CMS or config gives you: ```ts { type: "section", styleOverride: { background: "{colors.black}", color: "{colors.grey.light}", paddingBlock: "3rem", "@desktopUp": { paddingBlock: "4rem" }, }, // … } ``` Note the `@desktopUp` in there. Named breakpoints work in a runtime payload exactly as they do in a `styled` component — define them once with `defineMediaQuery`, reference them by `@name` — which means the people or systems writing overrides get your breakpoint vocabulary instead of guessing pixel values. Same failure mode as at build time, too: if a definition never reaches the build, the name silently emits an at-rule that never matches. The block component is untouched. Every other section still renders the plain `Section`, and the deviation is data — visible where the content lives, deletable in one edit, and not a permanent new axis in your component API. Two notes on how this lands in the cascade. First, `styled` components accept a `className` at the call site like any React element, which is how the runtime class rides along next to the generated hash. Second — and this is the part that makes overrides actually work — **runtime CSS is emitted without a cascade layer.** Salty's own rules all live in [layers](/astro/docs/basics/scoping-and-composition), and in native CSS an unlayered rule outranks every layered one regardless of specificity. So the override wins over the component's own styles with no specificity fight, no `priority` bump, and no `!important`. That's exactly what you want for a deliberate one-off, and exactly why you shouldn't reach for this casually: a runtime rule sits above your entire layer hierarchy by construction. It's a trump card, not a tiebreaker. If you'd rather target something that already has a selector — a global id, an element you don't wrap — use `runtime.css(styles, "#hero")` and skip the class entirely. --- ## What comes along, and what doesn't Because it's the same parser, most of Salty's authoring surface works unchanged. The exceptions are the things that need either a component wrapper or a place in the static stylesheet — `defineRuntime` returns strings, not components, and its output lives in a per-request `