npm package: @inlite/vite-scss-generate-index
Description: Vite plugin to generate _index.scss files automatically
Latest version: 0.2.0

# 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

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

## Basic Usage

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

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

## Usage With Global Utils

```js
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:

```scss
/* 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:

```scss
@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.