• Stars
    star
    1,802
  • Rank 25,778 (Top 0.6 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created almost 8 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Load node modules according to tsconfig paths, in run-time or via API.

tsconfig-paths

npm version build Coverage Status MIT license code style: prettier

Use this to load modules whose location is specified in the paths section of tsconfig.json or jsconfig.json. Both loading at run-time and via API are supported.

Typescript by default mimics the Node.js runtime resolution strategy of modules. But it also allows the use of path mapping which allows arbitrary module paths (that doesn't start with "/" or ".") to be specified and mapped to physical paths in the filesystem. The typescript compiler can resolve these paths from tsconfig so it will compile OK. But if you then try to execute the compiled files with node (or ts-node), it will only look in the node_modules folders all the way up to the root of the filesystem and thus will not find the modules specified by paths in tsconfig.

If you require this package's tsconfig-paths/register module it will read the paths from tsconfig.json or jsconfig.json and convert node's module loading calls into to physical file paths that node can load.

How to install

yarn add --dev tsconfig-paths

or

npm install --save-dev tsconfig-paths

How to use

With node

node -r tsconfig-paths/register main.js

If process.env.TS_NODE_BASEURL is set it will override the value of baseUrl in tsconfig.json:

TS_NODE_BASEURL=./dist node -r tsconfig-paths/register main.js

With ts-node

ts-node -r tsconfig-paths/register main.ts

If process.env.TS_NODE_PROJECT is set it will be used to resolved tsconfig.json

With webpack

For webpack please use the tsconfig-paths-webpack-plugin.

With mocha and ts-node

As of Mocha >= 4.0.0 the --compiler was deprecated. Instead --require should be used. You also have to specify a glob that includes .ts files because mocha looks after files with .js extension by default.

mocha -r ts-node/register -r tsconfig-paths/register "test/**/*.ts"

With other commands

As long as the command has something similar to a --require option that can load a module before it starts, tsconfig-paths should be able to work with it.

With ts-node and VSCode

The following is an example configuration for the .vscode/launch.json.

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Functions",
      "request": "launch",
      "type": "node",
      "runtimeArgs": [
        "-r",
        "${workspaceFolder}/functions/node_modules/ts-node/register",
        "-r",
        "${workspaceFolder}/functions/node_modules/tsconfig-paths/register"
      ],
      "args": ["${workspaceFolder}/functions/src/index.ts"],
      "cwd": "${workspaceFolder}",
      "protocol": "inspector",
      "env": {
        "NODE_ENV": "development",
        "TS_NODE_PROJECT": "${workspaceFolder}/functions/tsconfig.json"
      },
      "outFiles": ["${workspaceFolder}/functions/lib/**/*.js"]
    }
  ]
}

Bootstrapping with explicit params

If you want more granular control over tsconfig-paths you can bootstrap it. This can be useful if you for instance have compiled with tsc to another directory where tsconfig.json doesn't exists.

For example, create a wrapper script called tsconfig-paths-bootstrap.js with the contents below:

const tsConfig = require("./tsconfig.json");
const tsConfigPaths = require("tsconfig-paths");

const baseUrl = "./"; // Either absolute or relative path. If relative it's resolved to current working directory.
const cleanup = tsConfigPaths.register({
  baseUrl,
  paths: tsConfig.compilerOptions.paths,
});

// When path registration is no longer needed
cleanup();

Then run with:

node -r ./tsconfig-paths-bootstrap.js main.js

Configuration Options

You can set options by passing them before the script path, via programmatic usage or via environment variables.

ts-node --project customLocation/tsconfig.json -r tsconfig-paths/register "test/**/*.ts"

CLI and Programmatic Options

Environment variable denoted in parentheses.

  • -P, --project [path] Path to TypeScript JSON project file (TS_NODE_PROJECT)

Config loading process

  1. Use explicit params passed to register
  2. Use process.env.TS_NODE_PROJECT to resolve tsConfig.json and the specified baseUrl and paths.
  3. Resolves tsconfig.json from current working directory and the specified baseUrl and paths.

Programmatic use

The public API consists of these functions:

register

export interface ExplicitParams {
  baseUrl: string;
  paths: { [key: string]: Array<string> };
  mainFields?: (string | string[])[];
  addMatchAll?: boolean;
  cwd?: string;
}

/**
 * Installs a custom module load function that can adhere to paths in tsconfig.
 */
export function register(explicitParams: ExplicitParams): () => void;

This function will patch the node's module loading so it will look for modules in paths specified by tsconfig.json or jsconfig.json. A function is returned for you to reinstate Node's original module loading.

loadConfig

export function loadConfig(cwd: string = process.cwd()): ConfigLoaderResult;

export type ConfigLoaderResult =
  | ConfigLoaderSuccessResult
  | ConfigLoaderFailResult;

