rolldown-css-manifest-injector

A lightweight and robust Vite 8+ / Rolldown plugin designed for hybrid backend applications (PHP, Symfony, Laravel, WordPress, custom engines).

It bridges the gap between traditional backend asset workflows (like compiling SCSS via IDE File Watchers) and modern frontend tooling. It injects externally compiled CSS files directly into the Vite manifest.json with secure MD5 hashing, post-processing (Autoprefixer, CSSNano), and automatic cleanup of outdated hashes by pattern.

Why this plugin?

Vite is fundamentally a JavaScript-first bundler. When you pass raw CSS into Vite's input, it mutates relative asset paths (url()) inside your CSS and duplicates tons of images/fonts into the build directory.

This plugin solves that pain point. You keep your CSS compilation native to your IDE or external watchers (maintaining pristine relative paths for fonts/images), and let this plugin handle production-ready hashing, post-processing, and backend manifest orchestration.

Features

• 0% asset mutations: Does not touch your relative font or image paths inside CSS.
• Automated Post-processing: Runs your CSS through autoprefixer and cssnano out of the box during production build.
• Secure Backend Hashing: Computes content-based MD5 hashes (8 characters) and writes custom metadata (_css name suffix) to prevent backend naming collisions.
• Smart Cleanup: Automatically purges only outdated hashed files by strict regex mask before writing new ones (100% safe for foreign CSS files).

Installation

npm install --save-dev rolldown-css-manifest-injector

Usage

Add the plugin to your vite.config.js:

import {defineConfig} from 'vite';
import {cssManifestInjector} from 'rolldown-css-manifest-injector';

export default defineConfig({
	plugins: [
		cssManifestInjector({
			srcDir: './www/assets/css',               // Where your IDE saves compiled CSS
			destDir: './www/assets/build/css'         // Where hashed files should be placed
		})
	],
	build: {
		outDir: './www/assets/build',
		emptyOutDir: true,
		manifest: 'manifest.json'
	}
});

Result in manifest.json

{
  "resources/my-template/css/style.css": {
    "file": "css/style.c3762211.css",
    "name": "style_css",
    "src": "resources/my-template/css/style.css",
    "isEntry": true
  }
}

Naming behavior

The plugin generates stable, collision‑free names for backend usage based on the original source path, not the hashed output:

• The source path is used to derive the logical name.
• The hash lives only in the built filename (file), not in name.
• The first path segment may be kept or trimmed depending on your project layout.
• Adds a suffix. By default, it is _css

This keeps names short, predictable, and perfectly suited for backend template engines.

Example Table

| Source file | Built file (in outDir) | Manifest file | Manifest name | |------------------------------|----------------------------------|---------------------------|------------------| | SRC_DIR/css/style.HASH.css | OUT_DIR/css/style.css | css/style.css | css/style_css | | SRC_DIR/style.css | OUT_DIR/style.HASH.css | style.HASH.css | style_css | | SRC_DIR/css/admin.css | OUT_DIR/css/admin.HASH.css | css/admin.HASH.css | css/admin_css | | SRC_DIR/theme.css | OUT_DIR/theme.HASH.css | theme.HASH.css | theme_css |

Backend Integration Example (Twig / PHP)

Since the plugin registers files with a secure _css suffix, you can easily parse it in your template engine without naming collisions with same-named JS files:

{# Beautifully isolated asset injection #}
{# Simple flat CSS #}
<link rel="stylesheet" href="{{ vite_asset('style_css') }}">

{# Namespaced CSS from subfolder #}
<link rel="stylesheet" href="{{ vite_asset('css/style_css') }}">

License

MIT