skip to content

In a Vite config, what does `css.preprocessorOptions.scss.additionalData` do, and why can it duplicate CSS or break relative imports?

level: middleimportance: should knowfreq 8%

answer

  1. options keyed by extension
  2. prepended to each compiled stylesheet
  3. variables and mixins, not rules
  4. same text, many folders
  5. string or (source, filename) function

basics

~20 s

additionalData 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
typescript
// 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

for a junior

Recall that css.preprocessorOptions is keyed by extension and that additionalData adds code to the top of each Sass stylesheet Vite compiles.

for a middle

Explain why injected rules repeat once per stylesheet, why relative paths break, and when the (source, filename) function form is the right tool.

for a senior

Show you keep the injected module free of output, check the built CSS for repeated rules, and route the import through an alias.

for a principal

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