tsed-migration

# Migrate to Ts.ED v8 Migrate in small, verifiable steps. v7 already supports ESM, `useDefineForClassFields: false` and `settings.get()`, so do all preparation on v7, verify, and only then bump to v8. References, loaded on demand: - [`@tsed/common` symbol → owning package](references/common-symbols.md) - [Deprecated and removed APIs with replacements](references/deprecated-apis.md) Live guide: `https://tsed.dev/introduction/migrate-from-v7.md` and `https://tsed.dev/introduction/what-is-news-v8.md`. ## 1. Assess 1. Read `package.json`: the `@tsed/*` major, the `type` field, the test runner, the dev runner (`ts-node`, `ts-node-dev`, `tsx`, SWC), `barrelsby`. 2. Read `tsconfig.json`, `.swcrc`, `vite.config.ts` / `vitest.config.ts`, `jest.config.*`. 3. Pick the path: | Starting point | Path | | ----------------- | --------------------------------------------------------------------------------------------------------------- | | v7 | Sections 2 to 7 | | v6 | First reach the latest v7 with `https://tsed.dev/introduction/migrate-from-v6.md`, verify, then sections 2 to 7 | | v5 or older | Do not upgrade in place. Scaffold a v8 project with the `tsed-cli` skill and port code feature by feature | | Plain Express app | Section 8 | 4. Confirm Node.js >= 20.11.0 (>= 22 when the Ts.ED CLI v7 is used). 5. Require a clean git tree and a passing test suite before starting. Commit after each section. Do not bump `@tsed/*` to 8.x before sections 2 to 4 pass on v7. ## 2. Prepare on v7: compiler and configuration access 1. Update every `@tsed/*` package to the latest 7.x. 2. Set `useDefineForClassFields: false` in every transpiler configuration that exists: - `tsconfig.json` → `compilerOptions.useDefineForClassFields` - `.swcrc` and SWC options in `vite.config.ts` / `vitest.config.ts` → `jsc.transform.useDefineForClassFields` - Keep `legacyDecorator: true` and `decoratorMetadata: true` (SWC), `experimentalDecorators` and `emitDecoratorMetadata` (tsc). 3. Replace proxy access on the configuration object. v8 removes it: ```ts import {Configuration, Injectable} from "@tsed/di"; @Injectable() export class MyService { constructor(@Configuration() private settings: Configuration) { settings.get<string>("myOption"); // v7 and v8 // settings.myOption // v7 only, undefined in v8 } } ``` 4. Find candidates: search for `settings.`, `configuration.` and `this.settings.` followed by a custom key. Built-in accessors (`rootDir`, `env`, `imports`, `routes`, `mount`, `logger`, `debug`, `version`) keep working; anything else must use `.get("key")`, `constant("key")` or `@Constant("key")`. ## 3. Prepare on v7: switch to ESM 1. `package.json`: set `"type": "module"`. 2. `tsconfig.json`: `"module": "NodeNext"`, `"moduleResolution": "NodeNext"`, `"target": "esnext"`. 3. Add `.js` to every relative import and export, and `/index.js` to directory imports: ```ts import {ProductsService} from "./services/ProductsService.js"; import * as rest from "./controllers/rest/index.js"; ``` 4. Fix deep CommonJS imports (`lodash/get` → `lodash/get.js`) and named imports from CommonJS-only packages (`import fs from "fs-extra"`). 5. Replace `__dirname` / `__filename` with `import.meta.dirname` / `import.meta.filename`, and `require()` with `import`. 6. JSON: `import config from "./config.json" with {type: "json"}`, or read the file with `node:fs`. 7. Replace `barrelsby` with `@tsed/barrels` (binary `barrels`, configuration `.barrels.json`); the barrelsby configuration format is accepted. 8. Replace `ts-node` / `ts-node-dev` with SWC: install `@swc-node/register @swc/core @swc/helpers`, run with `node --import @swc-node/register/esm-register src/index.ts`, and add `nodemon` for watch mode. Details: `https://tsed.dev/introduction/migrate-from-v7.md`. Do not mix `require` and `import` to work around a failing import; fix the import form. ## 4. Verify on v7 ```sh npx tsc --noEmit grep -rnE "from \"\.{1,2}/[^\"]*\"" src | grep -vE "\.(js|json)\"" # must print nothing npm test npm start # boot, hit one route, stop ``` Stop and fix before continuing. A failure here is not a v8 problem. ## 5. Bump to v8 1. Set every `@tsed/*` runtime package to the same 8.x version. Do not align `@tsed/logger*`, `@tsed/barrels` or `@tsed/cli*`; they are versioned separately. 2. Install and boot. `@tsed/common` 8.x still exists as a compatibility barrel, so the application should start before step 6. 3. Apply the v8 behaviour changes: - Request logging is no longer automatic. Add `import "@tsed/platform-log-request";` in `Server.ts` and set `logger: {logRequest: true}`. `PlatformLogMiddleware` from `@tsed/platform-log-middleware` is deprecated. - View engines must be imported explicitly, for example `import "@tsed/engines/PugEngine.js";`. - `Configurable`, `Enumerable`, `Writable` and the `@tsed/core` versions of `ReadOnly` and `Deprecated` are removed. - Hooks moved to `@tsed/hooks` (`$on`, `$asyncEmit`, `$alter`, `$asyncAlter`). 4. Re-run section 4 commands. ## 6. Remove `@tsed/common` 1. List usages: `grep -rn "@tsed/common" src test`. 2. Rewrite each import with [the symbol table](references/common-symbols.md). Typical split: ```ts // before: import {BodyParams, Controller, Post, Req, UseBefore, PlatformTest} from "@tsed/common"; import {Controller} from "@tsed/di"; import {Req} from "@tsed/platform-http"; import {UseBefore} from "@tsed/platform-middlewares"; import {BodyParams} from "@tsed/platform-params"; import {Post} from "@tsed/schema"; // tests only import {PlatformTest} from "@tsed/platform-http/testing"; ``` 3. Add each owning package to `dependencies`, then remove `@tsed/common`. 4. `@tsed/common` imported `@tsed/logger-file` as a side effect. If file appenders are used, add `import "@tsed/logger-file";` explicitly. 5. Resolve remaining deprecations with [the replacement table](references/deprecated-apis.md). Adopt the functional DI API only where it simplifies code; decorators remain supported. See the `tsed-di` skill. Do not import `PlatformTest` from `@tsed/platform-http` in application code; it lives in `@tsed/platform-http/testing`. ## 7. Tests: Jest to Vitest Jest is unstable with ESM. Migrate when the suite fails after section 3. 1. Install `vitest unplugin-swc @swc/core @vitest/coverage-v8`; create `vitest.config.ts` from `https://tsed.dev/tutorials/vitest.md` (SWC plugin with `useDefineForClassFields: false`). 2. Replace `jest.fn`, `jest.spyOn`, `jest.mock` with `vi.fn`, `vi.spyOn`, `vi.mock` (import `vi` from `vitest` unless `globals: true`). 3. Replace `PlatformTest.inject([...], fn)` with `PlatformTest.invoke(Token)` or `PlatformTest.get(Token)`. 4. Use the `tsed-testing` skill for test structure and the `tsed-cli` skill to add `@tsed/cli-plugin-vitest`. ## 8. Plain Express application 1. Move the legacy code to `src/legacy/` and make sure `src/index.ts` does not exist. 2. Scaffold over the existing `package.json` with the `tsed-cli` skill (`tsed init .`, platform `express`); rename conflicting scripts first. 3. Export the legacy `express.Router()` and mount it in `@Configuration`: `middlewares: [{use: expressRouter, hook: "$beforeRoutesInit"}]`, so existing routes keep working. 4. In legacy handlers, reach Ts.ED services with `inject(MyService)` from `@tsed/di`. 5. Port routes to controllers incrementally (`tsed-controllers`, `tsed-middlewares`). Guide: `https://tsed.dev/introduction/migrate-from-express.md`. ## Pitfalls - Injected properties are `undefined` in constructors or at runtime: `useDefineForClassFields` is still `true` in one of `tsconfig.json`, `.swcrc`, `vite.config.ts`, `vitest.config.ts`. - `ERR_MODULE_NOT_FOUND` on a relative path: missing `.js` extension or a directory import without `/index.js`. - `ERR_REQUIRE_ESM`: a CommonJS entry point or loader (`ts-node`, `--require`) is still in use. Use `--import`. - `Module '"@tsed/common"' has no exported member 'Returns'` (or `Property`, `Required`): in v8 the barrel re-exports only the routing decorators of `@tsed/schema`. Import from `@tsed/schema`. - Request logs disappeared after the bump: `@tsed/platform-log-request` is not imported. - The migration guide shows `import ... from "./config.json.js" assert {type: "json"}` and `@swc-node/register/register-esm`. Use `./config.json` with `with {type: "json"}` and `@swc-node/register/esm-register`. - Controllers discovered through barrels silently vanish when `barrels` is not run before start. Keep `"barrels": "barrels"` in the start script chain. ## Checklist - Sections 2 to 4 verified on v7 before the v8 bump. - `"type": "module"`, `NodeNext`, `.js` extensions everywhere, no `require`, no `__dirname`. - `useDefineForClassFields: false` in every transpiler configuration. - No custom key read through `settings.<key>`. - All `@tsed/*` runtime packages on the same 8.x version; `@tsed/common` removed and no import of it left. - `@tsed/platform-log-request` and view engines imported explicitly where needed. - `npx tsc --noEmit`, the test suite and a manual boot all pass.