Introduction

A lightweight CommonJS runtime alias resolver for Node.js that enables @alias/* imports using jsconfig.json, without requiring a bundler or ESM.

This package reads path mappings from jsconfig.json and patches Node’s native module resolution system so aliases work at runtime with require().

Why This Package Exists

Node.js does not natively support path aliases in CommonJS.

While editors understand jsconfig.json, Node ignores it at runtime. This package bridges that gap by resolving aliases dynamically using Node’s internal resolver.

Features

• Supports @alias/* imports in CommonJS
• Reads compilerOptions.baseUrl and paths from jsconfig.json
• No bundler, transpiler, or ESM required
• Zero external dependencies
• Works with Node.js services, CLIs, and scripts

Installation

npm install aliases-require

Configuration

Create a jsconfig.json in your project root:

{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "@src/*": ["src/*"]
        }
    }
}

Usage

• Register the Alias Resolver (Must Be First)

require('aliases-require');

• Import Using Aliases

const { isFunction } = require('@src/helpers/types');

isFunction(function x() {});

Important Notes

• This package patches Node’s internal module resolver
• Registration must occur before any aliased imports
• Intended for applications, not shared libraries
• Compatible with CommonJS only

Node.js Compatibility

• Node.js ≥ 14
• CommonJS — require
• Not intended for ESM projects