injectDirective

Overview

injectDirective is a utility for injecting JavaScript directive statements into compiled output files.

It scans files based on the provided glob pattern(s) and inserts one or more directive statements (e.g. "use strict", "use client") at the top of each file when applicable.

Directives are injected in a safe and controlled way, ensuring they are not duplicated and do not interfere with existing file structure.

Key capabilities

• Directive Injection
  Adds one or multiple directive statements to matched files.

• Targeted File Processing

  • Processes only JavaScript output files.
  • Skips files that are empty, contain no executable code, or only directives.

• Smart Placement

  • Injected after shebang (#!) and banner comments.
  • Maintains correct execution order.

• Content Preservation
  Keeps the original file structure intact without modifying existing code.

• Idempotent Operation
  Running multiple times will not duplicate directives.

Why use this?

• Ensures required directives (e.g. "use strict", "use client") are consistently applied.
• Prevents duplicate directive declarations.
• Automatically adapts to file type (e.g. CommonJS vs ESM).
• Helps maintain correct runtime behavior.
• Simplifies directive management in build pipelines.

Importing

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

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

Syntax

injectDirective(
  pattern: StringCollection,
  bannerText: StringCollection,
  options?: InjectJsArtifactsOptions
): Promise<void>

injectDirective(pattern, bannerText, options?): Promise<void>

Parameters

pattern

Glob pattern or list of patterns used to target files for directive injection.

Accepted values:

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

Supported glob features

Patterns support common glob syntax:

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

File processing behavior

All files matched by the provided pattern(s) are scanned.

Only files recognized as JavaScript output files are processed.

This includes common formats such as:

• .js.
• .mjs.
• .cjs.
• .esm.js.
• .module.js.

Files outside these formats are automatically skipped.

Additional filtering

A matched file will be skipped if it:

• Is empty or contains only whitespace.
• Contains no executable JavaScript code.
• Contains only directive statements.

Important notes

• Directive injection only applies to valid JavaScript output files.
• Existing directives are automatically detected and not duplicated.
• File structure (shebang, banners, and code order) is preserved.

Examples

// Single pattern
injectDirective("dist/**/*.js", "use strict");

// Multiple patterns
injectDirective(["dist/**/*.js", "build/**/*.mjs"], "use client");

// Using Set
injectDirective(new Set(["dist/**/*.js"]), "use strict");

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

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

Summary

• Uses glob patterns to select target files.
• Processes only valid JavaScript output files.
• Skips non-executable or directive-only files.

directive

Directive string or collection of strings to inject into matched files.

Accepted values:

• string ➔ single directive.
• string[] ➔ multiple directives.
• Set<string> ➔ unique collection of directives.

Each entry represents a directive that will be injected as a standalone statement.

Injection behavior

• Directives are inserted at the top of each file.
• Existing shebang (#!) and banner comments are preserved.
• Existing "use *" directives are automatically detected.
• Duplicate directives are not injected.

Each directive is normalized into:

"directive-name";

Automatic handling

• "use strict" is automatically handled for CommonJS files.
• Duplicate "use strict" will not be inserted.
• Custom directives are trimmed and normalized before injection.

Normalization

Each directive is normalized before injection:

• Wrapped in quotes if needed.
• Ensured to end with a semicolon.
• Consistent line formatting is applied.

The operation is idempotent — running multiple times will not duplicate directives.

Important notes

• Only top-level "use *" directives are considered.
• Directives are inserted before executable code.
• Existing file structure (shebang, banners, code order) is preserved.

Examples

Single directive:

await injectDirective(
  "dist/**/*",
  "use strict"
);

Multiple directives:

await injectDirective(
  "dist/**/*",
  ["use strict", "use client"]
);

Using Set:

await injectDirective(
  "dist/**/*",
  new Set(["use strict", "use client"])
);

Summary

• directive defines which directive statements are injected.
• Supports single or multiple directives.
• Automatically avoids duplicates.
• Normalized into valid "use *" statements.

options

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

Returns

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

Version information

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