In a Vite config, what does `css.preprocessorOptions.scss.additionalData` do, and why can it duplicate CSS or break relative imports?
answer
- options keyed by extension
- prepended to each compiled stylesheet
- variables and mixins, not rules
- same text, many folders
- string or (source, filename) function
basics
~20 sadditionalData prepends code, or a function's result, to every Sass stylesheet Vite compiles. Inject only variables, mixins or a tokens @use: real CSS rules get emitted once per stylesheet, and a relative path breaks in files from other folders.
solid answer
~40 s`css.preprocessorOptions` passes options to each preprocessor, keyed by extension (`scss`, `sass`, `less`, `styl`). Vite adds `additionalData` to every key: a string prepended to each stylesheet of that type it compiles - an imported `.scss` file, a `.module.scss` file, a component's `lang="scss"` block - or a `(source, filename)` function that returns the new source. Partials that a stylesheet loads through `@use` do not get it. Because the text is copied into each compiled stylesheet, inject only what emits no CSS, such as `@use "@/styles/tokens" as *;` exposing variables and mixins; if the injected module outputs rules, every stylesheet emits them and the bundle repeats them. Because the same text lands in files in different folders, a relative path in it resolves differently per file, so use an alias or an absolute path.
code
typescript · 17 lines// vite.config.ts - give every job-board stylesheet the design tokens
import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
export default defineConfig({
resolve: {
alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) },
},
css: {
preprocessorOptions: {
scss: {
// variables and mixins only: anything that emits CSS is repeated per stylesheet
additionalData: `@use "@/styles/tokens" as *;\n`,
},
},
},
})go deeper
Recall that css.preprocessorOptions is keyed by extension and that additionalData adds code to the top of each Sass stylesheet Vite compiles.
Explain why injected rules repeat once per stylesheet, why relative paths break, and when the (source, filename) function form is the right tool.
Show you keep the injected module free of output, check the built CSS for repeated rules, and route the import through an alias.
Decide how a shared design-token package is consumed across apps: injected globally, imported explicitly per file, or exposed as CSS custom properties.
## What `css.preprocessorOptions` is `css.preprocessorOptions` maps a stylesheet extension to the options Vite passes to that preprocessor: | Key | Preprocessor | Notes | |---|---|---| | `scss` / `sass` | Sass | uses `sass-embedded` if installed, otherwise `sass` | | `less` | Less | Less's own options, such as `math` | | `styl` / `stylus` | Stylus | only `define` is supported | Each preprocessor's own options pass straight through. On top of them, Vite supports one option of its own under every key: **`additionalData`**. ## What `additionalData` injects `additionalData` is either: 1. a **string**, prepended to the source of each stylesheet of that type that Vite compiles, or 2. a **function** `(source, filename) => string | { content, map }` whose return value becomes the whole new source - so it must include `source` itself. "Each stylesheet Vite compiles" means each `.scss` file imported from JavaScript, each `.module.scss` file and each `lang="scss"` style block in a framework component. It does **not** mean every file on disk: Vite removes `additionalData` from the options before it calls Sass, so a partial such as `_mixins.scss` that a stylesheet loads through `@use` is read by Sass unchanged. In the job-board SPA, the injected line gives every component stylesheet the design tokens: ```ts css: { preprocessorOptions: { scss: { additionalData: `@use "@/styles/tokens" as *;\n` }, }, }, ``` Every `.scss` file can now use `$brand-teal` or `@include card-shadow` without its own `@use` line. ## Why it duplicates CSS Each stylesheet is a separate Sass compilation. A module loaded through `@use` is emitted once **per compilation**, so if `tokens.scss` contains a real rule - a `.visually-hidden` helper, an `@font-face`, a `:root` block of custom properties - every stylesheet that received the prefix emits it again, and the final CSS repeats it once per file. Vite's docs state the rule directly: if you include actual styles and not just variables, those styles are duplicated in the final bundle. Keep the injected module to things that produce no output by themselves: - variables and maps; - functions; - mixins, which emit only where they are included. Global rules belong in one stylesheet that the app imports once, such as `src/styles/global.scss` imported from `main.ts`. ## Why relative paths break The same text is prepended to files in many directories. `@use "../styles/tokens"` resolves from `src/jobs/` but not from `src/jobs/detail/` or from `src/components/`. Vite's docs say to use absolute paths or aliases instead; Vite respects its aliases in Sass imports, so `@use "@/styles/tokens"` works from every folder once `resolve.alias` maps `@`. ## Checking for duplication Duplication is silent: the build succeeds and the page looks right, so look at the output instead. 1. Build once without the prefix and once with it, and compare the total CSS size; a jump that grows with the number of component stylesheets is the signature. 2. Search the built CSS for a selector that only the injected module defines, such as `.visually-hidden`; more than one hit means the module emits output. 3. Move whatever emits CSS into a stylesheet imported once, and keep the injected module to declarations. ## When to use the function form The function receives the original source and the file name, which lets you vary the prefix per file: - skip folders that must not receive it, such as vendored stylesheets; - inject a different tokens module for one part of the app; - leave a file alone when it already loads the module itself. ```ts additionalData: (source, filename) => filename.includes('/vendor/') ? source : `@use "@/styles/tokens" as *;\n${source}` ``` ## Related `css` keys - `css.devSourcemap` (experimental, default `false`) turns on CSS source maps in dev; with it, Vite also maps the injected prefix so positions still point into your file. - `css.preprocessorMaxWorkers` (default `true`, meaning up to the number of CPUs minus one) caps preprocessor threads; `0` runs them on the main thread. - How Sass's module system itself works - `@use`, `@forward`, configuring a module with `with` - belongs to Sass, not to Vite's config. ## What interviewers listen for - That `additionalData` is copied into each compiled stylesheet, not shared once. - That it should carry declarations, not CSS output. - That paths inside it must not depend on the importing file's folder.
- How does the function form of Vite's `scss.additionalData` differ from the string form?A string is prepended to every stylesheet as is. A function receives `(source, filename)` and its return value replaces the whole source, so it must include `source`; it may also return `{ content, map }` with a source map. That lets you skip a folder such as vendored styles, or inject a different tokens module for one part of the app.
- Does `scss.additionalData` apply to the partials that a stylesheet loads with `@use`?No. Vite prepends it to the source of each stylesheet it compiles and removes it from the options passed to Sass, so partials loaded with `@use` or `@forward` are read unchanged. So a partial that needs the tokens must load them with its own `@use`.
- additionalData is added once, so injected rules appear once in the bundle
- Relative paths in additionalData resolve from the Vite config's folder
- additionalData is also prepended to partials loaded through @use
- Putting global rules in the injected module is the way to share them
- additionalData works only as a string, never as a function