Usage

Learn how to use Logixlysia in your Elysia applications

Installation

bun add logixlysia

Basic Usage

import { Elysia } from 'elysia'
import logixlysia from 'logixlysia'

const app = new Elysia()
  .use(logixlysia())
  .get('/', () => 'Hello World')
  .listen(3000)

Using the plugin in several modules

Create the plugin once and .use() that same instance in every module. If each module calls logixlysia() again, each module’s routes are still logged through its own instance, but Elysia runs only the first instance’s onRequest: a later instance adds no request ID and runs no request-phase enrichers, its lines are written when the handler returns rather than when a streamed body ends, and useLogger() in its routes resolves to the first instance’s logger. app.stop() flushes only the first instance’s transports.

// logging.ts
import logixlysia from 'logixlysia'

export const logging = logixlysia({ config: { requestId: true } })

// users.ts
import { Elysia } from 'elysia'
import { logging } from './logging'

export const users = new Elysia().use(logging).get('/users', () => [])

The request boundary is app-wide: once the plugin is mounted anywhere, every request of the application gets an access line, routes on parent apps included.

Request context

Accumulate fields during a request; they are merged into the automatic access log, or into the custom log line that replaces the access line:

.get('/users/:id', ({ request, store, params }) => {
  store.logger.mergeContext(request, { userId: params.id })
  return { ok: true }
})

See Request context for details.

Presets

logixlysia({ preset: 'dev' }) // pretty console + banner
logixlysia({ preset: 'prod' }) // JSON logs + autoRedact
logixlysia({ preset: 'json' }) // minimal JSON console

Explicit config overrides preset defaults. Details: Presets.

Configuration

Basic Options

logixlysia({
  config: {
    showStartupMessage: true,
    startupMessageFormat: 'simple', // or 'banner'
    ip: true,
    autoRedact: false, // Set to true to auto-redact sensitive PII (emails, IPs, credit cards, JWTs)
    logQueryParams: true,
    logFilePath: './logs/app.log'
  }
})

Custom Log Format

Customize log messages using placeholders:

logixlysia({
  config: {
    customLogFormat:
      '{now} {level} {duration} {method} {pathname}{query} {status}'
  }
})

Available placeholders:

Log Filtering

Filter logs by level:

logixlysia({
  config: {
    logFilter: {
      level: ['ERROR', 'WARNING']
    }
  }
})

Logixlysia keeps only the listed levels and drops the rest.

Pino Integration

Logixlysia writes its own lines and exposes a pino instance as store.pino for your application’s structured logging:

app.get('/users/:id', ({ store, params }) => {
  const { pino } = store

  pino.info(
    {
      userId: params.id,
      action: 'view_profile'
    },
    'User profile accessed'
  )

  return { user: 'data' }
})

Configure Pino options:

logixlysia({
  config: {
    pino: {
      level: 'debug',
      prettyPrint: true,
      redact: ['password', 'token'],
      base: { service: 'my-api' }
    }
  }
})

Learn more in the Pino Integration guide.

File Logging

Save logs to files:

logixlysia({
  config: {
    logFilePath: './logs/app.log',
    logRotation: {
      maxSize: '10m',
      interval: '1d',
      maxFiles: '7d',
      compress: true
    }
  }
})

See File Logging and Log Rotation for details.

Output Control

Control where logs are sent:

logixlysia({
  config: {
    // Disable console output
    disableInternalLogger: false,

    // Disable file output
    disableFileLogging: false,

    // Use only transports (disable console and file)
    useTransportsOnly: false,

    // Custom transports
    transports: [customTransport]
  }
})

Error Handling

Logixlysia automatically captures and logs errors:

app.get('/error', () => {
  throw new Error('Something went wrong!')
})

Logixlysia logs the error automatically with the request method, path, status, and error message. For an HttpError, it also logs code, why, fix, and link. It does not log stack traces.

Examples

Production Setup

const app = new Elysia()
  .use(
    logixlysia({
      config: {
        logFilePath: './logs/production.log',
        logRotation: {
          maxSize: '100m',
          interval: '1d',
          maxFiles: '30d',
          compress: true
        },
        logFilter: {
          level: ['ERROR', 'WARNING']
        },
        autoRedact: true,
        redactKeys: ['customerSsn']
      }
    })
  )
  .listen(3000)

Development Setup

const app = new Elysia()
  .use(
    logixlysia({
      config: {
        showStartupMessage: true,
        startupMessageFormat: 'banner',
        pino: {
          level: 'debug',
          prettyPrint: true
        }
      }
    })
  )
  .listen(3000)