TypeScript configuration

UDIOT is ESM-only. Use Node.js >=22.17.0 and set "type": "module" in your application's package.json. Install TypeScript and @types/node as development dependencies. RC package validation uses the repository's locked TypeScript compiler; do not infer compatibility with every older TypeScript release.

Node application

Save this as tsconfig.json and put the quick-start program in src/main.ts:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "useDefineForClassFields": false,
    "esModuleInterop": true,
    "skipLibCheck": false,
    "rootDir": "src",
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

DOM libraries are included because the root declaration surface also references browser types; this does not make browser globals available at runtime in Node.

npx tsc -p tsconfig.json
node dist/main.js

Use .js extensions for relative ESM imports in TypeScript, for example import { service } from './service.js'.

Decorators and metadata

The current decorator APIs use TypeScript's legacy decorator implementation. Enable experimentalDecorators; enable emitDecoratorMetadata for constructor injection. Import reflect-metadata before evaluating decorated application classes. Repeated imports are safe. Do not substitute stage-3 decorators without adapting the framework.

Set useDefineForClassFields to false. With an ES2022 target TypeScript defaults it to true, and then a field declared in a subclass, such as @Prop() label!: string or @InjectProperty() theme!: ThemeService, is redefined as undefined after the framework's base constructor has set it, and an initialized @State() field replaces the decorator's change tracking.

A transpiler that strips types but does not emit decorator metadata is not equivalent to compiling with tsc. If using Vite, esbuild or another transpiler, verify its decorator/metadata handling before relying on implicit constructor injection. Explicit registration alone does not synthesize constructor metadata.

Browser builds

Use @tagna/udiot/browser and a bundler. Set module to ESNext and moduleResolution to Bundler; retain the DOM libraries. Avoid root/server, database-server and Node-only imports in browser code. Browser consumers and individual database adapters have separate compatibility requirements.

Troubleshooting

• A compile-time module-resolution error can indicate an incompatible moduleResolution setting. Use NodeNext or Bundler.
• A runtime ERR_PACKAGE_PATH_NOT_EXPORTED means the installed package does not expose that path/condition. Changing tsconfig alone cannot export it.
• Use ESM import; the package export map has no CommonJS require condition. Do not work around this by compiling application imports to CommonJS.
• Missing constructor metadata can cause failed or incomplete injection. Check decorator settings, compilation output and metadata import order.
• skipLibCheck: true can hide declaration incompatibilities. Keep it false for a release-validation build.

See installation and public entry points.