@beignet/provider-logger-pino

Pino-backed LoggerPort provider for Beignet.

Use this package when you want ctx.ports.logger backed by Pino while keeping application code dependent on the stable LoggerPort interface from @beignet/core/ports.

createPinoLoggerProvider(...) returns the stable PinoLoggerProvider type. LoggerPinoConfig describes its validated config; the Zod schema remains internal.

Install

bun add @beignet/core @beignet/provider-logger-pino pino
Copy

Pretty development logs are optional:

bun add -d pino-pretty
Copy

Setup

import { createNextServer, createNextServerLoader } from "@beignet/next";
import { createPinoLoggerProvider } from "@beignet/provider-logger-pino";
import { initialPorts } from "@/infra/port-wiring";

export const getServer = createNextServerLoader(() =>
  createNextServer({
    ports: initialPorts,
    providers: [createPinoLoggerProvider()],
    context: ({ ports }) => ({
      requestId: crypto.randomUUID(),
      ports,
    }),
  }),
);
Copy

The provider installs ctx.ports.logger. It flushes the provider-owned Pino logger during server.stop() so buffered destinations and transports can drain before shutdown.

beignet doctor --strict checks that installed Pino logger providers are registered in server/providers.ts.

Environment

The provider reads LOG_-prefixed environment variables:

LOG_FORMAT=pretty requires pino-pretty. If it is unavailable, the provider falls back to JSON logging and emits a warning.

Use createPinoLoggerProvider(...) when you want to pass options directly instead of relying only on LOG_* env vars. Options override env-derived values:

import { createPinoLoggerProvider } from "@beignet/provider-logger-pino";

export const providers = [
  createPinoLoggerProvider({
    level: "debug",
    format: "pretty",
    service: "api",
    timestamp: true,
  }),
];
Copy

Direct adapter

Use createPinoLogger(...) when the app owns Pino configuration, transports, or destinations:

import { createPinoLogger } from "@beignet/provider-logger-pino";
import pino from "pino";

const destination = pino.destination("./app.log");
const pinoLogger = pino({ level: "info" }, destination);
const logger = createPinoLogger({ logger: pinoLogger });
Copy

The direct factory only adapts the supplied Pino logger to LoggerPort; the caller owns flushing and destination shutdown.

Usage

ctx.ports.logger.info("Post published", {
  postId: post.id,
  actorId: ctx.actor.type === "user" ? ctx.actor.id : undefined,
});

const log = ctx.ports.logger.child({ requestId: ctx.requestId });
log.error("Failed to publish post", { error });
Copy

Exports

Installed ports

The provider contributes ctx.ports.logger, the standard Beignet LoggerPort. Use createPinoLogger(...) when app infrastructure needs to own the underlying Pino logger; application workflows should continue to depend on the stable port.

Instrumentation

This provider does not record devtools provider events for each log call. Logs are the primary output. Use provider instrumentation on the external providers doing work, and include requestId, traceId, actor, tenant, or feature metadata in log bindings when those fields are useful operational context.

Failure behavior

Invalid LOG_* configuration fails during provider setup. If LOG_FORMAT=pretty is configured without pino-pretty, the provider falls back to JSON logging and emits a warning instead of failing startup.

Local and tests

Use LOG_FORMAT=pretty for local development when pino-pretty is installed. Use a memory or fake LoggerPort in use-case tests when assertions should not depend on console output.

Deployment notes

Use JSON logs in production unless the runtime explicitly expects formatted text. Set LOG_SERVICE per deployed service and include request/trace metadata from Beignet context so logs correlate with devtools, provider events, and error reports.

Read next

• Docs site logging guide: https://beignetjs.com/logging
• Providers: https://beignetjs.com/providers
• Pino documentation: https://getpino.io/

License

MIT