SMSCode is a virtual number platform — users purchase temporary phone numbers to receive SMS verification codes. Think of it as a marketplace that connects users who need phone numbers with SMS providers who supply them, handling payments, order lifecycle, and real-time delivery in between.

This isn't a toy project or a demo. It's a production system with real money, real users, and real SMS providers that can fail in creative ways. Building it taught me more about Rust in production than any tutorial or book ever could.

This post is a deep dive into how it works — the architecture decisions, the patterns that survived production, and the ones that didn't.

The Migration Story

SMSCode started on Directus, a Node.js headless CMS. For the early stage, Directus was perfect — it gave me a database, an admin panel, and a REST API with zero custom code. I could focus on building the product instead of building infrastructure.

But as the platform grew past a few thousand users, the cracks showed:

• Query performance — Directus abstracts SQL behind a generic query builder. As relationships got complex, generated queries became inefficient and hard to optimize.
• Business logic limitations — order lifecycle management, atomic balance operations, and provider integration needed logic that didn't fit Directus's hook system.
• Memory usage — the Node.js process was consuming 300-400MB at rest, spiking higher under load.
• Concurrency — background tasks (order expiration, provider reconciliation) competed with API requests on the same event loop.

I needed a custom backend. The question was: what do I build it with?

I considered staying in the Node.js ecosystem — Hono or Fastify would have been the safe choice. But the workload profile of SMSCode is unusual: it's not just request-response. There are 10 background tasks running on configurable intervals, real-time SSE streams, webhook processing, and atomic financial operations. All running 24/7 with zero tolerance for memory leaks or GC pauses.

Rust with Axum was the answer. Axum gave me the web framework, Tokio gave me the async runtime for background tasks and SSE, and Rust's type system gave me guarantees that the financial logic would be correct.

The migration took about three weeks. Memory usage dropped from ~400MB to ~12MB. Tail latency dropped by 10x. And the codebase became easier to reason about, not harder — because the type system caught entire categories of bugs at compile time. You can see the result live at smscode.gg.

Architecture Overview

The system has three main components:

┌──────────────────┐     ┌──────────────────┐
│   Astro (Web)    │     │  Admin SSR       │
│   SSR pages      │     │  TanStack Start  │
│   Port 4321      │     │  Port 3001       │
└────────┬─────────┘     └────────┬─────────┘
         │ axumFetch()            │ axumFetch()
         │ (internal auth)        │ (admin auth)
         ▼                        ▼
