Skip to main content

Prerequisites​

  • Node.js version 18 or above
  • TypeScript version 5.0 – 5.4

Installation​

yarn add @clawject/di
tip

Remember to install language service plugin to get support for Clawject features right in your code editor!

tsconfig.json​

Firstly, you need to define custom transformers in your tsconfig.json.

tip

@clawject/di/transformer/metadata is optional, it's used to generate metadata for your configuration classes which allows you to share configuration via npm packages. Visit sharing configurations section to learn more about it.

tsconfig.json
{
  "compilerOptions": {
    "plugins": [
      { "transform": "@clawject/di/transformer" },
      {
        "transform": "@clawject/di/transformer/metadata",
        "afterDeclarations": true
      }
    ]
  }
}

ts-patch​

Patches typescript to allow custom transformers (plugins) during build.

ts-patch is the best way to utilize Clawject features. It allows you to use Clawject with any build tool that uses typescript compiler.

For detailed ts-patch configuration guide - please refer to ts-patch documentation.

ts-patch, webpack, ts-loader​

warning

When using webpack with ts-loader - make sure transpileOnly mode is disabled. Basically, transpileOnly disables the ability to perform static type checking, which is required for Clawject to work. Also, if you're using Babel - please make sure that it's applied after ts-loader. ts-loader#transpileOnly

webpack.config.js
import { ClawjectWebpackPlugin } from '@clawject/di/webpack';

export default {
  module: {
    rules: [{
      test: /\.ts$/,
      loader: 'ts-loader',
      options: {
        // This option needed if you have typescript >= 5 and using
        // live-compiler method of ts-patch
        // https://github.com/nonara/ts-patch#method-1-live-compiler
        compiler: 'ts-patch/compiler'
      }
    }]
  },
  plugins: [
    new ClawjectWebpackPlugin()
  ]
};

ts-patch, vite, rollup-plugin-typescript2​

danger

Currently Vite or rollup-plugin-typescript2 not correctly utilizes ts-patch, it's ignoring compilation errors produced by Clawject, so it could lead to runtime errors.

vite.config.ts
import { defineConfig } from 'vite';
import typescript from 'rollup-plugin-typescript2';

export default defineConfig({
  esbuild: false,
  plugins: [
    typescript(),
  ],
});

ts-patch, pure typescript (tsc)​

To make Clawject work with pure typescript (tsc), you need to define custom transformers in your tsconfig.json, and that's all.

About typescript watch mode

Clawject will work pretty well in native tsc watch mode as well!

Without ts-patch​

If you don't want to use ts-patch for some reason - you can utilize Clawject features without it.

webpack, ts-loader​

webpack.config.js
import { ClawjectTransformer } from '@clawject/di/transformer';
import { ClawjectMetadataTransformer } from '@clawject/di/transformer/metadata';
import { ClawjectWebpackPlugin } from '@clawject/di/webpack'

export default {
  module: {
    rules: [{
      test: /\.ts$/,
      loader: 'ts-loader',
      options: {
        getCustomTransformers: (program, getProgram) => ({
          before: [ClawjectTransformer(getProgram)],
          afterDeclarations: [ClawjectMetadataTransformer(getProgram)]
        })
      }
    }]
  },
  plugins: [
    new ClawjectWebpackPlugin()
  ]
};