Usage

Learn how to use Logixlysia in your Elysia applications

Installation

bun add logixlysia@next elysia@next

The next tag tracks the Elysia 2 open beta. For Elysia 1.4, install logixlysia from the default latest tag instead.

Basic Usage

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

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

Request context

Accumulate fields during a request; they are merged into the automatic access log:

.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}ms {method} {pathname}{query} {status}'
  }
})

Available placeholders:

Placeholder	Description	Example
{now}	Current timestamp	2025-12-21 10:00:00
{level}	Log level (DEBUG, INFO, WARNING, ERROR)	INFO
{duration}	Request duration (formatted)	12ms, 1.5s
{method}	HTTP method	GET
{pathname}	Request path (alias: {path}); includes query if logQueryParams: true	/users
{query}	Raw query string	?id=123
{status}	Response status code	200
{statusText}	HTTP status text	Not Found
{message}	Custom message	User profile accessed
{icon}	Logixlysia fox 🦊 (level-colored chip when colors + TTY)	🦊
{speed}	Slow-request badge when duration ≥ verySlowThreshold	⚡ slow
{service}	Service prefix from config.service	[my-api]
{context}	Context JSON on main line when tree is off / empty	{"id":1}
{ip}	Client IP address	127.0.0.1
{epoch}	Unix timestamp	1734729600

Log Filtering

Filter logs by level, status, or method:

logixlysia({
  config: {
    logFilter: {
      level: ['ERROR', 'WARNING'],
      status: [500, 404],
      method: 'GET'
    }
  }
})

Pino Integration

Logixlysia is powered by Pino. Access the Pino instance directly:

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!')
})

Errors are automatically logged with stack traces and request details.

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']
        },
        pino: {
          level: 'info',
          redact: ['password', 'token', 'apiKey']
        }
      }
    })
  )
  .listen(3000)

Development Setup

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