┌──────────────────────────────────────────────┐
│              Axum API (Rust)                  │
│              Port 3000                        │
│                                               │
│  /internal/*  ── Web frontend calls          │
│  /v1/*        ── Public REST API             │
│  /webhooks/*  ── SMS + payment callbacks     │
│  + 10 background tasks (Tokio)               │
└──────┬──────────┬──────────┬─────────────────┘
       │          │          │
       ▼          ▼          ▼
  PostgreSQL  Redis × 3   SMS Providers
  (17 tables) (session,   Payment Gateways
              cache,
              ratelimit)

Astro is a thin proxy — it handles SSR rendering and session cookies but delegates all business logic to Axum via internal HTTP calls. This is a deliberate choice: Axum is the single source of truth. The web frontend (what you see at smscode.gg) can be rebuilt or replaced without touching business logic.

The admin panel is a separate TanStack Start (React SSR) app. It communicates with Axum over the internal network, never exposed publicly. Different deployment cadence, different auth model, clean separation.

Axum handles everything else: API routes, webhooks, background tasks, metrics, and real-time event streaming. A single Rust binary.

Application State

One of the first things you design in an Axum app is your AppState — the shared state injected into every request handler. Getting this wrong means refactoring hundreds of handlers later.

#[derive(Clone)]
pub struct AppState {
    inner: Arc<AppStateInner>,
}

struct AppStateInner {
    pool: PgPool,
    redis_session: ConnectionManager,
    redis_cache: ConnectionManager,
    redis_ratelimit: ConnectionManager,
    config: Config,
    providers: ProviderRegistry,
    payment_client: reqwest::Client,
    webhook_client: reqwest::Client,
    email_client: reqwest::Client,
    metrics: Metrics,
    prom_handle: PrometheusHandle,
    push_service: Option<WebPushService>,
}

A few things to note:

Three separate Redis connections — session, cache, and rate limit data live on three different Redis instances. This means I can flush the cache or rate limit data without killing user sessions. During development, I accidentally flushed Redis once. With a single instance, that would have logged out every user. With isolation, it was just a cache miss.

Separate HTTP clients — payment gateway calls get a 10-second timeout. Webhook dispatch gets a 3-second timeout with no redirect following. SMS provider calls go through a proxy with their own circuit breaker. Each client is tuned for its specific use case.

Arc<AppStateInner> pattern — AppState is a thin Clone-able wrapper around an Arc. Cloning the state for each handler is just incrementing a reference count — zero allocation. The inner struct holds the actual data, which is shared across all handlers and background tasks.

Optional services — push_service: Option<WebPushService> is None when VAPID keys aren't configured. The app gracefully degrades instead of panicking on startup. Same pattern for payment gateways and Google OAuth.

Error Handling

Every Axum handler returns Result<impl IntoResponse, AppError>. The AppError enum covers every failure mode:

#[derive(Debug, thiserror::Error)]
pub enum AppError {
    #[error("Authentication required")]
    Unauthorized,

    #[error("Insufficient balance")]
    InsufficientBalance,

    #[error("{0}")]
    NotFound(String),

    #[error("{0}")]
    Validation(String),

    #[error("Too many requests")]
    RateLimit,

    #[error("Too many requests")]
    RateLimitWithRetry(i64),

    #[error("Provider error: {0}")]
    Provider(String),

    #[error(transparent)]
    Internal(#[from] anyhow::Error),

    #[error("Database error")]
    Database(#[from] sqlx::Error),
}

The IntoResponse implementation maps each variant to the correct HTTP status code and a consistent JSON envelope:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough balance"
  }
}

Two important details:

Internal errors are opaque — AppError::Internal and AppError::Database both return a generic "Internal server error" to the client while logging the full error with tracing::error!. Users never see stack traces or database error messages.

Rate limit with retry — RateLimitWithRetry(i64) adds a Retry-After header to the response, telling clients exactly when they can retry. This is critical for the public API where automated clients need to back off gracefully.

The ? operator makes error propagation clean across the entire callstack:

async fn create_order(
    State(state): State<AppState>,
    auth: AuthUser,
    Json(input): Json<CreateOrderInput>,
) -> Result<Json<OrderResponse>, AppError> {
    let product = get_product(&state, input.product_id)
        .await?  // → AppError::NotFound if missing
        .ok_or_else(|| AppError::NotFound("Product not found".into()))?;

    check_cancel_limit(&state, auth.user_id)
        .await?;  // → AppError::Conflict if exceeded

    let balance = atomic_debit(&state, auth.user_id, product.price)
        .await?;  // → AppError::InsufficientBalance

    let number = state.providers()
        .get_number(&params)
        .await
        .map_err(|e| AppError::Provider(e.to_string()))?;

    // ... create order record
    Ok(Json(order.into()))
}

Every ? either propagates to the correct HTTP error or converts automatically via #[from]. No try/catch chains, no forgotten error handling.

Atomic Balance Operations

Financial operations are the most critical part of the system. A user's balance must always be consistent with their transaction ledger. Getting this wrong means users lose money or get free credit.

The core pattern is debit-first, refund-on-failure:

1. BEGIN TRANSACTION
   a. UPDATE users SET balance = balance - $price
      WHERE id = $user_id AND balance >= $price
      RETURNING balance
   b. INSERT transaction (ORDER_DEBIT, -$price, balance_after)
   c. COMMIT

2. Call SMS provider (external API — OUTSIDE transaction)

3. On success: INSERT order record
4. On failure: BEGIN → credit balance back + INSERT ORDER_REFUND → COMMIT

The debit happens before the provider call. Why? Because the provider call can take seconds. If we deducted after, a user could spend the same balance twice by firing two concurrent requests.

The SQL itself is a single atomic statement with a CAS (compare-and-swap) guard:

UPDATE users
SET balance = balance - $1
WHERE id = $2 AND balance >= $1
RETURNING balance

If the balance is insufficient, zero rows are returned, and we map that to AppError::InsufficientBalance. No race condition possible — PostgreSQL's row-level locking guarantees atomicity.

To prevent integer overflow on refunds (balance is BIGINT):

UPDATE users
SET balance = balance + $1
WHERE id = $2 AND balance <= 9223372036854775807 - $1
RETURNING balance

A background task (reconcile_balances) runs every 30 minutes, comparing each user's balance against the sum of their transaction ledger. Any mismatch is logged and alerted. In months of production, it has never found one — but I sleep better knowing it's checking.

Background Tasks with Leader Election

SMSCode runs 10 background tasks on configurable intervals. These handle everything from expiring old orders to syncing the product catalog from SMS providers.

The challenge: I want to run multiple Axum instances for high availability, but background tasks should only run on one instance at a time. The solution is Redis-based leader election using SETNX:

async fn acquire_leader_lock(
    redis: &ConnectionManager,
    task: &str,
    instance_id: &str,
    ttl_secs: u64,
) -> bool {
    let key = format!("task_lock:{task}");
    let result: RedisResult<Option<bool>> = redis::cmd("SET")
        .arg(&key)
        .arg(instance_id)
        .arg("NX")        // Only set if not exists
        .arg("EX")        // Expire after TTL
        .arg(ttl_secs)
        .query_async(&mut redis.clone())
        .await;

    matches!(result, Ok(Some(true)))
}

Each task tick: try to acquire the lock. If another instance already holds it, skip. If we get it, run the task, then release the lock with a Lua CAS script (only delete if we still own it):

if redis.call("GET", KEYS[1]) == ARGV[1] then
    return redis.call("DEL", KEYS[1])
end
return 0

The lock TTL is max(interval × 2, 30s) — a safety net so that if an instance crashes mid-task, the lock expires and another instance picks up. Normal runs release immediately.

The task loop itself is shutdown-aware using Tokio's CancellationToken:

loop {
    tokio::select! {
        _ = shutdown.cancelled() => break,
        _ = interval.tick() => {
            if !acquire_leader_lock(...).await { continue; }

            tokio::select! {
                _ = shutdown.cancelled() => {
                    release_leader_lock(...).await;
                    break;
                }
                result = func(state.clone()) => {
                    // log and record metrics
                    release_leader_lock(...).await;
                }
            }
        }
    }
}

The nested select! ensures that even a long-running task is interrupted promptly on SIGTERM — critical for zero-downtime deployments.

Provider Integration with Circuit Breaker

SMS providers are external APIs that fail in exciting ways — timeouts, rate limits, malformed responses, or just going down entirely. A failing provider shouldn't take down the entire platform.

Each provider implements the ProviderClient trait:

#[async_trait]
pub trait ProviderClient: Send + Sync {
    fn code(&self) -> &str;
    fn circuit_state(&self) -> (u32, bool);

    async fn get_number(&self, params: &GetNumberParams)
        -> Result<GetNumberResult, ProviderError>;
    async fn cancel_activation(&self, id: &str)
        -> Result<bool, ProviderError>;
    async fn get_status(&self, id: &str)
        -> Result<StatusResult, ProviderError>;
    // ... more methods
}

The Send + Sync bounds are required because providers are stored as Arc<dyn ProviderClient> in the ProviderRegistry and shared across all Tokio tasks. This is where Rust's type system shines — the compiler enforces that provider implementations are thread-safe.

Each provider has a built-in circuit breaker. After N consecutive failures, the circuit opens and subsequent calls fail fast without hitting the external API. After a cooldown period, the circuit enters a half-open state and allows one probe request. If it succeeds, the circuit closes and normal operation resumes.

The ProviderRegistry loads provider configs from the database with a 5-minute cache, dispatching to the correct client based on the protocol column (e.g., sms_activate, sms_bower). Adding a new provider protocol means implementing the trait — the registry handles discovery and caching automatically.

Real-Time with Server-Sent Events

When a user purchases a number and waits for the SMS code, they need to know the moment it arrives. Polling every few seconds works but wastes resources. SSE gives us push-based updates with minimal overhead.

The architecture:

Browser EventSource
    → Astro /api/orders/stream (session check)
        → Axum /internal/user/orders/stream (Redis pub/sub)
                ↑
    Redis PUBLISH ← webhook handler (OTP received)
                  ← background task (order expired)
                  ← order action (created, canceled)

When an SMS webhook arrives with an OTP code, the handler updates the database and publishes an event to the user's Redis channel:

// Publish order event to Redis pub/sub
publish_order_event(&state, user_id, OrderEvent {
    order_id,
    status: "OTP_RECEIVED".into(),
    phone_number: Some(phone),
    otp_code: Some(code),
    otp_message: Some(message),
}).await;

The SSE handler subscribes to the user's channel and streams events as they arrive. The Astro layer validates the session cookie and proxies the stream, adding auth without exposing the internal Axum endpoint.

Fallback: If the SSE connection drops (tab backgrounded, network hiccup), the frontend falls back to polling. On reconnect, it polls once immediately to catch any events missed during the gap — because Redis pub/sub is fire-and-forget, events during a disconnection are lost.

This works across multiple Axum replicas because Redis pub/sub broadcasts to all subscribers. A webhook hitting replica A publishes to Redis, and the SSE connection on replica B receives it instantly.

Four Auth Layers

Different consumers need different auth mechanisms:

The internal auth uses a shared secret between Astro and Axum — only valid over the internal network (never exposed to the internet). Astro reads the session cookie, decrypts it (AES-256-GCM), and forwards the user identity in a separate header.

The admin auth uses a separate session store in Redis. Admin sessions carry permissions (role, permissions array), checked by the dashboard_auth middleware before any handler runs.

All key comparisons use constant-time comparison to prevent timing attacks. Password hashing uses argon2id via spawn_blocking — heavy CPU work runs on Tokio's blocking thread pool, keeping the async runtime responsive.

Monitoring

You can't run a financial platform blind. SMSCode exports metrics at two levels:

In-memory metrics — a custom Metrics struct using DashMap and ring buffers tracks per-endpoint latency (p50/p95/p99), provider call performance, cache hit rates, balance operations, and background task health. Exposed via /internal/metrics as JSON for the admin dashboard.

Prometheus metrics — standard counters and histograms (http_requests_total, http_request_duration_seconds, provider_api_calls_total, etc.) scraped by Prometheus every 15 seconds. Grafana dashboards visualize trends and AlertManager sends notifications to Telegram when thresholds are breached.

The monitoring stack runs on a separate LXC container from the application — if Axum crashes, monitoring stays up and alerts fire.

Infrastructure

Production runs on a single EPYC server with Proxmox VE, using LXC containers (not Docker):

LXC over Docker because: near-native performance, lower resource overhead, and systemd service management instead of Docker's restart policies. Each service (smscode-api, smscode-web, smscode-admin) is a systemd unit with proper dependency ordering and env file loading.

Traffic flows through Cloudflare (DDoS protection, TLS termination) → Cloudflare Tunnel → Traefik (routing) → the appropriate service. The only ports exposed to the internet are behind Cloudflare — the actual server IP is hidden.

VLAN segmentation isolates production from infrastructure. The monitoring container can scrape metrics from the app container, but not the other way around.

Deployment

Deployments are automated via a single script:

./scripts/deploy.sh api    # Build + deploy Axum
./scripts/deploy.sh web    # Build + deploy Astro
./scripts/deploy.sh admin  # Build + deploy Admin
./scripts/deploy.sh all    # All three

The script handles building (cross-compilation for Rust, bun run build for the frontends), uploading artifacts to the server, creating backups, restarting systemd services, and running health checks. If the health check fails, it rolls back automatically.

For the Rust binary, I build with --release on my local machine and scp the binary to the server. The binary is ~15MB and starts in milliseconds. Compare that to deploying a Node.js app with node_modules — it's a refreshingly simple deployment model.

Lessons from Production

After running this system in production, a few hard-won lessons:

Debit first, refund on failure. Never rely on a successful external API call before touching balances. Provider APIs are unreliable. Your database isn't. Debit the balance, call the provider, and refund if it fails. The alternative — reserving balance or deducting after — creates race conditions that are nearly impossible to reproduce in testing but trivial to trigger in production.

Three Redis instances, not one. The first time I needed to flush the rate limit store during a configuration change, I was glad sessions and cache were on separate instances. Isolation costs almost nothing and saves you from cascading failures.

Circuit breakers are essential. A failing SMS provider without a circuit breaker will eat your timeout budget across every request. With a circuit breaker, failures are detected in milliseconds after the circuit opens, and the system gracefully routes to other providers.

SSE with polling fallback. Pure SSE is fragile — browsers throttle background tabs, mobile connections drop, proxies have idle timeouts. Always have a polling fallback that activates seamlessly. Users don't care about the transport mechanism; they care that the OTP appears when it arrives.

Reconciliation tasks are non-negotiable. For anything financial, run periodic reconciliation. Our reconcile_balances task has never found a discrepancy — which tells me the atomic operations are correct. But the moment I remove it is the moment a bug will slip through.

Rust's compile times are the real cost. The initial build of the workspace takes ~2 minutes. Incremental rebuilds are 10-15 seconds. Coming from the instant feedback loop of Node.js, this requires an adjustment in workflow — I batch changes and think more carefully before compiling. But in exchange, when it compiles, it usually works.

What's Next

The platform is stable and handling production traffic at smscode.gg. Upcoming work includes:

• Horizontal scaling — the leader-elected task system already supports multiple replicas. Next step is load balancing across multiple Axum instances behind Traefik.
• More providers — the ProviderClient trait makes adding new SMS providers straightforward. Each new protocol is a separate module implementing the same trait.
• GraphQL for the admin — the admin panel currently makes many small REST calls. A GraphQL layer would let it fetch exactly the data it needs in a single request.

Building a production Rust service from scratch was a significant investment — but seeing SMSCode handle thousands of concurrent operations at 12MB of memory with sub-millisecond latency made every fight with the borrow checker worth it.

You can find my full tech stack here.

Thanks for reading!

In my self-hosted infrastructure post, I mentioned Cloudflare sitting in front of my services. What I didn't cover was how much work Cloudflare actually does beyond basic proxying — and how a zero trust model changed the way I think about network security entirely.

This post goes deeper into DNS management, Cloudflare's security stack, and the zero trust architecture that ties everything together.

DNS Fundamentals (That People Get Wrong)

Before diving into Cloudflare specifics, it's worth revisiting how DNS actually works — because most developers treat it like magic and then get surprised when things break.

DNS is a distributed, hierarchical database. When someone visits app.example.com, the query travels through multiple layers: root nameservers, TLD nameservers (.com), authoritative nameservers (yours or your provider's), and finally returns an IP address. Each layer caches the result based on TTL (time-to-live) values.

The most common mistake I see is setting TTLs too high during development. If you set a TTL of 86400 (24 hours) and then need to change a DNS record, you're waiting up to a full day for the change to propagate globally. During active development or migration, I keep TTLs at 300 seconds (5 minutes). Once everything is stable, I increase them.

# Check current DNS resolution and TTL
dig app.example.com +short
dig app.example.com +noall +answer

# Check propagation across different nameservers
dig @8.8.8.8 app.example.com    # Google DNS
dig @1.1.1.1 app.example.com    # Cloudflare DNS
dig @9.9.9.9 app.example.com    # Quad9

The other common mistake: not understanding the difference between record types. A records point to IPv4 addresses, AAAA to IPv6, CNAME is an alias to another domain (but can't be used at the zone apex), and MX handles email routing. Cloudflare adds proxy functionality on top — when a record is "proxied" (orange cloud), traffic goes through Cloudflare's network instead of directly to your server.

Cloudflare DNS Management

I manage all my domains through Cloudflare. The free tier alone gives you authoritative DNS with Anycast routing, DDoS protection, and a CDN. For a self-hosted setup, that's an incredible amount of value for zero cost.

My DNS setup follows a consistent pattern across all domains:

# Zone: example.com
# Root domain and www → main web server (proxied)
example.com        A      → Cloudflare Proxy → Origin Server
www                CNAME  → example.com (proxied)

# Subdomains for services (proxied)
app                A      → Cloudflare Proxy → Origin Server
api                A      → Cloudflare Proxy → Origin Server
status             A      → Cloudflare Proxy → Origin Server

# Internal services (DNS-only, accessed via Tailscale)
grafana            A      → Internal IP (DNS only, gray cloud)
proxmox            A      → Internal IP (DNS only, gray cloud)

# Email (MX records, never proxied)
@                  MX     → mail provider
@                  TXT    → SPF record
_dmarc             TXT    → DMARC policy

The key decision for each record is whether to proxy it through Cloudflare (orange cloud) or not (gray cloud). Proxied records get DDoS protection, caching, WAF, and hide your origin IP. DNS-only records expose the real IP. The rule is simple: proxy anything public, DNS-only for internal services.

For internal services, I point DNS records to Tailscale IPs. These are only resolvable and reachable from within the Tailscale network. Even if someone discovers the DNS record, the IP is useless without being on the mesh.

Automating DNS with Terraform

Managing DNS records through the Cloudflare dashboard works for a few records. Once you have dozens across multiple domains, it becomes error-prone. I use Terraform with the Cloudflare provider to manage everything as code.

# providers.tf
terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
  }
}

provider "cloudflare" {
  api_token = var.cloudflare_api_token
}

Each domain gets its own module:

# modules/example-com/main.tf
resource "cloudflare_zone" "main" {
  account_id = var.account_id
  zone       = "example.com"
}

resource "cloudflare_record" "root" {
  zone_id = cloudflare_zone.main.id
  name    = "@"
  content = var.origin_ip
  type    = "A"
  proxied = true
  ttl     = 1  # Auto TTL when proxied
}

resource "cloudflare_record" "app" {
  zone_id = cloudflare_zone.main.id
  name    = "app"
  content = var.origin_ip
  type    = "A"
  proxied = true
  ttl     = 1
}

resource "cloudflare_record" "grafana" {
  zone_id = cloudflare_zone.main.id
  name    = "grafana"
  content = var.tailscale_ip
  type    = "A"
  proxied = false  # Internal only
  ttl     = 300
}

Now DNS changes go through version control. I can review changes in a PR before applying them, and if something goes wrong, I roll back with terraform apply using a previous state. No more clicking around in dashboards wondering who changed what and when.

# Preview changes before applying
terraform plan

# Apply changes
terraform apply

# Oops, roll back
git revert HEAD && terraform apply

Cloudflare Tunnel: No Open Ports

This is the feature that changed my setup the most. Cloudflare Tunnel (formerly Argo Tunnel) creates an outbound-only connection from your server to Cloudflare's network. Traffic flows from visitors → Cloudflare → tunnel → your server. Your server never accepts inbound connections from the internet.

This means zero open ports on your firewall. No port 80, no port 443, nothing. The attack surface drops to essentially zero because there's nothing to scan or probe.

Setting up a tunnel:

# Install cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

# Authenticate with Cloudflare
cloudflared tunnel login

# Create a tunnel
cloudflared tunnel create my-server

# This generates a credentials file at:
# ~/.cloudflared/<tunnel-id>.json

The tunnel configuration maps public hostnames to internal services:

# ~/.cloudflared/config.yml
tunnel: my-server
credentials-file: /root/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: app.example.com
    service: http://localhost:8080
  - hostname: api.example.com
    service: http://localhost:3000
  - hostname: status.example.com
    service: http://localhost:9090
  # Catch-all rule (required)
  - service: http_status:404

Each hostname maps to a local service. Cloudflare handles TLS termination, so the tunnel connects to your services over plain HTTP internally. Traefik becomes optional for public services — though I still use it for internal routing and middleware.

I run cloudflared as a systemd service so it starts automatically and reconnects on failure:

cloudflared service install
systemctl enable cloudflared
systemctl start cloudflared

The DNS records for tunneled services use CNAME pointing to <tunnel-id>.cfargotunnel.com. Terraform handles this too:

resource "cloudflare_record" "app_tunnel" {
  zone_id = cloudflare_zone.main.id
  name    = "app"
  content = "${var.tunnel_id}.cfargotunnel.com"
  type    = "CNAME"
  proxied = true
}

Zero Trust: Trust Nothing, Verify Everything

Traditional network security works like a castle with a moat — everything outside the perimeter is untrusted, everything inside is trusted. The problem is obvious: once an attacker gets past the perimeter (phishing, compromised credentials, supply chain attack), they have access to everything.

Zero trust flips this model. No user, device, or network is inherently trusted. Every request must be authenticated and authorized, regardless of where it comes from. Even if you're on the "internal" network, you still prove who you are before accessing anything.

My zero trust stack has three layers:

Layer 1: Cloudflare Access

Cloudflare Access puts an authentication layer in front of any web application. Instead of exposing a login page to the internet and hoping your app's auth is bulletproof, Cloudflare handles authentication before the request ever reaches your server.

I protect internal dashboards like this:

# Cloudflare Access application
resource "cloudflare_access_application" "grafana" {
  zone_id          = cloudflare_zone.main.id
  name             = "Grafana"
  domain           = "grafana.example.com"
  session_duration = "24h"
}

# Access policy: only allow specific emails
resource "cloudflare_access_policy" "grafana_policy" {
  application_id = cloudflare_access_application.grafana.id
  zone_id        = cloudflare_zone.main.id
  name           = "Allow admins"
  precedence     = 1
  decision       = "allow"

  include {
    email = ["admin@example.com"]
  }
}

When someone visits grafana.example.com, Cloudflare intercepts the request and presents a login screen. They can authenticate via email OTP, Google, GitHub, or any other configured identity provider. Only after successful authentication does Cloudflare forward the request to the origin. The application itself never sees unauthenticated traffic.

This is particularly powerful for services that have weak or no built-in auth. I have some older tools that only support basic HTTP auth — putting Cloudflare Access in front of them gives me proper authentication without modifying the application.

Layer 2: Tailscale for Machine-to-Machine

While Cloudflare Access handles browser-based access, Tailscale handles machine-to-machine and SSH communication. Every device in my network has a Tailscale client installed, and they communicate over WireGuard-encrypted tunnels.

Tailscale ACLs (Access Control Lists) define who can reach what:

{
  "acls": [
    {
      "action": "accept",
      "src": ["group:admins"],
      "dst": ["tag:server:*"]
    },
    {
      "action": "accept",
      "src": ["tag:monitoring"],
      "dst": ["tag:server:9100"]
    },
    {
      "action": "accept",
      "src": ["tag:server"],
      "dst": ["tag:server:*"]
    }
  ],
  "groups": {
    "group:admins": ["user@example.com"]
  },
  "tagOwners": {
    "tag:server": ["group:admins"],
    "tag:monitoring": ["group:admins"]
  }
}

This ACL says: admins can reach any port on servers, the monitoring stack can only reach port 9100 (node_exporter) on servers, and servers can talk to each other. Everything else is denied by default.

The key insight is that these ACLs work at the network level. Even if a service has no authentication, it's only reachable by authorized devices. Defense in depth — the network enforces what the application might not.

Layer 3: Application-Level Auth

The innermost layer is application-level authentication. Even with Cloudflare Access and Tailscale ACLs, each service still has its own auth. If Cloudflare Access were somehow bypassed (configuration error, new network path), the application still requires valid credentials.

For services behind Cloudflare Access, I validate the Cf-Access-Jwt-Assertion header to ensure the request actually came through Access and wasn't somehow injected:

import jwt
import requests

# Cloudflare's public keys for JWT verification
CERTS_URL = "https://example.cloudflareaccess.com/cdn-cgi/access/certs"

def verify_cf_access_token(request):
    token = request.headers.get("Cf-Access-Jwt-Assertion")
    if not token:
        return False

    keys = requests.get(CERTS_URL).json()["public_certs"]
    for key in keys:
        try:
            decoded = jwt.decode(
                token,
                key=jwt.algorithms.RSAAlgorithm.from_jwk(key["cert"]),
                algorithms=["RS256"],
                audience="<your-audience-tag>"
            )
            return True
        except jwt.InvalidTokenError:
            continue
    return False

Three layers, three independent auth mechanisms. An attacker would need to bypass Cloudflare Access, be on the Tailscale network, and have valid application credentials. Each layer reduces the blast radius if another layer fails.

WAF & Security Rules

Cloudflare's Web Application Firewall runs on every proxied request. The managed rulesets catch common attacks — SQL injection, XSS, path traversal — without any configuration. But the real power is in custom rules.

I use custom WAF rules for patterns specific to my services:

# Block requests with suspicious user agents
(http.user_agent contains "sqlmap") or
(http.user_agent contains "nikto") or
(http.user_agent contains "nmap") → Block

# Rate limit API endpoints
(http.request.uri.path matches "^/api/") → Rate limit: 100 req/min per IP

# Block access to sensitive paths
(http.request.uri.path contains "/.env") or
(http.request.uri.path contains "/wp-admin") or
(http.request.uri.path contains "/.git") → Block

# Country-based restrictions for admin paths
(http.request.uri.path contains "/admin") and
(not ip.geoip.country in {"ID"}) → Block

The country-based rule is practical, not security theater. I know that all legitimate admin access comes from Indonesia. Blocking other countries for admin paths eliminates a massive amount of automated scanning noise. It's not a security boundary — it's a noise reduction filter.

Caching Strategy

Cloudflare's CDN caches static assets at edge locations worldwide. For a self-hosted setup, this means your server handles less traffic and users get faster responses regardless of their location.

My caching strategy:

# Page Rules (or Cache Rules in the new UI)

# Static assets: cache aggressively
*.example.com/assets/*     → Cache Everything, Edge TTL: 1 month
*.example.com/images/*     → Cache Everything, Edge TTL: 1 month
*.example.com/fonts/*      → Cache Everything, Edge TTL: 1 year

# API responses: never cache
api.example.com/*          → Bypass Cache

# HTML pages: short cache with revalidation
app.example.com/*          → Edge TTL: 1 hour, Browser TTL: 5 min

For my static sites (like this blog), I use the Cache Everything page rule with long edge TTLs. The site is rebuilt and deployed on each push, and I purge the Cloudflare cache as part of the deployment pipeline:

# Purge entire cache after deployment
curl -X POST "https://api.cloudflare.com/client/v4/zones/<zone-id>/purge_cache" \
  -H "Authorization: Bearer <api-token>" \
  -H "Content-Type: application/json" \
  --data '{"purge_everything": true}'

Putting It All Together

Here's how traffic flows through the stack for a public service:

User → Cloudflare DNS (Anycast)
     → Cloudflare Edge (WAF, DDoS, Cache)
     → Cloudflare Tunnel (encrypted, outbound-only)
     → Origin Server
     → Traefik (internal routing)
     → Docker Container

For an internal service accessed by an admin:

Admin → Cloudflare DNS
      → Cloudflare Access (authentication)
      → Cloudflare Tunnel
      → Origin Server
      → Service (validates CF Access JWT)

For SSH and machine-to-machine:

Admin Device → Tailscale (WireGuard mesh)
             → ACL Check
             → Target Server

No single layer is responsible for security. Each layer adds defense, and the failure of any one layer doesn't compromise the whole system. That's the core principle of zero trust — assume every layer will eventually fail, and design accordingly.

What I'd Do Differently

If I were starting over:

• Cloudflare Tunnel from day one. I spent months with open ports and Cloudflare proxy before discovering Tunnel. The reduction in attack surface is dramatic and the setup is simpler than managing firewall rules.
• Terraform from the start. Manual DNS management through dashboards doesn't scale. Once you have more than one domain, it's worth the initial investment to codify everything.
• Tighter Tailscale ACLs. I started with a permissive "*" rule and tightened over time. Starting tight and loosening is safer than starting loose and tightening.

Wrap Up

The combination of Cloudflare (DNS, Tunnel, Access, WAF) and Tailscale (mesh VPN, ACLs) gives you an enterprise-grade zero trust architecture for the cost of a few hours of setup. Most of Cloudflare's features are free, and Tailscale's free tier covers up to 100 devices.

The old model of "everything behind the firewall is safe" doesn't work anymore — it probably never did. Zero trust isn't just a buzzword. It's a fundamentally better way to think about network security: verify everything, trust nothing, and design for the assumption that every layer will eventually be compromised.

If you're running self-hosted services with open ports and no authentication layer beyond the application itself, start with Cloudflare Tunnel. It's the single highest-impact change you can make — zero open ports, automatic TLS, and DDoS protection in about 15 minutes of setup.

Thanks for reading!

I've been writing JavaScript and TypeScript for years. It's the language I think in, the ecosystem I know inside out. Node.js is what I reach for by default — fast to prototype, massive ecosystem, and good enough for most things.

But "good enough" has a ceiling. When I started building services that needed to handle tens of thousands of concurrent connections, process data with minimal latency, and run for months without memory creeping up — I started hitting that ceiling. That's when I picked up Rust.

This isn't a "Rust is better than Node" post. It's a practical walkthrough of what the transition actually looks like — the mental shifts, the code patterns, and the real tradeoffs — from someone who still writes TypeScript daily.

Why Rust?

The honest answer: performance and reliability.

Node.js is single-threaded by design. Yes, we have worker threads and the event loop handles I/O concurrently, but CPU-bound work blocks the main thread. For I/O-heavy web services, Node is excellent. For anything that involves heavy computation, data processing, or needs predictable low-latency responses — you feel the limits.

Rust gave me:

• No garbage collector — memory is freed deterministically, no GC pauses, no memory creep over long-running processes.
• True parallelism — real threads with zero-cost abstractions for concurrency.
• Compile-time guarantees — if it compiles, an entire class of bugs (null references, data races, use-after-free) simply cannot exist.
• Predictable performance — no JIT warmup, no deoptimization surprises. The performance you measure is the performance you get.

That said, Rust has a real learning curve. The first few weeks were humbling.

The Ownership Mental Model

The single biggest shift coming from JavaScript to Rust is ownership. In JavaScript, you don't think about who "owns" a value. Everything is garbage collected. You create objects, pass them around, and the runtime figures out when to clean them up.

In Rust, every value has exactly one owner. When the owner goes out of scope, the value is dropped. If you want to give a value to someone else, you move it — and the original variable becomes invalid.

fn main() {
    let name = String::from("hello");
    let greeting = name; // `name` is moved to `greeting`

    println!("{}", name); // ERROR: value used after move
}

In JavaScript, this would just work — both variables point to the same string, and the GC handles cleanup. In Rust, this is a compile-time error.

The first time you hit this, it feels like the compiler is fighting you. But there's a reason: Rust is preventing you from having two variables that could both try to free the same memory, or from reading data that another part of your code is modifying.

Borrowing: The Solution

Instead of moving values everywhere, Rust lets you borrow them — either as a shared reference (&T, read-only, multiple allowed) or a mutable reference (&mut T, exclusive, only one at a time).

fn greet(name: &str) {
    println!("Hello, {name}!");
}

fn main() {
    let name = String::from("Zevs");
    greet(&name);       // borrow `name` — we still own it
    println!("{name}"); // still valid, we only lent it out
}

The mental model that clicked for me: think of values like physical objects. You can hand someone a book to read (shared borrow), or hand it to them to write in (mutable borrow), but you can't let two people write in it at the same time. And if you give the book away (move), you don't have it anymore.

Coming from TypeScript where everything is a reference and mutation is unrestricted, this feels limiting at first. After a while, it starts feeling like a superpower — the compiler enforces discipline that you'd otherwise need extensive testing and code review to maintain.

Comparing HTTP Servers

Let's look at something concrete: building an HTTP server. This is where most Node developers start with Rust.

Express / Hono (TypeScript)

import { Hono } from 'hono'

interface User {
  id: number
  name: string
  email: string
}

const users: User[] = [
  { id: 1, name: 'Zevs', email: 'zevs@example.com' },
]

const app = new Hono()

app.get('/users', (c) => {
  return c.json(users)
})

app.get('/users/:id', (c) => {
  const id = Number(c.req.param('id'))
  const user = users.find(u => u.id === id)
  if (!user) {
    return c.json({ error: 'User not found' }, 404)
  }
  return c.json(user)
})

app.post('/users', async (c) => {
  const body = await c.req.json<Omit<User, 'id'>>()
  const user: User = {
    id: users.length + 1,
    ...body,
  }
  users.push(user)
  return c.json(user, 201)
})

export default app

Straightforward. Parse params, find data, return JSON. The TypeScript types give us editor support but no runtime guarantees — c.req.json<Omit<User, 'id'>>() doesn't actually validate the body at runtime.

Axum (Rust)

use axum::{
    extract::{Path, State, Json},
    http::StatusCode,
    response::IntoResponse,
    routing::{get, post},
    Router,
};
use serde::{Deserialize, Serialize};
use std::sync::{Arc, Mutex};

#[derive(Clone, Serialize, Deserialize)]
struct User {
    id: u32,
    name: String,
    email: String,
}

#[derive(Deserialize)]
struct CreateUser {
    name: String,
    email: String,
}

type AppState = Arc<Mutex<Vec<User>>>;

async fn list_users(
    State(users): State<AppState>,
) -> Json<Vec<User>> {
    let users = users.lock().unwrap();
    Json(users.clone())
}

async fn get_user(
    State(users): State<AppState>,
    Path(id): Path<u32>,
) -> impl IntoResponse {
    let users = users.lock().unwrap();
    match users.iter().find(|u| u.id == id) {
        Some(user) => Ok(Json(user.clone())),
        None => Err(StatusCode::NOT_FOUND),
    }
}

async fn create_user(
    State(users): State<AppState>,
    Json(input): Json<CreateUser>,
) -> impl IntoResponse {
    let mut users = users.lock().unwrap();
    let user = User {
        id: users.len() as u32 + 1,
        name: input.name,
        email: input.email,
    };
    users.push(user.clone());
    (StatusCode::CREATED, Json(user))
}

#[tokio::main]
async fn main() {
    let state: AppState = Arc::new(Mutex::new(vec![
        User {
            id: 1,
            name: "Zevs".into(),
            email: "zevs@example.com".into(),
        },
    ]));

    let app = Router::new()
        .route("/users", get(list_users).post(create_user))
        .route("/users/{id}", get(get_user))
        .with_state(state);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
        .await
        .unwrap();
    axum::serve(listener, app).await.unwrap();
}

More verbose, yes. But look at what you get for free:

• Thread-safe state — Arc<Mutex<Vec<User>>> is enforced by the compiler. You literally cannot share mutable state between handlers without proving it's safe.
• Deserialization with validation — Json<CreateUser> automatically deserializes and validates the request body. If a field is missing, Axum returns a 422 before your handler even runs.
• Type-safe path extraction — Path(id): Path<u32> extracts and parses the path parameter. If someone sends /users/abc, it returns a 400 automatically.
• Exhaustive pattern matching — the match in get_user forces you to handle both the found and not-found cases. You can't forget.

The Rust version is longer, but it handles edge cases that the TypeScript version silently ignores.

Error Handling: try/catch vs Result

In JavaScript, errors are thrown and (hopefully) caught:

async function fetchUser(id: number): Promise<User> {
  const res = await fetch(`/api/users/${id}`)
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`)
  }
  const data = await res.json()
  return data as User
}

// Caller must remember to try/catch
try {
  const user = await fetchUser(1)
  console.log(user.name)
}
catch (err) {
  console.error('Failed:', err)
}

The problem: nothing forces the caller to handle the error. Forget the try/catch, and the error propagates silently until it crashes your process or gets swallowed by a generic handler.

In Rust, errors are values, not exceptions:

use reqwest;
use serde::Deserialize;

#[derive(Deserialize)]
struct User {
    name: String,
}

async fn fetch_user(id: u32) -> Result<User, reqwest::Error> {
    let user = reqwest::get(format!("http://api/users/{id}"))
        .await?
        .error_for_status()?
        .json::<User>()
        .await?;
    Ok(user)
}

// Caller MUST handle the Result — the compiler enforces it
async fn main_logic() {
    match fetch_user(1).await {
        Ok(user) => println!("{}", user.name),
        Err(e) => eprintln!("Failed: {e}"),
    }
}

The ? operator is Rust's equivalent of await for errors — it propagates the error to the caller if it fails, or unwraps the success value if it succeeds. But unlike exceptions, the return type Result<User, reqwest::Error> makes it explicit that this function can fail. The compiler won't let you ignore it.

This was one of the things that immediately made me a better programmer. In TypeScript, I had to rely on discipline and code review to ensure errors were handled. In Rust, the type system does it for me.

Custom Error Types

In real applications, you usually define your own error types. With the thiserror crate, this is clean:

use thiserror::Error;

#[derive(Error, Debug)]
enum AppError {
    #[error("user {0} not found")]
    NotFound(u32),

    #[error("database error: {0}")]
    Database(#[from] sqlx::Error),

    #[error("request failed: {0}")]
    Request(#[from] reqwest::Error),

    #[error("unauthorized")]
    Unauthorized,
}

Every error variant is typed, carries context, and converts automatically from library errors via #[from]. Pattern matching on these errors gives you fine-grained control:

match do_something().await {
    Ok(result) => handle_success(result),
    Err(AppError::NotFound(id)) => return not_found(id),
    Err(AppError::Unauthorized) => return redirect_to_login(),
    Err(e) => {
        tracing::error!("unexpected error: {e}");
        return internal_error();
    }
}

Compare this to JavaScript where catch (err) gives you an unknown type and you're left guessing what went wrong with instanceof checks.

Async: Promises vs Futures

Both Node and Rust use async/await, but the underlying mechanics are fundamentally different.

In JavaScript, Promises are eager — they start executing immediately when created:

const promise = fetchUser(1) // Already running!
// ... do other stuff ...
const user = await promise // Wait for it to finish

In Rust, Futures are lazy — they do nothing until polled:

let future = fetch_user(1); // Nothing happens yet
// ... do other stuff ...
let user = future.await;    // NOW it starts executing

This laziness is actually an advantage. It means you can compose futures without accidentally triggering side effects. You build up a computation graph, and nothing runs until you explicitly drive it.

Concurrency Patterns

Running tasks concurrently in JavaScript:

// Run in parallel
const [users, posts] = await Promise.all([
  fetchUsers(),
  fetchPosts(),
])

// Race — first one wins
const result = await Promise.race([
  fetchFromPrimary(),
  fetchFromFallback(),
])

In Rust with Tokio:

// Run in parallel
let (users, posts) = tokio::join!(
    fetch_users(),
    fetch_posts(),
);

// Race — first one wins
tokio::select! {
    result = fetch_from_primary() => handle(result),
    result = fetch_from_fallback() => handle(result),
}

Similar syntax, but Rust's tokio::select! is more powerful — it cancels the losing future automatically, while JavaScript's Promise.race leaves the other promise running in the background.

Where Rust really shines is CPU-bound concurrency. In Node, you'd need worker threads:

// Node.js — worker threads for CPU work (cumbersome)
const { Worker } = require('node:worker_threads')

const worker = new Worker('./heavy-computation.js', {
  workerData: input,
})
worker.on('message', (result) => { /* ... */ })

