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
• Deprecated and removed APIs with replacements

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:

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:

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:

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

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. Typical split:

// 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. 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.