Context and logging

A handler receives the execution's NileContext as its second argument. Use it for shared resources such as the logger and database, the signed-in session, and the request identifier for correlating logs. Use the logger for records you choose to write.

When to use itCopy Anchor Link

Read context.resources when a handler needs the logger or database. Read getSession("rest") for the signed-in user. Read context.execution for the request ID, transport and cancellation signal. Use updateHookState for state that belongs to one execution. Use set and get only for application-wide values.

Complete exampleCopy Anchor Link

The server registers a logger and a database as resources. The handler writes one log entry per outcome and includes the request's identifiers in the data it logs.

import {
  createAction,
  createLogger,
  createNileServer,
  createServices,
  type NileContext,
} from "@nilejs/nile";
import { Err, Ok } from "@nilejs/nile/fp";
import { z } from "zod";

const logger = createLogger("team-workspace", {
  mode: "prod",
  chunking: "daily",
});

const renameProjectSchema = z.object({
  projectId: z.string().uuid(),
  name: z.string().trim().min(1, "Name is required"),
});

type RenameProjectInput = z.infer<typeof renameProjectSchema>;

const renameProjectHandler = (
  data: RenameProjectInput,
  context?: NileContext
) => {
  const activeLogger = context?.resources?.logger;

  if (data.name === "system") {
    activeLogger?.warn({
      atFunction: "renameProject",
      message: "Rejected a reserved project name",
      data: { projectId: data.projectId },
    });
    return Err("Choose a different project name");
  }

  activeLogger?.info({
    atFunction: "renameProject",
    message: "Project renamed",
    data: { projectId: data.projectId },
  });

  return Ok({ projectId: data.projectId, name: data.name });
};

const renameProjectAction = createAction({
  name: "rename",
  description: "Rename a project",
  validation: renameProjectSchema,
  handler: renameProjectHandler,
});

const services = createServices([
  {
    name: "projects",
    description: "Project operations",
    actions: [renameProjectAction],
  },
]);

export const server = await createNileServer({
  serverName: "team-workspace",
  services: services,
  resources: { logger: logger },
  rest: { baseUrl: "/api", allowedOrigins: ["https://app.example.com"] },
});

Handlers are typed with NileContext and read optional fields with ?.. Nile passes the context on every call, including server.invoke calls. The fields are optional because your handler can also be called from a test or a background job that has no request.

With the logger above, createLogger writes structured lines to logs/ relative to the working directory. The starter's startup line looks like this:

22:31:21.321 INFO  onBoot my-app booted - PGLite schema ready

What the context gives youCopy Anchor Link

Use getContext<AppDatabase>() outside a handler when you need the typed resources, for example in a module that does not receive the context. It throws if the server has not been created.

Logger optionsCopy Anchor Link

Each entry includes the application name, the function name you pass as atFunction, the message, your optional data and a log ID. Nile attaches execution IDs to related log entries.

LimitsCopy Anchor Link

• context.set writes to a map in this process. Other instances do not see it, and a restart clears it.
• A logger resource does not record every request. Log the events you need.
• Time-based chunking does not ship or delete logs. Plan retention for your deployment.

Common mistakesCopy Anchor Link

• Storing the current user with set("user", ...). Concurrent requests share that value. Read the session instead.
• Logging passwords, tokens or personal data in data. Log identifiers and outcomes.
• Calling getContext at module load before createNileServer has run.
• Assuming context.execution exists outside an execution. Read it with ?..

See alsoCopy Anchor Link

• Context explains shared and request-scoped state.
• Logging covers file layout and reading logs.
• Production operations describes execution IDs, telemetry and log filters.