In Rust, you just spawn a task on a thread pool:

// Rust — spawn blocking work on a thread pool
let result = tokio::task::spawn_blocking(move || {
    heavy_computation(input)
}).await?;

Or use rayon for data parallelism that automatically scales across all CPU cores:

use rayon::prelude::*;

// Process millions of items across all cores
let results: Vec<Output> = inputs
    .par_iter()
    .map(|item| process(item))
    .collect();

There's no JavaScript equivalent that's this simple and this fast.

The Type System

TypeScript's type system is structural and exists only at compile time — it's erased at runtime. Rust's type system is nominal and exists at every level, from compile time to the actual memory layout.

Enums: Rust's Secret Weapon

TypeScript has union types. Rust has algebraic data types (enums with data). This is, hands down, the feature I miss most when I go back to TypeScript.

// TypeScript: discriminated union
type ApiResponse
  = | { status: 'success', data: User }
    | { status: 'error', message: string }
    | { status: 'loading' }

function handle(response: ApiResponse) {
  switch (response.status) {
    case 'success':
      console.log(response.data.name)
      break
    case 'error':
      console.error(response.message)
      break
    case 'loading':
      console.log('Loading...')
      break
  }
}

// Rust: enum with data
enum ApiResponse {
    Success { data: User },
    Error { message: String },
    Loading,
}

fn handle(response: ApiResponse) {
    match response {
        ApiResponse::Success { data } => println!("{}", data.name),
        ApiResponse::Error { message } => eprintln!("{message}"),
        ApiResponse::Loading => println!("Loading..."),
    }
}

They look similar. But here's the difference: if you add a new variant to the Rust enum, the compiler immediately flags every match that doesn't handle it. In TypeScript, switch on a discriminated union won't warn you about missing cases by default (you need exhaustive-deps lint rules, and even then it's not bulletproof).

Rust enums are also how Option<T> and Result<T, E> work — they're not special language features, they're just enums:

enum Option<T> {
    Some(T),
    None,
}

enum Result<T, E> {
    Ok(T),
    Err(E),
}

This means null and errors are handled through the same pattern matching system as everything else. No special syntax, no special rules. It's elegant.

Traits vs Interfaces

TypeScript interfaces define a shape. Rust traits define behavior.

// TypeScript: interface
interface Serializable {
  serialize: () => string
}

class User implements Serializable {
  serialize(): string {
    return JSON.stringify(this)
  }
}

// Rust: trait
trait Serializable {
    fn serialize(&self) -> String;
}

impl Serializable for User {
    fn serialize(&self) -> String {
        serde_json::to_string(self).unwrap()
    }
}

The key difference: in Rust, you can implement traits for types you don't own. I can implement Serializable for String or Vec<u8> or any third-party type. In TypeScript, you can't retroactively make a class implement an interface without modifying it.

This extensibility is what makes Rust's ecosystem so composable. The serde crate (Rust's de facto serialization framework) works by implementing Serialize and Deserialize traits — and you can add support for any data format or any type without modifying either.

The Ecosystem: npm vs Cargo

Cargo is batteries-included in a way that npm isn't. Testing, formatting, linting, documentation generation — all built into the toolchain. No arguing about which test runner to use, no configuring formatters, no installing extra dev dependencies for basic workflows.

The crates I use most frequently:

• tokio — async runtime, the foundation everything else builds on
• axum — HTTP framework by the Tokio team
• serde + serde_json — serialization/deserialization
• sqlx — async database driver with compile-time SQL checking
• reqwest — HTTP client
• tracing — structured logging and diagnostics
• thiserror / anyhow — error handling
• clap — CLI argument parsing

The ecosystem is smaller than npm, but the quality bar is noticeably higher. Fewer packages to choose from, but less decision fatigue and fewer abandoned dependencies.

Performance: Real Numbers

I ran a simple benchmark on an identical API (JSON serialization, database query, response) on the same hardware:

Rust isn't just faster — it's a different class of performance. The 10x lower memory usage means I can run more services on the same hardware. The sub-millisecond p99 latency means tail latency doesn't exist. The instant cold start means serverless deployments are truly instant.

But these numbers only matter for specific workloads. For a blog, a CRUD app, or a prototype — the difference is irrelevant. Node is fast enough, and you ship weeks sooner.

When I Use Which

After working with both for a while, I've developed a simple decision framework:

I use Node.js / TypeScript when:

• Rapid prototyping and MVPs — nothing beats the iteration speed.
• Frontend + full-stack web apps — Nuxt, Astro, and the ecosystem are unmatched.
• Scripting and tooling — quick scripts, CLIs, build tools.
• The team is JavaScript-heavy — hiring and onboarding matter.

I use Rust when:

• High-throughput backend services — APIs handling thousands of RPS.
• Long-running processes — daemons, workers, queue consumers where memory stability matters.
• Data processing pipelines — parsing, transforming, aggregating large datasets.
• Systems-level work — anything touching the network stack, file systems, or needing fine-grained control.
• Performance-critical paths — the hot loop that everything else depends on.

