docs: add v4 migration draft

Author: danielpza

README.md

@@ -14,6 +14,9 @@
 
 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)
+
 ## Setup Steps
 
 ### 1. Install

docs/migrating-to-v4.md

@@ -0,0 +1,27 @@
+# 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 },
+            },
+          ],
+```