Vite SCSS Generate Index

Vite plugin for SCSS projects that watches a source folder during vite serve, generates _index.scss files for each directory, and optionally prepends a managed global @use header to watched files.

Generated indexes default to Sass modules and emit @forward statements for sibling SCSS files and nested folders.

Features

• Supports Vite ^8.0.3.
• Generates _index.scss barrel files automatically while developing.
• Skips generating _index.scss in the configured source root itself.
• Uses @forward by default instead of deprecated Sass @import.
• Optionally prepends a managed global @use "... " as *; header.
• Resolves the global header target from the configured SCSS source root.
• Supports excluding files or directories from global header injection to avoid circular dependencies.
• Reconciles global headers on server startup, and injects them for newly created files during dev.
• Ignores ordinary file save/change events.

Installation

npm install @inlite/vite-scss-generate-index

Basic Usage

import { defineConfig } from "vite";
import viteScssGenerateIndex from "@inlite/vite-scss-generate-index";

export default defineConfig({
  plugins: [
    viteScssGenerateIndex({
      src: "src/scss",
    }),
  ],
});

Usage With Global Utils

import { defineConfig } from "vite";
import viteScssGenerateIndex from "@inlite/vite-scss-generate-index";

export default defineConfig({
  plugins: [
    viteScssGenerateIndex({
      src: "src/scss",
      sassMode: "forward",
      globalUse: "utils",
      globalUseExclude: ["utils"],
    }),
  ],
});

With this config:

• globalUse: "utils" is resolved from src/scss.
• If src/scss/_utils.scss exists, the plugin uses that file automatically.
• A file like src/scss/components/_button.scss gets @use "../utils" as *;.
• A file like src/scss/components/forms/_field.scss gets @use "../../utils" as *;.
• src/scss/_utils.scss is excluded from header injection, so it does not @use itself.
• If globalUse starts with @, for example @/styles/utils, the plugin keeps it verbatim and does not rewrite it to a relative path.

Options

• src: Root SCSS folder, relative to the Vite project root.
• sassMode: Generated statement type. Defaults to "forward". Set to "use" if generated _index.scss files should directly load sibling modules instead of re-exporting them.
• globalUse: Optional Sass module name or path. Values that start with @ are kept verbatim. Other values are resolved from the configured src root and rewritten to the correct relative @use path for each watched file.
• globalUseExclude: Optional list of file or directory paths, also resolved from the configured src root, that should never receive the managed global @use header.
• quote: Optional quote style for generated statements. Accepts "single" or "double".
• singleQuotes: Backward-compatible alias for single-quote output when quote is not provided.

Generated Index Output

Generated _index.scss files contain a managed block:

/* generated:index:start */
@forward "button";
@forward "card";
@forward "forms";
/* generated:index:end */

If new files are added later, the plugin appends them while preserving the order of existing generated entries.

Managed Global Header

When globalUse is configured, the plugin prepends a managed block if the same @use line is not already present:

@use "../utils" as *;
/* generated:global-use:end */

Behavior:

• On server startup, the plugin scans existing files and corrects managed global headers to the current relative path.
• During dev, the plugin prepends the managed header only for newly created files or files that appear at a new path.
• Ordinary file save/change events trigger no plugin processing.
• The header path is recalculated per file when the header is inserted or startup reconciliation runs, unless globalUse starts with @, in which case it is written unchanged.
• Existing identical @use lines are not duplicated.
• The plugin only manages the marked block it owns.
• Excluded files and directories do not receive the managed header.

Notes

• The plugin runs only during vite serve.
• Dot-directories are ignored.
• Processing runs on server startup and on create/delete/move-style filesystem events only.
• chokidar is bundled as a runtime dependency.