ensureCssImport - Build Tools

Overview

ensureCssImport ensures required CSS imports exist in compiled JavaScript files, with optional deduplication and sorting.

Why use this?

Supports multiple CSS imports.
Fully idempotent.
Optional dedupe & sorting.

Importing

import { ensureCssImport } from "@rzl-zone/build-tools";

const { ensureCssImport } = require("@rzl-zone/build-tools");

Syntax

ensureCssImport(
  pattern: StringCollection,
  options: EnsureCssImportOptions
): Promise<void>

ensureCssImport(pattern, options): Promise<void>

Parameters

Prop

Type

`pattern`

Glob pattern or list of patterns that target JavaScript output files.

Accepted values:

string ➔ single glob pattern.
string[] ➔ multiple glob patterns.
Set<string> ➔ unique collection of patterns.

Supported glob features

Patterns support common glob syntax, including:

* ➔ match any characters except /.
** ➔ match nested directories.
{} ➔ brace expansion (match multiple extensions or patterns).
! ➔ exclude patterns (can be combined with options.patternOptions.ignore).

Info

Pattern resolution behavior can be customized via options.patternOptions (e.g. hidden files, case sensitivity, concurrency, and ignore rules).

File Matching Behavior

This utility only processes files that match recognized JavaScript build output formats.
This filtering is applied after pattern matching.
Supported file types include:
- .js.
- .mjs.
- .cjs.
- .esm.js.
- .module.js.

Files that do not match these formats will be automatically ignored, even if they are included in the provided pattern.

Examples:

dist/index.js ➔ ✅ processed.
dist/index.ts ➔ ❌ ignored.
dist/styles.css ➔ ❌ ignored.
dist/index.js.map ➔ ❌ ignored.

Examples

TypeScript/JavaScript

// Single pattern
ensureCssImport("dist/**/*.js");

// Multiple patterns
ensureCssImport(["dist/**/*.js", "build/**/*.js"]);

// Using Set
ensureCssImport(new Set(["dist/**/*.js"]));

// With options
ensureCssImport("dist/**/*.{js,cjs,mjs}", {
  patternOptions: {
    ignore: ["**/*.test.js"]
  }
});

// Exclude pattern
ensureCssImport([
  "dist/**/*.{js,cjs,mjs}",
  "!dist/**/*.test.js"
]);

`options`

Optional configuration object that defines how the utility function should behave in various scenarios, allowing customization and greater control at runtime.

`cssImportPath`

Description:
CSS import path(s) to ensure exist in JS output.

Accepts a single path or multiple paths.
Required:
Type:
string | readonly (string | readonly string[])[] | Set<string>
Default:
-

Example:

TypeScript/JavaScript

await ensureCssImport(["dist/**/*.js", "build/*/*.mjs"], {
  cssImportPath: "./search.css"
});

// Using array, css import path
await ensureCssImport(["dist/**/*.js", "build/*/*.mjs"], {
  cssImportPath: ["./search.css", "./theme.css"]
});

// Using set, css import path
await ensureCssImport(["dist/**/*.js", "build/*/*.mjs"], {
  cssImportPath: new Set(["./search.css", "./theme.css"])
});

Notes

Will throw error if this value is empty string, empty array or unset.

`dedupe`

Description:
Remove duplicate CSS imports (recommended).
Required:
Type:
boolean
Default:
true
Example:
TypeScript/JavaScript
await ensureCssImport(["dist/**/*.js", "build/*/*.mjs"], { dedupe: false });

`sort`

Description:
Sort CSS imports alphabetically before inserting.
Required:
Type:
boolean
Default:
false
Example:
TypeScript/JavaScript
await ensureCssImport(["dist/**/*.js", "build/*/*.mjs"], { sort: true });

`minify`

Description:
Minify JS output (except directive prologue).
- Keeps "use client" / "use strict" on separate lines.
- Everything else is collapsed into a single line.
Required:
Type:
boolean
Default:
false
Example:
TypeScript/JavaScript
await ensureCssImport(["dist/**/*.js", "build/*/*.mjs"], { minify: true });

`logLevel`

Description:
Controls how detailed the logger output should be during execution.
Supported values
- silent ➔ no output.
- error ➔ errors only.
- info ➔ standard logs (default).
- debug ➔ verbose logs.
Notes
- Invalid values are automatically reset to default.
- All levels include error output except silent.
Required:
Type:
"error" | "silent" | "info" | "debug"
Default:
"info"

Example:

TypeScript/JavaScript

// Minimal output (errors only)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "error"
});

// Debug mode (verbose logs)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "debug"
});

// Silent mode (no logs)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "silent"
});

`patternOptions`

Description:
Controls how input file patterns are matched.

Used to filter or adjust which files are included during processing.
Useful for ignoring files, handling hidden files, or tweaking matching behavior.
Behavior
- Affects which files are selected.
- Can exclude unwanted files (e.g. test files).
- Falls back to default configuration when invalid type or not provided.
Required:
Type:
object

Default:

{
  absolute: false,
  baseNameMatch: false,
  caseSensitiveMatch: true,
  concurrency: os.cpus().length,
  dot: true,
  followSymbolicLinks: true,
  globstar: true,
  ignore: [],
  markDirectories: false,
  objectMode: false,
  onlyDirectories: false,
  onlyFiles: true,
  unique: true,
  throwErrorOnBrokenSymbolicLink: false
}

Example:

TypeScript/JavaScript

// Ignore source maps
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  patternOptions: {
    ignore: ["**/*.map"]
  }
});

// Case-insensitive matching
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  patternOptions: {
    caseSensitiveMatch: false
  }
});

// Disallowing patterns to match entries that begin with a period (.).
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  patternOptions: {
    dot: false
  }
});

Returns

Returns a Promise<void>.
The function performs asynchronous file processing and does not return any value.

Version information

Since: v0.0.7.
Category: ensure.
Stability: ✅ Stable (Production-ready).

Made with ❤️ by @rzl-app