In practice, my projects are often both. A TypeScript frontend with Nuxt, calling a Rust API service via Axum. Or a Node.js orchestration layer that delegates heavy lifting to Rust microservices. They complement each other well.

What I Wish I Knew Earlier

A few things that would have saved me weeks of frustration:

Don't fight the borrow checker. When the compiler rejects your code, it's usually pointing at a design issue, not a syntax issue. Instead of adding .clone() everywhere to make it compile, step back and think about who should own the data. The borrow checker is teaching you better architecture.

Start with String, not &str. Coming from JavaScript, you'll want to use owned types (String, Vec<T>, HashMap) everywhere at first. That's fine. You can optimize to borrowed types (&str, &[T]) later when you understand lifetimes better. Premature optimization of lifetimes is the root of all borrow checker frustration.

Use anyhow for applications, thiserror for libraries. anyhow::Result gives you ergonomic error handling without defining error types upfront — perfect for application code. thiserror gives you structured, typed errors — perfect for library code where callers need to match on error variants.

Read the clippy lints. cargo clippy isn't just a linter — it's a Rust teacher. Every suggestion comes with an explanation of why the alternative is better. Running clippy on my early Rust code was humbling but incredibly educational.

The Rust community is genuinely helpful. The Rust Users forum, the subreddit, and Discord are some of the most welcoming programming communities I've encountered. Don't hesitate to ask questions — everyone remembers fighting the borrow checker for the first time.

Conclusion

Learning Rust made me a better TypeScript developer. The concepts of ownership, explicit error handling, and thinking about data lifetimes — these are transferable ideas that improved how I write code in any language. I now think more carefully about who owns data, where mutations happen, and what errors a function can produce, even when writing JavaScript.

Rust isn't a replacement for Node.js in my workflow. It's an addition. A powerful tool for the problems where Node struggles — and there are more of those problems than I initially thought.

If you're a Node.js developer curious about Rust, my advice: start with a small project. Rewrite a CLI tool you already have, or build a simple API with Axum. The first week will be painful. By the third week, you'll start to feel the compiler working with you instead of against you. And by the first month, you'll wonder how you ever wrote concurrent code without the borrow checker watching your back.

You can find my full tech stack here.

Thanks for reading!

Every app on your phone is making network requests, processing data, and executing logic that you can't see. As developers, understanding what's happening behind the scenes isn't just curiosity — it's a critical skill for security research, debugging, and building better software.

This post covers my approach to Android reverse engineering using tools I use daily: Frida for runtime instrumentation, mitmproxy for traffic interception, and Jadx for static analysis. Everything here is for educational purposes — understanding how apps work so you can build more secure ones.

The Toolkit

Before diving in, here's the stack:

These tools complement each other. Jadx gives you the static picture — what the code looks like. Frida gives you the dynamic picture — what the code actually does at runtime. mitmproxy shows you what's going over the wire.

Static Analysis with Jadx

Every RE session starts with static analysis. Before you run anything, understand the codebase.

Decompiling the APK

Pull the APK from a device or download it, then open it in Jadx:

# Pull APK from connected device
adb shell pm path com.example.app
adb pull /data/app/.../base.apk ./target.apk

# Open in Jadx GUI
jadx-gui target.apk

Jadx decompiles DEX bytecode back to Java source. It's not perfect — obfuscated apps produce mangled class names like a.b.c.d — but it's usually readable enough to understand the architecture.

What to Look For

When I open an APK in Jadx, I focus on a few things:

1. Network layer — Find the HTTP client configuration. Most apps use OkHttp or Retrofit. Search for OkHttpClient, Interceptor, or Retrofit.Builder:

// Common pattern: custom OkHttp interceptor adding auth headers
public class AuthInterceptor implements Interceptor {
    @Override
    public Response intercept(Chain chain) {
        Request original = chain.request();
        Request request = original.newBuilder()
            .header("Authorization", "Bearer " + getToken())
            .header("X-Device-Id", getDeviceId())
            .build();
        return chain.proceed(request);
    }
}

This tells you what headers the app sends, how auth works, and what custom interceptors modify requests.

2. Certificate pinning — Search for CertificatePinner, TrustManager, or SSL. If the app pins certificates, you'll need to bypass this before mitmproxy can intercept traffic.

3. Encryption/signing — Look for request signing logic. Many apps sign API requests with HMAC or similar schemes. Search for Mac.getInstance, MessageDigest, Cipher, or Signature:

// Request signing pattern
public String signRequest(String path, String body, long timestamp) {
    String payload = path + body + timestamp;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(SECRET_KEY, "HmacSHA256"));
    byte[] hash = mac.doFinal(payload.getBytes());
    return Base64.encodeToString(hash, Base64.NO_WRAP);
}

Understanding the signing scheme is critical — without it, modified requests will be rejected by the server.

4. Obfuscation — Check proguard-rules.pro or look for patterns indicating obfuscation tools (ProGuard, R8, DexGuard). Heavy obfuscation means you'll rely more on dynamic analysis with Frida.

Traffic Interception with mitmproxy

Once you understand the app's network layer from static analysis, it's time to see real traffic.

Setup

mitmproxy acts as a proxy between the device and the internet. All HTTPS traffic flows through it, and you can inspect, modify, or replay requests.

# Start mitmproxy on your machine
mitmproxy --listen-port 8080

# Or use the web interface
mitmweb --listen-port 8080

Configure the Android device to use your machine as a proxy:

# Set proxy on connected device via ADB
adb shell settings put global http_proxy $(hostname -I | awk '{print $1}'):8080

# Install mitmproxy CA certificate on device
# Download from http://mitm.it on the device browser

For apps targeting Android 7+, user-installed CA certificates aren't trusted by default. You need to install the cert as a system CA, which requires root:

# Convert mitmproxy cert to Android system format
openssl x509 -inform PEM -subject_hash_old \
  -in ~/.mitmproxy/mitmproxy-ca-cert.pem | head -1
# Output: c8750f0d (example hash)

cp ~/.mitmproxy/mitmproxy-ca-cert.pem c8750f0d.0

# Push to device system cert store (requires root)
adb root
adb remount
adb push c8750f0d.0 /system/etc/security/cacerts/
adb shell chmod 644 /system/etc/security/cacerts/c8750f0d.0
adb reboot

What You See

With mitmproxy running, every API call the app makes is visible:

POST https://api.example.com/v2/feed
    Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
    X-Device-Id: a1b2c3d4-e5f6-7890
    X-Request-Sign: Kx8mNpQ2r1...
    Content-Type: application/json

    {"page": 1, "limit": 20, "filter": "trending"}

You can see the exact headers, request body, response, timing, and status codes. This is invaluable for understanding API contracts that aren't documented.

Scripting with mitmproxy

mitmproxy supports Python scripts for automating analysis. For example, logging all API endpoints and their parameters:

# log_endpoints.py
from mitmproxy import http

def response(flow: http.HTTPFlow):
    if "api.example.com" in flow.request.pretty_host:
        print(f"{flow.request.method} {flow.request.path}")
        print(f"  Status: {flow.response.status_code}")
        print(f"  Request size: {len(flow.request.content)} bytes")
        print(f"  Response size: {len(flow.response.content)} bytes")
        print()

mitmproxy -s log_endpoints.py

You can also modify requests on the fly — change parameters, swap tokens, or inject headers to test how the server responds.

Dynamic Instrumentation with Frida

This is where the real magic happens. Frida lets you inject JavaScript into a running process, hook any function, read and modify arguments, and change return values — all without modifying the APK.

Setup

Install Frida on your machine and push the Frida server to the device:

# Install Frida CLI tools
pip install frida-tools

# Download frida-server for your device architecture
# Push to device
adb push frida-server-16.x.x-android-arm64 /data/local/tmp/frida-server
adb shell chmod 755 /data/local/tmp/frida-server

# Start frida-server (requires root)
adb shell su -c '/data/local/tmp/frida-server &'

Verify it's running:

frida-ps -U  # List processes on USB device

Bypassing SSL Pinning

The first thing you'll want to do is bypass certificate pinning so mitmproxy can intercept traffic. This is the most common Frida use case:

// ssl_bypass.js
Java.perform(() => {
  // Bypass OkHttp CertificatePinner
  const CertificatePinner = Java.use('okhttp3.CertificatePinner')
  CertificatePinner.check.overload(
    'java.lang.String',
    'java.util.List'
  ).implementation = function (hostname, peerCertificates) {
    console.log(`[*] Bypassing pin for: ${hostname}`)
    // Do nothing — skip the pin check
  }

  // Bypass custom TrustManager
  const TrustManagerImpl = Java.use('com.android.org.conscrypt.TrustManagerImpl')
  TrustManagerImpl.verifyChain.implementation = function () {
    console.log('[*] Bypassing TrustManager verification')
    return arguments[0] // Return the unverified chain
  }
})

frida -U -l ssl_bypass.js -f com.example.app

The -f flag spawns the app fresh with Frida attached from the start, which is important for intercepting early network calls.

Hooking Functions

The real power of Frida is hooking arbitrary functions. Say you found an interesting method in Jadx:

// Found in Jadx: com.example.app.crypto.RequestSigner
public class RequestSigner {
    public String sign(String path, String body, long timestamp) {
        // ... signing logic
    }
}

You can hook it to see exactly what's being signed:

// hook_signer.js
Java.perform(() => {
  const Signer = Java.use('com.example.app.crypto.RequestSigner')

  Signer.sign.implementation = function (path, body, timestamp) {
    console.log('[*] sign() called')
    console.log(`    path: ${path}`)
    console.log(`    body: ${body}`)
    console.log(`    timestamp: ${timestamp}`)

    // Call the original method
    const result = this.sign(path, body, timestamp)
    console.log(`    signature: ${result}`)

    return result
  }
})

Every time the app signs a request, you see the inputs and output in your terminal. This is how you reverse-engineer proprietary signing schemes.

Modifying Behavior

Frida can also change how functions behave:

// Force a function to always return true
Java.perform(() => {
  const Auth = Java.use('com.example.app.auth.AuthManager')

  Auth.isLoggedIn.implementation = function () {
    console.log('[*] isLoggedIn() → forcing true')
    return true
  }

  // Change a parameter before it reaches the original function
  Auth.validateToken.implementation = function (token) {
    console.log(`[*] Original token: ${token}`)
    // Call original with modified token
    return this.validateToken('modified_token_here')
  }
})

Tracing and Discovery

When you don't know which function to hook, Frida can trace entire classes:

// trace_class.js — log every method call on a class
Java.perform(() => {
  const target = Java.use('com.example.app.api.ApiClient')
  const methods = target.class.getDeclaredMethods()

  methods.forEach((method) => {
    const name = method.getName()
    const overloads = target[name].overloads

    overloads.forEach((overload) => {
      overload.implementation = function () {
        const args = Array.from(arguments).map((a) => {
          return a ? a.toString() : 'null'
        })
        console.log(`[*] ${name}(${args.join(', ')})`)
        return this[name].apply(this, arguments) // eslint-disable-line prefer-spread
      }
    })
  })
})

This is like setting a breakpoint on every method in a class — you see the call sequence, arguments, and can narrow down to the specific function you care about.

Objection: Frida Made Easy

Objection is a toolkit built on top of Frida that provides common RE tasks as simple commands:

# Start objection on a running app
objection -g com.example.app explore

Once inside the Objection REPL:

# Disable SSL pinning (one command)
android sslpinning disable

# List all activities
android hooking list activities

# List methods in a class
android hooking list class_methods com.example.app.api.ApiClient

# Hook a method and watch calls
android hooking watch class_method com.example.app.api.ApiClient.sendRequest

# Dump the keystore
android keystore list

# Search for classes containing "Crypto"
android hooking search classes Crypto

# Dump shared preferences
android hooking get_current_activity

Objection is perfect for exploration. When you know what you're looking for, write custom Frida scripts. When you're exploring, use Objection.

uiautomator2: UI Automation

Sometimes you need to automate the app's UI — navigate screens, tap buttons, scroll feeds — while your Frida hooks and mitmproxy capture data.

uiautomator2 is a Python library for Android UI automation:

import uiautomator2 as u2

# Connect to device
d = u2.connect()

# Launch app
d.app_start('com.example.app')

# Wait for element and tap
d(text="Sign In").click()

# Type text
d(resourceId="com.example.app:id/email").set_text("test@example.com")

# Scroll
d.swipe_ext("up", scale=0.8)

# Screenshot
d.screenshot("screen.png")

# Get element info
info = d(resourceId="com.example.app:id/balance").info
print(f"Balance text: {info['text']}")

Combined with Frida hooks, this creates a powerful pipeline: automate user flows in the UI while capturing every API call and function invocation happening underneath.

A Complete RE Workflow

Here's how I approach reverse engineering an Android app from scratch:

Phase 1: Reconnaissance

# Pull the APK
adb pull $(adb shell pm path com.example.app | cut -d: -f2) target.apk

# Decompile with Jadx
jadx-gui target.apk

In Jadx, I map out:

• The network layer (HTTP client, interceptors, base URLs)
• Authentication mechanism (token storage, refresh logic)
• Request signing (if any)
• Certificate pinning implementation
• Interesting business logic classes

Phase 2: Traffic Analysis

# Start mitmproxy
mitmweb --listen-port 8080

# Configure device proxy
adb shell settings put global http_proxy <host_ip>:8080

# If the app uses SSL pinning, bypass with Frida first
frida -U -l ssl_bypass.js -f com.example.app

Browse the app normally and observe the traffic in mitmproxy. Document:

• All API endpoints and their request/response format
• Authentication headers and how tokens are structured
• Any request signing or encryption patterns
• Rate limiting behavior

Phase 3: Deep Dive with Frida

Based on what I found in Phase 1 and 2, I write targeted Frida hooks:

Java.perform(() => {
  // Hook the request signing function found in Jadx
  const Signer = Java.use('com.example.app.crypto.RequestSigner')
  Signer.sign.implementation = function (path, body, ts) {
    console.log(`[sign] ${path}`)
    console.log(`  body: ${body.substring(0, 100)}`)
    console.log(`  ts: ${ts}`)
    const result = this.sign(path, body, ts)
    console.log(`  sig: ${result}`)
    return result
  }

  // Hook SharedPreferences to see what's being stored
  const SP = Java.use('android.app.SharedPreferencesImpl$EditorImpl')
  SP.putString.implementation = function (key, value) {
    console.log(`[prefs] ${key} = ${value}`)
    return this.putString(key, value)
  }
})

Phase 4: Documentation

This is the most important step that most people skip. Document everything:

• API endpoint map with request/response schemas
• Authentication flow diagram
• Request signing algorithm
• Interesting findings and potential vulnerabilities

Without documentation, you'll forget everything within a week and have to redo the analysis.

Security Lessons

Reverse engineering apps taught me more about building secure software than any security course. Here are patterns I see repeatedly:

Client-side validation is not validation. Every check that happens on the client can be bypassed with Frida. Price checks, quantity limits, feature flags — if the server doesn't enforce it, it doesn't exist.

Hardcoded secrets are always found. API keys, signing secrets, encryption keys embedded in the APK — Frida can dump them at runtime even if they're obfuscated in the binary. Use server-side key management.

Certificate pinning is a speed bump, not a wall. It takes roughly 30 seconds to bypass standard certificate pinning with Frida or Objection. It's still worth implementing — it raises the bar — but don't rely on it as your sole security measure.

Obfuscation slows analysis, it doesn't prevent it. ProGuard renames classes, but the logic is the same. DexGuard adds more layers, but Frida hooks at the JVM level, bypassing bytecode obfuscation entirely. Focus your security budget on server-side hardening.

The real security boundary is the server. Every request from the client should be treated as potentially malicious. Validate everything server-side: authentication, authorization, input validation, rate limiting, business logic constraints. The client is untrusted territory.

Ethics and Legality

A note on responsible use. The techniques in this post are powerful — and with power comes responsibility.

Authorized use only. Only reverse engineer apps you own, have permission to test, or are participating in a legitimate bug bounty program for. Unauthorized access to computer systems is illegal in most jurisdictions.

