Introduction

Nuxt has recently introduced an experimental feature: async context support using NodeJS AsyncLocalStorage.
This enhancement promises to simplify how developers manage context across nested async functions, but there is more !

It's important to note that the "experimental" label is due to limited support across platforms; however, it is stable when using NodeJS, making it a reliable option for developers working within that environment.

https://nuxt.com/docs/guide/going-further/experimental-features#asynccontext

AsyncLocalStorage in NodeJS allows you to store and access data consistently across asynchronous operations. It maintains a context, making it easier to manage data like user sessions or request-specific information.

What Does AsyncContext Solve?

• Context Consistency Across Async Operations: AsyncContext ensures that context data remains accessible throughout all asynchronous calls without manually passing it through layers of functions.
  
  

• Reducing Boilerplate Code: Simplifies codebases by eliminating repetitive context-passing logic.
  
  

Maintaining a consistent request context has been a challenge in NodeJS applications, even before Nuxt.

The challenge

One use case was implementing a logging system to track customer paths through our website. To achieve this, we needed to include a correlation ID with every log entry, ensuring we could consistently trace each customer’s journey.

This issue is that when you have more application logic with multiple layers you have to pass the context down these layers.

Let's look at an example :

nuxt-demo-async-context/
├── public/
│   └── favicon.ico
├── server/
│   ├── api/
│   │   ├── index.ts
│   │   └── users.ts
│   ├── middleware/
│   │   └── correlationId.middleware.ts
│   ├── repository/
│   │   └── user.repository.ts
│   ├── service/
│   │   └── user.service.ts
│   └── utils/
│       └── logger.ts
├── .gitignore
├── README.md
├── app.vue
├── nuxt.config.ts
├── package-lock.json
├── package.json
├── tsconfig.json
└── yarn.lock

File Structure and Code Drafts

1. [id].ts

export default defineEventHandler((event) => {
  const id = event.context.params.id;
  const { correlationId } = event.context;
  try {
    const user = userService.getUserById(id, correlationId);
    return {
      user,
      message: `User with ID ${id} retrieved successfully`
    };
  } catch (error) {
    return {
      statusCode: 404,
      message: `User with ID ${id} not found`
    };
  }
});

1. userRepository.ts

// This would typically interact with a database
const users = new Map<string, { id: string; name: string; email: string }>();

export default {
  findById(id: string) {
    return users.get(id) || null;
  },

  save(user: { id: string; name: string; email: string }) {
    users.set(user.id, user);
    return user;
  }
};

As you can see, the issue is that we are passing down on every layers the correlationId variable that is a request context, it mean that every function has a dependance for the correlationId variable.

Now imagine if we have to do this on every application logic.

Please do not set this kind of logic in a global variable, NodeJS will share this context between every request for every user.

Solution

AsyncContext can resolve this issue !

Once you activate the experimental feature asyncContext in Nuxt.

You can access the event from anywhere now.

We can create a middleware that will pass this correlationId to the event to be available anywhere in the application :

server/middleware/correlationId.ts

import { randomUUID } from 'crypto';
import { setCookie, getCookie } from "#imports";

export default defineEventHandler((event) => {
  // Add a random correlationId to the event context
  const correlationId = getCookie(event, "correlationId") || randomUUID();
  event.context.correlationId = correlationId;

  setCookie(event, "correlationId", correlationId);
});

Now we can do something like :

export default {
  info(message: string) {
    const { context: { correlationId } } = useEvent();
    console.log(JSON.stringify({ level: 'INFO', message, correlationId }));
  },
  error(message: string) {
    const { context: { correlationId } } = useEvent();
    console.error(JSON.stringify({ level: 'ERROR', message, correlationId }));
  }
};

There's no longer a need to pass the request or a parameter down to our logger.

We can apply this technique to get a user context, it's a common use case.

Conclusion

AsyncContext simplifies context management in Nuxt applications, reducing boilerplate code and ensuring consistency across asynchronous operations.

We can go further by implementing dependency injection for services like request context or user services.

This approach reduces coupling and minimizes dependencies between layers, making the codebase more modular, easier to maintain, and testable.

Further Reading

PoC available here https://github.com/marc-arnoult/nuxt-demo-async-context

For more details on how to implement AsyncContext and explore other experimental features in Nuxt, check out the official documentation.
https://nodejs.org/api/async_context.html