Async Local Storage in Node.js: The Hidden Power You’re Probably Not Using
Context is king — and this Node.js feature helps you preserve it, even across async calls.
Ever faced this?
You’re debugging a Node.js app.
You log a userId at the start of a request…
…and by the time your code hits the DB layer 4 async calls later?
❌ userId is gone.
❌ Your log is useless.
❌ You don’t know which request it belongs to.
Been there?
That’s where AsyncLocalStorage swoops in like a superhero you didn’t know you had.
What is AsyncLocalStorage?
AsyncLocalStorage is part of Node’s async_hooks module.
It lets you persist data across async calls, without manually passing it through every function.
Think of it as:
✅ Thread-local storage — but for Node’s async world.
✅ A contextual storage box — specific to each request.
Real-World Use Case:
Logging Per Request
Say you’re building an API, and you want to tag every log with the correct requestId.
Without ALS, you’d have to pass that requestId around… to every service… every function.
But with ALS?
Here’s how simple it becomes:
const { AsyncLocalStorage } = require('async_hooks');
const asyncLocalStorage = new AsyncLocalStorage();// Middleware to set requestId per request
app.use((req, res, next) => {
const context = new Map();
context.set('requestId', req.headers['x-request-id'] || generateId());
asyncLocalStorage.run(context, () => {
next();
});
});
// Anywhere in your code
function logWithRequestId(message) {
const store = asyncLocalStorage.getStore();
const requestId = store?.get('requestId') || 'unknown';
console.log(`[${requestId}] ${message}`);
}Now all your logs are tagged. Without passing requestId explicitly. 🧠
Why Should You Care?
Because in real-world Node.js apps:
- You use async/await or promises everywhere
- You want to trace requests cleanly, especially in microservices
- You’re tired of attaching
reqto every utility function
AsyncLocalStorage saves your mental bandwidth and helps clean up your codebase.
Caveats You Should Know
- Works best with modern async/await code — callbacks can break context
- Doesn’t persist across process boundaries (obviously)
- Available from Node.js v13.10+ (recommended v14+)
When Should You Use It?
Use AsyncLocalStorage when you need:
- Request-scoped logging or tracing
- To store auth tokens/user IDs per request
- Clean context handling in large-scale async apps
Not a replacement for full-blown observability tools — but a great first step.
TL;DR
- AsyncLocalStorage helps maintain context across async calls
- It simplifies logging, tracing, and debugging
- It’s built-in, underused, and surprisingly powerful
Over to You
Have you used AsyncLocalStorage before? Or are you still manually passing context?
Drop a comment with your best logging/debugging war story 👇
Let’s learn from each other’s chaos.
At Dev Simplified, We Value Your Feedback 📊
👉 Follow us to not miss any updates.
👉 Have any suggestions? Let us know in the comments!