Extension Architecture

Overview

The CSS & JS Minifier extension follows a modular architecture pattern that separates concerns into distinct layers for better maintainability, testability, and code reusability.

Architecture Layers

1. Extension Entry Point (src/extension.ts)

• Purpose: Activation / deactivation lifecycle management.
• Responsibilities: Synchronous command registration at the top of activate() (prevents the “command not found” race documented in #145), onDidSaveTextDocument listener for the minifyOnSave feature, output channel initialization, and reporting activation failures via showErrorMessage with a pointer to the output panel.

2. Commands Layer (src/commands/)

• Purpose: VS Code command handlers and user interaction logic.
• Components:
  • minifyCommand.ts — extension.minify and extension.minifyInNewFile handlers, plus the shared processDocument() core. Handles both active-editor and explorer-URI invocations, plus the untitled-document guard (#145).
  • index.ts — command exports.

3. Services Layer (src/services/)

• Purpose: Business logic and minification orchestration.
• Components:
  • minificationService.ts — facade that routes to the appropriate strategy based on languageId.
  • fileService.ts — file system operations, URI and filename generation for the minified sibling with the configured minifiedNewFilePrefix (inserted before the last extension, for any extension and case; createMinifiedUri keeps the source document’s scheme and authority), the guard that refuses to write the new file over its source (#255), and the size-reduction statistics rendering.
  • strategies/localCssMinifier.ts — CSS via LightningCSS (Rust transform()).
  • strategies/localJsMinifier.ts — JavaScript via oxc-minify (Rust minifySync()).
  • strategies/index.ts, index.ts — barrel exports.

4. Utils Layer (src/utils/)

• Purpose: Reusable validation and localization helpers.
• Components:
  • validators.ts — file type and content validation with localized user feedback, and the minifiedNewFilePrefix check (isValidFilePrefix, getValidFilePrefix): 1 to 32 characters of letters, digits, ., - and _, no ... Both entry points that write a new file read the setting through getValidFilePrefix; an invalid value shows an error and writes nothing (#259). Minify on save shows it once per session per value.
  • l10nHelper.ts — one-line delegate to vscode.l10n.t(message, ...args) so every call site imports from a single stable path. See INTERNATIONALIZATION.md.
  • index.ts — barrel exports.

5. Lib Layer (src/lib/)

• Purpose: Shared infrastructure constants and pure helpers.
• Components:
  • constants.ts — byte size constants used for the size-reduction display.
  • helpers.ts — pure functions such as formatBytes() and calculateStats().
  • index.ts — barrel exports.

6. Types Layer (src/types/)

• Purpose: Domain type definitions shared across layers.
• Components:
  • minification.ts — MinificationStats, MinificationResult.
  • index.ts — barrel exports.

Benefits of Modular Architecture

✅ Separation of Concerns

• Each module has a single responsibility
• Clear boundaries between UI logic, business logic, and utilities
• Easier to locate and modify specific functionality

✅ Code Reusability

• No duplicate validation or API logic between commands
• Shared utilities across different command handlers
• Consistent error handling patterns

✅ Enhanced Testability

• Pure functions easier to unit test
• Isolated business logic can be tested independently
• Mocking external dependencies is straightforward

✅ Improved Maintainability

• 63% reduction in main file complexity
• Self-documenting code with comprehensive JSDoc
• Clear module dependencies and exports

✅ Better Developer Experience

• IntelliSense support for all module functions
• Type safety with proper interfaces
• Consistent coding patterns throughout

Data Flow

User Action (Command / Keybinding / Context Menu / onDidSaveTextDocument)
    ↓
Command Handler (commands/minifyCommand.ts)
    ↓
Validation (utils/validators.ts)
    ↓
Minification Service (services/minificationService.ts)
    ↓
Strategy (services/strategies/local{Css,Js}Minifier.ts)
    ↓
File Operations (services/fileService.ts) + Stats (lib/helpers.ts)
    ↓
User Feedback (VS Code Notifications, localized via utils/l10nHelper.ts)

Module Dependencies

extension.ts
    ├── commands/minifyCommand.ts
    │     ├── utils/validators.ts
    │     ├── utils/l10nHelper.ts
    │     ├── services/minificationService.ts
    │     │     └── services/strategies/{localCssMinifier,localJsMinifier}.ts
    │     └── services/fileService.ts
    │           └── lib/helpers.ts (formatBytes, calculateStats)
    └── types/minification.ts (shared across layers)

Error Handling Strategy

Layered Error Handling

1. Validation Layer: Input validation with user-friendly messages
2. Service Layer: Minification error handling with specific error codes
3. Command Layer: Coordination and user notification
4. Extension Layer: Global error catching and logging

User Experience Focus

• All errors show appropriate VS Code notifications
• Context-aware error messages (file type, syntax errors)
• Both CSS and JS minification work fully offline

Configuration Management

Centralized Settings

• All configuration accessed through vscode.workspace.getConfiguration()
• Settings validated at the point of use
• Default values provided for all optional settings

Dynamic Configuration

• Settings can be changed without extension restart
• Configuration changes take effect immediately
• Per-workspace and global configuration support

Supported Workspaces

The manifest declares both workspace capabilities explicitly (capabilities in package.json), so the behaviour is a decision and not a default.

Why limited and not true: the extension never runs workspace code, spawns a process or uses the network, but minifiedNewFilePrefix ends up in the name of a file the extension writes, and the enum in the schema is not enforced on values read from settings.json. A workspace could set a prefix such as /../../x, and a save or a Minify and Save as New File would then write the minified document outside its folder. Restricting the three settings that decide when a file is written and where it goes closes that for an untrusted workspace. For a trusted workspace and for the user’s own settings, the runtime check in utils/validators.ts (#259) refuses any prefix that is not 1 to 32 letters, digits, ., - or _ without .., so no value can add a path segment. The two measures overlap on purpose. Everything else (manual in-place minification, autoOpenNewFile, showSizeReduction) keeps working in Restricted Mode. Why not false: nothing else needs trust, and without a declaration VS Code treats an extension as not supporting Workspace Trust and disables it in Restricted Mode.

Out of scope: running in the web (browser entry point). lightningcss and oxc-minify are native Rust bindings and do not load there.

Performance Optimizations

Efficient Processing

• Local Rust-based minification (LightningCSS + oxc-minify) — no network latency, fully offline.
• Synchronous minification APIs for instant results.
• Webpack bundling with oxc-minify, lightningcss, and detect-libc marked as externals so the platform-specific .node binaries are loaded from node_modules/ at runtime rather than bundled into dist/extension.js.
• .vscodeignore whitelists only the required native binaries per architecture, keeping each .vsix small.

Distribution (multi-target .vsix)

The extension ships eight platform-specific .vsix files — one per VS Code Marketplace target — instead of a single “universal” archive. This is required because both lightningcss and oxc-minify ship Rust-based .node binaries via optionalDependencies, and vsce package only bundles the bindings that npm install materialized on the packaging host.

VS Code reports Alpine hosts (Dev Containers, Remote SSH and WSL distributions based on Alpine) as alpine-x64 or alpine-arm64, and it only installs a package whose target matches exactly, so the linux-* packages are never offered there. Both native modules publish musl bindings, which is why these two extra targets exist.

Each runner:

1. npm ci — installs the native optional dependencies for its own OS/CPU automatically. The alpine-* targets are built on the glibc Linux runners with npm ci --libc=musl: oxc-minify declares libc on its bindings, so this selects the musl binding. lightningcss declares no libc, so its glibc and musl bindings are both installed and the glibc one (lightningcss-linux-*-gnu) is deleted before packaging.
2. npm run package — webpack production bundle.
3. npx vsce package --target <target> — produces the platform-tagged .vsix.
4. node scripts/verify-vsix-activation.mjs <vsix> — extracts the archive, require()s lightningcss and oxc-minify, and calls each once to prove the binaries load on that platform. The alpine-* targets run it inside a node:20-alpine container with --expect-libc musl, since musl bindings only load on a musl host. Exit 1 on a binding regression, 2 on an infrastructure failure.

The eight artifacts are attached to the GitHub Release and published to the Marketplace as separate platform-tagged listings by the Build & Release workflow (.github/workflows/release.yml). VS Code serves each user the artifact that matches their OS/CPU. The same files are then published to Open VSX (used by VSCodium, Eclipse Theia, Gitpod and other forks) by .github/workflows/publish-openvsx.yml, which downloads them from the GitHub Release instead of rebuilding, so both registries serve identical artifacts. See AGENTS.md → Cross-platform CI matrix for the workflow contract and .github/instructions/publish-update-extension.instructions.md for the release runbook.

Future Extensibility

• New strategies: add another services/strategies/*Minifier.ts and wire it into minificationService.
• New file types: extend utils/validators.ts and register the language in package.json.
• New languages: add package.nls.<locale>.json + l10n/bundle.l10n.<locale>.json; see INTERNATIONALIZATION.md.

Last Updated: 2026-10-28 Extension Version: 1.3.4