🎛️🪵😎 A fun, lightweight, structured console-style logger with tag-based filtering for TypeScript projects.

• Drop-in replacements for console.* methods: debug, info, warn, error, log
• Scoped tagging via log.options({ tag })
• Filters logs using LOG or LOG_VERBOSE environment variables (supports wildcards)
• Runtime log level: log.level = 'warn' or log.setLogLevel('warn') to suppress lower levels (unless LOG/LOG_VERBOSE is set)
• Per-call configuration: timestamps, level formatting, and custom tags
• Wildcard filtering support (e.g. auth:*, metrics*)
• Global setup via log.setup({ ... })
• Designed for Node.js and edge runtimes
• Debug output is always gated: debug logs only appear if LOG/LOG_VERBOSE match, or if log.level is 'debug' and DEBUG=1 is set
• log.level = 'silent' or log.setLogLevel('silent') suppresses all output
• All log filtering logic falls back to LOG/LOG_VERBOSE if set, otherwise uses the runtime log level

pnpm add @variablesoftware/logface

import { log } from "@variablesoftware/logface"; // Basic usage log.debug("Boot sequence initiated"); log.info("App started on port %d", 3000); log.warn("Disk usage at %d%%", 91); log.error("Database connection failed: %s", err.message); // Scoped/tagged logs log.options({ tag: "auth" }).debug("User login event"); log.options({ tag: "metrics", timestamp: true }).info("Memory: %dMB", 182); log.options({ tag: "api", levelShort: false }).warn("Rate limit exceeded"); // Global setup log.setup({ timestamp: true, levelShort: false }); // Runtime log level (NEW) log.level = "warn"; // Only warn, error, and log will be emitted log.setLogLevel("error"); // Only error and log will be emitted log.level = "silent"; // Suppress all output // Restore to default log.level = "debug";

[D][init] Booting... [I][auth] Login successful [L][metrics] 200 OK 

Use log.setup() to enable timestamps or full level names.

Use LOG or LOG_VERBOSE to filter logs by tag or level:

LOG=auth node app.js LOG=metrics,debug,auth* node app.js LOG="!foo;auth,debug" node app.js # Negation: suppress 'foo' unless also matches 'auth' or 'debug'

• Wildcards are supported (e.g. auth:*, metrics*).
• Negation is supported: Prefix a pattern with ! to suppress logs matching that pattern, unless also matched by a positive pattern. Example: LOG="!foo;auth,debug" suppresses logs with tag foo unless they also match auth or debug.
• If neither is set, you can control output at runtime:

log.level = "warn"; // Only warn, error, and log log.level = "silent"; // Suppress all output

Debug logs are only shown if LOG/LOG_VERBOSE match, or if log.level is 'debug' and DEBUG=1 is set in the environment.

For wildcard matching, structured output, test helpers, global setup, and advanced filtering:

➡️ See LOGGING.md for full logging level guidance

MIT © Rob Friedman / Variable Software

Built with ❤️ by @variablesoftware
Thank you for downloading and using this project. Pull requests are warmly welcomed!

• Naming, logging, error messages, and tests avoid cultural or ableist bias
• Avoids assumptions about input/output formats or encodings
• Faithfully reflects user data — no coercion or silent transformations
• Designed for clarity, predictability, and parity with underlying platforms (e.g., Cloudflare APIs)
• Works well in diverse, multilingual, and inclusive developer environments

Logface supports powerful customization via a config file. You can control emoji, color, and more for your log output.

1. Copy the example config:

   cp logface.example.config.js logface.config.js

2. Edit logface.config.js to your liking.

// logface.config.js module.exports = { emojiRandom: true, // Random emoji per log message emojis: { debug: ["🐛", "🔍", "🦠"], info: ["ℹ️", "💡", "🧭"], log: ["📝", "📄", "🗒️"], warn: ["⚠️", "🚧", "🛑"], error: ["🔥", "💥", "💣"], }, colorEnabled: true, // Enable/disable color colorLibrary: "chalk", // 'chalk', 'picocolors', 'colorette', or 'kleur' };

Logface disables emoji and color automatically during tests for stable output. You can also set these manually:

module.exports = { emojiRandom: false, emojis: { debug: "", info: "", log: "", warn: "", error: "" }, colorEnabled: false, };

• emojiRandom: true for random emoji per log, false for fixed.
• emojis: Object mapping log levels to emoji (array or string).
• colorEnabled: Enable/disable color output.
• colorLibrary: Choose color library: 'chalk', 'picocolors', 'colorette', 'kleur'.

• Use .js for CommonJS or ESM (depends on your package.json type).
• Use .mjs for guaranteed ESM.

// logface.config.mjs export default { emojiRandom: true, emojis: { debug: ["🐛", "🔍", "🦠"], info: ["ℹ️", "💡", "🧭"], log: ["📝", "📄", "🗒️"], warn: ["⚠️", "🚧", "🛑"], error: ["🔥", "💥", "💣"], }, colorEnabled: true, colorLibrary: "picocolors", };

• Add logface.config.js to your .gitignore to avoid committing user-specific config.
• See logface.example.config.js for a template.

For more, see LOGGING.md.