Node.js "--loader is deprecated" - Migrate to --import + register()

Newer Node deprecated the --loader/--experimental-loader flag in favor of registering loader hooks via module.register() and the --import flag. The old form still works for now but emits a deprecation warning that, under --throw-deprecation, becomes a failure.

What this error means

CI logs show ExperimentalWarning: --loader is deprecated, use --import instead, often from a TypeScript/ESM loader invocation. With strict deprecation flags it can fail the step; otherwise it is noise that signals the loader setup needs migrating.

Node output

(node:12345) ExperimentalWarning: `--loader` is deprecated,
use `register()` and `--import` instead.
(Use `node --trace-warnings ...` to show where the warning was created)

Common causes

A custom ESM loader invoked with --loader

Setups passing --loader ./my-loader.mjs (or --experimental-loader) use the deprecated entry point. Node now prefers loaders registered through module.register() and --import.

A tool wrapper still using the old flag

A test/build wrapper or a NODE_OPTIONS=--loader=... line carries the deprecated flag, so every run warns.

How to fix it

Register the loader via --import

Move the hook registration into a small ESM entry that calls module.register(), then pass it with --import.

JavaScript / Terminal

// register-loader.mjs
import { register } from 'node:module'
register('./my-loader.mjs', import.meta.url)

# run with --import instead of --loader
node --import ./register-loader.mjs app.mjs

Update wrappers and env vars

Replace --loader/--experimental-loader in scripts and NODE_OPTIONS with the --import form.
Confirm the loader package supports module.register() on your Node version.
Do not run with --throw-deprecation until the migration is complete.

How to prevent it

Use --import + module.register() for ESM loaders.
Prefer a package’s documented register entry over raw --loader.
Avoid --throw-deprecation while old loader flags remain.