Responsible disclosure. If you find vulnerabilities, report them to the developer through their security contact or bug bounty program. Don't exploit them, don't publish exploit code, and give the developer reasonable time to fix issues before any public disclosure.

Educational context. Understanding how apps work makes you a better developer and a better security engineer. The goal is to build more secure software — not to break existing ones.

Wrap Up

Reverse engineering is a skill that compounds. The more apps you analyze, the faster you recognize patterns — the same OkHttp interceptor setup, the same JWT structure, the same HMAC signing scheme. What takes hours at first becomes minutes with experience.

The tools in this post — Frida, mitmproxy, Jadx, Objection — cover 95% of what you'll need for Android RE. The remaining 5% is native code analysis (IDA Pro, Ghidra) for apps with C/C++ libraries, which is a topic for another post.

If you're a developer who has never looked at their own app from the attacker's perspective, I'd encourage you to try. Install mitmproxy, set up Frida, and see what your app looks like from the outside. You might be surprised.

You can find my full tech stack here.

Thanks for reading!

There's a moment every developer hits — you're paying $50/month for a handful of small VPS instances, your services are scattered across three different cloud providers, and you realize you have no idea where half your stuff is running. That was me two years ago. Today, everything runs on hardware I own, in a setup I fully control.

This post walks through how I built my self-hosted infrastructure from the ground up — the decisions, the stack, and the lessons I picked up along the way.

Why Self-Host?

The obvious answer is cost. Running a few services on cloud VPS instances is cheap, but once you start stacking databases, queues, monitoring, storage, and multiple apps — costs add up fast. A single bare-metal server can replace several cloud instances for a fraction of the recurring cost.

But cost isn't the real reason. Control is. When you self-host, you own the data, you own the network, and you decide the rules. No vendor lock-in, no surprise pricing changes, no arbitrary rate limits. If something breaks, it's on you — but at least you can actually fix it.

There's also the learning aspect. Managing your own infrastructure teaches you things that no tutorial or managed service ever will. DNS propagation, firewall rules, disk I/O bottlenecks, certificate renewal failures at 3 AM — these are the experiences that make you a better engineer.

The Hardware Layer

Everything starts with Proxmox, an open-source virtualization platform built on top of Debian. It gives you a clean web UI for managing virtual machines and containers, with support for clustering, live migration, and backups out of the box.

I run Proxmox on a dedicated server with enough RAM and cores to comfortably host 20+ services. The storage backend is ZFS — a filesystem that handles compression, snapshots, and data integrity verification natively. ZFS snapshots are incredibly useful for rollbacks. Before any risky upgrade, I snapshot the dataset, and if things go wrong, I can roll back in seconds.

# Create a snapshot before upgrading
zfs snapshot rpool/data/myservice@pre-upgrade

# Something went wrong? Roll back instantly
zfs rollback rpool/data/myservice@pre-upgrade

For lightweight services, I use LXC containers instead of full VMs. LXC gives you near-native performance with process-level isolation — perfect for running databases, reverse proxies, or any service that doesn't need a full kernel. The resource overhead is minimal compared to a VM.

My general rule: LXC for infrastructure services, Docker for application workloads. This keeps things clean and separable.

Container Orchestration

Most of my application workloads run in Docker containers, orchestrated with Docker Compose. For the scale I operate at, Compose hits the sweet spot — declarative, version-controlled, and simple enough that I can understand exactly what's running without consulting a dashboard.

A typical service looks like this:

# docker-compose.yml
services:
  app:
    image: ghcr.io/my-org/my-app:latest
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/app
      REDIS_URL: redis://redis:6379
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=Host(`app.example.com`)
      - traefik.http.routers.app.tls.certresolver=cloudflare
    networks:
      - traefik
      - internal

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - internal

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    networks:
      - internal

volumes:
  pgdata:

networks:
  traefik:
    external: true
  internal:

The pattern is consistent across all services: the app connects to an external Traefik network for ingress, while databases and caches live on an internal network that's not exposed. Labels on the app container tell Traefik how to route traffic — no separate config files to maintain.

I also use Kubernetes for workloads that need horizontal scaling or more sophisticated scheduling. But honestly, for most self-hosted scenarios, Docker Compose is more than enough. K8s introduces significant operational complexity that's only worth it when you genuinely need it.

Reverse Proxy & SSL

Traefik is the centerpiece of my ingress layer. It automatically discovers services via Docker labels, handles TLS termination, and manages certificate renewal — all without manual intervention.

The Traefik configuration is minimal:

# traefik.yml
entryPoints:
  web:
    address: ':80'
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ':443'

certificatesResolvers:
  cloudflare:
    acme:
      email: admin@example.com
      storage: /letsencrypt/acme.json
      dnsChallenge:
        provider: cloudflare

providers:
  docker:
    exposedByDefault: false
    network: traefik

api:
  dashboard: true

Every new service I deploy gets automatic HTTPS with zero extra configuration. I just add the Traefik labels to the Docker Compose file, and Traefik picks it up within seconds. The DNS challenge via Cloudflare means I can issue wildcard certificates and don't need to expose port 80 for HTTP challenges.

Cloudflare also sits in front as a CDN and DDoS protection layer. DNS records point to Cloudflare, which proxies traffic to my server. This keeps my actual server IP hidden and adds an extra layer of caching for static assets.

Networking

This is where things get interesting. My network setup has evolved significantly over time.

At the edge, I run pfSense as my primary firewall. It handles VLAN segmentation, NAT, and firewall rules. I separate my network into multiple VLANs — management, servers, IoT devices, and guest traffic are all isolated from each other. A compromised IoT device shouldn't be able to reach my server VLAN, and guest WiFi shouldn't see anything on my internal network.

UniFi access points and switches handle the physical layer. The UniFi controller runs as an LXC container on Proxmox, managing all network hardware from a single interface. Say what you will about Ubiquiti's pricing, but the management experience is hard to beat for a home/small office setup.

For remote access, Tailscale is a game-changer. It creates a WireGuard-based mesh VPN that connects all my devices — laptops, phones, servers — into a single private network, regardless of where they physically are. No port forwarding, no dynamic DNS, no VPN server to maintain.

# Access my home server from anywhere
ssh user@server  # Just works, over Tailscale

# Access internal services without exposing them publicly
curl http://grafana:3000  # Only accessible via Tailscale network

Services that don't need to be public — like Grafana, Proxmox UI, or internal admin panels — are only accessible through Tailscale. This drastically reduces the attack surface. The only ports exposed to the internet are 80 and 443, both behind Cloudflare.

Monitoring & Observability

Running your own infrastructure without monitoring is like driving at night with the headlights off. Prometheus scrapes metrics from every service, and Grafana turns those metrics into dashboards I can actually understand.

Every Docker host runs node_exporter and cadvisor for system and container metrics. Application services expose custom Prometheus endpoints where relevant. Prometheus collects everything and stores it with configurable retention.

# prometheus.yml
scrape_configs:
  - job_name: node
    static_configs:
      - targets:
          - 'node-exporter:9100'

  - job_name: cadvisor
    static_configs:
      - targets:
          - 'cadvisor:8080'

  - job_name: traefik
    static_configs:
      - targets:
          - 'traefik:8080'

I have Grafana dashboards for CPU/memory/disk usage, container health, network throughput, and Traefik request rates. AlertManager sends notifications to Telegram when something goes wrong — disk usage above 85%, a container restarting in a loop, or Traefik returning too many 5xx errors.

The monitoring stack itself runs on a separate LXC container so it stays up even if the Docker host has issues. You don't want your monitoring to go down at the same time as the thing it's monitoring.

Backup Strategy

The one thing I've learned the hard way: backups that aren't tested are not backups.

My strategy is layered:

1. ZFS snapshots — automatic hourly snapshots with 7-day retention. Instant rollback for filesystem-level issues.
2. Application-level backups — PostgreSQL pg_dump runs nightly via cron, compressed and stored on a separate ZFS dataset.
3. Off-site replication — critical data is synced to MinIO on a separate machine using rclone, and the most important stuff goes to an off-site location.

# Nightly database backup via cron
0 3 * * * pg_dump -Fc mydb > /backups/mydb-$(date +\%Y\%m\%d).dump
# Sync to MinIO
0 4 * * * rclone sync /backups minio:backups --min-age 1h

I test restores quarterly. It's tedious, but the one time you need a backup and it doesn't work, you'll wish you had tested it.

Provisioning with Ansible

When I started, I configured everything manually — SSH in, install packages, edit config files. That works for one server. It doesn't work when you need to rebuild or replicate.

Ansible handles all server provisioning now. Every package, every config file, every cron job is defined in playbooks. If my server dies tomorrow, I can spin up a new Proxmox host and have everything running again by executing a single command.

ansible-playbook -i inventory site.yml

The playbooks cover base system setup, Docker installation, Traefik configuration, monitoring stack deployment, firewall rules, and user management. It's not glamorous work, but it's the difference between a one-hour recovery and a two-day scramble.

Lessons Learned

After running this setup for a while, a few things stand out:

Start simple. Don't build the perfect infrastructure on day one. Start with Docker Compose on a single server. Add complexity only when you hit real limitations, not imagined ones.

Automate early. The second time you manually configure something, write an Ansible playbook for it. Your future self will thank you.

Network segmentation matters. VLANs and firewall rules feel like overkill until you have a security incident. It's much easier to set up segmentation from the start than to retrofit it later.

Monitor everything, alert selectively. Collect all the metrics you can, but only alert on things that require immediate action. Alert fatigue is real and dangerous.

Document your setup. Not for others — for yourself in six months when you've forgotten why that one iptables rule exists. I keep a private wiki with network diagrams, service inventories, and runbooks for common operations.

What's Next

The infrastructure is never really "done." I'm currently exploring moving more workloads to Kubernetes for better resource utilization and looking into GitOps workflows with Flux or ArgoCD for automated deployments. I'm also considering adding a secondary node for Proxmox clustering to enable live migration and high availability.

But for now, this setup handles everything I throw at it — multiple web apps, databases, queues, monitoring, and storage — all on hardware I own, running software I control. It's not perfect, but it's mine.

If you're thinking about self-hosting, my advice is simple: just start. Pick one service you're currently paying for in the cloud, spin up a cheap used server or a mini PC, and move it over. You'll learn more in a weekend than in a month of reading documentation.

Thanks for reading!

I spend most of my working hours in the terminal. Over the years, my setup has gone through many iterations — from the default Bash on Ubuntu, to iTerm2 with Oh My Zsh, to a heavily customized Kitty setup. Each time, I thought I'd found the endgame. I never had.

This post documents my current terminal setup as of early 2026, running on Fedora 43. It's fast, minimal, and — most importantly — stays out of my way.

Ghostty

Ghostty is my terminal emulator. Built by Mitchell Hashimoto (the creator of Vagrant, Terraform, and many others at HashiCorp), Ghostty is GPU-accelerated, written in Zig, and genuinely feels like it was designed by someone who uses a terminal 12 hours a day.

What sold me on Ghostty over alternatives like Kitty or Alacritty:

• Native splits and tabs — no need for tmux just to have panes (though I still use tmux for sessions).
• Fast — rendering is buttery smooth even with large scrollback.
• Sane defaults — most things work well out of the box. The config file is minimal.
• Native GTK on Linux — it feels like a proper GNOME app, not an electron wrapper.

My config is straightforward:

# Font
font-family = "JetBrainsMono Nerd Font"
font-size = 12.5

# Theme
theme = "TokyoNight"
window-theme = "ghostty"

# Padding
window-padding-x = 12
window-padding-y = 8
window-padding-balance = true

# Shell
command = "/usr/bin/zsh"

# Cursor
cursor-style = "block"
cursor-style-blink = true

# Scrollback
scrollback-limit = 1000000

# Misc
mouse-hide-while-typing = true
copy-on-select = true
unfocused-split-opacity = 0.85

The TokyoNight theme runs consistently across Ghostty, tmux, and my editor — having a unified color scheme across tools removes a surprising amount of visual friction.

For keybindings, I use Ghostty's built-in splits alongside tmux. Ghostty splits (Ctrl+Super+R/D) for quick side-by-side work, tmux sessions for persistent workspaces that survive terminal restarts:

# Splits
keybind = "ctrl+super+r=new_split:right"
keybind = "ctrl+super+d=new_split:down"
keybind = "ctrl+super+z=toggle_split_zoom"

# Split navigation
keybind = "alt+shift+left=goto_split:left"
keybind = "alt+shift+right=goto_split:right"
keybind = "alt+shift+up=goto_split:up"
keybind = "alt+shift+down=goto_split:down"

# Tab navigation
keybind = alt+1=goto_tab:1
keybind = alt+2=goto_tab:2
keybind = alt+3=goto_tab:3

Zsh + Zinit

I use Zsh as my shell, managed with Zinit as the plugin manager. I moved away from Oh My Zsh as a framework a while ago — it's great for getting started, but loading the full framework adds noticeable startup latency. With Zinit, I cherry-pick only the OMZ snippets I actually need.

My plugin setup:

# Plugin manager
source "${ZINIT_HOME}/zinit.zsh"

# Completions (load before compinit)
zinit light zsh-users/zsh-completions

# Oh My Zsh snippets — only what I use
zinit snippet OMZP::git
zinit snippet OMZP::sudo
zinit snippet OMZP::docker
zinit snippet OMZP::docker-compose
zinit snippet OMZP::node
zinit snippet OMZP::python
zinit snippet OMZP::command-not-found

# Initialize completion
autoload -Uz compinit && compinit

# fzf-tab (must be after compinit)
zinit light Aloxaf/fzf-tab

# Autosuggestions, then syntax highlighting (order matters)
zinit light zsh-users/zsh-autosuggestions
zinit light zsh-users/zsh-syntax-highlighting

The three plugins that make the biggest difference in daily usage:

• zsh-autosuggestions — suggests commands as you type based on history. Accept with right arrow. Once you're used to this, you can't go back.
• zsh-syntax-highlighting — colors valid commands green and invalid ones red as you type, before hitting enter. Catches typos instantly.
• fzf-tab — replaces the default tab completion with a fuzzy finder. Combined with fzf-preview, it shows directory contents while you're navigating.

# fzf-tab: preview directories while completing
zstyle ':fzf-tab:complete:cd:*' fzf-preview 'ls --color $realpath'
zstyle ':fzf-tab:complete:__zoxide_z:*' fzf-preview 'ls --color $realpath'

History is configured to deduplicate and share across sessions:

HISTSIZE=5000
HISTFILE="$HOME/.zsh_history"
SAVEHIST=$HISTSIZE
setopt appendhistory sharehistory
setopt hist_ignore_all_dups hist_save_no_dups

Starship Prompt

Starship is a cross-shell prompt written in Rust. It's fast (sub-millisecond rendering), configurable, and shows contextual information based on the current directory — git branch, language versions, Docker context, command duration.

My prompt format keeps the left side clean (directory + git) and pushes language/tool indicators to the right using a fill:

format = """
$directory\
$git_branch\
$git_status\
$fill\
$python$nodejs$golang$rust$docker_context\
$cmd_duration\
$line_break\
$character"""
add_newline = false
palette = 'nord'

I use the Nord color palette for the prompt, which pairs well with the TokyoNight terminal theme — both are cool-toned and low-contrast enough to not be distracting.

A few tweaks that matter:

[directory]
truncation_length = 3
truncation_symbol = '…/'
truncate_to_repo = false

[cmd_duration]
min_time = 500
style = 'fg:gray'

The cmd_duration module shows elapsed time for any command that takes longer than 500ms. Useful for noticing when a build or test run took longer than expected.

tmux

tmux handles session persistence. If my terminal crashes or I close the window, my sessions survive. I can also detach from a session on my desktop and reattach from SSH on my laptop — the session state is preserved.

I rebind the prefix to Ctrl+Space instead of the default Ctrl+B:

unbind C-b
set -g prefix C-Space
bind C-Space send-prefix

Pane navigation is bound to Alt+Arrows (no prefix needed), and new splits inherit the current working directory:

