unloader

0.9.0 verified Mon Apr 27 auth: no javascript

A Node.js custom loader framework with a Rollup-like plugin interface (v0.9.0). Requires Node.js >=22.18.0. Provides synchronous hooks (options, resolveId, load, transform) for developing loaders such as TypeScript or Oxc loaders. Supports ESM and CJS, virtual modules, and source maps. Breaking changes in v0.9.0 removed module.register and async/worker support. Integrates with unplugin. Less feature-rich than tsx but offers a familiar plugin system for Rollup developers.

Common errors

error TypeError: (intermediate value).resolve is not a function ↓

cause Custom resolver callback not bound to plugin context; using arrow function with 'this.resolve' incorrectly

fix

Use function() { ... } instead of arrow functions for hooks, or capture context via second argument (resolveId receives context as third argument before v0.7? Actually resolveId uses 'this' as context; ensure you are using normal function, not arrow, to have correct 'this'.

error Error: Plugin hook returned a Promise. Synchronous hooks only. ↓

cause Plugin hook (e.g., load, transform) returned a Promise or async function, which is not supported since v0.9.0

fix

Make the hook synchronous; use readFileSync, not readFile.

error Error: The module '.package.json' was resolved to a non-existent file ↓

cause resolveId hook returned an invalid file path or failed to resolve correctly

fix

Check that resolveId returns a valid absolute path or an object with id, or returns undefined to let default resolver handle.

Warnings

breaking v0.9.0 removed module.register, dropped async/worker/quansync support; plugin hooks throwing Promises now throws ↓

fix Rewrite any async or promise-based plugin hooks to be synchronous. Use sync versions of file I/O, etc.

breaking v0.8.0 dropped Node <22.18 support ↓

fix Upgrade Node.js to v22.18.0 or above.

breaking v0.7.0 moved PluginContext to this: use this.meta, this.error instead of context.meta, context.error ↓

fix In buildStart and other hooks, access meta via 'this.meta', error via 'this.error', etc.

breaking v0.6.0 dropped Node 18 support, requires Node 20.19+ ↓

fix Upgrade to Node.js >=20.19 or use an older version of unloader.

Install

npm install unloader

yarn add unloader

pnpm add unloader

Imports

Plugin
```
import type { Plugin } from 'unloader'
```
Type import only; Plugin is a TypeScript interface.

PluginContext

wrong

const { PluginContext } = require('unloader')

correct

import type { PluginContext } from 'unloader'

PluginContext is a TypeScript type, cannot be required.

unloader
wrong
```
const unloader = require('unloader')
```
correct
```
import * as unloader from 'unloader'
```
Package is ESM-only; named exports require import * or import {}.

Quickstart

Creates a minimal unloader plugin with resolveId and load hooks for a virtual module.

import { readFileSync } from 'node:fs'
import type { Plugin } from 'unloader'

const myPlugin: Plugin = {
  name: 'example',
  resolveId(source, importer, options) {
    if (source === 'virtual') return '/virtual.js'
    return this.resolve(`${source}.js`, importer, options)
  },
  load(id) {
    if (id === '/virtual.js') return { code: 'export const foo = 1' }
    return readFileSync(id, 'utf8')
  },
}

export default { plugins: [myPlugin] }