esbuild-plugin-virtual

0.1.0 verified Fri May 01 auth: no javascript

An esbuild plugin for loading virtual modules from memory, inspired by @rollup/plugin-virtual. Version 0.1.0 is designed for esbuild's plugin system, enabling in-memory module resolution during bundling. Releases are stable but infrequent. Key differentiators: simple API (object map of module names to content), works with both Node and Deno, virtual modules are resolved with a 'virtual:' prefix internally. Compared to file-based alternatives, it eliminates filesystem I/O for tests or dynamic content. Currently ships TypeScript definitions, but lacks advanced features like virtual directories or lazy loading.

Common errors

error Error: Cannot find module 'esbuild-plugin-virtual' ↓

cause Missing install or wrong import syntax (e.g., using require in ESM-only package).

fix

Ensure package is installed: npm install --save-dev esbuild-plugin-virtual. Use import, not require.

error TypeError: virtual is not a function ↓

cause Importing the default export incorrectly, or using an older Node version without ESM support.

fix

Use 'import virtual from "esbuild-plugin-virtual"' and ensure Node >= 12.20 for ESM.

error The plugin "virtual" must be an object with a "name" property ↓

cause Passing an object directly as a plugin instead of calling the virtual() factory function.

fix

Correct: plugins: [virtual({...})]. Incorrect: plugins: [{...}].

Warnings

gotcha Virtual module names must not contain the 'virtual:' prefix in the plugin object keys; internal resolution adds it automatically. ↓

fix Use bare module names (e.g., 'my-module') without 'virtual:' prefix.

gotcha Virtual modules are resolved only for the entry points and files in the build graph; they cannot be used as plugins or loaders for other resources. ↓

fix Use virtual modules for JavaScript/TypeScript content only; for other file types, use different plugins.

breaking No known breaking changes in current version; package is simple and stable. ↓

fix N/A

Install

npm install esbuild-plugin-virtual

yarn add esbuild-plugin-virtual

pnpm add esbuild-plugin-virtual

Imports

default
wrong
```
const virtual = require('esbuild-plugin-virtual')
```
correct
```
import virtual from 'esbuild-plugin-virtual'
```
Package is ESM-only; default export is the plugin factory function. For CommonJS, use dynamic import or a bundler.
virtual type
```
import type { VirtualPlugin } from 'esbuild-plugin-virtual'
```
TypeScript types are included; the default export is a function returning an esbuild Plugin. You can also import the type for parameter definitions.
Plugin as named
wrong
```
import { default as virtual } from 'esbuild-plugin-virtual'
```
correct
```
import { virtual } from 'esbuild-plugin-virtual'
```
The package also exports a named export 'virtual' identical to default. Avoid mixing default and named in same line.

Quickstart

Shows basic usage: creating virtual modules and bundling an entry point that imports them.

import * as esbuild from 'esbuild';
import virtual from 'esbuild-plugin-virtual';

await esbuild.build({
  entryPoints: ['src/entry.ts'],
  bundle: true,
  outfile: 'out.js',
  plugins: [
    virtual({
      'my-module': `export const msg = 'Hello from virtual!';`,
      'another-module': `export default 42;`,
    }),
  ],
}).then(() => console.log('Built successfully'));