Migration Guide

Migrate from Pino, Winston, or console.log to @sylphx/cat.

From Pino

Basic Setup

Pino:

import pino from 'pino'

const logger = pino({
  level: 'info'
})

@sylphx/cat:

import { createLogger } from '@sylphx/cat'

const logger = createLogger({
  level: 'info'
})

Pretty Printing

Pino:

import pino from 'pino'

const logger = pino({
  transport: {
    target: 'pino-pretty',
    options: { colorize: true }
  }
})

@sylphx/cat:

import { createLogger, prettyFormatter } from '@sylphx/cat'

const logger = createLogger({
  formatter: prettyFormatter({ colors: true })
})

Child Loggers

Pino:

const child = logger.child({ requestId: 'req-123' })
child.info('Message')

@sylphx/cat:

const child = logger.child({ requestId: 'req-123' })
child.info('Message')

✅ Same API

Serializers

Pino:

import pino from 'pino'

const logger = pino({
  serializers: {
    err: pino.stdSerializers.err,
    req: pino.stdSerializers.req,
    res: pino.stdSerializers.res
  }
})

@sylphx/cat:

import { createLogger, autoSerializeErrors, requestSerializer } from '@sylphx/cat'

const logger = createLogger({
  plugins: [autoSerializeErrors()]
})

logger.info('Request', {
  req: requestSerializer(req),
  res: responseSerializer(res)
})

Redaction

Pino:

const logger = pino({
  redact: ['password', 'creditCard']
})

@sylphx/cat:

import { redactionPlugin } from '@sylphx/cat'

const logger = createLogger({
  plugins: [
    redactionPlugin({
      fields: ['password', 'creditCard']
    })
  ]
})

From Winston

Basic Setup

Winston:

import winston from 'winston'

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console()
  ]
})

@sylphx/cat:

import { createLogger, jsonFormatter, consoleTransport } from '@sylphx/cat'

const logger = createLogger({
  level: 'info',
  formatter: jsonFormatter(),
  transports: [consoleTransport()]
})

Multiple Transports

Winston:

const logger = winston.createLogger({
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'app.log' })
  ]
})

@sylphx/cat:

import { consoleTransport, fileTransport } from '@sylphx/cat'

const logger = createLogger({
  transports: [
    consoleTransport(),
    fileTransport({ path: 'app.log' })
  ]
})

Custom Format

Winston:

const logger = winston.createLogger({
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  )
})

@sylphx/cat:

import type { Formatter, LogEntry } from '@sylphx/cat'

class CustomFormatter implements Formatter {
  format(entry: LogEntry): string {
    return JSON.stringify({
      timestamp: entry.timestamp,
      level: entry.level,
      message: entry.message,
      ...entry.data
    })
  }
}

const logger = createLogger({
  formatter: new CustomFormatter()
})

Child Loggers

Winston:

const child = logger.child({ requestId: 'req-123' })

@sylphx/cat:

const child = logger.child({ requestId: 'req-123' })

✅ Same API

From console.log

Basic Replacement

console.log:

console.log('User login:', userId)
console.error('Error:', error)

@sylphx/cat:

import { createLogger } from '@sylphx/cat'

const logger = createLogger()

logger.info('User login', { userId })
logger.error('Error', { error })

Structured Logging

console.log:

console.log(`User ${userId} logged in from ${ip}`)

@sylphx/cat:

logger.info('User login', { userId, ip })

Error Handling

console.log:

try {
  // ...
} catch (error) {
  console.error('Error:', error.message)
  console.error('Stack:', error.stack)
}

@sylphx/cat:

import { autoSerializeErrors } from '@sylphx/cat'

const logger = createLogger({
  plugins: [autoSerializeErrors()]
})

try {
  // ...
} catch (error) {
  logger.error('Error', { error }) // Includes message, stack, cause
}

API Mapping

Pino → @sylphx/cat

Pino	@sylphx/cat	Notes
pino()	createLogger()	Basic logger
logger.child()	logger.child()	✅ Same
logger.level = 'debug'	logger.setLevel('debug')	Method call
pino.stdSerializers.err	serializeError()	Function import
redact: ['password']	redactionPlugin({ fields: ['password'] })	Plugin
transport: { target: 'pino-pretty' }	formatter: prettyFormatter()	Built-in

Winston → @sylphx/cat

Winston	@sylphx/cat	Notes
winston.createLogger()	createLogger()	Similar API
new winston.transports.Console()	consoleTransport()	Function call
new winston.transports.File()	fileTransport()	Function call
winston.format.json()	jsonFormatter()	Built-in
winston.format.combine()	Custom formatter	Implement Formatter
logger.child()	logger.child()	✅ Same

Feature Comparison

Feature	Pino	Winston	@sylphx/cat
Child loggers	✅	✅	✅
Custom transports	✅	✅	✅
Redaction	✅	❌	✅
Pretty printing	Via package	Via format	Built-in
OpenTelemetry	Partial	❌	✅ Full
W3C Trace Context	❌	❌	✅
Tail-based sampling	❌	❌	✅
Universal runtime	❌	❌	✅
Bundle size	11 KB	80 KB	8.93 KB

Migration Checklist

1. Install @sylphx/cat

npm install @sylphx/cat
npm uninstall pino # or winston

2. Update Imports

// Before
import pino from 'pino'

// After
import { createLogger } from '@sylphx/cat'

3. Convert Logger Creation

// Before (Pino)
const logger = pino({ level: 'info' })

// After
const logger = createLogger({ level: 'info' })

4. Update Transports

// Before (Winston)
transports: [
  new winston.transports.Console(),
  new winston.transports.File({ filename: 'app.log' })
]

// After
transports: [
  consoleTransport(),
  fileTransport({ path: 'app.log' })
]

5. Convert Serializers to Plugins

// Before (Pino)
serializers: {
  err: pino.stdSerializers.err
}

// After
plugins: [autoSerializeErrors()]

6. Update Redaction

// Before (Pino)
redact: ['password', 'token']

// After
plugins: [
  redactionPlugin({
    fields: ['password', 'token']
  })
]

7. Test Thoroughly

// Verify log output
logger.info('Test', { key: 'value' })

// Verify child loggers
const child = logger.child({ requestId: '123' })
child.info('Test')

// Verify error serialization
logger.error('Error', { error: new Error('Test') })

Breaking Changes

None (Mostly Compatible)

@sylphx/cat is designed for easy migration with minimal breaking changes:

• ✅ Child logger API is identical
• ✅ Log level methods are identical (info, error, etc.)
• ✅ Structured logging works the same way

Minor Differences

1. Formatter instead of format

   // Pino: format
   // @sylphx/cat: formatter

2. Plugins instead of serializers

   // Pino: serializers
   // @sylphx/cat: plugins

3. Function calls instead of classes

   // Winston: new winston.transports.Console()
   // @sylphx/cat: consoleTransport()

See Also

• Getting Started - Quick start
• API Reference - Complete API
• Examples - Real-world examples