# Pane navigation without prefix
bind -n M-Left  select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up    select-pane -U
bind -n M-Down  select-pane -D

# Keep cwd for new panes/windows
bind '"' split-window -v -c "#{pane_current_path}"
bind % split-window -h -c "#{pane_current_path}"
bind c new-window -c "#{pane_current_path}"

The Tokyo Night tmux theme keeps the status bar consistent with the rest of the setup. I disable the clock and git indicator to keep it minimal — Starship already handles those.

CLI Tools

These are the tools that replaced standard Unix utilities in my workflow:

eza

eza replaces ls. Git-aware, icons, tree view, and color-coded output. I alias ls to it globally:

alias ls='eza --icons'
alias ll='eza -l --icons'
alias la='eza -la --icons'
alias lt='eza --tree --icons --level=2'
alias lg='eza -l --git --icons'

The lg alias is particularly useful — it shows git status per-file inline with the listing.

bat

bat replaces cat. Syntax highlighting, line numbers, git diff integration. Aliased to cat because there's zero reason to use plain cat for reading files.

alias cat='bat'

fzf

fzf is a fuzzy finder that integrates with everything — shell history (Ctrl+R), file search (Ctrl+T), directory navigation, and tab completion via fzf-tab. It's one of those tools that once you internalize the keybindings, you wonder how you ever lived without it.

zoxide

zoxide replaces cd. It tracks the directories you visit and lets you jump to them with partial matches. Instead of typing cd ~/workspace/projects/my-app, I just type cd my-app and zoxide figures out the rest.

# Replaces cd with zoxide's smart jump
eval "$(zoxide init --cmd cd zsh)"

uv

uv is a Python package manager written in Rust. It's absurdly fast — installing packages feels instant compared to pip. I use it for all Python work now.

The Full Picture

Here's how everything fits together:

Ghostty (GPU-accelerated terminal)
  └─ Zsh (shell)
       ├─ Zinit (plugin manager)
       │    ├─ zsh-autosuggestions
       │    ├─ zsh-syntax-highlighting
       │    └─ fzf-tab
       ├─ Starship (prompt)
       ├─ tmux (session management)
       └─ CLI tools
            ├─ eza (ls)
            ├─ bat (cat)
            ├─ fzf (fuzzy finder)
            ├─ zoxide (cd)
            └─ uv (python packages)

The entire setup initializes in under 100ms. Zsh startup is fast because Zinit lazy-loads most plugins, Starship renders the prompt in single-digit milliseconds, and Ghostty's GPU rendering means there's never a visible lag between keypress and output.

What I'd Change

No setup is perfect. A few things I'm still iterating on:

• Neovim integration — I use VS Code as my primary editor, but I keep meaning to build out a proper Neovim config for remote editing over SSH where VS Code feels heavy.
• Dotfiles management — My configs are currently just files on disk. I should probably set up a proper dotfiles repo with symlink management via stow or chezmoi.
• Shell startup profiling — Zsh startup is fast enough, but I haven't profiled it in a while. There might be low-hanging fruit I'm missing.

Wrap Up

A terminal setup is deeply personal — what works for me might feel wrong to you. The key is to invest time in tools you use every day. Small optimizations in your terminal workflow compound over thousands of hours of use. A 2-second save on a command you run 50 times a day is nearly 10 hours saved per year.

If you're still on the default terminal with default Bash, I'd encourage you to try just one thing from this post. Start with Starship or eza — they're drop-in replacements that require zero commitment. Once you see the difference, you'll naturally want to optimize more.

You can find my full tech stack here.

Thanks for reading!

Every developer eventually builds a personal site. Most of us rebuild it every year or two, chasing the latest framework. I've been through Jekyll, Hugo, Gatsby, Next.js, and Nuxt. This iteration is the one that stuck — not because Vue 3 is objectively the best choice, but because the developer experience finally matches how I want to work.

This post is a walkthrough of the entire stack — the architecture, the build pipeline, and the patterns that make writing content feel effortless.

Why Vue 3 + SSG

Static site generation means the site is pre-rendered to HTML at build time. No server, no runtime, no database. The output is a folder of HTML files that can be deployed anywhere — Netlify, Cloudflare Pages, a simple Nginx server, or even a GitHub Pages repo.

Vue 3 might seem like overkill for a personal site, but the combination of Vue's component model with static generation gives me something that pure static site generators (Hugo, Eleventy) can't: interactive components embedded directly in markdown content. I can write a blog post in Markdown and drop in a Vue component for a live demo, an interactive chart, or a custom visualization — all without leaving the markdown file.

The framework powering this is vite-ssg, built by Anthony Fu. It takes a standard Vue 3 + Vite application and generates static HTML for every route at build time. The client-side JavaScript then hydrates the HTML, making it interactive. You get the SEO benefits of pre-rendered HTML with the interactivity of a single-page application.

// src/main.ts
import { ViteSSG } from 'vite-ssg'
import { routes } from 'vue-router/auto-routes'
import App from './App.vue'

export const createApp = ViteSSG(
  App,
  { routes },
  ({ router, app, isClient }) => {
    // Plugins, router guards, client-only setup
    app.use(createPinia())

    if (isClient) {
      setupRouterScroller(router, { behavior: 'auto' })

      router.beforeEach(() => NProgress.start())
      router.afterEach(() => NProgress.done())
    }
  },
)

The isClient guard ensures that browser-specific code (scroll behavior, progress bars) only runs in the browser, not during SSG pre-rendering. This pattern appears everywhere when you work with SSG — you have to be mindful that your code runs in two contexts: Node.js at build time and the browser at runtime.

File-Based Routing

Routes are generated automatically from the filesystem using unplugin-vue-router. Every .vue or .md file in the pages/ directory becomes a route:

pages/
├── index.md              → /
├── uses.md               → /uses
├── photos.vue            → /photos
├── bookmarks.vue         → /bookmarks
└── posts/
    ├── index.md          → /posts
    ├── building-smscode.md    → /posts/building-smscode
    ├── terminal-setup-2026.md → /posts/terminal-setup-2026
    └── from-node-to-rust.md   → /posts/from-node-to-rust

No router configuration to maintain. Create a file, get a route. Delete the file, the route disappears. The plugin generates type-safe route definitions, so <RouterLink to="/posts"> gets compile-time validation.

The route generation also handles frontmatter. Each markdown file has YAML frontmatter at the top — title, date, description, duration. This metadata is read at build time using gray-matter and attached to the route's meta:

// vite.config.ts
VueRouter({
  extensions: ['.vue', '.md'],
  routesFolder: 'pages',
  extendRoute(route) {
    const path = route.components.get('default')
    if (path?.endsWith('.md')) {
      const { data } = matter(fs.readFileSync(path, 'utf-8'))
      route.addToMeta({ frontmatter: data })
    }
  },
})

This is what powers the blog listing page. The ListPosts component reads route metadata from the router directly — no API calls, no file imports, just data that's already available in the route definitions:

// ListPosts.vue
const routes: Post[] = router.getRoutes()
  .filter(i => i.path.startsWith('/posts')
    && i.meta.frontmatter.date
    && !i.meta.frontmatter.draft)
  .map(i => ({
    path: i.meta.frontmatter.redirect || i.path,
    title: i.meta.frontmatter.title,
    date: i.meta.frontmatter.date,
    lang: i.meta.frontmatter.lang,
    duration: i.meta.frontmatter.duration,
  }))

Posts are sorted by date, grouped by year, and the year headers render as large, semi-transparent text in the background — a subtle but effective visual hierarchy. Draft posts (marked with draft: true in frontmatter) are filtered out of the listing but still accessible via direct URL during development.

Markdown as Vue Components

This is the core trick that makes the whole setup work. unplugin-vue-markdown compiles Markdown files into Vue Single File Components at build time. This means every .md file is a Vue component — it can use other components, receive props, and has full access to Vue's reactivity system.

---
title: My Blog Post
date: 2026-03-06T00:00:00Z
duration: 10min
---

This is regular markdown with **bold** and `code`.

But I can also use Vue components directly:

<MyCustomChart :data="chartData" />

Or use HTML with UnoCSS utilities:

<div flex gap-4 items-center>
  <span text-2xl>Interactive content in markdown!</span>
</div>

Each markdown file is wrapped in a WrapperPost component that provides the layout — title, date, duration, navigation links, and social sharing buttons. The wrapper reads the frontmatter and renders the chrome around the content:

<!-- WrapperPost.vue -->
<template>
  <div v-if="frontmatter.title" class="prose m-auto mb-8">
    <h1 class="mb-0">
      {{ frontmatter.title }}
    </h1>
    <p v-if="frontmatter.date" class="opacity-50 !-mt-6">
      {{ formatDate(frontmatter.date) }}
      <span v-if="frontmatter.duration">· {{ frontmatter.duration }}</span>
    </p>
  </div>
  <article>
    <slot />
  </article>
</template>

The markdown pipeline itself is heavily customized with markdown-it plugins:

• Shiki — Syntax highlighting with the Vitesse dark/light themes. Supports diff notation (// [!code ++]), line highlighting, and even TypeScript type annotations via TwoSlash.
• Anchor links — Every heading gets a permalink anchor for direct linking.
• Table of contents — The [[toc]] directive generates a floating TOC from headings.
• External links — All external links automatically get target="_blank" and rel="noopener".
• Magic links — Brand names like {SMSCode} auto-link to their URLs with custom icons. This is configured in vite.config.ts:

md.use(MarkdownItMagicLink, {
  linksMap: {
    SMSCode: 'https://smscode.gg',
    UNDRCTRL: 'https://undrctrl.id',
    FYP: 'https://fyp.id',
  },
  imageOverrides: [
    ['https://smscode.gg', '/icons/smscode.svg'],
    ['https://undrctrl.id', '/icons/undrctrl.svg'],
  ],
})

• GitHub Alerts — Markdown > [!NOTE] and > [!WARNING] blocks render as styled callouts.

UnoCSS: Utility-First, Zero Config

UnoCSS replaces Tailwind CSS. It's an on-demand atomic CSS engine — it only generates the CSS for utilities you actually use, and it's significantly faster than Tailwind's JIT compiler because it skips the PostCSS step entirely.

The key feature I rely on is attributify mode. Instead of stuffing all utility classes into a class attribute, you write them directly as HTML attributes:

<!-- Traditional utility classes -->
<div class="flex gap-4 items-center opacity-50 mt-4">
  <!-- Attributify mode -->
  <div flex gap-4 items-center op50 mt-4></div>
</div>

It reads cleaner and is easier to scan visually. The Vue compiler and UnoCSS work together to transform these attributes into actual CSS at build time.

The design itself is intentionally minimal. Dark mode is toggled via VueUse's useDark with class-based switching on the <html> element. The color palette is sparse — mostly grays with opacity variations. Content width is constrained by a .prose class that sets max-width and typographic defaults.

The CSS entry point is clean:

:root {
  --c-bg: #fff;
  --c-scrollbar: #eee;
}

html.dark {
  --c-bg: #050505;
  --c-scrollbar: #111;
}

A slide-enter animation plays when navigating between pages, giving each page load a subtle staggered reveal. Each child element in the content area enters with an increasing delay, creating a cascading effect that makes the page feel alive without being distracting.

Auto-Imports Everywhere

One of the best DX features in this stack is that almost nothing needs to be explicitly imported. Three unplugin plugins handle this:

unplugin-auto-import — Vue APIs (ref, computed, watch, onMounted), Vue Router APIs (useRoute, useRouter), and VueUse composables (useDark, useEventListener, useLocalStorage) are all available globally without import statements.

// vite.config.ts
AutoImport({
  imports: ['vue', VueRouterAutoImports, '@vueuse/core'],
})

unplugin-vue-components — Vue components in src/components/ are auto-registered. If I create MyWidget.vue, I can use <MyWidget /> in any template or markdown file without importing it.

unplugin-icons — Icons from the entire Iconify collection (150,000+ icons) are available as components. No icon fonts, no SVG imports — just use an HTML attribute:

<div i-ri-github-fill />
<div i-ri-article-line />
<div i-carbon-arrow-up-right />

The icon is resolved at build time, tree-shaken to only include the icons you actually use, and inlined as an SVG. Zero runtime cost.

The combined effect is significant. A typical .vue file in this project has zero import statements. Everything is available implicitly. This sounds like it would hurt readability, but in practice, the APIs are so well-known (Vue, VueUse) that explicit imports just add noise.

OG Image Generation

Every blog post automatically gets an Open Graph image for social media previews. The generation happens at build time using sharp — an SVG template is filled with the post title and rendered to a PNG:

// vite.config.ts — frontmatterPreprocess
const route = basename(id, '.md')
const path = `og/${route}.png`
generateOg(frontmatter.title, `public/${path}`)
frontmatter.image = `https://zevs.gg/${path}`

The generated image URL is set as the frontmatter image, which the head meta tags pick up automatically. When someone shares a post on Twitter, Telegram, or LinkedIn, they see a card with the post title — no manual image creation needed.

The SVG template uses a simple layout — title text on a solid background. The title is split into lines at word boundaries every 30 characters, then rendered with sharp:

async function generateOg(title: string, output: string) {
  const lines = title.trim().split(/(.{0,30})(?:\s|$)/g).filter(Boolean)

  const svg = ogTemplate.replace(
    /\{\{([^}]+)\}\}/g,
    (_, name) => ({ line1: lines[0], line2: lines[1], line3: lines[2] })[name] || ''
  )

  await sharp(Buffer.from(svg))
    .resize(1200 * 1.1, 630 * 1.1)
    .png()
    .toFile(output)
}

RSS Feed

The RSS feed is generated by a post-build script. It reads all markdown files, parses them with gray-matter and markdown-it, and outputs RSS, Atom, and JSON feeds:

// scripts/rss.ts
const files = await fg('pages/posts/*.md')
const posts = await Promise.all(
  files.map(async (i) => {
    const { data, content } = matter(await fs.readFile(i, 'utf-8'))
    const html = markdown.render(content)
    return { ...data, content: html, date: new Date(data.date) }
  })
)

posts.sort((a, b) => +new Date(b.date) - +new Date(a.date))

const feed = new Feed(options)
posts.forEach(item => feed.addItem(item))

await fs.writeFile('./dist/feed.xml', feed.rss2())
await fs.writeFile('./dist/feed.atom', feed.atom1())
await fs.writeFile('./dist/feed.json', feed.json1())

The full build pipeline runs sequentially:

# package.json build script
vite-ssg build          # 1. SSG pre-render all routes
tsx scripts/copy-fonts  # 2. Copy font files to dist
tsx scripts/rss.ts      # 3. Generate RSS/Atom/JSON feeds
cp _dist_redirects dist/_redirects  # 4. Copy redirect rules

Deployment

The site deploys to Netlify on every push. The netlify.toml configuration is minimal:

[build]
publish = "dist"
command = "pnpm run build"

[build.environment]
NODE_VERSION = "22"

[[headers]]
for = "/assets/*"

[headers.values]
Cache-Control = "public, max-age=31536000, immutable"

Static assets (JS, CSS, images) get year-long cache headers with immutable — since Vite hashes filenames, the content at any given URL never changes. HTML files use Netlify's default caching, which revalidates on each request.

The SPA fallback redirect ensures that client-side navigation works:

[[redirects]]
from = "/*"
to = "/index.html"
status = 200

This catches routes that don't have pre-rendered HTML (unlikely with SSG, but good as a safety net) and serves the SPA shell instead.

Code Quality

Pre-commit hooks keep the codebase consistent:

{
  "simple-git-hooks": {
    "pre-commit": "npx lint-staged"
  },
  "lint-staged": {
    "*": "eslint --fix"
  }
}

Every staged file — JS, TS, Vue, Markdown, JSON — runs through ESLint with @antfu/eslint-config before commit. This config includes formatting rules (replacing Prettier), Vue-specific rules, TypeScript checks, and UnoCSS attribute ordering. No separate Prettier config, no formatting debates — one tool handles everything.

The Full Architecture

Here's how everything connects:

