DEV Community: Chintan Shah

How to Scan for Hardcoded Secrets in a Node.js Project (GitHub Actions Guide)

Chintan Shah — Fri, 05 Jun 2026 05:46:18 +0000

Hardcoded API keys in source code are one of the most common security mistakes in Node.js projects. Not .env files committed by accident (though that happens too). I mean a Stripe key pasted into a test fixture, a GitHub token left in a debug script, or a PostgreSQL URL sitting in a migration comment.

Secret scanning in GitHub Actions catches these before merge. This guide covers a local scan, a full workflow file you can copy, how it compares to gitleaks and trufflehog, and what to do when you actually find a leaked key.

Takes about 10 minutes to set up.

TL;DR

Goal	What to do
Scan locally before commit	`npx secretguard .`
Block merges with live keys	Add workflow below to GitHub Actions
Scan git history for old leaks	Use gitleaks or trufflehog
Stop pushes at GitHub boundary	Enable push protection (free on public repos)
Avoid noise from test fixtures	Use a scanner that skips fake emails in `*.test.ts`

Why hardcoded secrets in source code are still a problem

.gitignore protects .env. It does not protect src/config.ts.

Common leak locations in Node.js repos:

Test files with copied production tokens
Debug scripts committed to scripts/
Database URLs in ORM config or seed files
Sample API responses checked into fixtures/
Commented-out credentials "just for reference"

GitHub secret scanning and push protection help at the remote. But you often discover the problem when git push fails at 6pm before a release. Scanning in CI on every pull request shifts that feedback to review time.

What to scan for

Credentials (rotate immediately if found)

