Navigation
Integrations

Set up Master CSS in SvelteKit

Install the SvelteKit add-on, connect the root stylesheet and choose static, runtime, progressive or pre-render-only CSS delivery.

On this page

Add Master CSS to a SvelteKit application. The add-on registers the Vite integration and imports its CSS entry from the root layout, so every route receives the shared styles.

#Installation

  1. #Add Master CSS

    In an existing SvelteKit project, run the Svelte CLI add-on from the project root. It installs static rendering and leaves existing server hooks unchanged.

    npx sv add @master/css-svelte-addon

  2. #Check the shared entry

    The add-on updates the project's CSS entry with @import '@master/css'; and imports that entry from src/routes/+layout.svelte. Keep the layout's existing script, child rendering and other imports. Do not put the global entry in a page that other routes never load.

    In vite.config.ts, keep both masterCSS() and sveltekit(...). Static mode does not need a Master CSS client or server hook.

  3. #Start using Master CSS

    Start the dev server and replace src/routes/+page.svelte with this paragraph. Keep the stylesheet import added to src/routes/+layout.svelte.

    4. Check the installed styles

    src/routes/+page.svelte
    <p id="master-check" class="w-fit m(0) p-md b-solid b(1) b-line-divider r-md text-sm font-regular bg-surface-raised fg-text-strong">  Hello World</p>
    A neutral surface, a fine border, small corners and 1rem of padding on every side.

#Check the static setup

Run npm run dev and change p-md to p-lg in the page. Its padding should grow from 1rem to 1.5rem. Restore it, then check the production build:

npm run buildnpm run preview

With server rendering enabled, the paragraph should keep its padding, rounded corners and raised surface when JavaScript is disabled. Visit another route to confirm that the root layout loads the entry there too. If styles are missing, check the Master CSS plugin in vite.config.ts and the CSS import in the root layout.

Component <style> blocks can use project tokens in native declarations. Keep the global CSS entry loaded for resets, native component rules and generated utilities. Use @reference for definition files outside the project context.

#Choose another rendering mode

Static mode is the default and needs no Master CSS hooks. Keep the CSS entry when changing modes:

ModeVite modeMaster CSS hooks
StaticstaticNone
RuntimeruntimeClient
ProgressiveprogressiveClient and server
Pre-render onlypre-renderServer with hydration manifest disabled
Generate new classes in the browser

In vite.config.ts, replace the existing masterCSS() call with this option. Keep the sveltekit(...) call, its adapter configuration, and any other plugins:

masterCSS({ mode: 'runtime' })

Load the bootstrap once from the client hook. Keep any existing hook exports:

src/hooks.client.ts
/// <reference types="@master/css/client" />import 'virtual:master-css-runtime'

SvelteKit renders its own HTML, so the Vite mode option alone does not insert a runtime script. The client import starts the runtime with the project program and handles Vite HMR.

After startup, run this in the browser console. The paragraph should gain an underline without rebuilding:

document.querySelector('#master-check').classList.add('underline')
Include server-rendered styles

For progressive rendering, change the Vite option above to mode: 'progressive', keep the client hook, and add the server handle:

src/hooks.server.ts
export { handle } from '@master/css-svelte/hooks.server'

If the application already has a server handle, preserve it and place the Master CSS handle first in SvelteKit's sequence(). Page transforms run in reverse order, so Master CSS then sees the HTML produced by the later handlers. For example, move your existing handle into src/hooks.application.ts without changing its behavior, then compose the two:

src/hooks.server.ts
import { sequence } from '@sveltejs/kit/hooks'import { handle as masterCSS } from '@master/css-svelte/hooks.server'import { handle as application } from './hooks.application'export const handle = sequence(masterCSS, application)

Keep unrelated exports such as handleError in hooks.server.ts.

A page covered by its pre-rendered classes can defer loading the runtime engine. Check initial styling with JavaScript disabled, then re-enable it and test a new class.

For pre-render-only delivery, choose mode: 'pre-render', remove only the Master CSS client bootstrap, and use this server configuration:

src/hooks.server.ts
/// <reference types="@master/css/client" />import manifest from 'virtual:master-css-manifest'import emittedGlobals from 'virtual:master-css-emitted-globals'import { createMasterCSSHandle } from '@master/css-svelte/hooks.server'export const handle = createMasterCSSHandle({  manifest,  emittedGlobals,  hydrationManifest: false})

This supplies CSS for the rendered HTML without a Master CSS browser runtime. Classes introduced later need a separately delivered stylesheet or a mode with runtime generation.