pages/*.md / pages/*.vue          (Content & Routes)
    │
    ├─ unplugin-vue-router        (File-based routing)
    ├─ unplugin-vue-markdown      (Markdown → Vue SFC)
    │   ├─ gray-matter            (YAML frontmatter)
    │   ├─ Shiki                  (Syntax highlighting)
    │   ├─ markdown-it-anchor     (Heading permalinks)
    │   ├─ markdown-it-toc        (Table of contents)
    │   └─ markdown-it-magic-link (Brand auto-linking)
    │
    ├─ unplugin-auto-import       (Vue/VueUse auto-imports)
    ├─ unplugin-vue-components    (Component auto-registration)
    ├─ unplugin-icons             (Iconify → SVG components)
    ├─ UnoCSS                     (Atomic CSS, attributify)
    │
    └─ vite-ssg                   (Static site generation)
        ├─ sharp                  (OG image generation)
        ├─ feed                   (RSS/Atom/JSON feeds)
        └─ dist/                  → Netlify

The entire build takes about 15 seconds. The development server starts in under 2 seconds with full HMR — editing a markdown file reflects instantly in the browser.

What I'd Change

Markdown limitations. The markdown-to-Vue compilation is powerful, but debugging errors inside markdown files is painful. If a Vue component inside markdown has a syntax error, the error message points to the compiled output, not the source. Better source maps would help.

Image optimization. I don't have an automated image pipeline yet. Images are manually compressed before commit. An on-the-fly optimization step (like vite-imagetools or a custom sharp pipeline) would be worthwhile.

Search. There's no search functionality. For a blog with a growing number of posts, this will eventually matter. A client-side search index built at SSG time (like FlexSearch) would fit the static architecture well.

Wrap Up

The core principle behind this stack is that content should be easy to create and hard to break. Writing a new blog post is: create a .md file, add frontmatter, write content, push. The build system handles routing, OG images, RSS feeds, syntax highlighting, and deployment automatically.

If you're building a personal site and value developer experience over simplicity, Vue 3 + Vite + SSG is a stack worth considering. The plugin ecosystem (all those unplugin-* packages) does most of the heavy lifting, and the result is a site that's fast to build, fast to load, and — most importantly — fast to write for.

Thanks for reading!

{
  "name": "my-cool-vue-components",
  "dependencies": {
    "vue": "^3.5.15"
  },
  "devDependencies": {
    "eslint": "^9.15.0"
  }
}

The main difference is that devDependencies are only needed during the build or development phase, while dependencies are required for the project to run. For example, eslint in the case above only lints our source code; it's no longer needed when we publish the project or deploy it to production.

The concept of dependencies and devDependencies was originally introduced for authoring Node.js libraries (those published to npm). When you install a package like vite, npm automatically installs its dependencies but not its devDependencies. This is because you are consuming vite as a dependency and don't need its development tools. So, even if vite uses prettier during its development, you won't be forced to install prettier when you only need vite in your project.

As the ecosystem has evolved, we can now build much more complex projects than ever before. We have meta-frameworks for building full-stack websites, bundlers for transpiling and bundling code and dependencies, and so on. Node.js became a lot more than just running JavaScript code and packages on the server side.

I'd roughly categorize projects into three types:

1. Apps: Websites, Electron apps, mobile apps, etc. Here, package.json primarily keeps track of dependency information, and the app itself is never published to npm.
2. Libraries: Packages designed to be published to npm, then installed and consumed by other projects.
3. Internal: Packages used within monorepos that are never published.

Fundamentally, the distinction between dependencies and devDependencies only truly makes sense for libraries intended for publication on npm. However, due to different scenarios and usage patterns, their meaning has extended far beyond the original purpose.

Tools often overload the meaning of dependencies and devDependencies to fit various scenarios, aiming for sensible defaults and better Developer Experience.

For example, Vite treats dependencies as "client-side packages" and automatically runs pre-optimization on them. Build tools like tsup, unbuild, and tsdown treat dependencies as packages to be externalized during bundling, automatically inlining (bundling) anything not listed in dependencies.

While these conventions certainly simplify things in most cases, they also force dependencies and devDependencies to wear multiple hats, making it harder to grasp the purpose of each package.

If we see vue listed in devDependencies, it could mean several things:

• We are inlining/bundling it.
• We are only referencing its types.
• We use it solely for testing.
• We have it to enable IDE IntelliSense.
• Or something else entirely.

Simply classifying packages as dependencies or devDependencies doesn't provide the full picture of that package's purpose without external documentation (also note that package.json doesn't support comments).

Categorize Your Dependencies

Let's forget about dependencies and devDependencies for a moment, how might we categorize our dependencies? Here are some rough ideas I could come up with:

• test: Packages used for testing (e.g., vitest, playwright, msw).
• lint: Packages for linting/formatting (e.g., eslint, knip).
• build: Packages used for building the project (e.g., vite, rolldown).
• script: Packages used for scripting tasks (e.g., tsx, tinyglobby, cpx).
• frontend: Packages for frontend development (e.g., vue, pinia).
• backend: Packages for the backend server.
• types: Packages for type checking and definitions.
• inlined: Packages that are included directly in the final bundle.
• prod: Runtime production dependencies.
• ...

Categorization might differ between projects. But that point is that dependencies and devDependencies lack the flexibility to capture this level of detail.

This thing had been bothering me for a while, though it didn't feel like a critical problem needing immediate resolution. Only until pnpm introduced catalogs, opening up possibilities for dependency categorization we never had before.

PNPM Catalogs

PNPM Catalogs is a feature allowing monorepo workspaces to share dependency versions across different packages via a centralized management location.

Basically, you add catalog or catalogs fields to your pnpm-workspace.yaml file and reference them using catalog:<name> in your package.json.

# pnpm-workspace.yaml
catalog:
  vue: ^3.5.15
  pinia: ^2.2.6
  cac: ^6.7.14

// package.json
{
  "dependencies": {
    "vue": "catalog:",
    "pinia": "catalog:",
    "cac": "catalog:"
  }
}

Or with named catalogs:

# pnpm-workspace.yaml
catalogs:
  frontend:
    vue: ^3.5.15
    # We locked the version for some reason, etc.
    pinia: 2.2.6
  prod:
    cac: ^6.7.14

// package.json
{
  "dependencies": {
    "vue": "catalog:frontend",
    "pinia": "catalog:frontend",
    "cac": "catalog:prod"
  }
}

During installation and publishing, pnpm automatically resolves dependencies to the versions specified in the catalogs. While it's originally designed for managing version consistency across monorepos, I found Named Catalogs are also a great way to also categorize dependencies. As shown above, we can categorize vue and cac into different catalogs even though they both presented in dependencies. This information makes version upgrade easier and would help on reviewing dependency changes.

A nice bonus: you can use comments in pnpm-workspace.yaml to share additional context with your team.

Tooling Support

Given that catalogs are still quite new, this shift requires better tooling support. A significant pain point for me on this was losing the ability to see a dependency's version at a glance in package.json when using catalog:<name>.

To address this, I created a VS Code extension, PNPM Catalog Lens, which displays the resolved version inline within package.json.

It also adds distinct colors to each named category for easier identification. This gives us the categorization and centralized version control without significantly impacting DX.

Since versions move to pnpm-workspace.yaml, CLI tools would need to make some integrations to support this. So far, we've adapted the following tools:

• taze: Checks and bumps dependency versions, now supporting reading and updating versions from catalogs.
• eslint-plugin-pnpm: Enforces using catalogs for all dependencies in package.json, with auto-fixes.
  • If you use @antfu/eslint-config, enable this by setting pnpm: true.
• pnpm-workspace-yaml: A utility library for reading and writing pnpm-workspace.yaml while preserving comments and formatting.
• node-modules-inspector: Visualizes your node_modules, now labeling dependencies with their catalog name for a better overview of their origin.
• nip: Interactive CLI to install packages to catalogs

Looking into the Future

Currently, I see the value of categorize dependencies is mainly for better communication and easier version upgrade reviews. However, as this convention gains wider adoption and tooling support improves, we could integrate this information more deeply with our tools.

For example, in Vite, we could gain more explicit control over dependency optimization, decoupling it from the dependencies and devDependencies fields:

// vite.config.ts
import { readWorkspaceYaml } from 'pnpm-workspace-yaml'
import { defineConfig } from 'vite'

const yaml = await readWorkspaceYaml('pnpm-workspace.yaml') // pseudo-API

export default defineConfig({
  optimizeDeps: {
    include: Object.keys(yaml.catalogs.frontend)
  }
})

Similarly, for unbuild, we could explicitly control externalization and inlining without manually maintaining lists in multiple places:

// build.config.ts
import { readWorkspaceYaml } from 'pnpm-workspace-yaml'
import { defineBuildConfig } from 'unbuild'

const yaml = await readWorkspaceYaml('pnpm-workspace.yaml')

export default defineBuildConfig({
  externals: Object.keys(yaml.catalogs.prod),
  rollup: {
    inlineDependencies: Object.keys(yaml.catalogs.inlined)
  }
})

For linting or bundling, we could enforce rules based on catalogs, such as throwing errors when attempting to import backend packages into frontend code, preventing accidental bundling mistakes.

This categorization could also provide valuable context for vulnerability reports. Vulnerabilities in build tools might be less severe than those in dependencies shipped to production.

...and so on.

I've already started migrating many of my projects to use named catalogs(node-modules-inspector for example). Even outside monorepos, the ability to categorize dependencies is a compelling reason to adopt to pnpm catalogs. I consider this an exploratory phase where we're still discovering best practices and improving tooling support.

So, that's why I'm writing this post: to invite you to consider this approach and try it out. We'd love to hear your thoughts and how you would utilize it. I look forward to seeing more patterns like this emerge, helping us build more maintainable projects with a better DX. Thanks for reading!

In modern programming, the function coloring problem isn't new. Based on how functions execute: synchronous (blocking) and asynchronous (non-blocking), we often classify them into two "colors" for better distinction. The problem arises because you generally cannot mix and match these colors freely.

For instance, in JavaScript:

• An async function can call both sync and other async functions.
• A sync function, however, cannot directly call an async function without changing its own color to async.

This restriction forces developers to propagate the "color" throughout their codebase. If a function deep in your logic needs to become async, it forces every caller up the chain to also become async, leading to a cascading effect (or "async inflection"). This makes refactoring harder, increases complexity, and sometimes leads to awkward workarounds like blocking async calls with await inside sync contexts, or vice versa.

We often discuss the async inflection problem, where a common solution is to make everything async since async functions can call both sync and async functions, while the reverse is not true. However, the coloring problem actually goes both ways, which seems to be less frequently discussed:

While an async function requires all the callers to be async, a sync function also requires all the dependencies to be sync.

At its core, it's the same problem with different perspectives. It depends on which part of the code you're focusing on and how difficult it is to change its "color." If the function you're working on must be async, the burden shifts to the callers. Conversely, if it must be sync, you'll need all your dependencies to be sync or provide a synchronous entry point.

Libraries in Practice

For example, the widely used library find-up provides two main APIs, findUp and findUpSync, to avoid dependents being trapped by the coloring problem. If you look into the code, you'll find that the package essentially duplicates the logic twice to provide the two APIs. Going down, you see its dependency locate-path also duplicates the locatePath and locatePathSync logic.

Say you want to build another library that uses findUp, like readNearestPkg, you would also have to write the logic twice, using findUp and findUpSync separately, to support both async and sync usage.

In these cases, even if our main logic does not come with its own "colors," the whole dependency pipeline is forced to branch into two colors due to an optional async operation down the road (e.g., fs.promises.stat and fs.statSync).

Async Plugins

Another case demonstrating the coloring problem is a plugin system with async hooks. For example, imagine we are building a Markdown-to-HTML compiler with plugin support. Say the parser and compiler logic are synchronous; we could expose a sync API like:

export function markdownToHtml(markdown) {
  const ast = parse(markdown)
  // ...
  return render(ast)
}

To make our library extensible, we might allow plugins to register hooks at multiple stages thoughout the process, for example:

export interface Plugin {
  preprocess: (markdown: string) => string
  transform: (ast: AST) => AST
  postprocess: (html: string) => string
}

export function markdownToHtml(markdown, plugins) {
  for (const plugin of plugins) {
    markdown = plugin.preprocess(markdown) // [!code hl]
  }
  let ast = parse(markdown)
  for (const plugin of plugins) {
    ast = plugin.transform(ast) // [!code hl]
  }
  let html = render(ast)
  for (const plugin of plugins) {
    html = plugin.postprocess(html) // [!code hl]
  }
  return html
}

Great, now we have a plugin system. However, having markdownToHtml as a synchronous function essentially limits all plugin hooks to be synchronous as well. This limitation can be quite restrictive. For instance, consider a plugin for syntax highlighting. In many cases, the best results for syntax highlighting might require asynchronous operations, such as fetching additional resources or performing complex computations that are better suited for non-blocking execution.

To accommodate such scenarios, we need to allow async hooks in our plugin system. This means that our main function, markdownToHtml, as the caller of the plugin hooks must also be async. We could implement it like this:

// [!code word:Promise]
// [!code word:async]
// [!code word:await]
export interface Plugin {
  preprocess: (markdown: string) => string | Promise<string>
  transform: (ast: AST) => AST | Promise<AST>
  postprocess: (html: string) => string | Promise<string>
}

export async function markdownToHtml(markdown, plugins) { // [!code hl]
  for (const plugin of plugins) {
    markdown = await plugin.preprocess(markdown) // [!code hl]
  }
  let ast = parse(markdown)
  for (const plugin of plugins) {
    ast = await plugin.transform(ast) // [!code hl]
  }
  let html = render(ast)
  for (const plugin of plugins) {
    html = await plugin.postprocess(html) // [!code hl]
  }
  return html
}

While this maximized the flexibility of the plugin system, this approach also forces all users to handle the process asynchronously, even in the cases where all plugins are synchronous. This is the cost of accommodating the possibility that some operations "might be asynchronous". To manage this, we often end up duplicating the logic to offer both sync and async APIs, and restrict async plugins to the async version only.

Such duplications lead to increased maintenance efforts, potential inconsistencies, and larger bundle sizes, which are not ideal for maintainers or users.

Is there a better way to handle this?

Introducing Quansync

What if we could make our logic decoupled from the coloring problem and let the caller decide the color?

Trying to make the situation a bit better, {@sxzz} and I took inspiration from gensync by {@loganfsmyth} and made a package called quansync. Taking it even further, we are dreaming of leveraging this to create a paradigm shift in the way we write libraries in the JavaScript ecosystem.

The name Quansync is borrowed from Quantum Mechanics, where particles can exist in multiple states simultaneously, known as superposition, and only settle into a single state when observed (try hovering over the atom below).

import fs from 'find-up'
import { quansync } from 'quansync'

export const readFile = quansync({
  sync: filepath => fs.readFileSync(filepath),
  async: filepath => fs.promises.readFile(filepath),
})

const content1 = readFile.sync('package.json')
const content2 = await readFile.async('package.json')

// The quansync function itself can behave like a normal async function
const content3 = await readFile('package.json')

import { quansync } from 'quansync'

export const readFile = quansync({
  sync: filepath => fs.readFileSync(filepath),
  async: filepath => fs.promises.readFile(filepath),
})

// Create a quansync with `function*` and `yield*`
// [!code word:function*:1]
export const readJSON = quansync(function* (filepath) {
  // Call the quansync function directly
  // and use `yield*` to get the result.
  // Upon usage, it will auto select the implementation
  // [!code word:yield*:1]
  const content = yield* readFile(filepath)
  return JSON.parse(content)
})

// fs.readFileSync will be used under the hood
const pkg1 = readJSON.sync('package.json')
// fs.promises.readFile will be used under the hood
const pkg2 = await readJSON.async('package.json')

// [!code word:quansync/macro]
import { quansync } from 'quansync/macro'

// Use async/await syntax
// They will be transformed to `function*` and `yield*` at build time
export const readJSON = quansync(async (filepath) => {
  const content = await readFile(filepath)
  return JSON.parse(content)
})

// Expose the classical sync API
export const readJSONSync = readJSON.sync

Three years ago, I wrote a post about shipping ESM & CJS in a single package, advocating for dual CJS/ESM formats to ease user migration and trying to make the best of both worlds. Back then, I didn't fully agree with aggressively shipping ESM-only, as I considered the ecosystem wasn't ready, especially since the push was mostly from low-level libraries. Over time, as tools and the ecosystem have evolved, my perspective has gradually shifted towards more and more on adopting ESM-only.

As of 2025, a decade has passed since ESM was first introduced in 2015. Modern tools and libraries have increasingly adopted ESM as the primary module format. According to {@wooorm}'s script, the packages that ships ESM on npm in 2021 was 7.8%, and by the end of 2024, it had reached 25.8%. Although a significant portion of packages still use CJS, the trend clearly shows a good shift towards ESM.

Here in this post, I'd like to share my thoughts on the current state of the ecosystem and why I believe it's time to move on to ESM-only.

The Toolings are Ready

Modern Tools

With the rise of Vite as a popular modern frontend build tool, many meta-frameworks like Nuxt, SvelteKit, Astro, SolidStart, Remix, Storybook, Redwood, and many others are all built on top of Vite nowadays, that treating ESM as a first-class citizen.

As a complement, we have also testing library Vitest, which was designed for ESM from the day one with powerful module mocking capability and efficient fine-grain caching support.

CLI tools like tsx and jiti offer a seamless experience for running TypeScript and ESM code without requiring additional configuration. This simplifies the development process and reduces the overhead associated with setting up a project to use ESM.

Other tools, for example, ESLint, in the recent v9.0, introduced a new flat config system that enables native ESM support with eslint.config.mjs, even in CJS projects.

Top-Down & Bottom-Up

Back in 2021, when {@sindresorhus} first started migrating all his packages to ESM-only, for example, find-up and execa, it was a bold move. I consider this move as a bottom-up approach, as the packages that rather low-level and many their dependents are not ready for ESM yet. I was worried that this would force those dependents to stay on the old version of the packages, which might result in the ecosystem being fragmented. (As of today, I actually appreciate that move bringing us quite a lot of high-quality ESM packages, regardless that the process wasn't super smooth).

It's way easier for an ESM or Dual formats package to depend on CJS packages, but not the other way around. In terms of smooth adoption, I believe the top-down approach is more effective in pushing the ecosystem forward. With the support of high-level frameworks and tools from top-down, it's no longer a significant obstacle to use ESM-only packages. The remaining challenges in terms of ESM adoption primarily lie with package authors needing to migrate and ship their code in ESM format.

Requiring ESM in Node.js

The capability to require() ESM modules in Node.js, initiated by {@joyeecheung}, marks an incredible milestone. This feature allows packages to be published as ESM-only while still being consumable by CJS codebases with minimal modifications. It helps avoid the async infection (also known as Red Functions) introduced by dynamic import() ESM, which can be pretty hard, if not impossible in some cases, to migrate and adapt.

This feature was recently unflagged and backported to Node.js v22 (and soon v20), which means it should be available to many developers already. Consider the top-down or bottom-up metaphor, this feature actually makes it possible to start ESM migration also from middle-out, as it allows import chains like ESM → CJS → ESM → CJS to work seamlessly.

To solve the interop issue between CJS and ESM in this case, Node.js also introduced a new export { Foo as 'module.exports' } syntax in ESM to export CJS-compatible exports (by this PR). This allows package authors to publish ESM-only packages while still supporting CJS consumers, without even introducing breaking changes (expcet for changing the required Node.js version).

For more details on the progress and discussions around this feature, keep track on this issue.

The Troubles with Dual Formats

While dual CJS/ESM packages have been a quite helpful transition mechanism, they come with their own set of challenges. Maintaining two separate formats can be cumbersome and error-prone, especially when dealing with complex codebases. Here are some of the issues that arise when maintaining dual formats:

Interop Issues

Fundamentally, CJS and ESM are different module systems with distinct design philosophies. Although Node.js has made it possible to import CJS modules in ESM, dynamically import ESM in CJS, and even require() ESM modules, there are still many tricky cases that can lead to interop issues.

One key difference is that CJS typically uses a single module.exports object, while ESM supports both default and named exports. When authoring code in ESM and transpiling to CJS, handling exports can be particularly challenging, especially when the exported value is a non-object, such as a function or a class. Additionally, to make the types correct, we also need to introduce further complications with .d.mts and .d.cts declaration files. And so on...

As I am trying to explain this problem deeper, I found that I actually wish you didn't even need to be bothered with this problem at all. It's frankly too complicated and frustrating. If you are just a user of packages, let alone the package authors to worry about that. This is one of the reasons I advocate for the entire ecosystem to transition to ESM, to leave these problems behind and spare everyone from this unnecessary hassle.

Dependency Resolution

When a package has both CJS and ESM formats, the resolution of dependencies can become convoluted. For example, if a package depends on another package that only ships ESM, the consumer must ensure that the ESM version is used. This can lead to version conflicts and dependency resolution issues, especially when dealing with transitive dependencies.

Also for packages that are designed to used with singleton pattern, this might introduce multiple copies of the same package and cause unexpected behaviors.

Package Size

Shipping dual formats essentially doubles the package size, as both CJS and ESM bundles need to be included. While a few extra kilobytes might not seem significant for a single package, the overhead can quickly add up in projects with hundreds of dependencies, leading to the infamous node_modules bloat. Therefore, package authors should keep an eye on their package size. Moving to ESM-only is a way to optimize it, especially if the package doesn't have strong requirements on CJS.

When Should We Move to ESM-only?

This post does not intend to diminish the value of dual-format publishing. Instead, I want to encourage evaluating the current state of the ecosystem and the potential benefits of transitioning to ESM-only.

There are several factors to consider when deciding whether to move to ESM-only:

New Packages

I strongly recommend that all new packages be released as ESM-only, as there are no legacy dependencies to consider. New adopters are likely already using a modern, ESM-ready stack, there being ESM-only should not affect the adoption. Additionally, maintaining a single module system simplifies development, reduces maintenance overhead, and ensures that your package benefits from future ecosystem advancements.

Browser-targeted Packages

If a package is primarily targeted for the browser, it makes total sense to ship ESM-only. In most cases, browser packages go through a bundler, where ESM provides significant advantages in static analysis and tree-shaking. This leads to smaller and more optimized bundles, which would also improve loading performance and reduce bandwidth consumption for end users.

Standalone CLI

For a standalone CLI tool, it's no difference to end users whether it's ESM or CJS. However, using ESM would enable your dependencies to also be ESM, facilitating the ecosystem's transition to ESM from a top-down approach.

Node.js Support

If a package is targeting the evergreen Node.js versions, it's a good time to consider ESM-only, especially with the recent require(ESM) support.

Know Your Consumers

If a package already has certain users, it's essential to understand the dependents' status and requirements. For example, for an ESLint plugin/utils that requires ESLint v9, while ESLint v9's new config system supports ESM natively even in CJS projects, there is no blocker for it to be ESM-only.

Definitely, there are different factors to consider for different projects. But in general, I believe the ecosystem is ready for more packages to move to ESM-only, and it's a good time to evaluate the benefits and potential challenges of transitioning.

How Far We Are?

The transition to ESM is a gradual process that requires collaboration and effort from the entire ecosystem. Which I believe we are on a good track moving forward.

To improve the transparency and visibility of the ESM adoption, I recently built a visualized tool called Node Modules Inspector for analyzing your packages's dependencies. It provides insights into the ESM adoption status of your dependencies and helps identify potential issues when migrating to ESM.

Here are some screenshots of the tool to give you a quick impression:

This tool is still in its early stages, but I hope it will be a valuable resource for package authors and maintainers to track the ESM adoption progress of their dependencies and make informed decisions about transitioning to ESM-only.

To learn more about how to use it and inspect your projects, check the repository .

Moving Forward

I am planning to gradually transition the packages I maintain to ESM-only and take a closer look at the dependencies we rely on. We also have plenty of exciting ideas for the Node Modules Inspector, aiming to provide more useful insights and help find the best path forward.

I look forward to a more portable, resilient, and optimized JavaScript/TypeScript ecosystem.

I hope this post has shed some light on the benefits of moving to ESM-only and the current state of the ecosystem. If you have any thoughts or questions, feel free to reach out using the links below. Thank you for reading!

People often assume that a zero-major version indicates that the software is not ready for production. However, all of the projects mentioned here are quite stable and production-ready, used by millions of projects.

Why? - I bet that's your question reading this.

Versioning

Version numbers act as snapshots of our codebase, helping us communicate changes effectively. For instance, we can say "it works in v1.3.2, but not in v1.3.3, there might be a regression." This makes it easier for maintainers to locate bugs by comparing the differences between these versions. A version is essentially a marker, a seal of the codebase at a specific point in time.

However, code is complex, and every change involves trade-offs. Describing how a change affects the code can be tricky even with natural language. A version number alone can't capture all the nuances of a release. That's why we have changelogs, release notes, and commit messages to provide more context.

I see versioning as a way to communicate changes to users — a contract between the library maintainers and the users to ensure compatibility and stability during upgrades. As a user, you can't always tell what's changed between v2.3.4 and v2.3.5 without checking the changelog. But by looking at the numbers, you can infer that it's a patch release meant to fix bugs, which should be safe to upgrade. This ability to understand changes just by looking at the version number is possible because both the library maintainer and the users agree on the versioning scheme.

Since versioning is only a contract, and could be interpreted differently to each specific project, you shouldn't blindly trust it. It serves as an indication to help you decide when to take a closer look at the changelog and be cautious about upgrading. But it's not a guarantee that everything will work as expected, as every change might introduce behavior changes, whether it's intended or not.

Semantic Versioning

In the JavaScript ecosystem, especially for packages published on npm, we follow a convention known as Semantic Versioning, or SemVer for short. A SemVer version number consists of three parts: MAJOR.MINOR.PATCH. The rules are straightforward:

• MAJOR: Increment when you make incompatible API changes.
• MINOR: Increment when you add functionality in a backwards-compatible manner.
• PATCH: Increment when you make backwards-compatible bug fixes.

Package managers we use, like npm, pnpm, and yarn, all operate under the assumption that every package on npm adheres to SemVer. When you or a package specifies a dependency with a version range, such as ^1.2.3, it indicates that you are comfortable with upgrading to any version that shares the same major version (1.x.x). In these scenarios, package managers will automatically determine the best version to install based on what is most suitable for your specific project.

This convention works well technically. If a package releases a new major version v2.0.0, your package manager won't install it if your specified range is ^1.2.3. This prevents unexpected breaking changes from affecting your project until you manually update the version range.

However, humans perceive numbers on a logarithmic scale. We tend to see v2.0 to v3.0 as a huge, groundbreaking change, while v125.0 to v126.0 seems a lot more trivial, even though both indicate incompatible API changes in SemVer. This perception can make maintainers hesitant to bump the major version for minor breaking changes, leading to the accumulation of many breaking changes in a single major release, making upgrades harder for users. Conversely, with something like v125.0, it becomes difficult to convey the significance of a major change, as the jump to v126.0 appears minor.

{@TkDodo|Dominik Dorfmeister} had a great talk about API Design, which mentions an interesting inequality that descripting this: "Breaking Changes !== Marketing Event"

Progressive

I am a strong believer in the principle of progressiveness. Rather than making a giant leap to a significantly higher stage all at once, progressiveness allows users to adopt changes gradually at their own pace. It provides opportunities to pause and assess, making it easier to understand the impact of each change.

I believe we should apply the same principle to versioning. Instead of treating a major version as a massive overhaul, we can break it down into smaller, more manageable updates. For example, rather than releasing v2.0.0 with 10 breaking changes from v1.x, we could distribute these changes across several smaller major releases. This way, we might release v2.0 with 2 breaking changes, followed by v3.0 with 1 breaking change, and so on. This approach makes it easier for users to adopt changes gradually and reduces the risk of overwhelming them with too many changes at once.

Leading Zero Major Versioning

The reason I've stuck with v0.x.x is my own unconventional approach to versioning. I prefer to introduce necessary and minor breaking changes early on, making upgrades easier, without causing alarm that typically comes with major version jumps like v2 to v3. Some changes might be "technically" breaking but don't impact 99.9% of users in practice. (Breaking changes are relative. Even a bug fix can be breaking for those relying on the previous behavior, but that's another topic for discussion :P).

There's a special rule in SemVer that states when the leading major version is 0, every minor version bump is considered breaking. I am kind of abusing that rule to workaround the limitation of SemVer. With zero-major versioning, we are effectively abandoning the first number, and merge MINOR and PATCH into a single number (thanks to David Blass for pointing this out):

Of course, zero-major versioning is not the only solution to be progressive. We can see that tools like Node.js, Vite, Vitest are rolling out major versions in consistent intervals, with a minimal set of breaking changes in each release that are easy to adopt. It would require a lot of effort and extra attentions. Kudos to them!

I have to admit that sticking to zero-major versioning isn't the best practice. While I aimed for more granular versioning to improve communication, using zero-major versioning has actually limited the ability to convey changes effectively. In reality, I've been wasting a valuable part of the versioning scheme due to my peculiar insistence.

Thus, here, I am proposing to change.

Epoch Semantic Versioning

In an ideal world, I would wish SemVer to have 4 numbers: EPOCH.MAJOR.MINOR.PATCH. The EPOCH version is for those big announcements, while MAJOR is for technical incompatible API changes that might not be significant. This way, we can have a more granular way to communicate changes. Similarly, we also have Romantic Versioning that propose HUMAN.MAJOR.MINOR. The creator of SemVer, Tom Preston-Werner also mentioned similar concerns and solutions in this blog post. (thanks to Sébastien Lorber for pointing this out).

But, of course, it's too late for the entire ecosystem to adopt a new versioning scheme.

If we can't change SemVer, maybe we can at least extend it. I am proposing a new versioning scheme called 🗿 Epoch Semantic Versioning, or Epoch SemVer for short. It's built on top of the structure of MAJOR.MINOR.PATCH, extend the first number to be the combination of EPOCH and MAJOR. To put a difference between them, we use a fourth digit to represent EPOCH, which gives MAJOR a range from 0 to 999. This way, it follows the exact same rules as SemVer without requiring any existing tools to change, but provides more granular information to users.

The name "Epoch" is inspired by Debian's versioning scheme.

The format is as follows:

• EPOCH: Increment when you make significant or groundbreaking changes.
• MAJOR: Increment when you make minor incompatible API changes.
• MINOR: Increment when you add functionality in a backwards-compatible manner.
• PATCH: Increment when you make backwards-compatible bug fixes.

I previously proposed to have the EPOCH multiplier to be 100, but according to the community feedback, it seems that 1000 is a more popular choices as it give more room for the MAJOR version and a bit more distinguision between the numbers. The multiplier is not a strict rule, feel free to adjust it based on your needs.

For example, UnoCSS would transition from v0.65.3 to v65.3.0 (in the case EPOCH is 0). Following SemVer, a patch release would become v65.3.1, and a feature release would be v65.4.0. If we introduced some minor incompatible changes affecting an edge case, we could bump it to v66.0.0 to alert users of potential impacts. In the event of a significant overhaul to the core, we could jump directly to v1000.0.0 to signal a new era and make a big announcement. I'd suggest assigning a code name to each non-zero EPOCH to make it more memorable and easier to refer to. This approach provides maintainers with more flexibility to communicate the scale of changes to users effectively.

[!TIP]
We shouldn't need to bump EPOCH often. It's mostly useful for high-level, end-user-facing libraries or frameworks. For low-level libraries, they might never need to bump EPOCH at all (ZERO-EPOCH is essentially the same as SemVer).

Of course, I'm not suggesting that everyone should adopt this approach. It's simply an idea to work around the existing system, and only for those packages with this need. It will be interesting to see how it performs in practice.

Moving Forward

I plan to adopt Epoch Semantic Versioning in my projects, including UnoCSS, Slidev, and all the plugins I maintain, and ultimately abandon zero-major versioning for stable packages. I hope this new versioning approach will help communicate changes more effectively and provide users with better context when upgrading.

I'd love to hear your thoughts and feedback on this idea. Feel free to share your comments using the links below!