export interface ConfigLoaderSuccessResult {
  resultType: "success";
  absoluteBaseUrl: string;
  paths: { [key: string]: Array<string> };
}

export interface ConfigLoaderFailResult {
  resultType: "failed";
  message: string;
}

This function loads the tsconfig.json or jsconfig.json. It will start searching from the specified cwd directory. Passing the tsconfig.json or jsconfig.json file directly instead of a directory also works.

createMatchPath

/**
 * Function that can match a path
 */
export interface MatchPath {
  (
    requestedModule: string,
    readJson?: Filesystem.ReadJsonSync,
    fileExists?: (name: string) => boolean,
    extensions?: ReadonlyArray<string>
  ): string | undefined;
}

/**
 * Creates a function that can resolve paths according to tsconfig paths property.
 * @param absoluteBaseUrl Absolute version of baseUrl as specified in tsconfig.
 * @param paths The paths as specified in tsconfig.
 * @param mainFields A list of package.json field names to try when resolving module files. Select a nested field using an array of field names.
 * @param addMatchAll Add a match-all "*" rule if none is present
 * @returns a function that can resolve paths.
 */
export function createMatchPath(
  absoluteBaseUrl: string,
  paths: { [key: string]: Array<string> },
  mainFields: (string | string[])[] = ["main"],
  addMatchAll: boolean = true
): MatchPath {

The createMatchPath function will create a function that can match paths. It accepts baseUrl and paths directly as they are specified in tsconfig and will handle resolving paths to absolute form. The created function has the signature specified by the type MatchPath above.

matchFromAbsolutePaths

/**
 * Finds a path from tsconfig that matches a module load request.
 * @param absolutePathMappings The paths to try as specified in tsconfig but resolved to absolute form.
 * @param requestedModule The required module name.
 * @param readJson Function that can read json from a path (useful for testing).
 * @param fileExists Function that checks for existence of a file at a path (useful for testing).
 * @param extensions File extensions to probe for (useful for testing).
 * @param mainFields A list of package.json field names to try when resolving module files. Select a nested field using an array of field names.
 * @returns the found path, or undefined if no path was found.
 */
export function matchFromAbsolutePaths(
  absolutePathMappings: ReadonlyArray<MappingEntry.MappingEntry>,
  requestedModule: string,
  readJson: Filesystem.ReadJsonSync = Filesystem.readJsonFromDiskSync,
  fileExists: Filesystem.FileExistsSync = Filesystem.fileExistsSync,
  extensions: Array<string> = Object.keys(require.extensions),
  mainFields: (string | string[])[] = ["main"]
): string | undefined {

This function is lower level and requires that the paths as already been resolved to absolute form and sorted in correct order into an array.

createMatchPathAsync

This is the async version of createMatchPath. It has the same signature but with a callback parameter for the result.

matchFromAbsolutePathsAsync

This is the async version of matchFromAbsolutePaths. It has the same signature but with a callback parameter for the result.

How to publish

yarn version --patch
yarn version --minor
yarn version --major

More Repositories

1

tsconfig-paths-webpack-plugin

Load modules according to tsconfig paths in webpack.
TypeScript
596
star
2

graphql-norm

Normalization and denormalization of GraphQL responses
TypeScript
31
star
3

uom

Extensible unit of measure conversion with type safety for typescript
TypeScript
18
star
4

three-x3d-loader

Three.js Loader for the X3D format.
JavaScript
15
star
5

graphql-add-remove-fields

Add or remove fields in graphql queries
TypeScript
9
star
6

tslint-divid

TSLint rules used in some projects at Divid.
TypeScript
9
star
7

ts-exhaustive-check

Exhaustive check for typescript type never
TypeScript
8
star
8

abstract-visuals

Abstract Visuals
JavaScript
6
star
9

graphql-norm-patch

Declarative patching of normalized GraphQL responses
TypeScript
6
star
10

uom-units

Predefined units for use with the uom package
TypeScript
3
star
11

advent-of-code-2017

Advent of code 2017
3
star
12

double-n

IEEE 754 double-precision binary floating-point with N number of significant precision bits
TypeScript
3
star
13

cron-backup-base

Dumping a backup file and transfer it via FTP or NFS (supports periodic backups and health checking)
Shell
3
star
14

eslint-config-divid

ESLint Sharable Config using typescript and prettier with functional programming style
JavaScript
2
star
15

graphql-norm-stale

Staleness tracking for normalized GraphQL responses
TypeScript
1
star
16

ctors-union

Define unions types via constructor functions
TypeScript
1
star
17

oas-to-ts

Convert an OpenAPI specifcation document to typescript types
TypeScript
1
star
18

cron-backup-postgres

Backup PostgresSQL to FTP or NFS (supports periodic backups)
Shell
1
star
19

scheduled-docker-system-prune

Runs docker system prune on a schedule
Shell
1
star