Context
When a request comes in, many small pieces of code run for it: middleware, your controller, a model, a helper, a log call. They all need to know a few things about this request (which app, which user, which team, its request id) without you passing them from function to function. Context is that shared, per-request information.
Strutvane keeps it in Node’s AsyncLocalStorage: a built-in way to attach a value to one request, so that it follows the code across every await, and two requests running at the same time never see each other’s value.
The smallest example
Section titled “The smallest example”You already use context every time you call a helper:
import { config, Controller, type HttpContext } from '@strutvane/framework'
export class HomeController extends Controller { async index(ctx: HttpContext): Promise<Response> { await new Promise((resolve) => setTimeout(resolve, 10)) // any await… return ctx.json({ app: config('app.name') }) // …still knows which app this is }}What you’ll see: { "app": "My App" }. config() found the app through the context, after an await, with no app object passed in.
What’s in the context
Section titled “What’s in the context”| Value | Set by | Used by |
|---|---|---|
| The current app (container, config, URLs) | Strutvane, around every request and command | config(), route(), now(), app(), models, facades |
| The request id | Strutvane, for every request | every log line of the request, error reports |
| The signed-in user | the auth middleware |
every log line (as an id), policies |
| The current team | tenancy, when teams are on | the ORM tenant scope, every log line |
| Your own values | you, with Context.add() |
every log line, and queued jobs from 0.3 |
Values that are about the request itself (the body, the bound models, the route) live on ctx, the request object every action receives. Context is for what all code should know without being handed ctx.
Context in your logs
Section titled “Context in your logs”Every log line written during a request carries its context, so you can find everything one request did:
import { Log } from '@strutvane/framework'
Log.info('Post published', { postId: 42 })What you’ll see in storage/logs/strutvane-2026-11-15.log:
[2026-11-15 10:22:01.123] local.INFO: Post published {"postId":42,"requestId":"01JD7Q6Y9X3V2K8M4N5P6R7S8T","userId":1}Add your own value for the rest of the request with Log.withContext():
Log.withContext({ orderId: 'ord_123' })Log.info('Charging the card') // context: { orderId: 'ord_123', requestId: … }Secrets are redacted from context like from everything else that’s logged. See Logging.
Adding your own values (preview)
Section titled “Adding your own values (preview)”import { Context, type HttpContext, type Middleware, type Next } from '@strutvane/framework'
export class AddPlanContext implements Middleware { async handle(ctx: HttpContext, next: Next): Promise<Response> { Context.add('plan', ctx.user === null ? 'guest' : 'pro') return next() }}Anywhere later in the same request:
Context.get('plan') // → 'pro'Hidden values
Section titled “Hidden values”Some values are useful to code but must never reach a log file: an internal key, a customer’s account number.
Context.addHidden('partnerAccount', account.number)Context.getHidden('partnerAccount') // available to your code, never written to logsContext in queued jobs (coming in 0.3)
Section titled “Context in queued jobs (coming in 0.3)”When a request dispatches a job, its context (request id, user, team and your own values, hidden ones included) is saved with the job and restored when a worker runs it. So the job’s log lines carry the same request id as the request that queued it, and the job runs inside the same team. Code that runs work on other threads (Concurrency.run) passes the team and request context along explicitly for the same reason (Concurrency).
Outside a request: scripts and tests
Section titled “Outside a request: scripts and tests”A standalone script or a test isn’t a request, so there’s no context until you create one. Helpers then stop with a clear message:
✖ config() was called outside a request or console command, so there is no current app.→ Call it from a controller, middleware or command, or wrap the code in app.run(() => …) (tests: await app.run(async () => …)).Wrap the code in app.run(), which sets the context for everything inside it:
import { randomBytes } from 'node:crypto'import { expect, test } from 'vitest'import { config } from '@strutvane/framework'import { createApp } from '../../bootstrap/app.ts'
test('code inside app.run() sees the app', async () => { const app = createApp({ APP_ENV: 'testing', APP_KEY: `base64:${randomBytes(32).toString('base64')}`, APP_NAME: 'Test App', DB_CONNECTION: 'sqlite' }) await app.boot() expect(await app.run(async () => config('app.name'))).toBe('Test App')})node strut commands get a context automatically, like requests.
Why not a global?
Section titled “Why not a global?”A global “current user” works when one process handles one request (PHP). A Node server handles many requests at the same time: while request A waits for the database, request B runs. A global would let B overwrite A’s user mid-request. AsyncLocalStorage gives each request its own value, carried across every await, and it’s also why two apps in one test file never see each other.
Common mistakes
Section titled “Common mistakes”“… was called outside a request or console command”
Section titled ““… was called outside a request or console command””Why: the code ran at the top level of a file (when it was imported), in a setTimeout started before the request, or in a script.
Fix: move it into a function that runs during a request, or wrap it in app.run(() => …).
My log lines from a background callback have no request id
Section titled “My log lines from a background callback have no request id”Why: work started outside the request (for example from a timer created at start-up) has no request context. Fix: do the work inside the request, or queue a job (from 0.3 it carries the context).
I put the user’s password in the context
Section titled “I put the user’s password in the context”Why: context values are written to every log line of the request. Fix: never put secrets in context; use hidden context for values code needs but logs must not show.
Next steps
Section titled “Next steps”- Logging: what context looks like in log files.
- Helpers: the helpers that read the current app.
- Request Lifecycle: where the context is set.