vite-plugin-raw-asset-uprooter

A lightweight, zero-dependency Vite & Rolldown plugin to bypass strict package encapsulation (exports field validation) for raw non-ESM/monolithic scripts and seamlessly adapt the build manifest for backend frameworks (such as Twig, Blade, PHP).

Why?

Modern bundlers like Vite 6+ (powered by Rolldown) enforce strict package encapsulation. If a package (e.g., @tko/build.knockout) restricts access via the exports field in its package.json, Vite will crash with a [rolldown:vite-resolve] error when you try to import a monolithic browser script directly using the ?url suffix.

Furthermore, when working with backend template engines (like Twig or Blade), the engine expects a clean path as a key in manifest.json (e.g., "node_modules/package/dist/file.js"). Vite natively pollutes the manifest with virtual keys for non-imported raw assets.

This plugin fixes both issues by completely hiding the original package from Vite's resolution graph during compilation, while post-processing manifest.json to generate flawless keys for your backend templates.

Installation

npm install vite-plugin-raw-asset-uprooter --save-dev

Usage

1. Configure the Plugin

Add the plugin to your vite.config.js and specify a virtual import name mapped to the actual physical path of the asset inside node_modules:

import { defineConfig } from 'vite';
import { viteRawAssetUprooter } from 'vite-plugin-raw-asset-uprooter';

export default defineConfig({
  plugins: [
    viteRawAssetUprooter({
      // 'virtual-import-name': 'path/to/the/raw/asset/from/project/root'
      'virtual:tko-core': 'node_modules/@tko/build.knockout/dist/browser.min.js'
    })
  ]
});

2. Import in your JavaScript

Use the registered virtual name instead of the raw package path. The plugin will automatically return the correct hashed asset URL:

import tkoUrl from 'virtual:tko-core';

console.log(tkoUrl); // Output: /assets/build/js/browser.min.DKXLBUw1.js

3. Result in manifest.json

The plugin rewrites the final manifest so your backend template engine can easily find the asset path without any regex workarounds:

{
  "node_modules/@tko/build.knockout/dist/browser.min.js": {
    "file": "js/browser.min.DKXLBUw1.js",
    "src": "node_modules/@tko/build.knockout/dist/browser.min.js",
    "type": "asset"
  }
}

License

MIT

Advanced: Shared Utilities

This package also exports the internal helper function replaceAllAliases, which allows you to manually resolve and expand Vite path aliases (like @, @public, etc.) inside any arbitrary path string.

It is highly useful for writing custom build scripts or hooks where you need to parse configured outDirs or target paths manually.

Usage of replaceAllAliases

import { replaceAllAliases } from 'vite-plugin-raw-asset-uprooter';

export default {
  plugins: [
    {
      name: 'my-custom-script',
      configResolved(resolvedConfig) {
        const rawPath = resolvedConfig.build.outDir; // e.g. "./@public/assets/build"
        
        // This will expand the aliases safely based on length sorting
        const absolutePath = replaceAllAliases(rawPath, resolvedConfig);
        
        console.log(absolutePath); // Output: /Users/.../project/www/assets/build
      }
    }
  ]
}

License

MIT