Cloud keys: AKIA... (AWS), sk_live_... (Stripe), ghp_... (GitHub)
Database URLs with embedded passwords (postgres://user:pass@...)
Private keys: RSA, OpenSSH, PGP blocks
JWTs and high-entropy strings assigned to api_key, API_KEY, secret

PII in source (compliance risk)

Emails, phone numbers, SSNs, credit card numbers in non-test files
Public IPs in config (private ranges like 192.168.x are usually fine to ignore)

.env must stay out of git. Add .env to .gitignore and commit only .env.example with placeholder values.

Scan your Node.js repo locally

No install. Works on any machine with Node 18+.

npx secretguard .

This scans the working tree (current files on disk), not git history. It skips node_modules, .git, dist, build, and binary files automatically. Findings are grouped by severity. Values are masked in output.

Useful variants:

# Scan only application source
npx secretguard ./src

# JSON for scripts or CI artifacts
npx secretguard . --json

# HTML report for security review
npx secretguard . --output report.html

# Extra ignore paths
npx secretguard . --ignore legacy --ignore sandbox

Exit codes: 0 = no CRITICAL findings, 1 = at least one CRITICAL. HIGH and MEDIUM are reported but do not fail by default. That is a practical default: a live Stripe key should block a merge; a JWT-shaped string in a test helper might be worth reviewing without stopping the pipeline.

Secret scanning in GitHub Actions

Below is a complete workflow file. Copy it to .github/workflows/secret-scan.yml.

name: Secret Scan

on:
  pull_request:
    branches: [main, master]
  push:
    branches: [main, master]

permissions:
  contents: read

jobs:
  secret-scan:
    name: Scan for hardcoded secrets
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Scan source for secrets and PII
        run: npx secretguard . --json > secretguard-report.json
        continue-on-error: true
        id: scan

      - name: Upload scan report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: secretguard-report
          path: secretguard-report.json

      - name: Fail on CRITICAL findings
        if: steps.scan.outcome == 'failure'
        run: |
          echo "CRITICAL secrets or PII found. Review the scan report artifact."
          exit 1

Why a separate workflow: Keeps security checks visible in the Actions tab. Teams can require this check in branch protection without coupling it to your test job.

Minimal one-liner if you already have a CI workflow:

- name: Scan for hardcoded secrets
  run: npx secretguard .

No API key or config file required. npx pulls the latest published version from npm.

Avoiding false positives in test files

Scanners that flag every email and phone number fail on real codebases. Test files contain user@example.com and 555-123-4567. That is fixture data, not a production leak.

Three approaches teams use:

Approach	Pros	Cons
Ignore all test directories	Zero noise	Misses real tokens copied into tests
Filter placeholder values	Works in prod files	Misses realistic fake data
Credentials everywhere, PII only in prod paths	Balanced	Slightly more complex

secretguard uses the third approach. PII patterns are skipped in *.test.*, *.spec.*, __tests__/, fixtures/, and mocks/. Placeholders like example.com and US 555- numbers are filtered elsewhere. Credentials are always scanned, including in test files, because a real ghp_ token in a test is still a real leak.

gitleaks vs trufflehog vs a Node.js CI scanner

Tool	Scans git history	Scans working tree	Node.js native	Best for
gitleaks	Yes	Yes (`detect --no-git`)	No (Go binary)	Finding secrets in past commits
trufflehog	Yes	Yes	No	Deep entropy + verified secrets
GitHub secret scanning	On push	No	N/A	Platform-level detection
secretguard	No	Yes	Yes	Fast PR check, credentials + PII

Practical combo many teams use:

gitleaks or trufflehog in CI weekly (or on main) for git history
secretguard on every PR for the current diff's files on disk
GitHub push protection enabled as a last line of defense

Example gitleaks step for comparison:

- name: Gitleaks scan
  uses: gitleaks/gitleaks-action@v2
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

None of these replace a secrets manager (Vault, AWS Secrets Manager, Doppler) or proper .gitignore hygiene.

Enable GitHub push protection (free for public repos)

GitHub can block pushes that contain known secret patterns before they enter the repo.

Go to Repository → Settings → Code security and analysis
Enable Secret scanning (public repos: free)
Enable Push protection

This is reactive at push time. CI scanning on pull requests is proactive at review time. Use both.

Official docs: Working with push protection

What to do when you find a leaked API key

Finding a secret is not enough. You have to assume it is compromised.

Step 1: Remove from code immediately

# Find the file and line from scan output, edit, commit
git add -A && git commit -m "Remove hardcoded API key"

Step 2: Rotate the credential

Stripe: roll the key in Dashboard → Developers → API keys
GitHub: revoke the PAT under Settings → Developer settings
AWS: deactivate the access key in IAM
Database: change the password and update your secrets manager

Step 3: Check git history

If the key was ever committed, removing it from HEAD is not enough. It still exists in old commits. Use gitleaks or git log -S 'sk_live_' to find when it was introduced. You may need git filter-repo or GitHub's secret scanning alert workflow for serious incidents.

Step 4: Enable prevention

Add secret scanning to CI (workflow above)
Add a pre-commit hook locally
Never use production keys in test fixtures; use env vars or mock values

Step 5: Document for your team

Log the incident (without the secret value). Note which key was rotated and when.

Pre-commit secret scan (optional)

Catch leaks before they leave your laptop:

#!/bin/sh
# .git/hooks/pre-commit
npx secretguard . || exit 1

chmod +x .git/hooks/pre-commit

Slower feedback than CI but prevents the push entirely. For teams, consider Husky to share hooks via the repo.

Example scan output

CRITICAL (2)
  src/config.ts:14  Stripe Live Secret Key  sk_live_****7890
  src/db.ts:8       Database URL (PostgreSQL)  postgres://****@host/db

HIGH (1)
  src/auth.ts:22    JWT Token  eyJhbG****In0

Add a screenshot of your own scan before publishing. Use alt text: secretguard terminal output showing masked API key findings.

Programmatic scan in Node.js

Embed scanning in custom tooling:

import { scan, credentialPatterns } from 'secretguard'

const result = await scan('./src', {
  patterns: [...credentialPatterns],
})

const critical = result.findings.filter((f) => f.severity === 'CRITICAL')
if (critical.length > 0) {
  console.error(`Found ${critical.length} critical issues`)
  process.exit(1)
}

FAQ

How do I detect hardcoded API keys in a Node.js project?

Run a secret scanner against your source tree: npx secretguard . locally, or add a GitHub Actions step that runs the same command on every pull request. Complement with gitleaks for git history if keys may exist in old commits.

What is the best secret scanning tool for GitHub Actions?

Depends on scope. gitleaks and trufflehog are strong for git history. For a lightweight check of current files without installing Go/Python tooling, a Node-native CLI like secretguard fits standard JavaScript CI images. Enable GitHub push protection regardless of which scanner you pick.

Does secret scanning replace .gitignore?

No. .gitignore prevents committing .env. Secret scanning catches credentials written directly in .ts, .js, .json, and test files that are supposed to be in the repo.

Should I scan test files?

Yes for credentials. A real GitHub token in auth.test.ts is a real leak. PII scanners should skip or filter test fixtures to avoid false positives from user@example.com.

What exit code should fail CI?

Fail on CRITICAL (live API keys, private keys, database passwords). Report HIGH and MEDIUM without blocking until your team agrees on policy.

Checklist before you merge

[ ] Run npx secretguard . locally once
[ ] Add .github/workflows/secret-scan.yml
[ ] Enable GitHub push protection
[ ] Fix CRITICAL findings and rotate any exposed keys
[ ] Confirm test fixtures use mocks, not production credentials
[ ] Add terminal screenshot to this post before publishing (if on own blog)

winston vs pino in 2026: A Production-Tested Comparison

Chintan Shah — Wed, 27 May 2026 04:55:08 +0000

I ran both winston and pino in production Node.js APIs over the past two years. Both are excellent. Both are well-maintained. Both have millions of weekly downloads. But they're built for different priorities.

This post compares them honestly: benchmarks, features, migration paths, and which one I'd reach for in different scenarios. At the end I'll cover where both fall short — and what I ended up doing about it.

TL;DR

If You...	Pick
Serve 5k+ RPS and care about throughput	pino
Already use winston in production with no real pain	winston (don't migrate for fun)
Need an obscure transport (syslog, raw TCP)	winston
Want a smaller, more focused API	pino
Need JSON logs for log aggregator only	pino
Need custom format combinators	winston

Benchmark: 10,000 Structured Logs

Same workload. JSON output to stdout. Structured metadata. Node 22.

Logger	Time (ms)	Memory (MB)	Bundle (gzipped)
pino	31	17	8 KB
winston	58	22	32 KB

pino is roughly 1.9x faster than winston on this machine (Node 22, Apple M-series, stdout redirected to /dev/null). Not new information but worth seeing real numbers rather than theoretical ones.

Benchmark code is at the bottom of this post.

When This Matters

If your API serves under 1k RPS, the difference is invisible to your users. Your bottleneck is your database, your downstream services, or your business logic. Not log serialization.

If your API serves 10k+ RPS or runs on small instances where every CPU cycle matters, pick pino.

Feature Comparison

Log Levels & Namespaces

Feature	winston	pino
Standard levels	Yes	Yes
Custom levels	Yes	Yes
Namespaced child loggers	Yes	Yes

Roughly equal. Neither is meaningfully easier.

PII Redaction

winston:

import winston from 'winston'
import { format } from 'winston'

const log = winston.createLogger({
  format: format.combine(
    format((info) => {
      delete info.password
      delete info.token
      return info
    })(),
    format.json()
  )
})

Field deletion via custom format. No path syntax. No pattern detection. The winston-redact plugin exists but is barely maintained as of 2026.

pino:

import pino from 'pino'

const log = pino({
  redact: {
    paths: ['password', 'token', 'user.email', 'user.*.email'],
    censor: '[REDACTED]'
  }
})

Cleaner. Path syntax with wildcards. Still no pattern detection (emails, SSNs, credit cards in free-form strings will leak through).

Winner: pino, by a clean API margin. Neither does automatic PII pattern detection.

Transports & Integrations

Destination	winston	pino
Console	Built-in	Built-in
File (with rotation)	winston-daily-rotate-file	pino-roll
Sentry	winston-sentry	pino-sentry
Datadog	winston-datadog	pino-datadog
Elasticsearch	winston-elasticsearch	pino-elasticsearch
CloudWatch	winston-cloudwatch	pino-cloudwatch-transport
Loki	community	pino-loki
Splunk	winston-splunk	pino-splunk
OpenTelemetry	winston-opentelemetry	pino-opentelemetry-transport

Both have most integrations. winston's ecosystem is larger but more fragmented (several popular plugins are unmaintained as of 2026). pino's ecosystem is smaller but more consistently maintained.

If you check the GitHub commit dates on plugins before installing, you'll quickly see what I mean.

TypeScript Support

Both work fine. pino's type inference is slightly nicer in 2026. winston's types are correct but verbose.

Browser Support

winston: Plugin-based (winston-browser), limited
pino: Node-only by design

Neither is great if you want the same logger in your frontend and backend. If that matters to you, neither of these is your answer (look at consola, loglevel, or other browser-focused options).

Backpressure & Reliability

winston:

Uses Node streams for transports
Built-in retry support varies by transport
No first-class circuit breaker

pino:

Uses worker threads (in pino.transport() mode) to move serialization off the main loop
Async transport by default, drops logs gracefully under backpressure
No first-class circuit breaker either

Winner: pino. The worker-thread architecture is a real engineering advantage when your log destination has hiccups.

When To Use Which

Use winston if:

You already use it in production. Migration cost is real and rarely worth it.
You need a transport that only winston has (winston-syslog is one example).
Your team has years of winston tribal knowledge.
You need flexible custom format chains.

Use pino if:

You're optimizing every CPU cycle.
You're okay with JSON-only output (typical for production).
You want a smaller, more focused API surface.
You're starting a new Node.js project today.

For new projects in 2026, pino is the safer default. It's faster, more focused, and the ecosystem is healthier.

Migration: winston → pino

The most common migration path. Takes 1-2 hours for a typical app.

// Before
import winston from 'winston'
const log = winston.createLogger({
  format: winston.format.json(),
  defaultMeta: { service: 'api' },
  transports: [new winston.transports.Console()]
})

log.info('User login', { userId: 123 })
log.error('Failed', err)

// After
import pino from 'pino'
const log = pino({
  base: { service: 'api' }
})

log.info({ userId: 123 }, 'User login')  // note: payload first
log.error({ err }, 'Failed')              // errors go in object

The Three Things That Trip People Up

Argument order swaps. winston: log.info(message, payload). pino: log.info(payload, message). A regex find-replace handles 80% of it.
Errors aren't first-class. winston accepts log.error(err). pino prefers log.error({ err }, 'description') because it serializes errors via the errorSerializer. Set up serializers early.
No pretty output in production. pino's default is JSON to stdout, no colors. In development, pipe through pino-pretty. In production, ship raw JSON to your aggregator.

Migration: pino → winston (Rare)

Almost no one does this. If you're considering it, you probably want:

More flexible custom format chains (winston's format.combine is genuinely nice)
A specific transport only winston has

Otherwise, stay on pino.

What's Missing From Both

Honest critique of both libraries:

Neither does automatic PII pattern detection. You write the regex or you use a plugin. In 2026 with GDPR, HIPAA, and PCI-DSS audits everywhere, this feels like a real gap. Path-based redaction (paths: ['user.email']) misses emails that slip into free-form message strings.
Neither has a built-in circuit breaker. If your log destination (Datadog, Elasticsearch) goes down, your app's transport queue grows until something bad happens. I've seen this OOM a production pod. You bolt the fix on yourself.
Neither has a great browser story. If your frontend and backend should share a logging abstraction, you're picking between two Node-first tools.

I ran into all three of these hard enough that I eventually built a logger to address them — logfx. It's newer than both and I'm not claiming it competes on adoption. But if any of these gaps resonate, it might be worth a look. I'll write up the full story in a follow-up post.

Conclusion

For most teams in 2026, pino is the right answer. Faster, well-maintained, focused API, healthy ecosystem.

winston is fine if you already use it. Don't migrate for fun. Migrations have real costs.

The "best logger" depends on what you're optimizing for. Hopefully this comparison made the tradeoffs clear.

Appendix: Benchmark Code

import { performance } from 'node:perf_hooks'
import winston from 'winston'
import pino from 'pino'

const ITERATIONS = 10_000
const PAYLOAD = {
  userId: 123,
  email: 'user@example.com',
  action: 'login',
  metadata: { ip: '1.2.3.4', userAgent: 'curl/8.0' }
}

const winstonLog = winston.createLogger({
  format: winston.format.json(),
  transports: [new winston.transports.Console()]
})

const pinoLog = pino()

function bench(name, fn) {
  global.gc?.()
  const memBefore = process.memoryUsage().heapUsed
  const start = performance.now()
  for (let i = 0; i < ITERATIONS; i++) fn()
  const elapsed = performance.now() - start
  const memAfter = process.memoryUsage().heapUsed
  console.log(`${name}: ${elapsed.toFixed(0)}ms, ${((memAfter - memBefore) / 1024 / 1024).toFixed(1)}MB`)
}

bench('winston', () => winstonLog.info('User login', PAYLOAD))
bench('pino', () => pinoLog.info(PAYLOAD, 'User login'))

Run with: node --expose-gc benchmark.js > /dev/null

(stdout redirected because we're measuring the logger, not the terminal.)

Got a strong opinion on winston vs pino? Drop a comment — genuinely curious what's driving people's choices in 2026. And if the gaps I mentioned above resonate, I'll link the follow-up post here when it's up.

logfx v1.0.0: One Logger for Development and Production

Chintan Shah — Wed, 27 May 2026 04:26:06 +0000

Today I'm shipping logfx v1.0.0. It's the first release I consider production-ready: 13 official integrations, PII redaction, retry and circuit breaker in the webhook transport, and zero dependencies. Same API in Node and browser.

Every logger forces a choice: readable output for development, or structured JSON for production. You either configure both manually or pick one and live with it. logfx v1.0.0 removes that choice. Same logger, auto-detected format based on NODE_ENV.

I've been maintaining logfx since v0.3.0.

The Problem

In development, you want logs you can read. Colors, emojis, clear structure. When something breaks at 2am, you need to scan output quickly.

In production, you need structured JSON. Datadog, Elasticsearch, Splunk, and every log aggregator expect JSON. Timestamps, levels, correlation IDs. Machine-readable.

Most loggers make you configure two setups or accept one format everywhere. logfx switches automatically.

The other pain point: logging user data. Emails, tokens, passwords. One slip and you're leaking PII. logfx handles that with built-in redaction and custom patterns.

The third: sending logs to a remote endpoint. Networks fail. Retries, circuit breakers, dead letter queues. You either build it or hope your logs get through. logfx ships it.

import { createLogger } from 'logfx'

const log = createLogger()

log.info('Server started', { port: 3000 })

Development output:

💡 INFO  Server started { port: 3000 }

Production output (NODE_ENV=production):

{"timestamp":"2026-01-14T12:00:00.000Z","level":"info","message":"Server started","data":{"port":3000}}

No format flag. No environment checks in your code. It just works.

What logfx Actually Does

Core Logging

Five levels (debug, info, success, warn, error), namespaced loggers, context metadata. Errors serialize with stack traces. Lazy evaluation so you can defer expensive operations until they're actually logged. Same API whether you're in Node, Bun, Deno, or the browser.

const authLog = createLogger({ namespace: 'auth' })
authLog.info('Login attempt', { userId: 123 })
// 💡 INFO [auth] Login attempt { userId: 123 }

Attach metadata to every log from a logger:

const log = createLogger({
  context: { service: 'api', version: '1.0.0' }
})
log.info('Request received', { path: '/users' })
// Every entry includes service and version

W3C TraceParent format is supported for correlating logs across services.

PII Redaction

Logging user data is risky. Emails, SSNs, credit cards, JWTs can leak. logfx has built-in patterns and key-based redaction:

const log = createLogger({
  redact: {
    keys: ['password', 'token', 'apiKey'],
    patterns: ['email', 'ssn', 'creditCard', 'phone', 'ip', 'jwt'],
    customPatterns: [
      { name: 'apiKey', regex: /sk_(live|test)_[a-zA-Z0-9]+/g }
    ]
  },
  transports: [transports.console({ format: 'json' })]
})

log.info('User signup', { email: 'user@example.com', password: 'secret' })
// {"email":"[REDACTED]","password":"[REDACTED]",...}

You can add custom patterns or masking functions. Useful when you need partial redaction for debugging (e.g. last 4 digits of a card).

Production Reliability (Webhook Transport)

When you send logs to a remote endpoint, networks fail. Timeouts, 5xxs, rate limits. logfx's webhook transport handles that:

Retry - Exponential backoff with jitter. Configurable max retries and delay.
Circuit breaker - Stops sending after N failures, reopens after a timeout.
Dead letter queue - Failed logs go to an in-memory queue. Optionally persist to disk.
Multi-region failover - Multiple URLs with round-robin or priority. Optional health checks.

You get this without writing retry logic or circuit breaker code. It's built in.

Framework Middleware

Express, Fastify, and Next.js integrations give you req.log and request IDs:

import express from 'express'
import { expressLogger } from 'logfx/middleware'

const app = express()
app.use(expressLogger())

app.get('/users', (req, res) => {
  req.log.info('Fetching users', { userId: req.query.id })
  res.json({ users: [] })
})

Output:

💡 INFO [http] Incoming request { method: 'GET', path: '/users', requestId: 'abc123' }
💡 INFO [http] Fetching users { userId: '42' }
💡 INFO [http] Request completed { method: 'GET', path: '/users', status: 200, durationMs: 45 }

Each request gets a unique ID. Status codes set log level (5xx = error, 4xx = warn). Skip health checks or customize ID extraction. The middleware works with Express, Fastify, and Next.js API routes.

13 Integrations

Separate packages for each platform. Install only what you need:

npm install logfx logfx-datadog
# or logfx-elasticsearch, logfx-sentry, logfx-cloudwatch, etc.

import { createLogger } from 'logfx'
import { datadogTransport } from 'logfx-datadog'

const log = createLogger({
  transports: [
    datadogTransport({
      apiKey: process.env.DD_API_KEY,
      service: 'my-api',
      batchSize: 100,
      flushInterval: 5000
    })
  ]
})

Available integrations: Datadog, Elasticsearch, Sentry, OpenTelemetry, AWS CloudWatch, Google Cloud Logging, Azure Monitor, Slack, Grafana Loki, Papertrail, Splunk, Honeycomb, Logtail. Each uses the same Transport interface. Add console, file, or webhook in the same array.

No monolith. Install only what you need. Each integration is a separate package.

File Transport with Rotation

Write to disk with size-based rotation and compression:

transports.file({
  path: './logs/app.log',
  rotation: {
    maxSize: '10mb',
    maxFiles: 5,
    compress: true
  }
})

Creates app.log.1, app.log.2, etc. Old files are gzipped. Prevents disk from filling up.

Browser Support

Same API in Node and browser. For SPAs, the Beacon transport sends logs reliably even when the user closes the tab:

transports.beacon({
  url: '/api/logs',
  events: { beforeunload: true, visibilitychange: true }
})

Uses the Beacon API. Falls back to fetch if unavailable. Non-blocking so it doesn't delay page unload. Useful for analytics, error reporting, or session replay when the user navigates away.

Log Sampling

For high traffic, reduce volume while keeping visibility:

const log = createLogger({
  sampling: {
    debug: 0.1,
    info: 0.5,
    warn: 1.0,
    error: 1.0
  }
})

Sample 10% of debug, 50% of info. Always log warnings and errors.

When It Helps

Node.js APIs - Express/Fastify/Next.js middleware, structured JSON to Datadog/Elasticsearch, request tracing
SPAs - Beacon transport for analytics or error reporting on page close
Microservices - Context and request IDs for correlating logs across services
Sensitive data - PII redaction before logs hit aggregation
High volume - Async buffering, sampling, circuit breaker when the log sink is down

What's in the Box

Zero dependencies on the core package
~3KB gzipped
ESM and CJS
Full TypeScript support
CI: tests, typecheck, build on Node 18, 20, 22, 24
Stress tested: 10k logs in under 1s, 1k with redaction in under 500ms

What It Doesn't Do

It's a logger, not a full observability platform. No distributed tracing (though OpenTelemetry integration injects trace IDs). No metrics. No APM. It logs. That's the scope.

Try It

npm install logfx

import { log } from 'logfx'

log.info('Hello', { version: '1.0.0' })
log.error('Something failed', new Error('oops'))

Links:

If you're on logfx 0.5.x, v1.0.0 adds integrations, PII redaction improvements, and production hardening. The core API is compatible. Upgrade and add what you need.

Wrapping Up

One logger for dev and prod. No format switching. No config. 13 integrations when you need them. PII redaction and production reliability built in.

I also maintain handlejson (GitHub) for safe JSON parsing, envconfig-kit (GitHub) for env validation, and upstatus (GitHub) for uptime monitoring. All focused Node/TS packages.

What logging setup are you using? Would love to hear what works (or doesn't) for you.

logfx v1.0.0: One Logger for Development and Production (TS, Zero deps, 13 integrations)

Chintan Shah — Thu, 05 Mar 2026 00:35:18 +0000

I've been maintaining logfx since v0.3.0.

The Problem

In development, you want logs you can read. Colors, emojis, clear structure. When something breaks at 2am, you need to scan output quickly.

In production, you need structured JSON. Datadog, Elasticsearch, Splunk, and every log aggregator expect JSON. Timestamps, levels, correlation IDs. Machine-readable.

Most loggers make you configure two setups or accept one format everywhere. logfx switches automatically.

The other pain point: logging user data. Emails, tokens, passwords. One slip and you're leaking PII. logfx handles that with built-in redaction and custom patterns.

The third: sending logs to a remote endpoint. Networks fail. Retries, circuit breakers, dead letter queues. You either build it or hope your logs get through. logfx ships it.

import { createLogger } from 'logfx'

const log = createLogger()

log.info('Server started', { port: 3000 })

Development output:

💡 INFO  Server started { port: 3000 }

Production output (NODE_ENV=production):

{"timestamp":"2026-01-14T12:00:00.000Z","level":"info","message":"Server started","data":{"port":3000}}

No format flag. No environment checks in your code. It just works.

What logfx Actually Does

Core Logging

const authLog = createLogger({ namespace: 'auth' })
authLog.info('Login attempt', { userId: 123 })
// 💡 INFO [auth] Login attempt { userId: 123 }

Attach metadata to every log from a logger:

const log = createLogger({
  context: { service: 'api', version: '1.0.0' }
})
log.info('Request received', { path: '/users' })
// Every entry includes service and version

W3C TraceParent format is supported for correlating logs across services.

PII Redaction

Logging user data is risky. Emails, SSNs, credit cards, JWTs can leak. logfx has built-in patterns and key-based redaction:

const log = createLogger({
  redact: {
    keys: ['password', 'token', 'apiKey'],
    patterns: ['email', 'ssn', 'creditCard', 'phone', 'ip', 'jwt'],
    customPatterns: [
      { name: 'apiKey', regex: /sk_(live|test)_[a-zA-Z0-9]+/g }
    ]
  },
  transports: [transports.console({ format: 'json' })]
})

log.info('User signup', { email: 'user@example.com', password: 'secret' })
// {"email":"[REDACTED]","password":"[REDACTED]",...}

You can add custom patterns or masking functions. Useful when you need partial redaction for debugging (e.g. last 4 digits of a card).

Production Reliability (Webhook Transport)

When you send logs to a remote endpoint, networks fail. Timeouts, 5xxs, rate limits. logfx's webhook transport handles that:

Retry - Exponential backoff with jitter. Configurable max retries and delay.
Circuit breaker - Stops sending after N failures, reopens after a timeout.
Dead letter queue - Failed logs go to an in-memory queue. Optionally persist to disk.
Multi-region failover - Multiple URLs with round-robin or priority. Optional health checks.

You get this without writing retry logic or circuit breaker code. It's built in.

Framework Middleware

Express, Fastify, and Next.js integrations give you req.log and request IDs:

import express from 'express'
import { expressLogger } from 'logfx/middleware'

const app = express()
app.use(expressLogger())

app.get('/users', (req, res) => {
  req.log.info('Fetching users', { userId: req.query.id })
  res.json({ users: [] })
})

Output:

💡 INFO [http] Incoming request { method: 'GET', path: '/users', requestId: 'abc123' }
💡 INFO [http] Fetching users { userId: '42' }
💡 INFO [http] Request completed { method: 'GET', path: '/users', status: 200, durationMs: 45 }

Each request gets a unique ID. Status codes set log level (5xx = error, 4xx = warn). Skip health checks or customize ID extraction. The middleware works with Express, Fastify, and Next.js API routes.

13 Integrations

Separate packages for each platform. Install only what you need:

npm install logfx logfx-datadog
# or logfx-elasticsearch, logfx-sentry, logfx-cloudwatch, etc.

import { createLogger } from 'logfx'
import { datadogTransport } from 'logfx-datadog'

const log = createLogger({
  transports: [
    datadogTransport({
      apiKey: process.env.DD_API_KEY,
      service: 'my-api',
      batchSize: 100,
      flushInterval: 5000
    })
  ]
})

Integrations by category:

Category	Package	Use case
APM / Observability	logfx-datadog, logfx-elasticsearch, logfx-sentry, logfx-otel	Datadog, Elasticsearch, Sentry, OpenTelemetry
Cloud	logfx-cloudwatch, logfx-google-cloud, logfx-azure	AWS, GCP, Azure logs
Alerts / SIEM	logfx-slack, logfx-loki, logfx-papertrail, logfx-splunk	Slack alerts, Grafana Loki, Papertrail, Splunk
Analytics	logfx-honeycomb, logfx-logtail	Honeycomb, Logtail (Better Stack)

Each uses the same Transport interface. Add console, file, or webhook in the same array. No monolith. Install only what you need.

File Transport with Rotation

Write to disk with size-based rotation and compression:

transports.file({
  path: './logs/app.log',
  rotation: {
    maxSize: '10mb',
    maxFiles: 5,
    compress: true
  }
})

Creates app.log.1, app.log.2, etc. Old files are gzipped. Prevents disk from filling up.

Browser Support

Same API in Node and browser. For SPAs, the Beacon transport sends logs reliably even when the user closes the tab:

transports.beacon({
  url: '/api/logs',
  events: { beforeunload: true, visibilitychange: true }
})

Uses the Beacon API. Falls back to fetch if unavailable. Non-blocking so it doesn't delay page unload. Useful for analytics, error reporting, or session replay when the user navigates away.

Log Sampling

For high traffic, reduce volume while keeping visibility:

const log = createLogger({
  sampling: {
    debug: 0.1,
    info: 0.5,
    warn: 1.0,
    error: 1.0
  }
})

Sample 10% of debug, 50% of info. Always log warnings and errors.

When It Helps

Node.js APIs - Express/Fastify/Next.js middleware, structured JSON to Datadog/Elasticsearch, request tracing
SPAs - Beacon transport for analytics or error reporting on page close
Microservices - Context and request IDs for correlating logs across services
Sensitive data - PII redaction before logs hit aggregation
High volume - Async buffering, sampling, circuit breaker when the log sink is down

What's in the Box

Zero dependencies on the core package
~3KB gzipped
ESM and CJS
Full TypeScript support
CI: tests, typecheck, build on Node 18, 20, 22, 24
Stress tested: 10k logs in under 1s, 1k with redaction in under 500ms

What It Doesn't Do

It's a logger, not a full observability platform. No distributed tracing (though OpenTelemetry integration injects trace IDs). No metrics. No APM. It logs. That's the scope.

Try It

npm install logfx

import { log } from 'logfx'

log.info('Hello', { version: '1.0.0' })
log.error('Something failed', new Error('oops'))

Links:

If you're on logfx 0.5.x, v1.0.0 adds integrations, PII redaction improvements, and production hardening. The core API is compatible. Upgrade and add what you need.

Wrapping Up

One logger for dev and prod. No format switching. No config. 13 integrations when you need them. PII redaction and production reliability built in.

I also maintain handlejson (GitHub) for safe JSON parsing, envconfig-kit (GitHub) for env validation, and upstatus (GitHub) for uptime monitoring. All focused Node/TS packages.

What logging setup are you using? Would love to hear what works (or doesn't) for you.

Safe JSON Parsing in Node.js Without try/catch (2026 Guide)

Chintan Shah — Fri, 30 Jan 2026 06:11:04 +0000

JSON.parse throws on invalid input. That is by design. The problem is not parsing itself. It is copying the same try/catch block across every API response, config file, cache read, and user input handler in your codebase.

This guide covers practical patterns for safe JSON parsing in Node.js without try/catch spam: a small DIY wrapper, default-value parsing, security hardening for untrusted input, and when you should still let errors throw.

TL;DR

Situation	Approach
Quick null fallback	DIY `safeParse` or `parse(str)`
Always need an object/array	`parse(str, { default: {} })`
Untrusted user/API input	`maxSize`, `maxDepth`, `safeKeys`
Debugging malformed JSON	`parseWithDetails` or `tryParse`
Large files (>100MB)	Stream parsing
You need the exact `SyntaxError`	Keep try/catch

The problem with JSON.parse

Every Node.js developer has written this:

let data
try {
  data = JSON.parse(str)
} catch {
  data = null
}

It works. It is also repetitive. API handlers, Redis cache reads, localStorage wrappers, webhook parsers, and config loaders all end up with the same five lines.

JSON.parse also returns any unless you add your own typing. Invalid JSON throws. Valid JSON with dangerous keys (__proto__) can still cause prototype pollution if you merge objects blindly.

Pattern 1: Minimal safe parse (DIY)

For a one-off script, a tiny helper is enough:

function safeParse<T = unknown>(input: string): T | null {
  try {
    return JSON.parse(input) as T
  } catch {
    return null
  }
}

const user = safeParse<{ name: string }>(responseText)
if (!user) {
  // handle invalid JSON
}

Pros: Zero dependencies, obvious behavior

Cons: No size limits, no prototype pollution guard, no error position, copy-paste across files

This pattern is fine for internal tools. It gets painful in production codebases with dozens of parse sites.

Pattern 2: Parse with defaults

When invalid JSON should not crash the flow but you still need a concrete fallback:

import { parse } from 'handlejson'

const config = parse(fileContents, { default: {} })
// {} if invalid — never throws

const user = parse(apiBody, { default: null })
// null if invalid

Same idea as the DIY wrapper, but consistent API across the project and TypeScript inference:

type User = { name: string; age: number }
const user = parse<User>(raw)
// User | null

Pattern 3: Untrusted input (security)

Parsing JSON from users, webhooks, or third-party APIs needs more than null fallbacks.

Three real attack vectors:

Option	Blocks
`maxSize`	Huge payloads that exhaust memory
`maxDepth`	Deeply nested JSON that blows the stack
`safeKeys`	Prototype pollution via `__proto__`, `constructor`, `prototype`

import { parse } from 'handlejson'

const userData = parse(untrustedInput, {
  maxSize: 10 * 1024 * 1024,
  maxDepth: 100,
  safeKeys: true,
})

Native JSON.parse does none of this. You can build it yourself, but most teams skip it until security review asks why it is missing.

Pattern 4: Know where parsing failed

null on error is clean for production paths. Debugging is easier with position and context:

import { parseWithDetails } from 'handlejson'

const result = parseWithDetails('{"name":"John", invalid}')
if (!result.success) {
  console.log(result.position)  // 18
  console.log(result.context)   // surrounding text
  console.log(result.error)     // detailed message
}

Tuple style if you prefer Go-like errors:

import { tryParse } from 'handlejson'

const [data, error] = tryParse(raw)
if (error) {
  console.log(error.message)
}

Use this in development, admin tools, or import pipelines where someone needs to fix the file.

Pattern 5: Validate shape without Zod

When you need basic type checks but do not want a 300KB schema library:

import { parse, tryValidate } from 'handlejson'

const schema = {
  name: 'string',
  age: '?number',
  email: '?string',
}

const data = parse(apiResponse, { schema })
// null if JSON is invalid OR schema fails

const [valid, error] = tryValidate(parsed, schema)
if (!valid) {
  console.log(error.path)       // 'age'
  console.log(error.expected)   // 'number'
  console.log(error.actual)     // 'string'
}

Good for API response guards and config files. Not a replacement for Zod when you need complex refinements.

Pattern 6: Large JSON files

JSON.parse loads the entire string into memory. For large exports or log dumps, stream in chunks:

import { createReadStream } from 'fs'
import { parseStream } from 'handlejson'

const stream = createReadStream('./large-export.json')
const result = await parseStream(stream, {
  onProgress: (parsed) => console.log('chunk parsed'),
})

If the file is under ~50MB and memory is not tight, plain parse is simpler.

Real-world examples

Fetch API response:

const response = await fetch('/api/user')
const user = parse(await response.text(), { default: {} })

Browser localStorage:

const saved = parse(localStorage.getItem('prefs'), { default: null })

Webhook with security limits:

const event = parse(req.body, {
  maxSize: 1024 * 1024,
  maxDepth: 50,
  safeKeys: true,
  default: null,
})

When try/catch is still the right choice

Do not eliminate throwing everywhere.

You need the native SyntaxError type for a library API
Invalid JSON is exceptional and should halt a batch job immediately
You are writing a JSON linter or code editor and must surface exact token errors to users
A framework expects thrown errors from parsers

For application glue code (APIs, config, cache), null-or-default parsing is usually clearer.

Performance

handlejson adds a thin wrapper over native parse. Rough numbers on small JSON (<1KB):

Approach	Throughput
Native `JSON.parse`	~6M ops/s
handlejson `parse`	~5.2M ops/s
With security options	~3.4M ops/s

For most HTTP APIs and background jobs, that gap is invisible. Profile before optimizing.

Comparison at a glance

Approach	Deps	Throws	Security opts	Error position
Native `JSON.parse`	0	Yes	No	Vague
DIY `safeParse`	0	No	No	No
handlejson	0	No	Yes	Yes
Zod + parse	1+	On schema fail	Via custom code	Via Zod

FAQ

How do I parse JSON safely in Node.js without try/catch?

Wrap JSON.parse in a helper that returns null on failure, or use a library like handlejson that does this with parse(str) and optional { default: value }.

What is prototype pollution in JSON.parse?

If parsed JSON contains keys like __proto__ and you merge objects unsafely, attacker-controlled data can pollute Object.prototype. Use safeKeys: true or sanitize keys before merge.

Is JSON.parse slow?

No. It is among the fastest options. Wrappers add small overhead. Security checks add more. The tradeoff is safety and ergonomics, not raw speed.

Should I use Zod or a safe parse wrapper?

Different jobs. Safe parse handles invalid JSON strings. Zod validates shape after parsing. Many teams use both: safe parse first, Zod for complex schemas.

handlejson (zero-dependency option)

If you want the patterns above in one package:

npm install handlejson

import { parse, stringify, parseWithDetails, tryValidate, parseStream } from 'handlejson'

const data = parse('{"name":"John"}')
const json = stringify({ name: 'John' })

Zero dependencies, ~1.5KB gzipped
TypeScript-first
npm | GitHub | Docs

Checklist

[ ] Replace repeated try/catch blocks with one shared parse helper
[ ] Add default fallbacks for non-critical paths (cache, optional config)
[ ] Enable safeKeys + maxSize for external input
[ ] Use parseWithDetails only in debug/admin paths
[ ] Keep native JSON.parse where throwing is the correct API contract

If you have a pattern that worked well in a high-traffic API, share it in the comments.

About handlejson (project background)

I built handlejson after one too many projects where every API response, localStorage read, and config file needed the same try/catch around JSON.parse. Existing options were either heavy, missing security features, or pulled in dependencies I did not want.

v1.0.0 (January 2026) is production-ready: 244 tests, zero dependencies, ~1.5KB gzipped, CI on Node 18/20/22.

Since v0.2.0:

tryValidate() with path, expected, and actual on failure
Optional schema fields ('?number')
Array item validation
Stream parsing for large files
Faster sanitizeKeys (only copies objects when dangerous keys exist)
~5.2M ops/s on small JSON (vs ~6M native)

Full launch write-up archived in the repo: seo-content/handlejson/post-1-original-v1-launch-archive.md

Earlier background: introducing handlejson (v0.2.0)

5 Ways to Validate Environment Variables in Node.js and TypeScript (2026)

Chintan Shah — Mon, 26 Jan 2026 05:24:20 +0000

process.env values are always strings. PORT is "3000", not 3000. DEBUG=false is the string "false", which is truthy in JavaScript. A missing DATABASE_URL does not stop your app from starting. It fails three hours later when a user hits the broken code path.

Validating environment variables at startup is the fix. Your app should refuse to boot with bad config, not limp into production and crash at 2am.

Here are the five main approaches teams use in 2026, with code you can copy today.

TL;DR

Approach	Best for
1. Manual checks	Scripts, prototypes
2. dotenv + manual casting	Small apps already on dotenv
3. Zod schema	Apps already using Zod everywhere
4. t3-env	T3 / Next.js stacks
5. envconfig-kit	Zero-dep, built-in `.env`, actionable errors

Why validate at startup?

Common production failures:

ALLOWED_ORIGINS unset → CORS crash on first real request
STRIPE_SECRET_KEY with trailing whitespace → auth errors for hours
ENABLE_CACHING=false as a string → if (config.ENABLE_CACHING) is truthy

Health checks pass. Deploy succeeds. Users hit the bug later.

Fail fast: validate once when the process boots. Crash with a clear message during deploy, not during peak traffic.

For the story behind this, see Make your app crash at startup, not in production.

Way 1: Manual validation

The baseline. No dependencies. Works everywhere.

function loadConfig() {
  const port = Number(process.env.PORT ?? '3000')
  if (Number.isNaN(port)) {
    throw new Error('PORT must be a number')
  }

  const databaseUrl = process.env.DATABASE_URL
  if (!databaseUrl) {
    throw new Error('DATABASE_URL is required')
  }

  const debug = process.env.DEBUG === 'true'

  return { port, databaseUrl, debug }
}

export const config = loadConfig()

Pros: Obvious, zero deps, full control

Cons: Grows messy at 15+ variables, no shared types, easy to forget new vars, boolean parsing bugs repeat everywhere

Fine for CLIs and throwaway services. Painful in APIs with dozens of env vars.

Way 2: dotenv + manual casting

Add dotenv to load .env in development:

import 'dotenv/config'

const port = parseInt(process.env.PORT ?? '3000', 10)
const apiKey = process.env.API_KEY
if (!apiKey) throw new Error('Missing API_KEY')

const enableCache = process.env.ENABLE_CACHING === 'true'

Pros: Standard .env workflow, tiny dependency

Cons: Still manual validation per variable, no URL/email/port validators, secrets can leak into error logs, TypeScript types are manual

Most Node tutorials stop here. Most production incidents start here too.

Way 3: Zod + dotenv

If Zod is already in your stack for API validation, extend it to env:

import { z } from 'zod'
import 'dotenv/config'

const envSchema = z.object({
  PORT: z.coerce.number().default(3000),
  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
  DEBUG: z.coerce.boolean().default(false),
})

export const config = envSchema.parse(process.env)

Pros: Powerful refinements, great TypeScript inference, familiar if you use Zod for requests

Cons: Zod adds bundle weight (~50KB+ minified depending on usage), separate dotenv setup, error messages aimed at developers not ops, no built-in secret masking in errors

Also consider: envalid if you want env-specific validators (port(), url()) without writing Zod coercions yourself:

import { cleanEnv, str, port, bool, url } from 'envalid'

export const config = cleanEnv(process.env, {
  PORT: port({ default: 3000 }),
  DATABASE_URL: url(),
  API_KEY: str(),
  DEBUG: bool({ default: false }),
})

Way 4: t3-env

Popular in Next.js / T3 stacks. Splits server and client env with compile-time safety:

import { createEnv } from '@t3-oss/env-nextjs'
import { z } from 'zod'

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    API_KEY: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_APP_URL: z.string().url(),
  },
  runtimeEnv: {
    DATABASE_URL: process.env.DATABASE_URL,
    API_KEY: process.env.API_KEY,
    NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  },
})

Pros: Client/server split prevents leaking secrets to the browser, well documented in T3 community

Cons: Requires Zod or Valibot, framework-oriented, runtimeEnv boilerplate, overkill for a plain Express API

Pick this if you are already on the T3 stack. Skip it for a standalone Node service.

Way 5: envconfig-kit

Zero-dependency validation with built-in .env loading and startup errors that tell you how to fix the problem:

import { env } from 'envconfig-kit'

export const config = env({
  PORT: { type: 'port', default: 3000 },
  NODE_ENV: {
    type: 'enum',
    values: ['development', 'staging', 'production'] as const,
    default: 'development',
  },
  DATABASE_URL: { type: 'url' },
  API_KEY: { type: 'string', secret: true },
  DEBUG: { type: 'boolean', default: false },
  ALLOWED_HOSTS: { type: 'array' },
  FEATURE_FLAGS: { type: 'json' },
  ADMIN_EMAIL: { type: 'email', optional: true },
})

No dotenv import. Loads .env, .env.local, and .env.${NODE_ENV} automatically. Priority: process.env → .env.local → .env.${NODE_ENV} → .env.

On failure:

❌ Environment validation failed:

  API_KEY: Missing required environment variable
  ➜ Fix: Add to .env file
    Example: API_KEY=your-value-here

  STRIPE_SECRET_KEY: Value contains leading/trailing whitespace
  ➜ Fix: Remove extra spaces

Pros: ~3KB gzipped, zero dependencies, secret masking (secret: true → **** in errors), presets for database/redis/auth, CLI (check, generate, doctor)

Cons: Smaller ecosystem than Zod, not tied to React/Next client env split

Real-world API config with presets:

import { env, presets } from 'envconfig-kit'

export const config = env({
  ...presets.server(),
  ...presets.database(),
  ...presets.redis(),
  ...presets.auth(),
  ...presets.cors(),
  ...presets.aws(),
  ...presets.smtp(),
  STRIPE_KEY: { type: 'string', secret: true },
  FEATURE_MODE: {
    type: 'enum',
    values: ['basic', 'premium', 'enterprise'] as const,
    default: 'basic',
  },
  MAX_CONNECTIONS: {
    type: 'integer',
    validate: (value) => value > 0 && value <= 1000,
    default: 100,
  },
})

npm install envconfig-kit

Full API (transforms, schema export, all types): README

npm | GitHub

Comparison table

Approach	Dependencies	Bundle (approx)	Built-in `.env`	Secret masking in errors	TypeScript inference
Manual	0	0	No	No	Manual
dotenv + manual	1	~2KB	Yes	No	Manual
Zod + dotenv	2	~50KB+	Manual	No	Strong
envalid	1	~20KB	No	No	Good
t3-env	2+	Medium	Manual	No	Strong
envconfig-kit	0	~3KB	Yes	Yes	Strong

Which should you pick?

Situation	Pick
5 env vars, internal tool	Manual or dotenv + manual
Already standardized on Zod	Zod schema (or t3-env for Next.js)
Next.js / T3 App Router	t3-env
Express/Fastify API, want zero deps	envconfig-kit
Need `port()`, `url()` helpers without Zod	envalid
Regulated / secret-heavy config	Anything with masking; envconfig-kit has it built in

Honest take: there is no wrong choice among 3–5 if you validate at startup. The wrong choice is skipping validation entirely.

What to validate

Minimum checklist for a typical API:

URLs: DATABASE_URL, REDIS_URL, webhook endpoints
Secrets: API keys, JWT secrets (secret: true or never log config)
Ports and numeric limits: PORT, pool sizes, timeouts
Enums: NODE_ENV, feature modes, log levels
Booleans: parsed explicitly, never if (process.env.FLAG)
Arrays: CORS_ORIGINS, ALLOWED_HOSTS (comma-separated)

CLI validation in CI

Validate before deploy, not only at runtime:

npx envconfig-kit check
npx envconfig-kit generate   # .env.example from schema
npx envconfig-kit doctor     # health check

For Zod-based setups, parse in a small validate-env.ts script in your CI pipeline.

FAQ

How do I validate environment variables in Node.js?

Define a schema at startup and throw (or process.exit(1)) if validation fails. Use manual checks, Zod, envalid, t3-env, or envconfig-kit depending on your stack.

Should I use dotenv in production?

Usually no. Load secrets from your host (Kubernetes, Railway, AWS). Use .env files locally. envconfig-kit and dotenv both respect process.env taking precedence.

Zod or envconfig-kit for env only?

If Zod is everywhere already, use Zod. If you want env-only validation with zero dependencies and built-in .env loading, envconfig-kit is simpler.

What is fail-fast startup validation?

The process exits immediately when config is invalid, so deploy fails before users are affected. Prefer this over runtime undefined errors.

envconfig-kit v0.2.0 highlights

If you use envconfig-kit (Way 5), v0.2.0 adds:

Framework presets (server, database, redis, auth, aws, smtp, cors)
Validators: enum, array, json, regex, integer
Secret masking in error output
Custom validate() hooks per field
Custom preset prefixes (presets.database('DB_'))

Full v0.2.0 launch notes archived in seo-content/envconfig-kit/post-v0.2.0-launch-archive.md.

Checklist

[ ] Centralize config in one module, not scattered process.env reads
[ ] Validate every required var before the server listens
[ ] Parse booleans and numbers explicitly
[ ] Never log raw secrets on validation failure
[ ] Commit .env.example, never .env
[ ] Run env check in CI before deploy

What approach does your team use? Curious if anyone still runs manual-only validation in production APIs.

How to Monitor API Uptime From the Command Line (No SaaS Required)

Chintan Shah — Fri, 23 Jan 2026 18:19:12 +0000

You deployed at 11pm. The pipeline is green. Health checks pass. Twenty minutes later a user reports 500s on /api/orders.

Monitoring API uptime from the command line is the fastest way to watch an endpoint during a rollout, debug a flaky dependency, or confirm a fix without opening another browser tab or paying for a dashboard you use twice a year.

This guide covers when a curl loop is enough, when you want something better, and how to set up upstatus for live terminal monitoring with POST support, degraded detection, and CI-friendly output.

TL;DR

Goal	What to use
One request, exit immediately	`curl -sf https://api.example.com/health`
Watch endpoints live during a deploy	`upstatus https://api.example.com`
POST health check with a JSON body	`upstatus https://api.example.com/health -m POST -b '{"probe":"full"}'`
Flag slow but alive APIs	`upstatus https://api.example.com -d 1000`
Logs/CI without terminal clearing	`upstatus https://api.example.com --no-clear`
Export stats when you stop (Ctrl+C)	`upstatus https://api.example.com --export json -o report.json`
Single smoke test in GitHub Actions	Programmatic `Monitor.check()` (see below)

Why monitor from the terminal?

SaaS uptime tools (UptimeRobot, Better Stack, Pingdom) are great for 24/7 alerting. You should use them for production.

But they are slow for right now problems:

You just deployed and want to watch response times tick up in real time
A third-party API is flaky and you need to see failure patterns over 10 minutes
You are on a VPN or SSH session without dashboard access
You want zero accounts, zero config files, zero monthly bill

A CLI monitor runs locally. No signup. No agent. No webhook setup. Install, paste URLs, watch.

Option 1: curl (the baseline)

For a single check that exits immediately, curl wins:

curl -sf -o /dev/null -w "%{http_code} %{time_total}s\n" https://api.example.com/health

-s silences progress. -f fails on HTTP 4xx/5xx. -w prints status and timing.

A bash loop for repeated checks:

while true; do
  curl -sf -o /dev/null -w "$(date +%H:%M:%S) %{http_code} %{time_total}s\n" \
    https://api.example.com/health || echo "$(date +%H:%M:%S) FAILED"
  sleep 30
done

This works. It also gets messy fast:

No uptime percentage across checks
No "degraded" state when the API is slow but returning 200
No POST body support without more flags
No structured export when you stop
Hard to monitor three URLs in one readable view

When you outgrow the loop, reach for a small CLI tool.

Option 2: upstatus (live multi-URL monitoring)

upstatus is a Node.js CLI for watching HTTP endpoints from your terminal. It tracks response times, calculates uptime percentage, and labels each URL as up, degraded, or down.

Install

npm install -g upstatus

No install? Use npx:

npx upstatus https://api.github.com

Monitor one or more URLs

upstatus https://api.example.com

Multiple endpoints, default 30-second interval:

upstatus https://api.example.com https://status.example.com https://api.github.com

Custom interval (60 seconds):

upstatus https://api.example.com -i 60

What you see

The terminal refreshes with live stats (powered by logfx):

✅ https://api.example.com ........ 187ms (99.8% uptime)
⚠️ https://slow-api.com ......... 1450ms (98.7% uptime) [degraded]
🔴 https://down.example.com ..... DOWN (last check failed)

Press Ctrl+C to stop. upstatus prints a final summary and can export results (see below).

POST health checks

Many APIs expose GET /health that always returns 200 even when the database is down. Real probes use POST with a body.

upstatus https://api.example.com/health \
  -m POST \
  -b '{"check":"deep"}'

Supported methods: GET, POST, PUT, PATCH, DELETE.

For auth headers or advanced config, use the programmatic API (see CI section).

Degraded vs down

Down means the request failed, timed out, or returned an unexpected status code.

Degraded means the API responded with the expected status, but slower than your threshold. Default threshold is 2000ms.

# Mark as degraded if response exceeds 1000ms
upstatus https://api.example.com -d 1000

This matters during rollouts. A service can be "up" while latency spikes. Catching degraded early is often the difference between a rollback and an outage.

Status	Meaning
`up`	Expected status code, under threshold
`degraded`	Expected status code, over threshold
`down`	Error, timeout, or wrong status code

Export results on exit

When you stop monitoring, export stats for an incident report or Slack update:

upstatus https://api.example.com --export json -o uptime-report.json

CSV works too:

upstatus https://api.example.com --export csv -o uptime-report.csv

Exports run on Ctrl+C. Handy after a 20-minute deploy watch when you need numbers, not screenshots.

JSON mode and `--no-clear` for logs and CI

`--no-clear`

By default, upstatus clears the terminal on each refresh (nice locally, bad in CI logs). Disable it:

upstatus https://api.example.com --no-clear

Use this in GitHub Actions log output, Docker containers, or any non-TTY environment.

`--json`

JSON mode prints stats as JSON every 5 check cycles:

upstatus https://api.example.com --json --no-clear

Example output shape:

[
  {
    "url": "https://api.example.com",
    "name": "api.example.com",
    "checks": 5,
    "uptime": 100,
    "avgResponseTime": 214,
    "lastCheck": {
      "status": "up",
      "statusCode": 200,
      "responseTime": 198
    }
  }
]

Note: The CLI is designed for continuous monitoring, not one-shot exits. For deploy smoke tests that must pass or fail in under 5 seconds, use curl or the programmatic API below.

CI/CD: smoke test after deploy

Quick smoke test (curl)

Still the right default for "did deploy work?":

curl -sf https://api.example.com/health

Add to GitHub Actions:

- name: Smoke test API
  run: curl -sf https://api.example.com/health

Smoke test with POST + retries (upstatus API)

When you need POST bodies, custom expected status codes, or retry logic, use Monitor.check() from the library. One request, explicit exit code.

Create scripts/smoke-check.mjs:

import { Monitor } from 'upstatus'

const url = process.env.API_URL
if (!url) {
  console.error('Set API_URL environment variable')
  process.exit(1)
}

const monitor = new Monitor({
  url,
  method: 'POST',
  body: JSON.stringify({ check: 'deep' }),
  expectedStatus: [200, 201],
  maxRetries: 2,
  timeout: 10000,
})

const result = await monitor.check()

if (result.status === 'down') {
  console.error(`Smoke check failed: ${result.error ?? result.statusCode}`)
  process.exit(1)
}

console.log(`Smoke check ${result.status}: ${result.responseTime}ms`)

GitHub Actions workflow:

name: Post-deploy smoke test

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install upstatus
        run: npm install upstatus

      - name: Smoke check production API
        run: node scripts/smoke-check.mjs
        env:
          API_URL: ${{ secrets.PROD_API_URL }}

For headers (Bearer tokens, API keys), pass headers in the Monitor config:

const monitor = new Monitor({
  url: process.env.API_URL,
  headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
  maxRetries: 2,
})

Store tokens in GitHub Actions secrets, not in the workflow file.

Watch during a long deploy (optional)

For a manual or scheduled job that watches an endpoint for several minutes:

- name: Watch API for 3 minutes after deploy
  run: timeout 180 npx upstatus ${{ secrets.PROD_API_URL }} --no-clear --json || true

timeout sends SIGTERM; upstatus exports on shutdown if --export is set. This is optional. Most teams use SaaS alerting for 24/7 coverage and CLI tools during incidents.

curl vs upstatus vs SaaS (comparison)

	curl loop	upstatus CLI	UptimeRobot / Better Stack
Setup time	0 min	30 sec	10-15 min
Cost	Free	Free	Free tier, then paid
Multi-URL dashboard in terminal	Manual	Built-in	Web UI
Uptime % over session	DIY	Built-in	Built-in
Degraded (slow) detection	DIY	`-d` flag	Varies by plan
POST health checks	Verbose flags	`-m POST -b`	Supported
24/7 alerting + history	No	No	Yes
Best for	One-off checks	Deploy watch, debugging	Production monitoring

Practical split: SaaS for always-on alerts. Terminal CLI for deploy night and incident debugging. curl for the fastest single-request smoke test.

Programmatic usage in Node.js

Embed monitoring in scripts, cron jobs, or custom tooling:

import { MonitorManager } from 'upstatus'

const manager = new MonitorManager()

manager.add({
  url: 'https://api.example.com',
  interval: 30,
  method: 'POST',
  body: JSON.stringify({ check: 'deep' }),
  headers: { Authorization: 'Bearer token' },
  degradedThreshold: 1500,
  expectedStatus: [200, 201],
  timeout: 10000,
  maxRetries: 2,
})

manager.startAll()

const stats = manager.getMonitor('api.example.com')?.getStats()
console.log(stats)

manager.stopAll()

Export utilities for reports:

import { exportToJson, exportToCsv } from 'upstatus'

const stats = [...manager.monitors.values()].map((monitor) => monitor.getStats())
const json = exportToJson(stats)

Full config options: upstatus README.

FAQ

How is this different from Uptime Kuma?

Uptime Kuma is a self-hosted dashboard with alerting, status pages, and history. upstatus is a terminal CLI with no UI to maintain. Use Kuma for team-wide 24/7 monitoring. Use upstatus when you want to watch endpoints from a shell session in 30 seconds.

Can upstatus replace UptimeRobot?

No. upstatus does not send email/SMS alerts or store months of history. It fills the gap when you need local, immediate visibility without creating another account.

Does it work on Windows?

Yes. Node.js 18+ on Windows, macOS, and Linux. Global install: npm install -g upstatus.

What Node version do I need?

Node 18 or later (uses native fetch).

How do I monitor an endpoint that requires authentication?

Use the programmatic API with headers: { Authorization: 'Bearer ...' }. Do not pass secrets on the CLI in shared screen recordings or shell history. Use environment variables in scripts.

Why does `--json` not exit after one check?

The CLI runs until you stop it. That is intentional for live monitoring. For CI smoke tests, call Monitor.check() once and process.exit(1) on failure.

What is the default check interval?

30 seconds. Override with -i 60 for 60 seconds.

Try it

npx upstatus https://api.github.com

GitHub: github.com/chintanshah35/upstatus
npm: npmjs.com/package/upstatus

If you maintain a side project API and only need to know "is it up right now?", a terminal monitor beats opening three browser tabs.

About upstatus

upstatus is an open-source CLI uptime monitor (~15KB gzipped). POST/PUT/PATCH support, degraded thresholds, retry with exponential backoff, JSON/CSV export, and a programmatic API for Node.js and TypeScript.

MIT licensed. Built with TypeScript and logfx for terminal output.

Full feature list and CLI reference: upstatus README.

logfx v0.5.0: From Dev Tool to Production Logger

Chintan Shah — Tue, 20 Jan 2026 02:52:46 +0000

Last month, I shared logfx. Since then, I've been using it in my projects and kept adding features I needed. v0.5.0 is the result - 15+ new features that make it production-ready.

Express Middleware

This was the most requested feature. Automatic request logging with timing and request IDs:

import express from 'express'
import { expressLogger } from 'logfx'

const app = express()
app.use(expressLogger())

app.get('/users', (req, res) => {
  req.log.info('Fetching users', { userId: req.query.id })
  res.json({ users: [] })
})

Output:

💡 INFO [http] Incoming request { method: 'GET', path: '/users', requestId: 'abc123' }
💡 INFO [http] Fetching users { userId: '42' }
💡 INFO [http] Request completed { method: 'GET', path: '/users', status: 200, durationMs: 45 }

You get req.log scoped to each request, automatic timing, and request IDs for tracing. Status codes automatically set the log level (5xx = error, 4xx = warn).

Options:

Skip routes (health checks)
Custom request ID extraction
Configurable headers

Fastify and Next.js Too

// Fastify
import Fastify from 'fastify'
import { fastifyLogger } from 'logfx'

const app = Fastify()
app.register(fastifyLogger())

app.get('/api/data', async (request, reply) => {
  request.log.info('Processing')
  return { ok: true }
})

// Next.js
import { withLogging } from 'logfx'

export default withLogging(async (req, res) => {
  req.log.info('API called', { path: req.url })
  res.json({ ok: true })
})

Color Themes

Added dracula and monokai themes because the default colors weren't great on every terminal:

import { createLogger } from 'logfx'

const log = createLogger({ theme: 'dracula' })
// or 'monokai', 'default'

log.info('Themed output')
log.success('Looks great')
log.error('Easy to spot')

Makes logs easier to scan when you're debugging at 2am.

File Rotation

Logs now rotate automatically when they hit a size limit:

import { createLogger, transports } from 'logfx'

const log = createLogger({
  transports: [
    transports.file({
      path: './logs/app.log',
      rotation: {
        maxSize: '10mb',
        maxFiles: 5,
        compress: true  // gzip old files
      }
    })
  ]
})

Creates app.log.1, app.log.2, etc. Old files get gzipped. No more disk space issues.

Issue Detection

This catches mistakes I kept making:

const log = createLogger({ detectIssues: true })

log.info('User data', { data: undefined })
// ⚠️ Warning: undefined value in log data

log.info('Auth', { password: 'secret123' })
// ⚠️ Warning: potential password in log data

Only runs in development. Saved me from logging passwords to production a few times already.

Format Auto-Detection

Pretty output in dev, JSON in production. No config needed:

// Development (NODE_ENV=development)
log.info('Server started')
// 💡 INFO Server started (pretty, colored)

// Production (NODE_ENV=production)
log.info('Server started')
// {"timestamp":"2026-01-19T...","level":"info","message":"Server started"}

Request ID Tracking

Built-in for tracing requests across your logs:

const log = createLogger({ requestId: 'req-123' })
log.info('Processing payment')
// Includes requestId in output for correlation

Great for debugging issues across microservices.

Better Error Serialization

Stack traces are readable in dev, structured in prod:

try {
  await connectDatabase()
} catch (error) {
  log.error('Connection failed', error)
}

Development output:

🔴 ERROR Connection failed
Error: Timeout
    at Database.connect (/app/db.js:45:11)
    at Server.start (/app/server.js:12:5)

Production output:

{
  "timestamp": "2026-01-19T13:45:00.000Z",
  "level": "error",
  "message": "Connection failed",
  "error": {
    "message": "Timeout",
    "stack": "Error: Timeout\n    at Database.connect...",
    "code": "ETIMEDOUT"
  }
}

Service Context

Automatically reads service metadata from environment:

// Reads SERVICE_NAME, SERVICE_VERSION, NODE_ENV
const log = createLogger()
log.info('Started')

// Output includes:
// {"service":"my-api","version":"1.0.0","environment":"production",...}

Structured JSON Output

Production-ready JSON format for log aggregation tools:

const log = createLogger({ format: 'json' })
log.info('User login', { userId: 123 })
// {"timestamp":"2026-01-19T...","level":"info","message":"User login","data":{"userId":123}}

Works with Datadog, Splunk, ELK stack, and other log aggregation tools.

Field Redaction

Hide sensitive data automatically:

const log = createLogger({
  redact: {
    fields: ['password', 'token', 'apiKey'],
    replacement: '***REDACTED***'
  }
})

log.info('User login', { 
  username: 'john', 
  password: 'secret123' 
})
// Output: { username: 'john', password: '***REDACTED***' }

Log Sampling

Reduce log volume in high-traffic scenarios:

const log = createLogger({
  sampling: {
    debug: 0.1,  // 10% of debug logs
    info: 0.5,   // 50% of info logs
    error: 1.0   // 100% of errors (always log)
  }
})

Useful when you're getting millions of requests.

Async Logging

Buffer and batch logs for better performance:

const log = createLogger({
  async: true,
  buffer: {
    size: 100,        // flush after 100 logs
    flushInterval: 1000  // or every 1 second
  }
})

Prevents logging from blocking your event loop.

Multiple Transports

Send logs to different destinations simultaneously:

import { createLogger, transports } from 'logfx'

const log = createLogger({
  transports: [
    transports.console({ format: 'pretty' }),
    transports.file({ 
      path: './logs/app.log',
      format: 'json'
    }),
    transports.webhook({ 
      url: 'https://logs.example.com/ingest',
      batchSize: 10
    })
  ]
})

Webhook Transport

Send logs to remote endpoints:

transports.webhook({
  url: 'https://logs.example.com',
  method: 'POST',
  headers: { 'Authorization': 'Bearer token' },
  batchSize: 10,
  flushInterval: 5000
})

Great for custom log aggregation services or alerting systems.

Environment Detection

Automatically adapts to your environment:

CI/CD: Auto-disables colors
TTY Detection: Only shows colors in terminals
NO_COLOR/FORCE_COLOR: Respects standard env vars
NODE_ENV: Auto-switches format (pretty in dev, JSON in prod)

Complete Feature List

Core Logging:

5 log levels (debug, info, success, warn, error)
Namespaced loggers
Colorful output with emojis
Timestamps
Context metadata

Production Features:

Format auto-detection (pretty/JSON)
Structured JSON output
Request ID tracking
Service context
Error serialization with stack traces
Field redaction
Log sampling
Async buffered logging

Transports:

Console transport
File transport with rotation
Webhook transport
Multiple transports simultaneously

Framework Integration:

Express middleware
Fastify plugin
Next.js API middleware

Developer Experience:

Color themes (default, dracula, monokai)
Issue detection (undefined values, passwords)
Environment detection (CI/CD, TTY)
TypeScript support
Zero dependencies

Why I Built This

I got tired of choosing between pretty logs in dev and structured logs in prod. Most loggers force you to pick one. logfx does both automatically.

Also wanted something that works in browsers and Node without extra config. Zero dependencies means no supply chain issues.

The middleware was the big one though. Every project needs request logging and I was copy-pasting the same code everywhere.

What Makes logfx Different

Works everywhere

One logger for your entire stack:

Node.js, Bun, Deno
Browsers (Chrome, Firefox, Safari)
Express, Fastify, Next.js
Edge runtimes (coming in v0.6.0)

Zero dependencies

No supply chain risk. No version conflicts. No security audits for logging dependencies.

Lightweight but feature-complete

~11KB gzipped (46KB uncompressed)
Full TypeScript support
117 passing tests
All the features you need, none you don't

Installation

npm install logfx

Quick Start

import { log } from 'logfx'

log.debug('Debugging info', { detailed: true })
log.info('Server started', { port: 3000 })
log.success('User created')
log.warn('Memory usage high', { usage: '85%' })
log.error('Connection failed', new Error('Timeout'))

Output:

🔍 DEBUG   Debugging info { detailed: true }
💡 INFO    Server started { port: 3000 }
✅ SUCCESS User created
⚠️ WARN    Memory usage high { usage: '85%' }
🔴 ERROR   Connection failed Error: Timeout
    at ...

Try It

npm install logfx@0.5.0

Links:

GitHub: github.com/chintanshah35/logfx
npm: npmjs.com/package/logfx
Release Notes: v0.5.0 Release
Original Post: Your console.log deserves better

How to Validate Environment Variables in Node.js (Fail Fast at Startup)

Chintan Shah — Thu, 15 Jan 2026 06:13:30 +0000

2am. Slack notification. Production app is down.

The error? Cannot read property 'split' of undefined

Turns out ALLOWED_ORIGINS wasn't set in production. The app started fine. Health checks passed. Then the first CORS request came in and crashed the server.

Or that time STRIPE_SECRET_KEY had a trailing space from copy-paste. App started. First payment request? Failed. Took 30 minutes to figure out.

Or when someone set ENABLE_CACHING=false as a string, but the code checked if (config.ENABLE_CACHING) - string "false" is truthy, so caching stayed on.

This stuff happens constantly.

The real problem isn't missing env vars

It's that your app doesn't know they're wrong until it tries to use them.

const port = process.env.PORT || 3000
const apiKey = process.env.API_KEY
const enableCache = process.env.ENABLE_CACHING
const origins = process.env.ALLOWED_ORIGINS?.split(',')

// App starts fine
// apiKey is undefined
// enableCache is the string "false" (truthy!)
// origins will crash when undefined
// Everything looks good... until it's not

Your app starts. Health checks pass. Then 5 minutes later, it tries to call the API and crashes because apiKey is undefined.

Or your boolean flag is the string "false" but your code checks if (enableCache) - string "false" is truthy, so the logic is backwards.

Or someone has a trailing space in STRIPE_KEY=" sk_live_123 " and all payment requests fail with cryptic auth errors.

Fail fast, not later

What if your app refused to start unless everything was valid?

import { env } from 'envconfig-kit'

const config = env({
  PORT: { type: 'number', default: 3000 },
  API_KEY: { type: 'string' },
  DATABASE_URL: { type: 'url' },
})

Now if API_KEY is missing or DATABASE_URL isn't a valid URL, your app won't start at all.

❌ Environment validation failed:

  API_KEY: Missing required environment variable
  ➜ Fix: Add to .env file
    Example: API_KEY=your-value-here

  STRIPE_SECRET_KEY: Value contains leading/trailing whitespace
  ➜ Fix: Remove extra spaces
    Current: " sk_live_123 "
    Expected: "sk_live_123"

Crash at startup, not during runtime. Get useful error messages, not undefined is not a function.

What you get

Type safety

config.PORT       // number
config.API_KEY    // string
config.DEBUG      // boolean
config.REDIS_URL  // string | undefined (if optional)

TypeScript knows the exact types. No more process.env.PORT as number.

Built-in .env loading

No need for dotenv. Automatically loads from .env, .env.local, .env.production, etc.

const config = env({ 
  PORT: { type: 'number' } 
})
// Just works. No extra setup.

Transform values

Parse arrays, trim whitespace, normalize URLs:

const config = env({
  ALLOWED_ORIGINS: {
    type: 'string',
    transform: (value) => value.split(',').map(s => s.trim())
  },
  API_URL: {
    type: 'url',
    transform: (value) => value.replace(/\/$/, '') // remove trailing slash
  }
})

config.ALLOWED_ORIGINS // ['http://localhost:3000', 'https://app.com']

Validation types that matter

string, number, boolean - the basics
url - validates protocol, catches localhost and http:/missing-slash
email - actual email validation
port - number between 0-65535

Real example

Here's what a typical API config looks like:

import { env } from 'envconfig-kit'

export const config = env({
  // Server
  PORT: { type: 'port', default: 3000 },
  HOST: { type: 'string', default: '0.0.0.0' },
  NODE_ENV: { type: 'string', default: 'development' },

  // Database
  DATABASE_URL: { type: 'url' },

  // Redis (optional)
  REDIS_URL: { type: 'url', optional: true },

  // API Keys
  API_KEY: { type: 'string' },
  JWT_SECRET: { type: 'string' },

  // External services
  STRIPE_KEY: { type: 'string' },
  SENDGRID_KEY: { type: 'string' },

  // CORS
  ALLOWED_ORIGINS: {
    type: 'string',
    default: 'http://localhost:3000',
    transform: (value) => value.split(',')
  },

  // Feature flags
  ENABLE_ANALYTICS: { type: 'boolean', default: false },
})

// Now everything is typed and validated
// App won't start if anything is wrong

CLI tools

Generate .env.example for your team:

npx envconfig-kit generate

Validate before deployment:

npx envconfig-kit check

Health check:

npx envconfig-kit doctor

Install

npm install envconfig-kit

Zero dependencies. 3KB minified. Works with CommonJS and ESM.

Stop debugging undefined errors at 2am. Make your app fail fast with clear error messages.

GitHub | npm

How to Parse JSON Safely in Node.js

Chintan Shah — Tue, 06 Jan 2026 06:46:33 +0000

I built a tiny library called handlejson because I got tired of writing try-catch blocks for JSON.parse everywhere. Just shipped v0.2.0 today with some features I actually needed in real projects.

The Problem

How many times have you written this?

let data
try {
  data = JSON.parse(str)
} catch {
  data = null
}

I wrote it hundreds of times. localStorage.getItem? try-catch. API response? try-catch. User input? try-catch. Every single time.

It works, but it's verbose. And there are other annoyances too - JSON.stringify throws on circular references, Date objects serialize to empty objects (useless), and there's no easy way to validate structure.

What handlejson Does

It's basically a wrapper around native JSON functions, but with all the annoying edge cases handled:

import { parse, stringify } from 'handlejson'

// Safe parsing - returns null on error, no try-catch needed
const user = parse(localStorage.getItem('user'))
const config = parse(invalidJson, { default: {} })

// Handles circular refs automatically
const obj = { a: 1 }
obj.self = obj
stringify(obj)  // '{"a":1,"self":"[Circular]"}'

// BigInt support
stringify({ value: BigInt(123) })  // '{"value":"123n"}'

That's the basics. Small, simple, just makes JSON parsing less annoying.

New in v0.2.0

I released v0.1.0 a while back with the core functionality. Today I'm shipping v0.2.0 with three features I kept needing:

Date Handling

This was the most annoying one. Every API response with dates means writing custom revivers to convert ISO strings back to Date objects:

// The old way
const user = parse(jsonString, {
  reviver: (key, value) => {
    if (key.endsWith('At') && typeof value === 'string') {
      const date = new Date(value)
      return isNaN(date.getTime()) ? value : date
    }
    return value
  }
})

Now it's just:

const user = parse(jsonString, { dates: true })
// Dates are automatically converted

Same for stringifying - Date objects serialize to ISO strings instead of empty objects:

stringify({ createdAt: new Date() }, { dates: true })
// → '{"createdAt":"2023-01-01T10:00:00.000Z"}'

Saves a lot of boilerplate. I was writing that reviver logic constantly.

Schema Validation

I kept hitting bugs where API responses had wrong types. A number field coming through as a string, that sort of thing. Instead of writing custom validation each time, you can pass a schema:

const schema = {
  name: 'string',
  age: 'number',
  active: 'boolean',
  address: {
    street: 'string',
    zip: 'number'
  }
}

const user = parse(apiResponse, { schema })
// Returns null if validation fails

It's not full JSON Schema (that'd be overkill), just simple type checking. The validation happens after parsing, so you get useful errors like "Field 'age': expected number, got string" instead of cryptic parse failures.

Useful for catching bugs early, especially when working with APIs you don't control.

Stream Parsing

This one's for processing large JSON files. Most projects won't need it, but if you're dealing with big datasets:

import { parseStream } from 'handlejson'

const result = await parseStream(response.body, {
  onProgress: (parsed) => console.log('Loading...'),
  onError: (err) => console.error('Error:', err)
})

if (result.complete) {
  console.log('Data:', result.data)
}

I added this because I was working on a feature that needed to process multi-MB JSON files. Loading everything into memory first wasn't ideal.

Real Example

Here's a common pattern I see (and wrote myself many times):

// Before
function loadUser() {
  const stored = localStorage.getItem('user')
  if (!stored) return null

  try {
    const parsed = JSON.parse(stored)
    if (parsed.createdAt) {
      parsed.createdAt = new Date(parsed.createdAt)
    }
    return parsed
  } catch {
    return null
  }
}

// After
function loadUser() {
  return parse(localStorage.getItem('user'), {
    default: null,
    dates: true
  })
}

Way cleaner. The new features make this even better - you can add schema validation if you want to be extra safe.

Why Build This?

There are other libraries that do similar things, but they're usually heavier or have more features than I need. I wanted something tiny that just handles the common edge cases.

It's ~2.8KB gzipped, zero dependencies, TypeScript native. Small enough that you can use it without thinking about bundle size.

Works in browser and Node.js. Same API everywhere.

Should You Use It?

If you're doing a lot of JSON parsing and tired of try-catch blocks everywhere, maybe. It's not revolutionary - just a quality-of-life improvement.

If you're happy with native JSON and don't mind the try-catch boilerplate, stick with that. No need to add dependencies for no reason.

But if you do a lot of JSON parsing (localStorage, API responses, user input), it cleans up your code quite a bit.

Try It

npm install handlejson

The v0.2.0 release is on npm now. If you want to try it, that's the latest version with all the new features.

All the new stuff is opt-in, so existing code using handlejson (if anyone is) won't break. The new features are optional options.

What do you think? Do you write try-catch blocks for JSON.parse a lot, or am I the only one bothered by this? Always curious what other developers think about this stuff.

Your console.log deserves better

Chintan Shah — Thu, 18 Dec 2025 22:11:14 +0000

I kept copy-pasting the same logging code into every new project. Eventually I just packaged it up. It's called logfx — a tiny library that makes your console output a bit easier to read.

The problem I kept running into

console.log('DEBUG: starting process')
console.log('INFO: connected')
console.log('ERROR: something broke')

It works, but it's hard to scan. Everything looks the same.

A small improvement

import { log } from 'logfx'

log.debug('Starting process')
log.info('Connected')
log.error('Something broke')

Output:

🔍 DEBUG   Starting process
💡 INFO    Connected
🔴 ERROR   Something broke

Just a bit of color and structure — but it makes a difference when you're debugging.

When logfx might help

logfx is a lightweight option for when you want:

Something simple — no config, just import and go
Readable dev logs — easier to scan in your terminal
A small footprint — ~2KB gzipped, zero dependencies
Quick projects — prototypes, scripts, side projects
Universal support — Node.js, browsers, Bun, Deno

What's inside

Lightweight

~2KB gzipped with zero dependencies. Tried to keep it minimal.

Nice defaults

Colors and structure out of the box — no setup needed.

TypeScript support

Built in TypeScript with full type inference.

Smart log levels

Debug logs auto-hide in production.

Transports

Console, file, webhook — in case you need to send logs somewhere.

A few examples

Namespaced loggers:

import { logger } from 'logfx'

const auth = logger('auth')
const db = logger('db')

auth.success('User logged in')  
// ✅ SUCCESS [auth] User logged in

db.info('Query executed')
// 💡 INFO [db] Query executed

Timers:

import { time, timeEnd } from 'logfx'

time('api-call')
await fetch('/data')
timeEnd('api-call')  
// ⏱️ api-call: 245.32ms

Pretty boxes:

import { box } from 'logfx'

box('Server running on port 3000', { title: 'Ready' })

╭─ Ready ─────────────────────────╮
│  Server running on port 3000    │
╰─────────────────────────────────╯

Tables:

import { table } from 'logfx'

table([
  { name: 'John', role: 'Admin' },
  { name: 'Jane', role: 'User' },
])

┌─────────┬─────────┐
│ name    │ role    │
├─────────┼─────────┤
│ John    │ Admin   │
│ Jane    │ User    │
└─────────┴─────────┘

JSON output:

import { createLogger, transports } from 'logfx'

const log = createLogger({
  transports: [transports.console({ format: 'json' })]
})

log.info('Request', { method: 'GET', path: '/api' })
// {"timestamp":"2025-12-18T...","level":"info","message":"Request","method":"GET","path":"/api"}

Try it out

npm install logfx

Hello, dev.to! I'm Chintan Shah 👋

Chintan Shah — Thu, 18 Dec 2025 05:27:19 +0000

Excited to finally join the dev.to community! Here's a bit about me.

Who am I?

I'm Chintan — a Senior Software Engineer based in Virginia. I've been building web applications for about 9 years now, and somehow I still get excited when a tricky bug finally clicks.

I have a Master's in Computer Science, but honestly, most of what I know came from breaking things in production and frantically Googling at 2am (kidding... mostly).

The journey so far

I've been lucky to work across some really different industries — healthcare, insurance, digital marketing, and travel. Each one taught me something different.

Healthcare taught me that your code actually matters — when clinicians rely on your software, you think twice before shipping. Insurance showed me what high-volume really means — millions of transactions, peak hours that can make or break systems. Marketing was all about speed and iteration. Travel? Resilience. Nothing prepares you for traffic spikes like holiday booking season.

These days, I'm leading projects and doing the full-stack thing — React and TypeScript on the frontend, Scala and Node.js on the backend, with a healthy dose of AWS thrown in.

What gets me excited

I genuinely enjoy the craft of building software. Whether it's architecting a micro frontend, setting up a clean CI pipeline, or making an app actually work with a screen reader — I'm into it.

Web accessibility is a big one for me. It's not a checkbox, it's the baseline. I've spent a lot of time with WCAG, screen readers, and making sure the things I build work for everyone.

Also, I have a soft spot for developer tooling. There's something satisfying about building tools that make other engineers' lives easier.

Outside of work

I tinker with open source and recently published a couple of npm packages. logfx is a tiny, colorful logging library with emojis, namespaces, and transports — because console.log deserves better. And upstatus is a simple CLI for uptime monitoring when you just need something quick and lightweight.

Building small, focused utilities is my kind of side project.

Why I'm here

I want to write more. Document what I learn. Share the random things I figure out. Maybe help someone avoid the same mistakes I made.

Topics I'll probably write about:

React patterns and frontend architecture
Full-stack development stories
Accessibility in practice
The occasional rant about something that took way too long to debug

Say hi!

Find me on GitHub or LinkedIn.

Always down to chat about code, career stuff, or swap stories about that one bug that haunted you for days.

See you around! 🙌