Skip to main content

v5.x → v6.x

The v6 major version stabilizes the Plugin API and cleans up the proxy API on the ClsService.

There are no breaking changes in behavior and the core API. Apart from a few syntax changes, the migration should be straightforward.

Removed the onClsInit method in the Plugin interface​

The not very useful onClsInit method was removed from the Plugin interface. It has been replaced by the beforeSetup and afterSetup methods provided by the special ClsPluginHooks provider. See the Plugin API for more information.

Unless you specifically created a custom plugin that used this method, you can safely ignore this change.

Proxy provider accessors on ClsService moved under the proxy property​

The ClsService exposed a set of top-level methods to manage Proxy Providers. These methods have been moved under the proxy property of the ClsService.

The following methods have been moved:

  • getProxy -> proxy.get
  • setProxy -> proxy.set
  • resolveProxyProviders -> proxy.resolve

e.g. in v5.x you would write:

await this.cls.resolveProxyProviders([MyProxyProvider]);

this.cls.setProxy(MyOtherProxyProvider, new MyOtherProxyProvider(dependency));

const instance = this.cls.getProxy(SomeProxyProvider);

in v6.x, this becomes:

await this.cls.proxy.resolve([MyProxyProvider]);

this.cls.proxy.set(MyOtherProxyProvider, new MyOtherProxyProvider(dependency));

const instance = this.cls.proxy.get(SomeProxyProvider);

Existing plugin compatibility​

@nestjs-cls/transactional​

Both of these changes do affect the @nestjs-cls/transactional plugin. Make sure to update it to version v3.x or higher.

Transactional adapter packages are not affected, but it is still recommended to keep them on the latest version.

await module.init() required when using plugins or @UseCls() in tests​

Since v6, CLS plugins and the @UseCls() decorator rely on infrastructure initialized during onApplicationBootstrap. In tests that use Test.createTestingModule, this hook is not called unless you explicitly call await module.init().

If you upgrade from v4/v5 and your tests throw ClsPluginsHooksHost not initialized, add await module.init() to your setup:

const module = await Test.createTestingModule({ ... }).compile();
await module.init(); // required in v6 when using plugins or @UseCls()