node-cls

library1.0.7jsnpmunverified

Continuation Local Storage (CLS) for Node.js based on async_hooks, providing context propagation across async calls. Version 1.0.7 is stable and works with Node >=8.0.0. It is an alternative to the deprecated domain module and offers nested contexts, Symbol keys to avoid collisions, and an await-compatible start() method (Node 12+). Unlike similar libraries like cls-hooked or async-hooks-context, node-cls focuses on a simple API with create, run, get, start, and exit methods. Release cadence is low; no recent updates.

devops

npm install node-cls

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-CLS

node-cls

devopsjavascriptv1.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

cls (default)

✓ import cls from 'node-cls'

✗ const { cls } = require('node-cls')

The module exports a single object; default import or require works.

create

✓ const context = cls.create('key')

✗ const context = new cls.Context('key')

cls.create is a factory function, not a constructor.

get

✓ const ctx = cls.get('key')

✗ const ctx = global['cls'][key]

Access context by key using cls.get, not global state.

Demonstrates creating a contextual namespace, setting a property, running a function that retrieves the context synchronously and asynchronously.

import cls from 'node-cls'; const context = cls.create('request'); context.id = 123; context.run(() => { const ctx = cls.get('request'); console.log(ctx.id); // 123 setTimeout(() => { const laterCtx = cls.get('request'); console.log(laterCtx.id); // 123 (context retained) }, 100); });

Debug

Known issues

gotchaRequire node-cls before any other packages to avoid context loss in async hooks.

fix

Place `require('node-cls')` as the first line of your application entry point.

affects: >=1.0.0

gotchaWhen using express, register body-parser before node-cls middleware to prevent context loss.

fix

Order middlewares: app.use(bodyParser); app.use(cls.middleware);

affects: >=1.0.0

gotchaAsync hooks are still experimental in Node 8.x; stability not guaranteed.

fix

Upgrade to Node 12+ or use a stable alternative like cls-hooked.

affects: >=1.0.0 <2.0.0

deprecatedThe module does not actively use or mention Corepack; it has no official TypeScript types.

fix

Use @types/node-cls if available, or declare module manually.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: cls.create is not a function

Importing incorrectly with named import instead of default.

fix

Use `import cls from 'node-cls'` or `const cls = require('node-cls')`.

Error: async hook stack has overflowed

Infinite recursion in async hooks due to nested context creation without proper exit.

fix

Ensure each context.run() completes or call context.exit() when using start().

Cannot read property 'id' of undefined

Calling cls.get() outside of a run() or start() block where context is not active.

fix

Wrap code that needs context inside context.run() or await context.start().

Upgrade

Version history

1.0.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubssh://git@github.com/alfateam/node-cls ↗

packagenode-cls ↗

homepagehttps://github.com/alfateam/node-cls/blob/master/README.md ↗