From 650d0724b028b3d35b925bb00f1b1804901aede2 Mon Sep 17 00:00:00 2001 From: Edoardo Luppi Date: Wed, 5 Nov 2025 10:33:13 +0100 Subject: [PATCH] docs: refine the readme and v4 migration content --- README.md | 113 ++++++++++++++++++++++------------------ docs/migrating-to-v4.md | 47 +++++++---------- 2 files changed, 82 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index b489c26..7deb8c6 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,20 @@ -> [!IMPORTANT] -> [Looking for maintainers](https://github.com/LeDDGroup/typescript-transform-paths/issues/439) -> -> [Alternatives](https://github.com/LeDDGroup/typescript-transform-paths/issues/438) - ---- - -# typescript-transform-paths +

typescript-transform-paths

+

Transform compiled source module resolution paths using TypeScript's paths config, and/or custom resolution paths

+
[![npm version](https://img.shields.io/npm/v/typescript-transform-paths.svg)](https://www.npmjs.com/package/typescript-transform-paths) [![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2FLeDDGroup%2Ftypescript-transform-paths%2Fbadge%3Fref%3Dmaster&style=flat)](https://actions-badge.atrox.dev/LeDDGroup/typescript-transform-paths/goto?ref=master) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) -[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier) +[![Code Style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier) -Transform compiled source module resolution paths using TypeScript's `paths` config, and/or custom resolution paths. +
-> [!NOTE] -> Upgrading from v3 to v4?, see [migration](./docs/migrating-to-v4.md) +> [!TIP] +> Upgrading from v3 to v4? See the [migration](./docs/migrating-to-v4.md) documentation. + +> [!IMPORTANT] +> We are [looking for maintainers][issue-439]. +> Explore [alternatives][issue-438]. ## Setup Steps @@ -27,9 +26,9 @@ Transform compiled source module resolution paths using TypeScript's `paths` con ### 2. Configure -Add it to _plugins_ in your _tsconfig.json_ +Add it to `plugins` in your `tsconfig.json` file. -#### Example Config +#### Example Configuration ```jsonc { @@ -39,32 +38,33 @@ Add it to _plugins_ in your _tsconfig.json_ "paths": { "@utils/*": ["utils/*"], }, - // Note: To transform paths for both the output .js and .d.ts files, you need both of the below entries + // Note: to transform paths for both the output .js and .d.ts files, + // you need both of the below entries "plugins": [ // Transform paths in output .js files { "transform": "typescript-transform-paths" }, - // Transform paths in output .d.ts files (Include this line if you output declarations files) + // Transform paths in output .d.ts files (include this line if you output declarations files) { "transform": "typescript-transform-paths", "afterDeclarations": true }, ], }, } ``` -#### Example result +#### Example Result `core/index.ts` -```tsx -// The following transforms path to '../utils/sum' +```ts +// The following import path is transformed to '../utils/sum' import { sum } from "@utils/sum"; ``` -### 3. Usage +### 3. Use -- **Compile with `tsc`** — Use [ts-patch](https://github.com/nonara/ts-patch) -- **ts-node** — See [wiki](https://github.com/LeDDGroup/typescript-transform-paths/wiki/Integration-with-ts%E2%80%90node) -- **Use with NX** — Add the `typescript-transform-paths/nx-transformer` to project config +- Compile with **`tsc`** — Use [ts-patch][ts-patch]. +- Run with **`ts-node`** — See the [Wiki][ts-node-wiki]. +- Integrate with **Nx** — Add the `typescript-transform-paths/plugins/nx` transformer to the project configuration. `project.json` @@ -90,10 +90,10 @@ import { sum } from "@utils/sum"; ## Virtual Directories -TS allows defining -[virtual directories](https://www.typescriptlang.org/docs/handbook/module-resolution.html#virtual-directories-with-rootdirs) -via the `rootDirs` compiler option. -To enable virtual directory mapping, use the `useRootDirs` plugin option. +TypeScript allows defining [Virtual Directories][virtual-directories] via the `rootDirs` compiler option. +To enable Virtual Directory mapping, use the `useRootDirs` plugin option. + +`tsconfig.json` ```jsonc { @@ -113,38 +113,38 @@ To enable virtual directory mapping, use the `useRootDirs` plugin option. #### Example -``` -- src/ - - subdir/ - - sub-file.ts - - file1.ts -- generated/ - - file2.ts +```text +├src/ +├─ subdir/ +│ └─ sub-file.ts +├─ file1.ts +├generated/ +├─ file2.ts ``` `src/file1.ts` ```ts -import "#root/file2.ts"; // resolves to './file2' +import "#root/file2.ts"; // Resolves to './file2' ``` `src/subdir/sub-file.ts` ```ts -import "#root/file2.ts"; // resolves to '../file2' -import "#root/file1.ts"; // resolves to '../file1' +import "#root/file2.ts"; // Resolves to '../file2' +import "#root/file1.ts"; // Resolves to '../file1' ``` ## Custom Control -### Exclusion patterns +### Exclusion Patterns -You can disable transformation for paths based on the resolved file path. The `exclude` option allows specifying glob -patterns to match against resolved file path. +You can disable transformation for paths based on the resolved file path. +The `exclude` option allows specifying Glob patterns to match against those resolved file paths. -For an example context in which this would be useful, see [Issue #83](https://github.com/LeDDGroup/typescript-transform-paths/issues/83) +For an example context in which this would be useful, see [issue #83][issue-83]. -Example: +`tsconfig.json` ```jsonc { @@ -164,17 +164,17 @@ Example: ``` ```ts -// This path will not be transformed +// This path will NOT be transformed import * as sm1 from "sub-module1/index"; ``` -### @transform-path tag +### @transform-path Use the `@transform-path` tag to explicitly specify the output path for a single statement. ```ts // @transform-path https://cdnjs.cloudflare.com/ajax/libs/react/17.0.1/umd/react.production.min.js -import react from "react"; // Output path will be the url above +import react from "react"; // Output path will be the URL defined above ``` ### @no-transform-path @@ -183,14 +183,16 @@ Use the `@no-transform-path` tag to explicitly disable transformation for a sing ```ts // @no-transform-path -import "normally-transformed"; // This will remain 'normally-transformed', even though it has a different value in paths config +import "normally-transformed"; // This will remain 'normally-transformed' even though + // it has a different value in paths config ``` ## Version Compatibility -| `typescript-transform-paths` | TypeScript | NodeJS | -| ---------------------------- | --------------------- | ------ | -| ^3.5.2 | >=3.6.5, >=4.x, >=5.x | >=18 | +| typescript-transform-paths | TypeScript | Node.js | +|------------------------------|-----------------------|---------| +| ^4.0.0 | >=5.x | >=22 | +| ^3.5.2 | >=3.6.5, >=4.x, >=5.x | >=18 | ## Project Guidelines for Contributors @@ -205,8 +207,8 @@ GH_TOKEN=$(gh auth token) yarn release ## Alternatives -- [NodeJS subpath imports](https://nodejs.org/api/packages.html#subpath-imports) -- [Yarn link: protocol](https://yarnpkg.com/protocol/link) +- [Node.js Subpath imports][subpath-imports] +- [Yarn Link Protocol][yarn-link-protocol] ## Maintainers @@ -218,3 +220,12 @@ GH_TOKEN=$(gh auth token) yarn release
Daniel Perez + +[ts-patch]: https://github.com/nonara/ts-patch +[ts-node-wiki]: https://github.com/LeDDGroup/typescript-transform-paths/wiki/Integration-with-ts%E2%80%90node +[virtual-directories]: https://www.typescriptlang.org/docs/handbook/module-resolution.html#virtual-directories-with-rootdirs +[issue-83]: https://github.com/LeDDGroup/typescript-transform-paths/issues/83 +[issue-438]: https://github.com/LeDDGroup/typescript-transform-paths/issues/438 +[issue-439]: https://github.com/LeDDGroup/typescript-transform-paths/issues/439 +[subpath-imports]: https://nodejs.org/api/packages.html#subpath-imports +[yarn-link-protocol]: https://yarnpkg.com/protocol/link diff --git a/docs/migrating-to-v4.md b/docs/migrating-to-v4.md index b82a600..d5e8c57 100644 --- a/docs/migrating-to-v4.md +++ b/docs/migrating-to-v4.md @@ -1,27 +1,20 @@ -# Migrating from v3 to v4 - -## Breaking Changes - -### Package is now ESM only - -### Dropped support for older Node.js versions. Requires Node.js >22 - -### Dropped support for older typescript versions. Requires typescript >5.8.x - -### Removed `typescript-transform-paths/register` ts-node entrypoint - -See https://typestrong.org/ts-node/docs/compilers/ for how to configure ts-node to use custom transformers. - -### Renamed `nx` transformer entrypoint - -The nx plugin entrypoint was renamed from `typescript-transform-paths/nx-transformer` to `typescript-transform-paths/plugins/nx`: - -```diff - "transformers": [ - { -- "name": "typescript-transform-paths/nx-transformer", -+ "name": "typescript-transform-paths/plugins/nx", - "options": { "afterDeclarations": true }, - }, - ], -``` +

Migrating from v3 to v4

+ +### Breaking Changes + +- Package is now **ESM** only. +- Dropped support for old Node.js versions. It now **requires** Node.js `>=22`. +- Dropped support for old TypeScript versions. It now **requires** TypeScript `>=5.x`. +- Removed the `typescript-transform-paths/register` **ts-node** entrypoint. + See https://typestrong.org/ts-node/docs/compilers to understand how to configure **ts-node** to use custom transformers. +- Renamed the **Nx** transformer entrypoint from `typescript-transform-paths/nx-transformer` to `typescript-transform-paths/plugins/nx`. + + ```diff + "transformers": [ + { + - "name": "typescript-transform-paths/nx-transformer", + + "name": "typescript-transform-paths/plugins/nx", + "options": { "afterDeclarations": true }, + }, + ], + ```