unloader

library0.9.0jsnpmunverified

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.

devops

npm install unloader

github ↗package ↗

INSTALL

IMPORT

SIG · UNLOADER

unloader

devopsjavascriptv0.9.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Plugin

✓ import type { Plugin } from 'unloader'

Type import only; Plugin is a TypeScript interface.

PluginContext

✓ import type { PluginContext } from 'unloader'

✗ const { PluginContext } = require('unloader')

PluginContext is a TypeScript type, cannot be required.

unloader

✓ import * as unloader from 'unloader'

✗ const unloader = require('unloader')

Package is ESM-only; named exports require import * or import {}.

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] }

Debug

Known issues

breakingv0.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.

affects: >=0.9.0

breakingv0.8.0 dropped Node <22.18 support

fix

Upgrade Node.js to v22.18.0 or above.

affects: >=0.8.0

breakingv0.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.

affects: >=0.7.0

breakingv0.6.0 dropped Node 18 support, requires Node 20.19+

fix

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

affects: 0.6.0 - 0.7.x

Errors

Common errors & fixes

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

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: Plugin hook returned a Promise. Synchronous hooks only.

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: The module '.package.json' was resolved to a non-existent file

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.

Upgrade

Version history

0.9.0latest on npm

Audit

Dependencies

noderequiredRequires Node.js >=22.18.0 (v0.8.0+)

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/sxzz/unloader ↗

packagehttps://www.npmjs.com/package/unloader ↗