DEV Community: Royce

Authentik vs Keycloak vs Authelia SSO 2026

Royce — Wed, 18 Mar 2026 05:11:23 +0000

Authentik vs Keycloak vs Authelia: Self-Hosted SSO and Auth 2026

TL;DR

Self-hosted SSO in 2026 has three serious options. Authelia is a lightweight reverse proxy authentication layer — under 30MB RAM, configured in YAML, purpose-built for adding 2FA to homelab services. Authentik is a full identity provider with a modern UI, flow-based customization, and OIDC/SAML support — the default recommendation for teams who want proper SSO without Keycloak's complexity. Keycloak is the enterprise standard — Java-based, Red Hat-backed, supports every protocol including Kerberos and Active Directory federation, but requires 400MB–2GB RAM and significant configuration investment. Start with Authelia for homelab, move to Authentik for team use, consider Keycloak only if enterprise AD integration is non-negotiable.

Key Takeaways

Authelia: ~22K stars, Apache-2.0, Go — lightweight proxy auth, ~20MB container, YAML config, 2FA, not a full IdP
Authentik: ~15K stars, MIT, Python/Go — full IdP, OIDC/SAML/LDAP, visual flow builder, 2GB RAM minimum
Keycloak: ~25K stars, Apache-2.0, Java (Quarkus) — enterprise IdP, every protocol including Kerberos, 400MB–2GB+ RAM
Critical distinction: Authelia is proxy authentication middleware, not an identity provider — it cannot issue OIDC tokens for apps that need proper OAuth flows
Recommendation by use case: Homelab → Authelia; SMB/Team → Authentik; Enterprise with AD → Keycloak
Authelia + Authentik: Many setups combine both — Authelia for simple reverse proxy protection, Authentik as the OIDC backend

Understanding the Difference: Proxy Auth vs Identity Provider

Before comparing these three tools, a critical distinction: Authelia is not an identity provider. This is the most common point of confusion.

Proxy authentication (Authelia): Sits in front of your services in your reverse proxy (Traefik, Nginx, Caddy). When you visit service.yourdomain.com, Authelia checks if you're authenticated. If not, it shows a login page. It stores your credentials and issues a session cookie. It's excellent for protecting services that don't have built-in authentication.

Identity provider (Authentik, Keycloak): Issues OIDC tokens and SAML assertions that applications use to authenticate users via standard protocols. Apps like Gitea, Outline, Nextcloud, and Grafana have built-in SSO support that requires an OIDC/SAML provider. Only Authentik and Keycloak can fill this role.

In practice, many homelabs run both:

Authelia handles basic HTTP authentication for simple apps (simple dashboards, internal tools)
Authentik (or Keycloak) handles OIDC SSO for apps with proper OAuth support

Comparison Table

Feature	Authelia	Authentik	Keycloak
GitHub Stars	~22K	~15K	~25K
License	Apache-2.0	MIT	Apache-2.0
Language	Go	Python (Django) + Go	Java (Quarkus)
RAM (idle)	~20–30MB	~500MB–1GB	~400MB–2GB
RAM (recommended)	256MB	2GB	4GB+
Is a full IdP?	No (proxy auth only)	Yes	Yes
OIDC/OAuth 2.0	Limited (proxy only)	Yes	Yes
SAML 2.0	No	Yes	Yes (most complete)
LDAP	No	Yes (LDAP outpost)	Yes (federation + outbound)
Active Directory	No	Yes	Yes (best support)
Kerberos	No	No	Yes
Social login	No	Yes	Yes
MFA/2FA	Yes (TOTP, WebAuthn, Duo)	Yes (TOTP, WebAuthn, FIDO2)	Yes (TOTP, WebAuthn, SMS)
Passkeys/WebAuthn	Yes	Yes	Yes
Self-registration	No	Yes	Yes
User management UI	Basic	Excellent	Good (complex)
Flow customization	No	Yes (visual builder)	Yes (complex)
Branding/themes	No	Yes	Yes
Multi-tenancy	No	Yes	Yes (realms)
Federation	No	No	Yes (IdP chaining)
Config format	YAML files	Web UI + API	Web UI + CLI
GitOps-friendly	Yes	Partial	Partial
Setup complexity	Low	Medium	High
Reverse proxy integration	Native (Traefik/Nginx/Caddy)	Via outpost/proxy	Via reverse proxy headers

Resource Usage in Detail

Resource usage is often the deciding factor for homelab users.

Authelia

Authelia's Go binary is remarkably lean. The Docker container is under 20MB in size. At runtime:

Idle RAM: 15–30MB
Peak (during auth flow): ~50–100MB
Storage: Minimal (SQLite by default, a few MB for session data)

You can run Authelia on a Raspberry Pi alongside dozens of other services without noticing it. This is its killer advantage for resource-constrained homelabs.

Authentik

Authentik requires PostgreSQL and Redis alongside the main server container. Total stack:

Authentik server: ~300–500MB RAM
Authentik worker: ~200–400MB RAM
PostgreSQL: ~100–300MB RAM
Redis: ~30–50MB RAM
Total: ~700MB–1.2GB RAM for a lightly-used instance

For a team setup, 2GB RAM dedicated to the Authentik stack is comfortable. The official documentation recommends 2 vCPU and 2GB RAM minimum.

Keycloak

Keycloak runs on Java (Quarkus), which means JVM overhead. However, Quarkus has significantly reduced Keycloak's startup time and memory footprint compared to the older WildFly-based versions.

Idle RAM: ~400MB–800MB (Quarkus, depends on configuration)
Under load: 1–4GB+ depending on concurrent sessions and realm complexity
Database: External PostgreSQL required (add 100–300MB)
Total: ~600MB–2.5GB RAM for a typical installation

For enterprise deployments, plan for 4–8GB RAM per Keycloak node, with clustering for high availability.

Setup and Configuration

Authelia

Authelia is configured entirely through YAML files. This is one of its strongest features for GitOps and infrastructure-as-code workflows.

# configuration.yml
server:
  host: 0.0.0.0
  port: 9091

log:
  level: info

jwt_secret: a-very-long-secret-key

authentication_backend:
  file:
    path: /config/users_database.yml

access_control:
  default_policy: deny
  rules:
    - domain: "*.yourdomain.com"
      policy: two_factor
    - domain: "public.yourdomain.com"
      policy: bypass

session:
  name: authelia_session
  secret: another-long-secret
  expiration: 1h
  inactivity: 5m
  domain: yourdomain.com

storage:
  local:
    path: /config/db.sqlite3

notifier:
  smtp:
    username: you@gmail.com
    password: your-app-password
    host: smtp.gmail.com
    port: 587
    sender: auth@yourdomain.com

Traefik integration:

# In your Traefik-managed service's Docker labels:
labels:
  - "traefik.http.routers.myservice.middlewares=authelia@docker"

# Authelia middleware definition:
labels:
  - "traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.yourdomain.com"
  - "traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true"
  - "traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email"

Authentik Docker Compose

version: "3.4"

services:
  postgresql:
    image: docker.io/library/postgres:16-alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 5s
    volumes:
      - database:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${PG_PASS}
      POSTGRES_USER: authentik
      POSTGRES_DB: authentik

  redis:
    image: docker.io/library/redis:alpine
    command: --save 60 1 --loglevel warning
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 3s
    volumes:
      - redis:/data

  server:
    image: ghcr.io/goauthentik/server:2024.12
    restart: unless-stopped
    command: server
    environment:
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
    volumes:
      - ./media:/media
      - ./custom-templates:/templates
    ports:
      - "0.0.0.0:9000:9000"
      - "0.0.0.0:9443:9443"
    depends_on:
      - postgresql
      - redis

  worker:
    image: ghcr.io/goauthentik/server:2024.12
    restart: unless-stopped
    command: worker
    environment:
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./media:/media
      - ./certs:/certs
      - ./custom-templates:/templates
    depends_on:
      - postgresql
      - redis

volumes:
  database:
  redis:

Keycloak Docker Compose

version: "3"

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start-dev  # Use 'start' for production
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD}
      KC_HOSTNAME: auth.yourdomain.com
      KC_PROXY: edge  # Behind reverse proxy
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: ${KC_DB_PASSWORD}
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  pg_data:

Note: For production, use start instead of start-dev and configure KC_HOSTNAME_STRICT=false, TLS certificates, and a proper database with backups.

Use Case Matrix

Homelab (1–5 users, personal services)

Recommended: Authelia with optional Authentik for apps that need proper OIDC.

Most homelab services (Portainer, Grafana, dashboards) don't have built-in auth. Authelia protects them with minimal resources. Add Authentik only for apps that have native OIDC support (Gitea, Outline, Nextcloud) and benefit from real SSO.

Small Team (5–50 users, business applications)

Recommended: Authentik

Authentik handles the full SSO flow for modern business apps, has a user-friendly admin UI, and supports SAML for legacy enterprise apps. The flow-based customization lets you add registration approval, MFA enrollment, and custom login pages without writing code. Resource usage is manageable on a 2–4GB RAM VPS.

Mid-size Business (50–500 users, mixed legacy/modern apps)

Recommended: Authentik or Keycloak depending on Active Directory requirements.

If your organization has Windows Active Directory and needs to federate users from AD into your self-hosted apps, Keycloak's AD integration is more mature. If you're building green-field with modern protocols, Authentik handles this tier well.

Enterprise (500+ users, Kerberos, AD federation, complex compliance)

Recommended: Keycloak

Keycloak is the only option in this space with full Kerberos support, deep Active Directory federation, and the battle-tested scalability for high-concurrency enterprise auth. Red Hat's backing means long-term security patching. The configuration complexity is real, but enterprise IT teams are accustomed to it.

Common Combinations

Authelia + Authentik: Run Authelia for simple proxy auth on services without OIDC support, and point Authelia to Authentik as its LDAP/OIDC backend for user management. This gives you single user management with both proxy auth and full IdP capabilities.

Authentik + Authelia: The reverse — use Authentik as the primary IdP, and deploy Authelia only for protecting legacy services that can't be updated with OIDC.

Keycloak + Vault: For enterprise secrets management, Keycloak integrates with HashiCorp Vault (or Infisical) for federated identity in CI/CD pipelines.

For hands-on setup guides, see our how to self-host Authentik guide, our Authelia authentication middleware guide, and our Keycloak self-hosting guide. If you're building a full self-hosted stack and need to understand where SSO fits, the best open source authentication solutions overview covers the broader landscape.

Troubleshooting Common Issues

Authelia: "missing redirects" on first login

The most common Authelia configuration error: the session.domain in configuration.yml must match the top-level domain of all your services. If your services are on *.home.yourdomain.com, set session.domain: home.yourdomain.com. A mismatch causes session cookies to not be shared across subdomains, resulting in infinite login loops.

Authentik: Worker not starting

If the Authentik worker container keeps restarting, check for PostgreSQL connection errors (docker logs authentik-worker-1). The most common cause is a missing AUTHENTIK_SECRET_KEY environment variable or a mismatch between the server and worker environment files. Generate a secret key with openssl rand -base64 36.

Keycloak: "Invalid redirect URI" on login

In Keycloak's admin console, every OIDC client must have its redirect URIs explicitly allowlisted. Navigate to Clients → [your client] → Settings → Valid redirect URIs and add https://yourapp.yourdomain.com/*. The wildcard at the end is intentional. A missing or incorrectly scoped redirect URI is the most common Keycloak integration error.

All three: Clock skew

OIDC tokens have short expiry windows (typically 5 minutes). If your server's clock is more than a few minutes off, token validation will fail with cryptic errors. Run timedatectl to check clock sync status and enable systemd-timesyncd or ntpd if needed.

Backup and Disaster Recovery

For SSO infrastructure, backup and recovery planning is critical — if your auth system goes down, users can't access any protected services.

Authelia backup is simple: back up configuration.yml, the users database file, and the SQLite file (if using local storage). Everything else is stateless. Recovery is fast — restore those files and restart the container.

Authentik requires backing up the PostgreSQL database and the /media volume (certificates, custom themes). Use pg_dump for the database on a schedule. Authentik can export flows, applications, and providers as blueprints — storing these in git gives you configuration-as-code for rapid recovery.

Keycloak state lives in PostgreSQL. Back up the database with pg_dump and test restores regularly. Keycloak's realm export feature (docker exec keycloak /opt/keycloak/bin/kc.sh export --dir /tmp/export) creates a JSON export of all realm configuration including clients, users (without passwords), and flows. This is invaluable for disaster recovery.

Migrating from Auth0 or Clerk to Self-Hosted

Many teams are moving from Auth0 (Okta) or Clerk to self-hosted identity solutions to control costs and data. Both Authentik and Keycloak can replace these services for most use cases.

From Auth0: Export users via Auth0's Management API (passwords are hashed and can be imported). In Authentik, configure OIDC applications with the same client IDs and secrets as your Auth0 apps — some apps can be migrated with a configuration change, no code changes required. In Keycloak, the migration tooling is similar.

From Clerk: Clerk's OIDC compatibility is limited; it's primarily an SDK-based product. Migration to Authentik or Keycloak typically requires updating application code to use standard OIDC libraries (e.g., next-auth with an OIDC provider instead of Clerk's proprietary SDK).

For detailed migration steps, see our guide to migrating from Auth0 to Keycloak and our best open source Auth0 alternatives overview.

Methodology

Sources consulted: 8
GitHub star data from GitHub.com, March 2026
RAM benchmarks from official documentation and community measurements
Protocol support from official documentation for each project
Date: March 2026

Hoarder vs Wallabag vs Linkwarden 2026

Royce — Wed, 18 Mar 2026 05:10:41 +0000

Hoarder vs Wallabag vs Linkwarden: Self-Hosted Bookmark Managers 2026

TL;DR

The three strongest self-hosted bookmark managers in 2026 each solve a different problem. Hoarder (now rebranded as Karakeep) is the AI-first option: paste a URL and it auto-tags it using a local LLM, takes a screenshot, and archives the full page. Wallabag is the mature read-later tool — open since 2013, stable, focused on distraction-free reading rather than link organization. Linkwarden is the collaborative option with the most thorough archival format support (screenshot, PDF, HTML, Wayback Machine) and growing AI features. All three are free, self-hosted, and actively maintained.

Key Takeaways

Hoarder/Karakeep: ~10K stars, AGPL-3.0, Next.js — AI-powered auto-tagging via Ollama, full-page archiving, Pocket replacement with AI superpowers
Wallabag: ~12K stars, MIT, PHP — read-later focused, open since 2013, distraction-free reader mode, Pocket/Instapaper replacement
Linkwarden: ~16K stars, AGPL-3.0, Next.js — collaborative collections, screenshot+PDF+HTML archival, optional AI tagging via Ollama
Pocket is dead: Mozilla shut down Pocket in July 2025, making 2026 the first full year where self-hosted alternatives are the only option
AI tagging: Both Hoarder and Linkwarden integrate with Ollama for local LLM-based tag generation — no data sent to the cloud
Import/export: All three support Netscape HTML bookmark format import (the universal bookmark export format from every browser)

Why Self-Host Your Bookmarks?

Mozilla shut down Pocket in July 2025, forcing millions of users to find alternatives. The commercial options (Raindrop.io, Readwise Reader) are solid but cost $2.99–$7.99/month and process your bookmarks on their servers. If you're already running a home server or VPS, self-hosting a bookmark manager is a natural extension.

Beyond cost, the privacy argument is compelling: your reading list reveals a lot about your interests, research, and professional focus. Self-hosting keeps that data on your hardware.

The three tools here cover the main use cases:

Read-later / distraction-free reading: Wallabag
AI-organized bookmark collection: Hoarder
Collaborative link collections with thorough archival: Linkwarden

Feature Comparison

Feature	Hoarder	Wallabag	Linkwarden
GitHub Stars	~10K	~12K	~16K
License	AGPL-3.0	MIT	AGPL-3.0
Stack	Next.js (TypeScript)	PHP (Symfony)	Next.js (TypeScript)
AI auto-tagging	Yes (Ollama)	No	Yes (Ollama, optional)
AI summarization	Yes	No	Yes (optional)
Full-page archival	Yes (screenshot + text)	Yes (article text only)	Yes (screenshot + PDF + HTML)
Wayback Machine	No	No	Yes (optional)
Readability extract	Yes	Yes (primary feature)	Yes
Screenshots	Yes	No	Yes
PDF archival	No	No	Yes
Browser extension	Chrome + Firefox	Chrome + Firefox	Chrome + Firefox
Mobile app	iOS + Android	iOS + Android (unofficial clients)	PWA
Collaborative collections	No	No	Yes
Public link sharing	Yes	Yes	Yes
RSS import	No	Yes	No
Pocket import	Yes	Yes	Yes
Wallabag import	Via browser export	—	Via browser export
Tags	Yes (AI + manual)	Yes (manual)	Yes (AI + manual)
Full-text search	Yes	Yes	Yes
Resource usage	~500MB RAM	~256MB RAM	~512MB RAM
Database	PostgreSQL	MySQL/PostgreSQL/SQLite	PostgreSQL

Hoarder (Karakeep) Deep Dive

Hoarder rebranded to Karakeep in late 2025 but the project is the same. The core value proposition: you save a URL and the work is done. Hoarder fetches the full page, takes a screenshot, extracts readable text, and sends that content to a local LLM (via Ollama) to generate 3–5 relevant tags automatically.

The result is a bookmark library that stays organized without manual effort. Over time, your tags converge into a useful taxonomy of your interests — "devops", "python", "architecture", "security" — without you manually tagging each link.

AI models that work well:

llama3.2:3b — fast, good tag quality, runs on 8GB RAM
mistral:7b — better quality, needs 16GB RAM
phi3:mini-4k — smallest footprint, adequate quality

Noteworthy features:

Notes and images saved alongside bookmarks (not just URLs)
List view and card view with screenshots
iOS and Android apps with share sheet support
Full-text search across archived content

Limitations:

No collaborative features — single-user or per-account only
No PDF archival (screenshot + text only)
Less mature than Wallabag (launched 2024 vs Wallabag's 2013)

Hoarder Docker Compose

version: "3.8"

services:
  web:
    image: ghcr.io/karakeep-app/karakeep:release
    restart: unless-stopped
    volumes:
      - hoarder_data:/data
    ports:
      - 3000:3000
    environment:
      HOARDER_VERSION: release
      NEXTAUTH_SECRET: your-secret-here
      NEXTAUTH_URL: http://localhost:3000
      DATA_DIR: /data
      MEILI_ADDR: http://meilisearch:7700
      MEILI_MASTER_KEY: your-master-key
      # Optional: Ollama for AI tagging
      OLLAMA_BASE_URL: http://ollama:11434
      INFERENCE_TEXT_MODEL: llama3.2:3b
    depends_on:
      - meilisearch

  meilisearch:
    image: getmeili/meilisearch:v1.11
    restart: unless-stopped
    environment:
      MEILI_MASTER_KEY: your-master-key
      MEILI_NO_ANALYTICS: "true"
    volumes:
      - meilisearch_data:/meili_data

  # Optional: run Ollama in Docker
  ollama:
    image: ollama/ollama:latest
    restart: unless-stopped
    volumes:
      - ollama_data:/root/.ollama

volumes:
  hoarder_data:
  meilisearch_data:
  ollama_data:

Wallabag Deep Dive

Wallabag is the oldest of the three (2013) and the most focused: it's a read-later app, not a bookmark manager. The distinction matters. Wallabag fetches the article content, strips ads and navigation, and presents it in a clean reading view — similar to Pocket or Instapaper. It's not designed for saving URLs you want to reference later; it's for articles you want to read later.

Unique strengths:

RSS feed import — save articles from feeds automatically
E-reader export (EPUB, Mobi) for reading on Kindle
Official mobile apps for iOS and Android (not just PWA)
Annotate articles with highlights and notes
Well-maintained PHP codebase with strong security track record
MIT license (vs AGPL for Hoarder and Linkwarden)

Limitations:

No AI features (no auto-tagging, no summarization)
No screenshot or PDF archival — saves article text only
No collaborative features
PHP stack may feel dated compared to Next.js alternatives

Wallabag Docker Compose

version: "3"

services:
  wallabag:
    image: wallabag/wallabag:latest
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=wallaroot
      - SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql
      - SYMFONY__ENV__DATABASE_HOST=db
      - SYMFONY__ENV__DATABASE_PORT=3306
      - SYMFONY__ENV__DATABASE_NAME=wallabag
      - SYMFONY__ENV__DATABASE_USER=wallabag
      - SYMFONY__ENV__DATABASE_PASSWORD=wallapass
      - SYMFONY__ENV__SECRET=change-me-to-a-long-random-string
      - SYMFONY__ENV__FOSUSER_REGISTRATION=false
      - SYMFONY__ENV__DOMAIN_NAME=https://read.yourdomain.com
    ports:
      - "80:80"
    volumes:
      - wallabag_images:/var/www/wallabag/web/assets/images
    depends_on:
      - db
      - redis

  db:
    image: mariadb
    environment:
      - MYSQL_ROOT_PASSWORD=wallaroot
      - MYSQL_DATABASE=wallabag
      - MYSQL_USER=wallabag
      - MYSQL_PASSWORD=wallapass
    volumes:
      - wallabag_db:/var/lib/mysql
    restart: unless-stopped

  redis:
    image: redis:alpine
    restart: unless-stopped

volumes:
  wallabag_images:
  wallabag_db:

Linkwarden Deep Dive

Linkwarden sits between Hoarder and Wallabag in philosophy. It's a bookmark manager (not a read-later tool) with the most thorough archival support of the three. For every saved URL, Linkwarden automatically stores multiple formats: screenshot, PDF, single-file HTML, and can optionally ping the Wayback Machine. Even if the original site goes down, you have four ways to access the content.

The collaborative angle sets it apart: you can create shared collections with multiple users, each with their own permissions. This makes it usable for team link curation — a shared research collection, a team "read later" list, or a collaborative bookmarking tool for a small team.

Unique strengths:

Most thorough archival: screenshot + PDF + HTML + Wayback Machine
Collaborative collections with user permissions
16K stars — most popular of the three
Clean UI with tag and collection organization
Reader view for distraction-free reading
Annotation support

Limitations:

No native mobile apps (PWA only)
AI features more recent and less polished than Hoarder
No RSS import

Linkwarden Docker Compose

version: "3"

services:
  linkwarden:
    env_file: .env
    image: ghcr.io/linkwarden/linkwarden:latest
    restart: always
    ports:
      - 3000:3000
    volumes:
      - linkwarden_data:/data/data
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    restart: always
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_USER: postgres
      POSTGRES_DB: linkwarden
    volumes:
      - pg_data:/var/lib/postgresql/data

volumes:
  linkwarden_data:
  pg_data:

.env file:

NEXTAUTH_SECRET=your-long-secret
NEXTAUTH_URL=https://links.yourdomain.com
POSTGRES_PASSWORD=yourpassword
DATABASE_URL=postgresql://postgres:yourpassword@postgres:5432/linkwarden

Importing from Pocket

All three tools support Pocket import. The process:

Export from Pocket: Visit getpocket.com/export and download your HTML export file
Hoarder: Settings → Import → Pocket HTML
Wallabag: Import → Pocket → Upload HTML file
Linkwarden: Settings → Import → Netscape HTML Bookmarks

Note: After Pocket's shutdown in July 2025, the export URL may no longer be accessible. If you have an old Pocket export, all three tools accept it. If you're migrating from another bookmark tool, most export to Netscape HTML format.

When to Choose Each

Choose Hoarder if:

You want zero-effort organization — AI tags everything automatically
You're replacing Pocket and want similar UX but with local AI
You save a mix of links, notes, and images (not just URLs)
You run Ollama already or want an excuse to try local LLMs

Choose Wallabag if:

Your primary use case is reading long-form articles later, not organizing links
You want e-reader (Kindle/Kobo) export
You need RSS feed integration
MIT license is important
You prefer a mature, stable, battle-tested codebase

Choose Linkwarden if:

Archival completeness matters — you want screenshots, PDFs, AND HTML copies
You're doing collaborative bookmarking with a team
16K stars and the largest community gives you confidence
You want optional AI features without making them mandatory

For more on self-hosted alternatives to commercial services, see our guide to self-hosting Hoarder, our Wallabag self-hosting guide, and the best open source link management tools. For the full privacy-focused self-hosted stack, see our homelab software stack guide.

Browser Extension Comparison

All three tools provide browser extensions for one-click saving, but the experience differs meaningfully.

Hoarder's extensions (Chrome and Firefox) add a toolbar button that saves the current page immediately. A small popup confirms the save and shows the AI-generated tags once processing completes (usually 10–30 seconds). You can add manual tags or notes before saving. The extension also supports right-click saving of links from any page.

Wallabag's extensions trigger a save and redirect you away — there's no confirmation popup by default. The experience is functional but dated compared to the newer tools. A companion iOS share extension exists for saving from Safari.

Linkwarden's extensions show a save dialog with collection selection and tag input. You can choose which collection to save to immediately, and the extension shows a progress indicator while archival runs (screenshot + PDF processing). The ability to select the target collection at save time is a meaningful UX advantage for users with complex collection structures.

Self-Hosting Costs and Resources

Running any of these tools on a VPS costs $4–$12/month depending on provider and configuration.

Hoarder needs at minimum: 2 CPU cores, 1GB RAM for the app (excluding Ollama). Add 8–16GB RAM and 4+ CPU cores if you run Ollama on the same machine. The full stack with Ollama running llama3.2:3b needs ~10GB RAM. Alternatively, point Hoarder at an Ollama instance on a different machine.

Wallabag is the lightest: 1 vCPU and 512MB RAM handle a single-user instance comfortably. A Raspberry Pi 4 runs it with room to spare. The only scalability constraint is MySQL/MariaDB performance on very large archives.

Linkwarden needs 1–2 vCPU and 1–2GB RAM for the Next.js app and PostgreSQL. The archival processes (screenshot, PDF) can be CPU-intensive when saving many links simultaneously. A $6–8/month VPS handles typical individual or small team use.

For storage, all three archive page content. Linkwarden's multi-format archival (screenshot + PDF + HTML) uses the most storage — budget 500KB–2MB per saved link. At 10,000 saved links, that's 5–20GB of archived content.

Security and Privacy Notes

The primary privacy benefit of self-hosting bookmark managers is that your reading list and research habits stay on your server. But there are secondary privacy considerations.

When you save a link, all three tools fetch the URL from your server — meaning your server's IP address makes the HTTP request to the target website, not your personal device. This can be an advantage (websites log your server IP, not your home IP) or a disadvantage (your VPS provider can see outbound requests) depending on your threat model.

For Hoarder with Ollama, page content is sent to the local LLM running on your server. No data leaves your infrastructure. If you're not running Ollama, AI features are disabled and no third-party AI services are contacted.

Wallabag's article extraction is server-side. The PHP Mercury Parser-compatible extractor fetches and parses article content on your server.

Linkwarden's Wayback Machine integration (optional) sends URLs to archive.org. Disable this if you don't want link data shared externally.

Methodology

Sources consulted: 7
GitHub star data from GitHub.com, March 2026
Docker Compose configs from official documentation
Resource usage from community benchmarks and self-reported hardware requirements
Date: March 2026

Docmost vs Outline vs BookStack Wiki 2026

Royce — Wed, 18 Mar 2026 05:09:56 +0000

Docmost vs Outline vs BookStack: Self-Hosted Wiki and Docs 2026

TL;DR

For self-hosted wikis in 2026, the three strongest open source contenders are Docmost (modern block editor, real-time collab, AGPL), Outline (Notion-like polish, requires S3 + external auth), and BookStack (PHP, hierarchical structure, simplest setup). BookStack wins for ease of deployment and anyone who doesn't have an identity provider set up. Outline wins for teams who want the best editing experience and already run Authentik or Keycloak. Docmost is the rising contender — newer but rapidly improving, with better Draw.io integration than either competitor.

Key Takeaways

BookStack: ~16K stars, MIT, PHP/Laravel — easiest self-host, built-in email/password auth, hierarchical Books/Chapters/Pages structure
Outline: ~30K stars, BSL (source-available), TypeScript — best editing experience, requires external auth provider and S3 storage
Docmost: ~11K stars, AGPL-3.0, TypeScript — newer, real-time collab, native Draw.io, no S3 dependency for basic setup
Auth gotcha: Outline requires an external OIDC/OAuth provider (no built-in login) — plan for Authentik/Keycloak before deploying
License: Outline uses Business Source License (not OSI-approved open source) — important if you have legal requirements for OSS-only
Search quality: Outline has excellent full-text search; BookStack is good; Docmost is catching up

Why These Three?

The self-hosted wiki space is crowded — Wiki.js, DokuWiki, TiddlyWiki, XWiki, and Confluence Server all exist. But in 2026, three platforms have pulled ahead for teams that want modern editing experiences without Confluence's cost:

Docmost emerged from the frustration that Outline requires S3 and an external auth provider just to get started. It launched in 2024 and hit 11K stars faster than most tools in the space.
Outline is the established Notion-replacement for teams, backed by a small company with a hosted version. The self-hosted edition is free but source-available under BSL.
BookStack has been shipping monthly releases since 2015, maintained by a solo developer. It's the most opinionated of the three — fixed hierarchy, simpler UI — but it's the easiest to run.

Full Feature Comparison

Feature	Docmost	Outline	BookStack
GitHub Stars	~11K	~30K	~16K
License	AGPL-3.0	Business Source License	MIT
Language/Stack	TypeScript (Node.js)	TypeScript (Node.js)	PHP (Laravel)
Editor	Block editor (ProseMirror)	Block editor (ProseMirror)	WYSIWYG + Markdown
Real-time collab	Yes	Yes	No
Spaces/Collections	Yes (Spaces)	Yes (Collections)	Books → Chapters → Pages
Nested pages	Yes (unlimited depth)	Yes	Fixed 3-level hierarchy
Comments	Yes	Yes	Yes
Diagrams	Draw.io native + Mermaid	Mermaid only	Draw.io (plugin)
Templates	Yes	Yes	Yes
Full-text search	Good	Excellent	Good
REST API	Basic	Comprehensive	Yes
Webhooks	Yes	Yes	Yes
Built-in auth	Yes (email/password)	No (requires OIDC/OAuth)	Yes (email/password)
LDAP	Yes	No (via OIDC only)	Yes (native LDAP)
SAML	Yes	No	Yes
OIDC/OAuth	Yes	Yes (required)	Yes
S3/object storage	Optional	Required (or compatible)	No (local disk)
Dark mode	Yes	Yes	Yes
Mobile-friendly	Yes	Yes	Yes
Import from Notion	Yes	Yes	No
Import from Confluence	Partial	Partial	Via plugin
Export	Markdown, PDF	Markdown, PDF	PDF, HTML, Markdown

Authentication Deep Dive

Authentication is the biggest friction point when choosing between these three, so it deserves its own section.

BookStack

BookStack has full built-in email/password authentication. You can start using it immediately after installation with no external dependencies. For teams that want SSO later, BookStack supports:

LDAP (built-in)
SAML 2.0 (built-in)
OIDC (built-in)
Social logins (GitHub, Google, etc. via OAuth)

This makes BookStack the most accessible for teams that don't already have an identity provider.

Docmost

Docmost also includes built-in email/password auth. It additionally supports OIDC for SSO. You can get started without any external auth infrastructure, and add SSO later when your team grows.

Outline

Outline has no built-in email/password login. This is by design — the maintainers want to delegate auth entirely to identity providers. Before your first user can log in, you must configure at least one of:

Google OAuth (simplest if your team uses Google Workspace)
Slack OAuth
OIDC (works with Authentik, Keycloak, Logto, Zitadel, etc.)
Azure AD / Microsoft 365

For teams already running an identity provider like Authentik, this is a non-issue. For teams starting fresh, it adds a meaningful setup step. See our guide to self-hosting Authentik if you want to set up SSO for Outline.

Docker Setup

Docmost

version: "3"

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: "http://localhost:3000"
      APP_SECRET: "your-long-secret-here"
      DATABASE_URL: "postgresql://docmost:yourpassword@db/docmost"
      REDIS_URL: "redis://redis:6379"
    ports:
      - "3000:3000"
    restart: unless-stopped
    volumes:
      - docmost_data:/app/data/storage

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: yourpassword
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7.2-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  docmost_data:
  pg_data:
  redis_data:

Outline

Outline requires S3-compatible storage for file uploads. MinIO is the standard self-hosted option:

version: "3"

services:
  outline:
    image: docker.getoutline.com/outlinewiki/outline:latest
    environment:
      DATABASE_URL: postgres://outline:yourpassword@postgres:5432/outline
      REDIS_URL: redis://redis:6379
      URL: https://wiki.yourdomain.com
      SECRET_KEY: your-64-char-secret-here
      UTILS_SECRET: your-64-char-utils-secret
      # S3 (MinIO)
      AWS_ACCESS_KEY_ID: minio-access-key
      AWS_SECRET_ACCESS_KEY: minio-secret-key
      AWS_REGION: us-east-1
      AWS_S3_UPLOAD_BUCKET_URL: http://minio:9000
      AWS_S3_UPLOAD_BUCKET_NAME: outline
      AWS_S3_FORCE_PATH_STYLE: "true"
      # Auth (one provider required)
      OIDC_CLIENT_ID: outline
      OIDC_CLIENT_SECRET: your-oidc-secret
      OIDC_AUTH_URI: https://auth.yourdomain.com/application/o/authorize/
      OIDC_TOKEN_URI: https://auth.yourdomain.com/application/o/token/
      OIDC_USERINFO_URI: https://auth.yourdomain.com/application/o/userinfo/
    depends_on:
      - postgres
      - redis
    ports:
      - "3000:3000"
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: outline
      POSTGRES_PASSWORD: yourpassword
      POSTGRES_DB: outline
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:alpine
    restart: unless-stopped

  minio:
    image: minio/minio
    command: server /data --console-address :9001
    environment:
      MINIO_ROOT_USER: minio-access-key
      MINIO_ROOT_PASSWORD: minio-secret-key
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    restart: unless-stopped

volumes:
  pg_data:
  minio_data:

BookStack

BookStack is the simplest to deploy — just an app container and MySQL/MariaDB:

version: "3"

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - APP_URL=https://wiki.yourdomain.com
      - APP_KEY=base64:YOUR_GENERATED_KEY_HERE
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_DATABASE=bookstackapp
      - DB_USERNAME=bookstack
      - DB_PASSWORD=yourpassword
    volumes:
      - ./bookstack_app:/config
    ports:
      - "6875:80"
    restart: unless-stopped
    depends_on:
      - bookstack_db

  bookstack_db:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - MYSQL_ROOT_PASSWORD=yourrootpassword
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=yourpassword
    volumes:
      - ./bookstack_db:/config
    restart: unless-stopped

Generate the APP_KEY with: docker run --rm --entrypoint /bin/sh lscr.io/linuxserver/bookstack -c "APP_KEY= php artisan key:generate --show"

Content Organization Philosophies

The three tools take fundamentally different approaches to organizing knowledge, and your preference here may be the deciding factor.

BookStack: Fixed Hierarchy

BookStack enforces a strict three-level structure: Books contain Chapters, Chapters contain Pages. You can add a Shelves level above Books. This rigidity is actually a feature for some teams — everyone knows where to put things, and browsing the structure is intuitive for non-technical users. The downside: deeply nested information doesn't map well, and you can't have standalone pages outside a book.

Outline: Flat Collections with Nesting

Outline uses Collections (similar to BookStack's Books) but allows arbitrary nesting depth. Pages can be nested inside other pages without a fixed hierarchy. Search is strong enough that strict organization matters less — Outline encourages a "write first, organize later" workflow. Teams migrating from Notion find this familiar.

Docmost: Spaces with Flexible Structure

Docmost uses Spaces (like Outline's Collections, or BookStack's Books) with unlimited page nesting. The block editor experience is closest to Notion, with slash commands for inserting blocks. The native Draw.io integration for architecture diagrams is a meaningful advantage over Outline (which only supports Mermaid text diagrams).

When to Choose Each

Choose Docmost if:

You want real-time collaboration with a modern block editor
Draw.io / diagrams.net integration matters (architecture docs, system diagrams)
You want true AGPL open source (not source-available like Outline's BSL)
You're willing to accept a less mature project in exchange for faster improvement velocity

Choose Outline if:

You already have an OIDC provider (Authentik, Keycloak, Google Workspace, etc.)
Search quality and breadth of integrations are top priorities
You're migrating from Notion and want the closest equivalent experience
You need a polished API for programmatic doc management

Choose BookStack if:

You want the quickest path to a working wiki (no auth provider, no S3)
Your team is non-technical and benefits from a fixed, predictable structure
LDAP/SAML integration is needed without an intermediate identity provider
MIT license is required for organizational or compliance reasons

For more on self-hosted documentation tools, see our guide to the best open source Confluence alternatives, our self-hosting guide for Outline, and our how to self-host Docmost guide. If you need SSO for Outline, see our Authentik vs Keycloak vs Authelia comparison.

Migrating Between These Tools

Knowledge base migrations are painful but sometimes necessary. Here's what to expect.

Confluence → BookStack: The most common migration path. The confluence2bookstack community tool handles basic content. Tables, page hierarchy, and text content migrate reasonably well. Macros, attachments, and complex formatting require manual cleanup. BookStack's official migration guide covers the process step by step.

Confluence → Outline: Outline's import handles Confluence HTML exports. Nested page structures flatten into Outline's collection model. Images and attachments require separate handling. Expect to spend time reorganizing content that doesn't map cleanly to flat collections.

Notion → Docmost or Outline: Both tools accept Notion HTML and Markdown exports. The block editor structure is similar enough that most content migrates with reasonable fidelity. Notion databases don't have an equivalent — they become static tables or need to be moved to a dedicated tool.

Between the three: Moving between BookStack, Outline, and Docmost generally requires exporting to Markdown from the source and re-importing. None of the three have direct migration paths between each other, though community scripts exist for common migrations.

Permissions and Access Control

For teams, the permission model matters as much as the editing experience.

BookStack has the most granular permission system: you can control read, create, update, and delete access independently at the Shelf, Book, Chapter, and Page level, for both roles and individual users. LDAP/SAML integration means you can sync groups from your directory server to BookStack roles automatically. This makes BookStack the strongest choice for organizations with complex access requirements.

Outline uses a simpler model: workspace-level roles (Admin, Member, Viewer) plus collection-level permissions (read-only, read-write). Guest access via share links works for external sharing without accounts. The lack of built-in auth means you rely on your OIDC provider's groups to map to Outline roles.

Docmost supports role-based permissions at the Space level. Admin, Member, and Viewer roles exist at the workspace level, with Space-level overrides. The permission model is simpler than BookStack but suitable for most team use cases. SAML and OIDC support allows SSO-based role assignment.

Performance at Scale

All three tools are fast for typical team use (under 1,000 pages, under 100 users). At scale, differences emerge.

BookStack can handle large page counts well — the MySQL-backed search is fast and well-indexed. PHP can be slow for large page trees if not configured with opcache, but the LinuxServer Docker image handles this. Nginx in front of BookStack is recommended for production.

Outline is fast for editing but search performance depends heavily on PostgreSQL configuration. On large wikis (10,000+ pages), search can become slow without proper Postgres tuning (full-text search indexes). The S3 requirement means file uploads are not bottlenecked by your application server.

Docmost is newer and less tested at large scale. For most teams under 500 pages, performance is excellent. Watch GitHub issues for reports on large-scale performance as the project matures.

Methodology

Sources consulted: 7
GitHub star data from GitHub.com, March 2026
Docker Compose configs from official documentation for each project
License information verified from project repositories
Date: March 2026

TanStack Query vs SWR vs Apollo Client 2026

Royce — Wed, 18 Mar 2026 05:09:50 +0000

TanStack Query vs SWR vs Apollo Client 2026

TL;DR

TanStack Query v5 is the best general-purpose data fetching library for React in 2026 — 12M+ weekly downloads, rich mutation handling, and excellent devtools. SWR wins on bundle size (4 KB vs 13 KB) and simplicity for Vercel/Next.js apps with straightforward data needs. Apollo Client remains the gold standard for GraphQL-heavy applications with complex entity relationships — nothing else comes close for normalized graph caching.

Key Takeaways

TanStack Query: 12.3M weekly downloads, 48K GitHub stars — overtook SWR in 2024 and widened the gap
SWR: 4.9M weekly downloads, 32K GitHub stars — Vercel-backed, 4 KB gzipped, Next.js native
Apollo Client: 1.4M weekly downloads, 47.4K GitHub stars — GraphQL specialist, highest complexity
TanStack Query is 13.4 KB gzipped vs SWR at 4.2 KB — 3x size for 3x feature depth
Apollo's normalized cache (InMemoryCache) is the best in class for complex GraphQL entity graphs
SWR added useSWRMutation in v2 but manual optimistic update handling is still more complex than TanStack
TanStack Query v5 removed the status === "loading" state — now uses isPending consistently

Why Data Fetching Libraries Matter

useEffect + fetch leaves you reinventing: loading states, error boundaries, background refetching, cache invalidation, pagination, optimistic updates, and request deduplication. Each of these libraries solves the same core problem with different priorities.

The API type your backend exposes is the most important selection criterion. REST and tRPC apps thrive with TanStack Query or SWR. GraphQL apps are served best by Apollo Client (or urql — see Apollo Client vs urql 2026). The choice gets more nuanced when you have complex mutation patterns, real-time requirements, or bundle size constraints.

One of the most common mistakes teams make is choosing a data fetching library based on its simplest use case. SWR looks appealingly minimal in a tutorial that fetches user data. But tutorials don't show you what happens when you need to optimistically update a list after adding an item, or invalidate a cached query when a related mutation succeeds, or implement infinite scroll with cursor-based pagination. The libraries diverge significantly in these scenarios, and switching later is painful.

Server components in Next.js App Router have changed the calculus somewhat. For data that can be fetched server-side, you may not need a client-side data fetching library at all — fetch in a React Server Component with Next.js's built-in caching handles a wide range of use cases. The scenarios where TanStack Query and SWR still shine are: client-side data that depends on user interaction, real-time updates, optimistic UI, and cached data that needs to stay fresh across navigation. Apollo Client remains essential for GraphQL regardless of the server component trend.

Comparison Table

Dimension	TanStack Query v5	SWR v2	Apollo Client v3
Weekly Downloads	12.3M	4.9M	1.4M
GitHub Stars	48K	32K	47.4K
Bundle Size (gzipped)	13.4 KB	4.2 KB	~47 KB
API Type	REST / any	REST / any	GraphQL
Cache Strategy	Query-key based	URL/key based	Normalized entity cache
Mutations	`useMutation` hook	`useSWRMutation`	`useMutation`
Optimistic Updates	Built-in	Manual	Built-in
Subscriptions	No (use websockets)	No	Yes
Devtools	Excellent	Basic	Good
SSR/Next.js	Yes (Hydration)	Native	Yes
Offline support	Yes	Limited	Yes

TanStack Query v5

TanStack Query (formerly React Query) is the most fully-featured server state management library for React. v5 shipped with a more consistent API, improved TypeScript generics, and the new suspense mode built into the core hooks.


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

// Basic query
function UserProfile({ userId }: { userId: string }) {
  const { data, isPending, isError, error } = useQuery({
    queryKey: ["user", userId],
    queryFn: () => fetch(`/api/users/${userId}`).then((r) => r.json()),
    staleTime: 5 * 60 * 1000, // 5 minutes
    gcTime: 10 * 60 * 1000,   // 10 minutes (formerly cacheTime)
  });

  if (isPending) return <Spinner />;
  if (isError) return <Error message={error.message} />;

  return <div>{data.name}</div>;
}

// Mutation with optimistic updates
function UpdateUserForm({ user }: { user: User }) {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (update: Partial<User>) =>
      fetch(`/api/users/${user.id}`, {
        method: "PATCH",
        body: JSON.stringify(update),
        headers: { "Content-Type": "application/json" },
      }).then((r) => r.json()),

    onMutate: async (update) => {
      // Cancel in-flight queries for this user
      await queryClient.cancelQueries({ queryKey: ["user", user.id] });

      // Snapshot current state for rollback
      const previous = queryClient.getQueryData(["user", user.id]);

      // Optimistically update
      queryClient.setQueryData(["user", user.id], (old: User) => ({ ...old, ...update }));

      return { previous };
    },

    onError: (_err, _update, context) => {
      // Roll back on error
      queryClient.setQueryData(["user", user.id], context?.previous);
    },

    onSettled: () => {
      // Always refetch after mutation
      queryClient.invalidateQueries({ queryKey: ["user", user.id] });
    },
  });

  return (
    <button onClick={() => mutation.mutate({ name: "New Name" })}>
      {mutation.isPending ? "Saving..." : "Update Name"}
    </button>
  );
}

Pagination and infinite scroll are first-class features:

const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
  queryKey: ["posts"],
  queryFn: ({ pageParam }) => fetchPosts({ page: pageParam, limit: 20 }),
  initialPageParam: 1,
  getNextPageParam: (lastPage, pages) =>
    lastPage.hasMore ? pages.length + 1 : undefined,
});

TanStack Query's 60% year-over-year download growth tells its own story. The v5 API improvements — unified isPending status, consistent generics, improved suspense integration — removed several longstanding rough edges. Developers who tried earlier versions and found them confusing often report that v5 is significantly cleaner.

The devtools are TanStack Query's most underrated feature. The floating devtools panel shows every active query, its cache status, stale/fresh state, last-updated timestamp, and the data itself. When you're debugging why a component is showing stale data, or why a mutation didn't invalidate the right cache entries, the devtools make the answer immediately visible. SWR's devtools are minimal and Apollo's are good but slower to navigate.

When TanStack Query is the right choice:

REST or tRPC APIs with complex mutation patterns and cache coordination
Applications needing robust pagination, infinite scroll, or background refetch
Teams that want the best devtools and debugging experience
Projects where TypeScript inference quality and type safety are priorities
Applications with optimistic updates across multiple related queries

SWR

SWR (stale-while-revalidate) is Vercel's data fetching library. It follows the HTTP cache control strategy: return cached data immediately, then revalidate in the background. The API is intentionally minimal.


const fetcher = (url: string) => fetch(url).then((r) => r.json());

// Basic fetch — as simple as it gets
function UserProfile({ userId }: { userId: string }) {
  const { data, error, isLoading } = useSWR(`/api/users/${userId}`, fetcher, {
    revalidateOnFocus: true,
    revalidateOnReconnect: true,
    refreshInterval: 0, // Disable polling
    dedupingInterval: 2000,
  });

  if (isLoading) return <Spinner />;
  if (error) return <Error />;

  return <div>{data.name}</div>;
}

// Mutations with useSWRMutation (v2)
function UpdateUserButton({ userId }: { userId: string }) {
  const { trigger, isMutating } = useSWRMutation(
    `/api/users/${userId}`,
    async (url: string, { arg }: { arg: Partial<User> }) => {
      return fetch(url, {
        method: "PATCH",
        body: JSON.stringify(arg),
        headers: { "Content-Type": "application/json" },
      }).then((r) => r.json());
    }
  );

  return (
    <button onClick={() => trigger({ name: "New Name" })} disabled={isMutating}>
      {isMutating ? "Saving..." : "Update"}
    </button>
  );
}

SWR's focus on simplicity is genuine, not just marketing. The hook API is as small as it can be while still being useful. The stale-while-revalidate strategy means cached data is returned immediately (no loading flash) while a background request updates it silently — this produces a noticeably snappier UX for repeat visits to data-heavy pages.

SWR's global config and key-based revalidation are its most ergonomic features:


// Global config wraps your app
function App() {
  return (
  );
}

// Manual revalidation from anywhere
function RefreshButton() {
  const { mutate } = useSWRConfig();
  return <button onClick={() => mutate("/api/users/me")}>Refresh Profile</button>;
}

SWR's 4.2 KB bundle is its headline advantage. For Next.js apps with simple data needs — user profiles, settings pages, dashboard widgets — SWR is often sufficient and adds minimal overhead. When the data fetching pattern is "fetch this URL and display the result, refresh it occasionally," SWR does that job with the minimum possible code and bundle footprint.

Where SWR shows its limits is in complex mutations. useSWRMutation handles basic cases, but coordinating optimistic updates across multiple cache keys, rolling back failed mutations, and maintaining consistency between related queries requires significantly more manual work than with TanStack Query. Teams that start with SWR often find themselves writing custom cache management code that recreates what TanStack Query provides out of the box. If you're building something with heavy writes, compare the mutation examples carefully before choosing SWR.

When SWR is the right choice:

Next.js applications with straightforward server-state needs and limited mutations
Projects where bundle size is a hard constraint and 4 KB vs 13 KB is material
Simple GET-heavy interfaces like dashboards, profiles, and settings pages
Vercel-deployed apps where SWR's native Next.js integration is a team preference

Apollo Client

Apollo Client is purpose-built for GraphQL. Its normalized InMemoryCache is the technology that justifies its larger bundle (~47 KB gzipped): every entity returned from any query is stored by __typename + id. When two queries return the same user, one cache entry exists, and updates propagate automatically.


const client = new ApolloClient({
  uri: "/graphql",
  cache: new InMemoryCache({
    typePolicies: {
      User: {
        fields: {
          posts: {
            merge(existing = [], incoming) {
              return [...existing, ...incoming];
            },
          },
        },
      },
    },
  }),
});

// Query
const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
      email
      posts {
        id
        title
        createdAt
      }
    }
  }
`;

function UserProfile({ userId }: { userId: string }) {
  const { data, loading, error } = useQuery(GET_USER, {
    variables: { id: userId },
  });

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return <div>{data.user.name}</div>;
}

// Mutation with automatic cache update
const UPDATE_USER = gql`
  mutation UpdateUser($id: ID!, $name: String!) {
    updateUser(id: $id, name: $name) {
      id
      name
    }
  }
`;

function UpdateUserForm({ userId }: { userId: string }) {
  const [updateUser, { loading }] = useMutation(UPDATE_USER, {
    // Apollo automatically updates cache for matching __typename + id
    update(cache, { data }) {
      cache.modify({
        id: cache.identify({ __typename: "User", id: userId }),
        fields: {
          name: () => data.updateUser.name,
        },
      });
    },
  });

  return (
    <button
      onClick={() => updateUser({ variables: { id: userId, name: "New Name" } })}
      disabled={loading}
    >
      Update
    </button>
  );
}

Apollo's normalized cache is worth understanding at a deeper level because it's the feature that most distinguishes it. In a social app, the same User object might appear in 15 different queries — the current user's profile, a list of followers, a comment author, a post author. In TanStack Query, each query stores its own copy of that user. Update the user's name in one mutation, and you need to invalidate all 15 queries to get consistent data. In Apollo, there's one copy of the User object keyed by User:123. Update it in one mutation, and every query that includes that user reflects the change instantly, without re-fetching. For apps with dense entity graphs — social networks, project management tools, e-commerce catalogs — this is a material architectural advantage.

Real-time subscriptions are Apollo's exclusive advantage among the three:


const MESSAGE_SUBSCRIPTION = gql`
  subscription OnNewMessage($channelId: ID!) {
    messageAdded(channelId: $channelId) {
      id
      content
      author { id name }
      createdAt
    }
  }
`;

function MessageFeed({ channelId }: { channelId: string }) {
  const { data } = useSubscription(MESSAGE_SUBSCRIPTION, {
    variables: { channelId },
  });

  return <div>{data?.messageAdded?.content}</div>;
}

Apollo's 47 KB bundle is the library's main disadvantage for performance-sensitive applications. For mobile web apps where First Contentful Paint matters, 47 KB is significant. If you're using GraphQL but don't need subscriptions or normalized caching, urql is worth considering — it's ~18 KB and supports both document caching and normalized caching via a plugin. But if you've committed to Apollo Server and Apollo Studio on the backend, staying in the Apollo ecosystem for the client has real benefits in tooling coherence.

When Apollo Client is the right choice:

GraphQL APIs with complex entity relationships where normalized caching provides real value
Applications requiring real-time subscriptions over WebSocket or SSE
Teams where the Apollo ecosystem (Apollo Server, Apollo Studio, Apollo Federation) is already in use
Projects with large shared entity sets where cache normalization prevents stale data problems

When to Choose Each

Choose TanStack Query as your default for REST and tRPC applications. It handles the full lifecycle — background refetch, optimistic updates, pagination, and mutations — better than any competitor. The 13 KB bundle overhead is well justified by what you get. At 12M+ weekly downloads and 48K GitHub stars, it's also the industry standard in 2026, meaning you'll find tutorials, Stack Overflow answers, and team members who know it.

Choose SWR for simpler Next.js apps where bundle size matters and your mutation patterns don't require TanStack Query's full feature set. SWR's stale-while-revalidate pattern is perfectly suited for most dashboard and profile page patterns. If the primary data fetching concern is "keep this page fresh while the user navigates," SWR is elegant and minimal.

Choose Apollo Client when GraphQL is your primary API and you have complex entity relationships that benefit from normalized caching. Don't use Apollo for REST — TanStack Query is significantly better suited. If you need GraphQL but want a smaller bundle, evaluate urql as an alternative before defaulting to Apollo.

The React Server Component wildcard: As Next.js App Router and server components mature, some teams are finding they need client-side data fetching libraries for fewer queries. Server components handle the initial data load; client components use TanStack Query or SWR only for mutations and real-time updates. This hybrid approach is gaining traction and affects the relative importance of bundle size — if only 20% of queries happen on the client, a 13 KB vs 4 KB difference is less significant than it was in the pages-router era.

Cache Invalidation: The Critical Difference

Cache invalidation is the hardest problem in data fetching libraries, and the three tools approach it very differently. Understanding this difference often clarifies the selection decision.

TanStack Query uses explicit cache key invalidation: queryClient.invalidateQueries({ queryKey: ["user", userId] }) marks a query stale and triggers a background refetch. This is manual but predictable — you control exactly what refetches when. The query key structure is your cache key design, and good key design makes invalidation straightforward.

SWR uses URL-based keys and provides mutate(key) for invalidation. The simplicity is the point — most SWR apps use a URL as the key, so invalidating after a mutation to /api/users/123 means calling mutate("/api/users/123"). This works naturally for simple cases but becomes awkward when multiple different queries might return the same resource under different keys.

Apollo's normalized cache uses entity-level invalidation. You don't invalidate queries — you modify entities in the cache and Apollo propagates those changes to every query that included that entity. This is more sophisticated but also more opaque: when something doesn't update correctly, debugging requires understanding the cache's normalization logic. Apollo's cache modification API (cache.modify, cache.evict) is powerful but has a steeper learning curve than TanStack Query's query invalidation.

Methodology

Download statistics from npm trends and TanStack's own npm stats page (March 2026). Bundle sizes from Bundlephobia. GitHub stars from repository pages. Feature comparison based on official documentation for TanStack Query v5.90, SWR v2.3, and Apollo Client v3.12. Benchmark data on TanStack Query growth sourced from TanStack official npm statistics dashboard.

Turborepo vs Nx vs Moon: Monorepo Tools 2026

Royce — Wed, 18 Mar 2026 05:09:07 +0000

Turborepo vs Nx vs Moon: Monorepo Tools 2026

TL;DR

Turborepo is the right default for most JavaScript/TypeScript monorepos — simple setup, excellent caching, and Vercel Remote Cache. Nx wins for enterprise teams that need a full monorepo platform with code generators, affected-command intelligence, and first-class Angular/React support. Moon is the sleeper pick for polyglot repos (Node.js + Rust + Go) or teams that want reproducible toolchain management baked in.

Key Takeaways

Nx: ~5M weekly downloads — richest ecosystem, generators, affected commands, Nx Cloud
Turborepo: ~2M weekly downloads — simplest setup, Vercel-backed, Rust-based task runner
Moon: ~50K weekly downloads — Rust-based, polyglot support, built-in toolchain management
Turborepo can reduce build times by 70% in large JS/TS monorepos with remote caching
Nx benchmarks show 7x better performance than Turborepo in large-scale open-source tests
Moon manages language versions automatically — no more mismatched Node.js across machines
All three support remote caching — Vercel, Nx Cloud, and moonrepo.dev respectively

The Monorepo Build Problem

Without a build orchestration tool, a 50-package monorepo rebuilds everything on every CI run. With task caching, only packages with changed inputs rebuild. At scale, this difference is 10-50x in CI time.

The three tools in this comparison take different approaches to that core problem: Turborepo optimizes for simplicity and speed, Nx for completeness and enterprise scale, and Moon for reproducibility and polyglot correctness.

Understanding what these tools actually do is important before choosing one. They are not workspace managers — pnpm workspaces, npm workspaces, and Yarn workspaces handle package installation and linking. What Turborepo, Nx, and Moon add on top is task orchestration: knowing which tasks depend on which other tasks, caching the outputs of tasks that haven't changed, and running tasks in the right order with maximum parallelism. A monorepo without one of these tools will still work — but every CI run will be slow, and developers will spend time waiting for builds that don't need to run.

The "remote caching" feature is where the real ROI materializes. Without remote caching, developer A's cached builds aren't shared with developer B or with CI. With remote caching, if CI already built and tested a package on the main branch, the next developer who pulls that code gets the cached output immediately — zero rebuild time. For large teams, remote caching can eliminate 80-90% of total build time.

For broader monorepo context, see How to Set Up a Monorepo with Turborepo 2026 and Turborepo vs Nx Monorepo 2026.

Comparison Table

Dimension	Turborepo	Nx	Moon
Weekly Downloads	~2M	~5M	~50K
Written In	Rust	TypeScript (Rust core in progress)	Rust
Remote Cache	Vercel Remote Cache	Nx Cloud	moonrepo.dev
Code Generators	No	Yes	No
Affected Commands	Basic	Advanced	Yes
Polyglot Support	No	Limited	Yes (Node, Rust, Go)
Toolchain Mgmt	No	No	Yes (auto version mgmt)
Config Complexity	Low	Medium-High	Medium
Pricing (remote cache)	Free (self-host) / Vercel	Free tier / Nx Cloud	Free tier / moonrepo

Turborepo

Turborepo (acquired by Vercel in 2021) is the gateway drug of monorepo tooling. The turbo.json configuration is minimal, the caching is automatic, and setup from a standard pnpm workspace takes under an hour.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "package.json", "tsconfig.json"],
      "outputs": ["dist/**", ".next/**"]
    },
    "test": {
      "dependsOn": ["^build"],
      "inputs": ["src/**", "tests/**"]
    },
    "lint": {
      "inputs": ["src/**", "eslint.config.js"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

# Run builds across all packages (cached)
npx turbo build

# Run only affected packages (based on git diff)
npx turbo build --filter=...[HEAD^1]

# Remote cache via Vercel
npx turbo login
npx turbo link

Turborepo's caching model is file-hash based: if the inputs (source files, env vars, package.json) haven't changed, the outputs are restored from cache. Remote cache allows teams to share this across CI runs and developer machines.

Package filtering is Turborepo's daily workflow tool:

# Only the web app and its dependencies
npx turbo build --filter=@acme/web...

# Only packages changed since main
npx turbo test --filter=...[origin/main]

# Exclude a package
npx turbo build --filter=!@acme/legacy

What Turborepo doesn't have: code generators, advanced project graph visualization, or first-class framework scaffolding. It's a task runner with caching — excellent at that, nothing more. This scope limitation is deliberate. The Turborepo team believes the tool should stay focused on task orchestration and let pnpm workspaces handle package management and developers handle code generation via other tools. Whether this is a strength or a weakness depends entirely on your team's needs.

Turborepo's integration with Vercel Remote Cache deserves special mention. If you're deploying to Vercel, remote caching is free and zero-configuration — turbo login && turbo link and you're done. Builds from CI share caches with local development. Vercel also caches Turborepo outputs as part of build steps, meaning preview deployment builds can reuse the CI cache. This tight integration is a genuine advantage for Vercel users that Nx and Moon can't match.

The Rust rewrite (from Go, completed in 2024) improved Turborepo's performance significantly. Hash computation, file scanning, and graph traversal are all faster. For repos with thousands of files, the cold-start time (no cache hit) improved by 30-40%. Hot-path performance (most tasks cached) was already fast and remained so.

When Turborepo is the right choice:

JavaScript/TypeScript-only monorepos starting from scratch
Teams that want minimal configuration overhead and fast onboarding
Vercel-deployed projects where native Remote Cache integration is a hard advantage
Repos with 5-50 packages where Nx's feature depth isn't needed or wanted

Nx

Nx (by Nrwl) is the most feature-complete monorepo solution in the JavaScript ecosystem. It's been the enterprise standard for large Angular and React codebases for years and has expanded to support virtually every modern framework.

// nx.json
{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "defaultBase": "main",
  "targetDefaults": {
    "build": {
      "cache": true,
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"]
    },
    "test": {
      "cache": true,
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"]
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": ["default", "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)"]
  }
}

# Generate a new React library
nx generate @nx/react:library ui-components --bundler=vite

# Run affected tests (smarter than Turborepo's filter)
nx affected:test --base=main

# Visualize the project graph
nx graph

# Migrate to latest Nx version (automated)
nx migrate latest && nx migrate --run-migrations

Nx's affected commands are more sophisticated than Turborepo's filters: Nx builds a full dependency graph and knows exactly which projects are affected by any file change, including through transitive dependencies. This can mean running 3 packages instead of 15 in a large monorepo. Turborepo's --filter=...[HEAD^1] is simpler and covers most cases, but Nx's affected analysis uses deeper dependency tracking that can be more accurate in complex repos where a shared utility is consumed by many packages.

Nx Cloud provides distributed task execution — tasks fan out across multiple agents automatically, with no manual CI matrix configuration. For large teams, this can reduce CI time from 30 minutes to 5. The Nx Cloud free tier covers small teams, and enterprise pricing is per-seat for larger organizations. This pricing model makes Nx Cloud an easier sell than Turborepo Remote Cache at scale, since Turborepo's remote cache is free on Vercel but requires a paid plan or self-hosting for non-Vercel deployments.

Nx's code generators (called "generators" or formerly "schematics") are its most powerful differentiator for large teams. Running nx generate @nx/react:library ui-components creates the library, sets up the project configuration, adds it to the workspace graph, and generates test scaffolding — all in seconds. For organizations that create dozens of new packages per year, this consistency is significant. Without generators, new packages are created manually, leading to drift in how packages are structured, tested, and bundled.

The Nx migration story is also a practical advantage. If you start with Turborepo and outgrow it, nx migrate has tooling to help. Nx maintains a Turborepo-to-Nx migration guide with automated transforms. This migration path is documented, tested, and used by teams that started simple and grew into Nx's feature set.

When Nx is the right choice:

Large teams (10+ developers) who benefit from code generators and standardized project structure
Angular or NestJS projects (Nx has the best Angular support in the ecosystem)
Repos where affected-command intelligence meaningfully reduces CI scope
Organizations willing to invest in Nx Cloud for distributed execution across CI agents

Moon

Moon (by moonrepo) is the newest of the three and solves a different class of problems: reproducibility and polyglot correctness. Its killer feature is toolchain management — Moon installs and pins Node.js, pnpm, Bun, Deno, and even Rust and Go versions for each workspace, ensuring every developer and CI run uses identical versions.

# .moon/workspace.yml
projects:
  - "apps/*"
  - "packages/*"
  - "services/*"

vcs:
  manager: git
  defaultBranch: main

# .moon/toolchain.yml
node:
  version: "22.11.0"
  packageManager: pnpm
  pnpmVersion: "9.15.0"

rust:
  version: "1.82.0"

# moon.yml (per-project)
language: typescript
type: library

tasks:
  build:
    command: tsc --build
    inputs:
      - "src/**/*"
      - "tsconfig.json"
    outputs:
      - "dist"
  test:
    command: vitest run
    inputs:
      - "src/**/*"
      - "tests/**/*"

# Run tasks across all projects
moon run :build

# Run for specific project
moon run web:build

# Check affected projects
moon ci --base=main --head=HEAD

Moon's remote caching (moonrepo.dev) is free for open-source and affordable for teams. The Rust implementation ensures fast graph traversal even in massive repos.

Moon's approach to the Node.js version problem is worth explaining more concretely. The .moon/toolchain.yml file declares the exact Node.js version (and package manager version) the workspace requires. Moon installs and manages these versions automatically — similar to nvm or volta, but integrated into the build system and applied consistently across all tasks. This means you can't accidentally run a build with Node.js 20 when the project requires Node.js 22, because Moon is managing the runtime. For teams where "works on my machine" CI failures have been a recurring problem, this automatic toolchain management is a significant quality-of-life improvement.

The polyglot story is Moon's most unique feature. A workspace that has JavaScript services, a Rust CLI tool, and Go microservices can all be managed in one moon.yml dependency graph. Moon knows which Rust services need to be rebuilt when a shared type library changes, and which JavaScript services depend on the compiled Rust CLI. Turborepo and Nx are fundamentally JavaScript-centric tools; Moon is language-agnostic by design.

Moon's smaller community (50K weekly downloads vs Turborepo's 2M) is a practical consideration. There are fewer tutorials, fewer GitHub issues documenting edge cases, and fewer team members who will already know the tool when you hire them. The trade is worth making if your use case genuinely requires polyglot support or toolchain management — but for JavaScript-only repos, the community size difference is a real cost.

When Moon is the right choice:

Polyglot monorepos mixing Node.js, Rust, Go, or Python in the same dependency graph
Teams burned repeatedly by Node.js or package manager version mismatches across machines
Projects where deterministic builds are a compliance or reliability requirement
CI environments where toolchain reproducibility needs to be guaranteed, not assumed

When to Choose Each

Choose Turborepo as your default for JavaScript/TypeScript monorepos. It's the simplest path to caching and the easiest to maintain. If you're on Vercel, the free remote cache seals the deal. If you outgrow it, migrating to Nx has official tooling and is well-documented. Don't overthink the initial choice — Turborepo's simplicity means the cost of being wrong is low.

Choose Nx when you need a true monorepo platform — generators, affected intelligence, distributed task execution, and first-class framework support. The configuration cost is justified at scale. If your organization is creating multiple new packages per month, Nx's generators pay for themselves quickly in consistency and reduced bootstrapping time.

Choose Moon when language reproducibility matters more than ecosystem breadth, or when your repo spans multiple programming languages. It's the most principled approach to the "works on my machine" problem, and its toolchain management feature alone is worth evaluating if you've had Node.js version drift issues in CI.

The decision gets easier if you frame it as a progression: most teams should start with Turborepo, evaluate Nx when generators and affected commands become important, and consider Moon if polyglot support or strict toolchain reproducibility becomes a requirement. These are not competitors fighting for the same team — they serve different stages and different types of monorepos.

Methodology

Download statistics from npm trends (March 2026). Performance benchmarks sourced from the Nx large-monorepo benchmark repository (vsavkin/large-monorepo) and Turborepo documentation. Feature comparison based on official documentation for Turborepo 2.x, Nx 21.x, and Moon 1.x. Remote caching pricing reflects free-tier availability as of publication date.

Effect-TS vs fp-ts vs Neverthrow: TS Errors 2026

Royce — Wed, 18 Mar 2026 05:09:04 +0000

Effect-TS vs fp-ts vs Neverthrow: TS Errors 2026

TL;DR

Neverthrow is the pragmatic pick for teams adopting typed errors without a paradigm shift. Effect-TS is the most powerful option — a full async runtime, typed errors, dependency injection, and structured concurrency — but demands a steep learning investment. fp-ts is a battle-tested functional programming toolkit that's being superseded by Effect in most new projects. Start with Neverthrow; graduate to Effect when complexity justifies it.

Key Takeaways

fp-ts: 3.7M weekly downloads, 11.5K GitHub stars — widely used but new projects increasingly choose Effect
Neverthrow: 1.3M weekly downloads, 7.2K GitHub stars — simple Result type, low overhead
Effect-TS: ~13.6K GitHub stars — growing rapidly; v4 beta dropped bundle from ~70 KB to ~20 KB
Effect v4 is now in beta as of February 2026 with major bundle size improvements
Neverthrow is no longer actively maintained — PRs go unreviewed for months
fp-ts and Effect share the same core team — Effect is the official successor
All three solve the same core problem: making failure explicit in the type system

The Problem: TypeScript's Silent Failure Mode

JavaScript's throw is invisible to the type system. A function typed as Promise<User> can throw network errors, validation errors, or database failures — none of which appear in the return type. TypeScript pretends everything succeeds.

// Standard TypeScript — failure is invisible
async function getUser(id: string): Promise<User> {
  const user = await db.users.findById(id); // could throw
  return user; // or return null, or throw...
}

// The caller has no idea this can fail
const user = await getUser("123"); // what could go wrong? TypeScript says: nothing

The three libraries in this comparison solve this differently: Neverthrow with a minimal Result<T, E> type, fp-ts with a full functional programming toolkit, and Effect-TS with an entire async runtime.

This problem isn't theoretical. Untyped error handling is one of the leading causes of runtime failures in TypeScript applications. A function that throws a network timeout gets called by a function that calls another function — and somewhere five layers up, there's a catch clause that logs "Unknown error" and swallows the context. Typed errors make the failure modes explicit at every level of the call stack, so callers can handle specific error types and the compiler enforces that every error path is addressed.

The tradeoff is verbosity. Typed error handling requires more code than try/catch and forces you to thread error types through your function signatures. Teams new to this pattern often find it feels heavy for simple CRUD operations. The libraries in this comparison exist on a spectrum from "minimal overhead" (Neverthrow) to "maximum expressiveness at maximum complexity" (Effect-TS), and picking the right level of investment is the central question.

For related TypeScript patterns, see Neverthrow vs Effect-TS vs oxide-ts: Result Types and Effect-TS vs fp-ts 2026.

Comparison Table

Dimension	Effect-TS v4	fp-ts v2	Neverthrow 0.x
Weekly Downloads	~200K	3.7M	1.3M
GitHub Stars	13.6K	11.5K	7.2K
Bundle Size	~20 KB (v4)	~150 KB	~3 KB
Paradigm	Full runtime + FP	FP toolkit	Minimal Result type
Learning curve	High	High	Low
Typed errors	Yes	Yes (Either)	Yes (Result)
Async handling	Built-in fiber runtime	Task, TaskEither	ResultAsync
Dependency injection	Yes	No	No
Active maintenance	Yes	Maintenance mode	Minimal
Standard adoption	Growing fast	Established	Stable

Neverthrow

Neverthrow provides one thing: a Result<T, E> type with chainable methods. It's the smallest conceptual leap from standard TypeScript — no new paradigms, no unfamiliar operators.


type UserError = { type: "NOT_FOUND" } | { type: "DB_ERROR"; message: string };

function findUser(id: string): Result<User, UserError> {
  const user = userCache.get(id);
  if (!user) return err({ type: "NOT_FOUND" });
  return ok(user);
}

// Chaining
const result = findUser("123")
  .map((user) => ({ ...user, displayName: `${user.firstName} ${user.lastName}` }))
  .mapErr((error) => `Failed: ${error.type}`);

// Pattern matching
if (result.isOk()) {
  console.log(result.value);
} else {
  console.error(result.error);
}

ResultAsync handles promises:


function fetchUser(id: string): ResultAsync<User, UserError> {
  return ResultAsync.fromPromise(
    fetch(`/api/users/${id}`).then((r) => r.json()),
    (error): UserError => ({ type: "DB_ERROR", message: String(error) })
  );
}

// Compose async Results
const result = await fetchUser("123")
  .andThen((user) => fetchUserPreferences(user.id))
  .map((prefs) => prefs.theme);

The maintenance concern is real. Neverthrow's maintainer has been less active since late 2024, with open PRs aging. The library is stable — it's a small codebase with a well-defined scope — but teams starting new projects should weigh this against Effect's active development. Neverthrow's API is stable precisely because it doesn't try to do much. A library that doesn't change isn't necessarily abandoned; it might just be done. Whether that's acceptable depends on your risk tolerance for third-party dependencies.

Neverthrow's approach to composition is worth understanding deeply before committing. The andThen, map, mapErr, and orElse methods enable Railway-Oriented Programming — a pattern where you chain transformations and error handlers without nesting. At its best, this produces very readable code where the happy path flows left-to-right and errors are handled at natural branch points. At scale, however, complex chains can become difficult to debug because intermediate states aren't easily inspected. Effect-TS has better observability tools for this.

When Neverthrow is the right choice:

Teams adopting typed errors incrementally without a full paradigm shift
Simple CRUD apps where Railway-Oriented Programming covers the error patterns
Avoiding fp-ts/Effect's learning curve is a hard requirement for the team
Existing codebases adding typed error handling without a full refactor
Small libraries or utility packages where a minimal dependency is important

fp-ts

fp-ts brings Haskell-style functional programming to TypeScript: Option, Either, TaskEither, IO, Reader, and the full algebraic data type toolkit. It was the gold standard for typed FP in TypeScript for years.


type ApiError = { status: number; message: string };

const fetchUser = (id: string): TE.TaskEither<ApiError, User> =>
  TE.tryCatch(
    () => fetch(`/api/users/${id}`).then((r) => r.json()),
    (error): ApiError => ({ status: 500, message: String(error) })
  );

const getUserDisplayName = (id: string): TE.TaskEither<ApiError, string> =>
  pipe(
    fetchUser(id),
    TE.map((user) => `${user.firstName} ${user.lastName}`),
    TE.mapLeft((err) => ({ ...err, message: `Display name fetch failed: ${err.message}` }))
  );

// Run the computation
const result = await getUserDisplayName("123")();
if (E.isRight(result)) {
  console.log(result.right);
} else {
  console.error(result.left);
}

fp-ts's pipe function is central to everything:


const processUsers = (users: User[]): O.Option<string[]> =>
  pipe(
    users,
    A.filter((u) => u.isActive),
    A.map((u) => u.email),
    (emails) => (emails.length > 0 ? O.some(emails) : O.none)
  );

fp-ts in 2026: The library is in maintenance mode. The core fp-ts team has moved their energy to Effect-TS, which they consider the spiritual successor. fp-ts v2 receives bug fixes but no new features. For teams already invested in fp-ts, it continues to work well — but for new projects, Effect is the recommended path. The migration from fp-ts to Effect is non-trivial but possible, and the Effect team has published guides for teams making the transition.

The pipe function from fp-ts deserves special mention because it's genuinely influential. The pattern of threading a value through a series of transformations — without the intermediate variable assignment of imperative code — produces a particular kind of readable functional code. Many developers who encounter fp-ts for the first time through pipe end up adopting it even if they don't use the rest of the library. Effect has the same pattern, so fp-ts's core idiom carries over.

Bundle size is fp-ts's most significant disadvantage at ~150 KB. This is primarily a problem for frontend applications. For Node.js backends, 150 KB of runtime code is not meaningful. For frontend bundles where every KB affects Time to Interactive, fp-ts is a poor choice. Teams that want functional error handling on the frontend should look at Neverthrow (3 KB) or Valibot with custom Result types instead.

When fp-ts is the right choice:

Existing fp-ts codebases that are stable, well-tested, and deeply understood by the team
Teams with strong functional programming background who prefer fp-ts's minimal scope
Projects using fp-ts's Option and Array utilities extensively where Effect's approach differs
When you want to incrementally migrate to Effect — fp-ts and Effect share conceptual DNA

Effect-TS

Effect-TS is not just an error handling library — it's a complete TypeScript runtime for building production applications. Think of it as an answer to: what if TypeScript had structured concurrency, typed errors, dependency injection, resource management, and observability built in?


// Three type parameters: success, error, requirements (dependencies)
type UserEffect = Effect.Effect<User, UserNotFound | DatabaseError, UserRepository>;

const findUser = (id: string): Effect.Effect<User, UserNotFound | DatabaseError, UserRepository> =>
  Effect.flatMap(UserRepository, (repo) =>
    Effect.tryPromise({
      try: () => repo.findById(id),
      catch: (error): DatabaseError => ({ _tag: "DatabaseError", error }),
    })
  ).pipe(
    Effect.flatMap((user) =>
      user ? Effect.succeed(user) : Effect.fail<UserNotFound>({ _tag: "UserNotFound", id })
    )
  );

// Composing effects
const getUserWithPermissions = (id: string) =>
  pipe(
    findUser(id),
    Effect.flatMap((user) => fetchPermissions(user.id)),
    Effect.map(([user, permissions]) => ({ ...user, permissions }))
  );

Effect v4 (beta, February 2026) brings the bundle down from ~70 KB to ~20 KB for a minimal program including Stream and Schema — a major improvement for adoption concerns. The v4 team has focused heavily on making Effect more accessible: better error messages, cleaner stack traces, improved documentation, and the bundle size improvement that makes frontend usage more viable. Effect v4 is the version where the library crosses from "impressive but too heavy for most projects" to "worth seriously evaluating for complex backend applications."

The learning curve for Effect is real and shouldn't be underestimated. The three-parameter generic Effect<Success, Error, Requirements> is unfamiliar to most TypeScript developers. The pipe-heavy style requires comfort with function composition. The concept of a "fiber" (Effect's concurrency primitive) introduces new mental models for async code. Teams that have successfully adopted Effect report 2-4 weeks before developers feel productive, and 2-3 months before the patterns feel natural. Companies like Harbor have written publicly about choosing not to adopt Effect because the learning investment exceeded the benefit for their use case — that's a legitimate outcome, not a failure of the library.

// Effect's dependency injection

interface UserRepository {
  findById: (id: string) => Promise<User | null>;
}
const UserRepository = Context.GenericTag<UserRepository>("UserRepository");

const LiveUserRepository = Layer.succeed(UserRepository, {
  findById: (id) => db.users.findById(id),
});

// Test implementation
const TestUserRepository = Layer.succeed(UserRepository, {
  findById: (id) => Promise.resolve({ id, name: "Test User", email: "test@example.com" }),
});

// Provide dependencies at the boundary
Effect.runPromise(
  pipe(getUserWithPermissions("123"), Effect.provide(LiveUserRepository))
);

When Effect-TS is the right choice:

Complex backend services where structured concurrency and resource management matter
Teams willing to invest in the learning curve (expect 2-4 weeks to productive velocity)
Applications needing built-in retry, timeout, and circuit breaker patterns
Projects where testability through dependency injection is a priority
Long-lived services where the operational benefits (observability, structured errors, resource cleanup) justify the upfront complexity cost

When to Choose Each

Choose Neverthrow for incremental adoption — it's the smallest step toward typed errors and works with any existing TypeScript codebase. The 3 KB bundle fits anywhere, the API is learnable in an afternoon, and the Result type integrates cleanly with existing code. Accept the reduced maintenance activity for stable, well-scoped codebases.

Choose fp-ts only if you're maintaining an existing fp-ts codebase with a team that knows it well. For new projects in 2026, Effect-TS is the better investment at the same learning curve. The fp-ts team's own guidance is to evaluate Effect for new projects.

Choose Effect-TS when building complex, long-lived backend services and your team can absorb the learning curve. Effect v4's improved bundle size removes the last major adoption barrier. The expressiveness payoff is real for sufficiently complex systems — teams that have adopted it often describe it as making previously-difficult problems (retry with exponential backoff, request cancellation, complex concurrent workflows) feel straightforward.

The honest answer for most teams: Start with Neverthrow. Add typed errors to your 10 most important functions. Learn what it feels like to have failure modes visible in your type signatures. If you find yourself wanting more — dependency injection, structured concurrency, schema validation as part of the same ecosystem — then evaluate Effect. The transition from Neverthrow-style thinking to Effect-style thinking is a manageable conceptual leap.

A Note on the Result Pattern vs Exceptions

One question teams often ask when evaluating these libraries: should we go all-in on typed errors for every function, or only for functions that can "meaningfully fail"? The answer that works best in practice is selective adoption — use typed errors at service boundaries and external API calls, where failure modes are varied and callers need to handle them explicitly. Keep exceptions for truly unexpected errors (programming bugs, out-of-memory, etc.) that represent broken invariants rather than expected failure cases. This hybrid approach avoids the "Result for everything" trap where simple getters and pure functions become verbose for no benefit.

All three libraries support this hybrid approach. Neverthrow's fromThrowable utility wraps exception-throwing functions into Result-returning functions. fp-ts's tryCatch does the same. Effect's Effect.tryPromise and Effect.try wrap throwing code at the boundary. The pattern is: keep your own code typed-error-aware, wrap third-party libraries at the edges, and let exceptions propagate from true bugs.

Methodology

Download statistics from npm trends (March 2026). GitHub stars from repository pages. Bundle sizes from Bundlephobia and official Effect v4 release notes (effect.website blog). Maintenance status assessed from GitHub commit activity and open PR response times over the 6 months prior to publication.

Biome vs ESLint vs Oxlint: JS Linters 2026

Royce — Wed, 18 Mar 2026 05:08:19 +0000

Biome vs ESLint vs Oxlint: JS Linters 2026

TL;DR

ESLint v9 remains the safe default — 50M+ weekly downloads and an irreplaceable plugin ecosystem. Biome is the best choice for greenfield projects that want one fast tool for linting and formatting (no Prettier needed). Oxlint is the fastest raw linter at 50-100x ESLint's speed, but it's linting-only with ~300 rules and no auto-fix for most violations — use it as a CI speed layer, not a replacement.

Key Takeaways

ESLint: 50M+ weekly downloads — universal framework support, 700+ rules, 4000+ plugins
Biome: ~1.5M weekly downloads — 423+ rules, built-in formatter, Rust-based, 10-20x faster than ESLint
Oxlint: ~500K weekly downloads — 50-100x faster than ESLint, linting only, ~300 rules
Biome v2 ships type-aware linting — previously only possible with @typescript-eslint
Biome lints 10,000 files in 0.8 seconds vs ESLint's ~45 seconds
Oxlint is ~2x faster than Biome for pure linting workloads
ESLint flat config (eslint.config.js) is now the standard since v9 — old cascading config deprecated

The Rust Tooling Revolution

JavaScript tooling has entered its Rust era. Both Biome and Oxlint are written in Rust and compiled to native binaries — that's the source of their 10-100x speed advantage over Node.js-based ESLint. The performance gap isn't about algorithms; it's about the runtime. Node.js has JIT compilation, garbage collection pauses, and startup overhead that native Rust binaries simply don't have. When parsing and traversing abstract syntax trees for millions of lines of code, these differences compound.

The practical impact: a mid-sized repo that took ESLint 30-45 seconds to lint now takes Biome under 1 second or Oxlint under 0.5 seconds. In CI, this translates directly to developer cost and iteration speed. At $0.008 per CI minute on GitHub Actions, a team running 50 CI jobs per day that each spend 30 seconds on linting pays roughly $438 per year just for ESLint. Biome brings that to under $30. The math isn't hypothetical — multiple engineering teams have published case studies showing 60-80% CI cost reduction from switching linters.

But speed alone doesn't determine the right choice. Linting is fundamentally about catching bugs and enforcing code standards. A fast linter that doesn't catch your bugs is worthless. The question is whether Biome or Oxlint's rule coverage is sufficient for your codebase — and for many teams in 2026, it increasingly is.

For context on the broader tooling landscape, see Best Code Formatting Tools 2026 and OXC vs ESLint vs Biome: JavaScript Linting in 2026.

Comparison Table

Dimension	ESLint v9	Biome v2	Oxlint 0.x
Weekly Downloads	50M+	~1.5M	~500K
Written In	JavaScript	Rust	Rust
Linting	Yes (700+ rules)	Yes (423+ rules)	Yes (~300 rules)
Formatting	No (needs Prettier)	Yes (built-in)	No
Auto-fix	Excellent	Good	Limited
Type-aware rules	Yes (@typescript-eslint)	Yes (v2+)	No
Plugin ecosystem	4000+ packages	Growing	Minimal
Config complexity	Medium (flat config)	Low	Very low
Speed vs ESLint	1x	10-20x	50-100x

ESLint v9

ESLint turned 13 in 2026 and is more dominant than ever. The v9 release brought flat config — a single eslint.config.js replacing the old cascading .eslintrc.* system — which significantly reduces configuration surprises in monorepos.

// eslint.config.js (flat config, ESLint v9)

  js.configs.recommended,
  {
    files: ["**/*.{ts,tsx}"],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: "./tsconfig.json",
      },
    },
    plugins: {
      "@typescript-eslint": tsPlugin,
    },
    rules: {
      "@typescript-eslint/no-explicit-any": "error",
      "@typescript-eslint/strict-boolean-expressions": "warn",
    },
  },
  {
    files: ["**/*.{jsx,tsx}"],
    plugins: { react: reactPlugin },
    rules: {
      ...reactPlugin.configs.recommended.rules,
      "react/react-in-jsx-scope": "off",
    },
  },
];

ESLint's irreplaceable advantage is its plugin ecosystem. Framework-specific rules (Next.js, Remix, Astro), accessibility (jsx-a11y), security (eslint-plugin-security), and hundreds of specialized plugins have no equivalent in Biome or Oxlint. If you use Storybook, Vitest, or Playwright, there are ESLint plugins that know your APIs. The eslint-plugin-react-hooks rules alone have caught thousands of real bugs in production codebases — Biome ships equivalents, but the React hooks plugin's 12+ years of battle-testing means it handles subtle edge cases that newer implementations may miss.

The v9 flat config migration is worth understanding before committing to ESLint. The old cascading .eslintrc.json system created subtle inheritance bugs in monorepos where config files at different directory levels would combine in unexpected ways. Flat config is explicit: one eslint.config.js at the workspace root, no implicit inheritance, no surprise rule combinations. Teams that have migrated report significantly fewer "why is this rule triggering here?" debugging sessions.

The performance story is improving too. With Vercel's adoption of Oxlint as a pre-pass linter alongside ESLint, teams are finding 60%+ CI improvements without abandoning ESLint's rule depth. The dual-linter pattern (Oxlint fast pass + ESLint for specialized rules) is gaining traction specifically because it preserves ESLint's plugin ecosystem while addressing its performance bottleneck.

ESLint also has the most mature TypeScript integration. @typescript-eslint provides rules that understand your TypeScript types — not just syntax. Rules like no-floating-promises, strict-boolean-expressions, and consistent-return catch real TypeScript bugs that Biome is only beginning to approach with its v2 type-aware rules.

When ESLint is the right choice:

Any project with specialized plugin requirements (Next.js, jsx-a11y, testing frameworks)
Teams with existing ESLint configs where migration cost outweighs speed gains
Monorepos with mixed framework targets needing different rule sets per project
When @typescript-eslint's type-aware rules are required for safety-critical code

Biome

Biome emerged from the Rome project and has become the most credible ESLint+Prettier replacement for new projects. The v2 release was significant: it added type-aware linting rules (previously exclusive to @typescript-eslint), bringing Biome's capabilities much closer to a full ESLint+typescript-eslint setup.

// biome.json
{
  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
  "organizeImports": { "enabled": true },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": { "noExplicitAny": "error" },
      "style": { "useConst": "error" }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",
      "trailingCommas": "es5"
    }
  }
}

# Lint + format in one command
npx @biomejs/biome check --write .

# CI (no writes, exit code 1 on violations)
npx @biomejs/biome ci .

Biome's formatter is a drop-in Prettier replacement for most codebases. It formats JavaScript, TypeScript, JSX, JSON, and CSS. The output is intentionally close to Prettier's — migration scripts are available. Where Prettier and Biome differ, it's usually in edge cases involving complex expressions or unusual syntax — for typical TypeScript React codebases, the output is practically identical.

The v2 addition of type-aware linting is Biome's most significant capability expansion. Previously, rules that needed TypeScript type information — like "this function might return undefined but the caller doesn't check" — required @typescript-eslint with a type-checked config, which adds significant parse time because TypeScript's compiler needs to run. Biome v2 achieves similar analysis through its own type inference engine, maintaining its speed advantage while matching more of ESLint's rule coverage.

// Biome understands this TypeScript correctly
function processItems<T extends { id: string }>(items: T[]): Map<string, T> {
  return new Map(items.map((item) => [item.id, item]));
}

One practical consideration: Biome's VS Code extension is mature and provides real-time feedback with the same speed advantages as the CLI. Format-on-save with Biome is noticeably faster than with Prettier, which matters for large files or complex TypeScript. Teams that switch often mention the editor experience as an unexpected quality-of-life improvement.

The biggest practical migration challenge from ESLint to Biome is the missing rules. Biome's 423+ rules are growing rapidly, but specialized plugins — eslint-plugin-import, eslint-plugin-testing-library, Storybook-specific rules — either don't exist in Biome or are partial. Audit your current ESLint config before migrating: if you rely on 5+ specialized plugins, Biome may not yet cover enough of your rule set.

When Biome is the right choice:

New projects where you want zero Prettier + ESLint config overhead
Teams that prioritize fast CI and local feedback loops
Projects not requiring more than 5-6 specialized ESLint plugins
Codebases wanting both linting and formatting in one consistent tool

Oxlint

Oxlint (part of the OXC project) focuses on raw linting speed above all else. At 50-100x faster than ESLint, it can lint a monorepo with 100K lines in under a second. The tradeoff: no formatting, limited auto-fix, ~300 rules, and virtually no plugin ecosystem.

# Install and run
npm install -D oxlint
npx oxlint src/

# With specific rules
npx oxlint --deny=correctness --warn=perf src/

# TypeScript files
npx oxlint --tsconfig=tsconfig.json src/

// .oxlintrc.json
{
  "rules": {
    "no-unused-vars": "error",
    "no-console": "warn",
    "react/no-direct-mutation-state": "error"
  },
  "plugins": ["react", "typescript"],
  "ignorePatterns": ["dist/", "node_modules/"]
}

The most pragmatic Oxlint use case in 2026 is the dual-linter approach: Oxlint as a fast pre-pass for obvious errors (runs in 0.3s), then ESLint for type-aware and framework-specific rules (runs in 30s but only on changed files). Vercel's engineering blog documented 60%+ CI time reduction using exactly this pattern. The idea is that most trivial errors — unused variables, wrong equality operators, deprecated APIs — can be caught by Oxlint instantly before ESLint even starts. ESLint then only runs on files that passed Oxlint, and only when the Oxlint pass is clean.

Oxlint's auto-fix capabilities are a known limitation. Where ESLint and Biome can auto-fix the majority of their reported issues, Oxlint's auto-fix coverage is selective. Teams using Oxlint as their primary linter need to be comfortable manually addressing some categories of reported issues. The OXC team is actively expanding auto-fix support, but as of early 2026 it's still behind ESLint and Biome in this area.

Another consideration is Oxlint's configuration system. It's simpler than ESLint's flat config, which is either a feature or a limitation depending on your needs. You can't yet define complex per-directory rule overrides or build a layered config system comparable to ESLint. For simple projects this is fine; for monorepos with different standards across packages, it's a gap.

When Oxlint is the right choice:

CI pre-pass alongside ESLint for large monorepos where linting is a bottleneck
Basic linting for simple Node.js scripts or CLIs without framework requirements
Teams gradually migrating toward Rust-based tooling who want to start simply
Projects where zero-config basic correctness checks are the primary need

When to Choose Each

Choose ESLint v9 as your default unless you have a compelling reason to switch. Its flat config is cleaner than the old system, and no other tool matches its plugin depth. The performance cost is real but often acceptable — especially with caching enabled via --cache and running only on changed files in CI. ESLint is also the lowest-risk choice: every tutorial, every framework guide, and every team you hire from will know it.

Choose Biome for new projects in 2026 — it's the most mature ESLint+Prettier alternative and v2's type-aware rules close the functionality gap significantly. If your project doesn't need specialized ESLint plugins, Biome is strictly better: faster, simpler, one tool. The developer experience of a single biome check --write for both linting and formatting is genuinely pleasant compared to coordinating ESLint and Prettier separately.

Choose Oxlint as a CI accelerator alongside ESLint, not as a replacement. If your linting is a bottleneck and you can't migrate to Biome, Oxlint's dual-linter pattern offers significant speedups with minimal migration cost. Think of Oxlint as a fast pre-screen, not a full linting solution.

The trajectory matters here: Biome is moving fast. Rules coverage is growing, type-aware linting is new, and the community is maturing. A project that couldn't migrate to Biome six months ago because of a missing plugin might be able to today. It's worth rechecking Biome's rule parity with your current ESLint config every quarter if you're on ESLint and considering a switch.

For migration guidance, see How to Migrate ESLint to Biome and ESLint vs Biome 2026.

Methodology

Performance data sourced from the OXC benchmark repository (oxc-project/bench-javascript-linter) and Biome documentation. Download statistics from npm trends (March 2026). Rule counts from official documentation for Biome v2 and Oxlint 0.x. The 10,000-file benchmark reflects a mid-sized TypeScript monorepo with mixed JSX and utility code.

Zod vs Yup vs Valibot: Schema Validation 2026

Royce — Wed, 18 Mar 2026 05:08:19 +0000

Zod vs Yup vs Valibot: Schema Validation 2026

TL;DR

Zod is the default choice for TypeScript projects in 2026 — 31M weekly downloads, excellent DX, and Zod v4 closed most of the performance gap. Valibot wins on bundle size (1.4 KB vs Zod's 15+ KB) and is the right pick for edge/bundle-sensitive apps. Yup remains relevant for Formik codebases but has lost significant ground to both competitors.

Key Takeaways

Zod: 31M weekly downloads, 38.5K GitHub stars — the clear ecosystem leader
Yup: 5.1M weekly downloads, 23.6K GitHub stars — strong but declining market share
Valibot: 1.4M weekly downloads, 7.7K GitHub stars — fastest growing, bundle-first design
Zod v4 is 14x faster at string parsing, 7x faster at arrays vs Zod v3
Valibot's bundle footprint is ~1.4 KB for a login form vs Zod v4's 15 KB
All three support Standard Schema — framework-level interoperability is now guaranteed
Yup has no TypeScript-first design — type inference is bolted on, not native

Why Schema Validation Matters in 2026

Runtime schema validation is no longer optional. With tRPC, server actions, and form libraries all converging on schema-driven APIs, your choice of validation library now affects your entire stack — bundle size, TypeScript inference quality, and integration with tools like React Hook Form, Hono, and Valibot.

The landscape shifted dramatically in 2025 with two events: Zod v4's release (massive performance leap) and the Standard Schema specification reaching v1.0. Standard Schema means Zod, Valibot, and ArkType can now be used interchangeably in compatible frameworks — your schema library is less locked-in than ever.

Before Standard Schema, choosing a validation library was a sticky decision. If you picked Zod for a React Hook Form project, switching later meant rewriting every schema. If a library added Zod support but not Valibot support, you were locked in by your initial choice. Standard Schema changes this by defining a common interface that framework authors can target once and get compatibility with all compliant libraries. React Hook Form, Hono's validator middleware, and several others have adopted Standard Schema, which means the ecosystem pressure that used to favor only Zod now distributes across compliant libraries.

The practical stakes of schema validation extend beyond form inputs. API route handlers validate request bodies. tRPC procedures declare input schemas that generate both TypeScript types and runtime checks. Drizzle's insert operations can be validated against derived schemas. Server actions in Next.js and Remix parse FormData through schema declarations. Every one of these integration points is affected by your choice of schema library — which is why 2026 is a genuinely interesting time to compare the field.

For a deeper look at the form validation ecosystem, see Best React Form Libraries 2026 and Zod v4 vs ArkType vs TypeBox vs Valibot.

Comparison Table

Dimension	Zod v4	Yup 1.x	Valibot 1.x
Weekly Downloads	31M	5.1M	1.4M
GitHub Stars	38.5K	23.6K	7.7K
Bundle Size (login form)	~15 KB	~24 KB	~1.4 KB
TypeScript-first	Yes	Partial	Yes
Standard Schema	Yes	No	Yes
Async validation	Yes	Yes	Yes
Tree-shakable	Partial (Mini)	No	Yes
Inference quality	Excellent	Good	Excellent
Learning curve	Low	Low	Medium

Zod v4

Zod, created by Colin McDonnell, has been the TypeScript validation standard since 2020. The v4 release in 2025 was a landmark: 14x faster string parsing, 7x faster array parsing, 6.5x faster object parsing compared to v3. Zod v4 also introduced Zod Mini — a tree-shakable, functional variant that brings bundle size down from ~68 KB (v3 CommonJS) to around 15 KB.


const UserSchema = z.object({
  name: z.string().min(2).max(50),
  email: z.string().email(),
  age: z.number().int().min(0).max(120).optional(),
  role: z.enum(["admin", "user", "guest"]),
});

type User = z.infer<typeof UserSchema>;

// Parse (throws on failure)
const user = UserSchema.parse({ name: "Alice", email: "alice@example.com", role: "admin" });

// Safe parse (returns result object)
const result = UserSchema.safeParse(rawInput);
if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error.flatten());
}

Zod Mini uses the functional pipe style for better tree-shaking:


const EmailSchema = pipe(string(), email());
parse(EmailSchema, "user@example.com"); // "user@example.com"

Zod's biggest strength is its ecosystem depth. React Hook Form, tRPC, Drizzle, Hono, Next.js server actions — virtually every major TypeScript tool has first-class Zod support. When you reach for a new library and ask "does it have a Zod adapter?", the answer is almost always yes. This network effect compounds over time: the more tools support Zod natively, the more friction there is in switching away, and the more new tools prioritize Zod support first.

Zod v4's performance improvements are substantial and worth understanding in detail. The team rewrote the core parsing engine and achieved 14x faster string parsing, 7x faster array parsing, and 6.5x faster object parsing compared to v3. For most applications, raw parsing performance at the library level isn't the bottleneck — network latency and database queries dominate. But for high-throughput API servers processing thousands of requests per second, these improvements translate directly to server capacity. The v4 improvements also matter for the cold start cost in edge functions, where parsing overhead is more visible.

Error formatting is another area where Zod excels. The flatten() method produces nested error objects that map directly to form field paths, making it trivial to display field-level validation errors in a UI. The .format() method gives you the full error tree with custom message support. This level of ergonomic error handling is one of the reasons Zod became the default for form-adjacent validation.

When Zod is the right choice:

General TypeScript projects where ecosystem compatibility matters
tRPC or server actions with complex schemas
Team familiarity is a priority
You need rich error formatting out of the box
Existing codebase with Zod already present

Yup

Yup was the original JavaScript schema validation library and reached dominance through its Formik integration. Its fluent, chainable API was intuitive for JavaScript developers who weren't yet thinking TypeScript-first.


const UserSchema = yup.object({
  name: yup.string().min(2).max(50).required(),
  email: yup.string().email().required(),
  age: yup.number().integer().min(0).max(120),
  role: yup.mixed<"admin" | "user" | "guest">().oneOf(["admin", "user", "guest"]).required(),
});

type User = yup.InferType<typeof UserSchema>;

try {
  const user = await UserSchema.validate({ name: "Alice", email: "alice@example.com", role: "admin" });
} catch (err) {
  if (err instanceof yup.ValidationError) {
    console.error(err.errors);
  }
}

Yup's asynchronous validation is genuinely useful — you can validate against a database or API within your schema:

const UsernameSchema = yup.string().test(
  "unique-username",
  "Username already taken",
  async (value) => {
    const exists = await checkUsernameExists(value);
    return !exists;
  }
);

Where Yup struggles in 2026: TypeScript inference is retrofitted rather than native. InferType works but edge cases (discriminated unions, recursive schemas) produce less precise types than Zod. Yup also has no Standard Schema support, meaning newer frameworks won't add first-class Yup adapters going forward. The library has essentially reached feature stability — active maintenance continues, but the project isn't innovating at the pace of Zod or Valibot.

Yup's bundle size is also its largest practical disadvantage. At ~24 KB for a simple login form, it's the heaviest of the three. Unlike Zod Mini or Valibot, Yup offers no tree-shakable variant. Every validator, whether you use it or not, ships in the bundle. For server-side validation this doesn't matter, but for client-side or edge validation it's a meaningful cost.

That said, Yup's async-first design is genuinely useful in certain contexts. When validation logic needs to consult external state — checking username uniqueness against a database, verifying an email isn't blocklisted, confirming a promo code is valid — Yup's .test() method makes this clean and composable in a way that feels natural to JavaScript developers. Zod supports async refinements too, but Yup's API for it feels more intuitive to developers who grew up with promise-based JavaScript.

When Yup is the right choice:

Existing Formik codebases already using Yup
Teams with strong JavaScript (not TypeScript) background
Complex async validations are the dominant use case
Migrating incrementally from Joi with minimal disruption

Valibot

Valibot takes a fundamentally different architectural approach: every validator is a pure function, and schemas are composed via a functional pipe() API. This design enables aggressive tree-shaking — unused validators simply aren't bundled.


const UserSchema = v.object({
  name: v.pipe(v.string(), v.minLength(2), v.maxLength(50)),
  email: v.pipe(v.string(), v.email()),
  age: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(120))),
  role: v.picklist(["admin", "user", "guest"]),
});

type User = v.InferOutput<typeof UserSchema>;

// Safe parse
const result = v.safeParse(UserSchema, rawInput);
if (result.success) {
  console.log(result.output);
} else {
  console.error(v.flatten(result.issues));
}

Bundle size in practice: A login form schema (email + password) compiles to ~1.4 KB with Valibot vs ~15 KB with Zod v4 and ~24 KB with Yup. For edge functions, Cloudflare Workers, or mobile web apps, this difference is material. Cloudflare Workers has a 1 MB compressed bundle limit. If your worker handles form validation, Valibot takes 1.4 KB of that budget vs Zod's 15 KB. For a simple worker this doesn't matter, but for workers that also bundle a route framework, database client, and business logic, every kilobyte counts. Valibot's architecture was specifically designed with this constraint in mind — the library author originally built it while working on an edge-deployed application and found Zod's bundle cost unacceptable.

// Valibot v1 — Standard Schema compatible

const LoginSchema = v.object({
  email: v.pipe(v.string(), v.email()),
  password: v.pipe(v.string(), v.minLength(8)),
});

// Generate JSON Schema for OpenAPI
const jsonSchema = toJsonSchema(LoginSchema);

Valibot's runtime performance is roughly 2x faster than Zod v3 and comparable to Zod v4. The modular API requires slightly more verbose code for complex schemas, which is the primary DX tradeoff. Where Zod lets you write z.string().email().min(5) as a method chain, Valibot requires v.pipe(v.string(), v.email(), v.minLength(5)). This is more characters but also more explicit — each validator is a discrete, nameable function, which is better for static analysis and tree-shaking.

The Valibot ecosystem has grown substantially in 2025-2026. React Hook Form's Valibot resolver is production-ready. Hono's validator middleware supports Valibot natively. The @valibot/to-json-schema package generates OpenAPI-compatible JSON Schema from Valibot schemas, which matters for tightly-coupled API documentation. Standard Schema compliance means any library that added Standard Schema support automatically works with Valibot without additional adapter code.

One important consideration: Valibot's error messages are less detailed by default than Zod's. Zod generates rich, human-readable error messages with path information and issue codes out of the box. Valibot's issues are more raw and require manual formatting to display nicely in a UI. This is a deliberate tradeoff — better tree-shaking requires smaller default outputs — but it means more work for form validation UI code.

When Valibot is the right choice:

Edge functions, Cloudflare Workers, or bundle-size-critical apps
New projects that want maximum tree-shaking from day one
You want Standard Schema compliance without Zod's weight
React Native or embedded web contexts where bundle size is measured in KB

When to Choose Each

Choose Zod v4 when you need the richest ecosystem, best-in-class DX, and are building general TypeScript apps. The gap with Valibot on performance and bundle size is now smaller than ever, and the ecosystem advantage is enormous. Zod is particularly strong for tRPC projects — the library was designed with tRPC in mind, and the integration is seamless in both directions.

Choose Yup only if you're maintaining an existing Formik codebase or migrating from Joi. For new projects, Zod or Valibot are better starting points. The maintenance burden of keeping Yup in a new project when better alternatives exist isn't justified by any significant advantage.

Choose Valibot when bundle size directly impacts user experience — edge functions, mobile-optimized web apps, or any context where 15 KB matters. Valibot's growing ecosystem (React Hook Form resolver, Hono validator, Standard Schema support) means you won't sacrifice compatibility for the bundle savings.

A note on migration cost: All three libraries have similar API surface areas for simple schemas. Migration from Yup to Zod is well-documented and usually straightforward. Migration from Zod to Valibot requires rewriting schemas (different API), but codegens and scripts are available. If you're on Zod and bundle size becomes a concern, consider Zod Mini before switching to Valibot — the functional API is closer to Valibot's style and might be sufficient.

For related comparison, see Valibot vs Zod v4 and Joi vs Zod 2026.

Methodology

Data sourced from npm trends (March 2026), GitHub repository pages, and official benchmarks from the Valibot documentation and Zod v4 release notes. Bundle sizes measured with esbuild for a login form schema (email + password fields). Download counts represent weekly averages from the 30 days prior to publication.

Convex vs Supabase vs Firebase for SaaS Starters 2026

Royce — Wed, 18 Mar 2026 05:07:09 +0000

Choosing a real-time backend for a SaaS starter is one of the earliest and hardest-to-reverse decisions you make. Convex, Supabase, and Firebase each solve the same problem — give your application a backend with auth, database, and real-time data — but their architectures, pricing models, and developer experiences are fundamentally different. This guide breaks down all three as of 2026 so you can pick the right backend for your SaaS starter without learning the hard way.

The Three Philosophies

Convex is a TypeScript-native reactive backend. You write server functions in TypeScript, and any data change automatically propagates to all subscribed clients in real time. There is no SQL. There is no REST layer to define. Your database schema is your TypeScript types.

Supabase is PostgreSQL with a developer experience layer. It gives you a managed Postgres database, Row Level Security for access control, a realtime engine that listens to Postgres WAL changes, built-in auth, and an S3-compatible storage layer. Everything is built on proven open-source infrastructure.

Firebase is Google's mature backend-as-a-service platform. Firestore (the document database) and the Realtime Database are the core offerings, with Firebase Auth, Cloud Storage, and Cloud Functions completing the platform. Firebase is the most established of the three, with the broadest mobile SDK support and the deepest Google ecosystem integration.

Architecture Deep Dive

Convex Architecture

Convex runs your backend logic in a serverless TypeScript runtime. You write "mutations" (writes), "queries" (reads), and "actions" (side effects that can call external APIs). Queries are reactive by default — when the underlying data changes, every component subscribed to that query receives the update automatically without any manual subscription management.

// convex/messages.ts

  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("messages").order("desc").take(100)
  },
})

  args: { body: v.string(), author: v.string() },
  handler: async (ctx, { body, author }) => {
    await ctx.db.insert("messages", { body, author })
  },
})

On the client, you use useQuery and it stays live:

const messages = useQuery(api.messages.list)
// messages updates automatically when data changes

The Convex reactive model eliminates the need to manually manage websocket connections, invalidate caches, or write polling logic. It is the most developer-friendly real-time experience of the three options.

Supabase Architecture

Supabase wraps PostgreSQL with a REST API (PostgREST), a GraphQL API, and a realtime engine built on Elixir and Phoenix Channels. The realtime layer listens to the Postgres Write-Ahead Log (WAL) and broadcasts changes to subscribed clients.

// Supabase realtime subscription
const supabase = createClient(url, anonKey)

const channel = supabase
  .channel("messages")
  .on(
    "postgres_changes",
    { event: "INSERT", schema: "public", table: "messages" },
    (payload) => {
      setMessages((prev) => [...prev, payload.new])
    }
  )
  .subscribe()

The Supabase realtime model gives you change events from the database. You receive notifications of what changed and update your UI accordingly. It is less automatic than Convex (you manage the local state update) but it is battle-tested at scale and works with the full power of PostgreSQL — joins, indexes, full-text search, and complex queries.

Firebase Architecture

Firebase Firestore uses real-time listeners that fire whenever the underlying NoSQL document changes. The SDK abstracts away websocket management:


const q = query(collection(db, "messages"), orderBy("createdAt", "desc"))
const unsubscribe = onSnapshot(q, (snapshot) => {
  const messages = snapshot.docs.map((doc) => ({
    id: doc.id,
    ...doc.data(),
  }))
  setMessages(messages)
})

Firebase's realtime is built on Google's proprietary WebSocket infrastructure and is famously fast for document-level changes. Offline support for mobile apps is best-in-class — Firebase caches data locally and syncs when connectivity is restored, which is why it remains dominant in mobile SaaS applications.

Realtime Performance

Benchmarks from independent tests in 2026:

Metric	Convex	Supabase	Firebase
P50 update latency	~20ms	~50ms	~30ms
P99 latency (5,000 concurrent)	<50ms	100–200ms	<100ms
Offline support	No	No (partial)	Yes (Firestore)
Reactive queries	Yes (automatic)	Manual subscription	Manual onSnapshot

Convex sustains sub-50ms read/write latency at 5,000 concurrent connections. Supabase can see 100–200ms P99 latencies under similar load because the WAL-based realtime engine has higher processing overhead than Convex's purpose-built reactive system. Firebase Realtime Database (not Firestore) is the fastest for simple key-value subscriptions but is limited in query capability.

Pricing Comparison

Convex

The Convex free plan supports up to 6 developers working on 20 projects with 1 million function calls per month, 20 GB-hours of compute, and basic database and file storage. Convex Pro is priced per seat with additional charges for function execution overage.

Cost model: Compute-based (function execution time and calls). Costs scale with app usage, not data volume.

Supabase

The Supabase free tier gives you 2 projects with 500 MB database, 5 GB bandwidth, and 50,000 monthly active users. Supabase Pro is $25/month per project with 8 GB database, 250 GB bandwidth, and 100,000 MAU. Team plan is $599/month for SOC2 compliance and priority support.

Cost model: Service usage (database size, bandwidth, MAU). Most production apps land at $35–75/month after factoring in overages. At 500,000 MAU, auth costs alone reach $1,300/month.

Firebase

Firebase (Google Cloud) uses a pay-as-you-go model for Firestore: $0.06 per 100,000 reads, $0.18 per 100,000 writes, $0.02 per 100,000 deletes, plus $0.18 per GB stored. The Spark free plan is generous for development. Costs at scale can be unpredictable — high-read applications can generate large bills because every Firestore query counts individual document reads.

Cost model: Operations-based (reads/writes/deletes). Firebase is the most expensive at scale for read-heavy applications. Supabase Pro at $25/month is 4–5x cheaper for equivalent usage in most SaaS workloads.

Developer Experience Comparison

Factor	Convex	Supabase	Firebase
TypeScript	Native	Good	Partial
Schema definition	TypeScript types	SQL + Drizzle/Prisma	NoSQL (schemaless)
Query language	TypeScript API	SQL	Firestore Query API
Local dev	Convex dev server	supabase CLI	Firebase emulator
Type safety	End-to-end	Partial (via ORM)	Limited
Learning curve	Low	Medium	Medium
Self-hosting	No	Yes	No
Open source	No	Yes	No

Convex's TypeScript-native approach gives the tightest end-to-end type safety. Your database schema, server functions, and client queries share types without a code generation step. Supabase achieves similar type safety when you use Drizzle ORM or Prisma on top of the PostgreSQL layer — but this requires more setup. Firebase's Firestore is schemaless, which trades type safety for flexibility.

Auth Comparison

Convex Auth (convex-auth package): Provides email/password and OAuth flows built on top of Convex's data model. Relatively new compared to Supabase or Firebase Auth.

Supabase Auth: Full-featured authentication with email/password, magic links, OAuth (50+ providers), phone OTP, and SAML/SSO for enterprise. Row Level Security integrates directly with Supabase Auth, so your database access policies are co-located with your schema.

Firebase Auth: The most mature mobile auth SDK available. Social login, phone auth, anonymous auth, and deep integration with Firebase security rules. If you are building a mobile app with React Native or Flutter, Firebase Auth has the best native SDK support.

SaaS Boilerplate Ecosystem

All three backends have SaaS boilerplate support, but the ecosystems differ significantly:

Supabase has the largest boilerplate ecosystem. Nearly every major Next.js SaaS starter supports Supabase. See our best SaaS boilerplates with Supabase guide for the full list.

Convex has a growing set of dedicated starters. See the best Convex boilerplates guide for Convex-specific options.

Firebase has mature support in older boilerplates and strong React Native/Flutter starter coverage, but is less common in the latest Next.js SaaS starters — most have migrated to Supabase.

For a comparison that includes PocketBase as a self-hosted alternative, see our Convex vs Supabase vs PocketBase comparison.

When to Choose Each

Choose Convex When

You are building a highly interactive, real-time SaaS product (collaborative tools, live dashboards, multiplayer features)
Your team is TypeScript-only and wants end-to-end type safety with zero SQL
You want the simplest possible reactive data model without managing websocket subscriptions
You are building a product where real-time UX is a core differentiator

Avoid Convex if: You need self-hosting, SQL-based analytics, complex relational joins, or an open-source backend.

Choose Supabase When

Your SaaS is data-intensive with complex relational queries
You need PostgreSQL's power (full-text search, PostGIS, pg_vector for AI features)
Open source and self-hostability are requirements
You want Row Level Security to enforce access control at the database level
Your team is SQL-familiar or uses an ORM like Prisma or Drizzle

Avoid Supabase if: Your primary use case is simple document storage with heavy real-time updates at scale, or if your team has no SQL experience.

Choose Firebase When

You are building a mobile-first SaaS (React Native, Flutter, native iOS/Android)
Offline support is a product requirement
You are already in the Google Cloud ecosystem
You need the most mature and battle-tested mobile auth SDK available

Avoid Firebase if: You are building a web-only SaaS, you are cost-sensitive at scale, or you want to avoid vendor lock-in (Firebase is proprietary and cannot be self-hosted).

Migration Complexity

If you choose wrong and need to migrate:

Supabase → Firebase or Convex: Supabase exports PostgreSQL dumps. Migrating to Convex requires rewriting queries to the Convex API. Migrating to Firebase requires transforming relational data to a document model.

Firebase → Supabase: The most common migration path in 2026 as teams move from Firebase's NoSQL to PostgreSQL for better query capability. Firebase exports JSON; Supabase provides migration tools for common document-to-relational patterns.

Convex → anything: Convex exports data as JSON. No SQL schema to migrate, but you lose the reactive query model and need to rebuild subscriptions.

The safest long-term choice for migration flexibility is Supabase, because PostgreSQL is portable and the export format is standard.

Final Recommendation

For most SaaS starters in 2026: Supabase. The combination of PostgreSQL reliability, open-source freedom, mature auth, and the largest boilerplate ecosystem makes it the default choice. It is also the most cost-predictable at scale.

For real-time-first products: Convex. If your SaaS is built around live collaboration, reactive dashboards, or multiplayer features, Convex's reactive query model is worth the tradeoff of no SQL and no self-hosting.

For mobile-first products: Firebase. If most of your users are on mobile and offline support matters, Firebase Auth and Firestore are still the strongest mobile backend combination available.

Start with Supabase unless your use case clearly maps to Convex or Firebase. The boilerplate ecosystem, the available tooling, and the exit options are all superior.

Trigger.dev v3 vs BullMQ vs Graphile Worker 2026

Royce — Wed, 18 Mar 2026 05:06:56 +0000

Trigger.dev v3 vs BullMQ vs Graphile Worker 2026

When your application needs to run code outside the request/response cycle — send a batch of emails, process uploaded files, run ML inference, sync data with an external CRM — you reach for a background job library. In the Node.js ecosystem in 2026, three tools represent three distinct philosophies: Trigger.dev v3 (managed, TypeScript-first, no timeout limits), BullMQ (Redis-backed, battle-tested throughput), and Graphile Worker (PostgreSQL-native, no extra infrastructure).

Each is genuinely good. Choosing the wrong one for your constraints costs you either performance, operational overhead, or expensive migration. This comparison gives you the data to decide.

TL;DR

Trigger.dev v3 is the best choice if you want a managed platform, need jobs to run longer than 15 minutes, or are building AI/ML pipelines requiring long compute. BullMQ is the best choice for high-throughput queues (1,000+ jobs/second), rate-limited task processing, or complex job dependency graphs — if you already run Redis. Graphile Worker is the best choice if you want zero new infrastructure dependencies, already run PostgreSQL, and process fewer than 200 jobs/second.

Key Takeaways

BullMQ can process 1,000-10,000+ jobs/second; Graphile Worker tops out around 100-200/second due to PostgreSQL locking
Trigger.dev v3 has no execution timeout — jobs can run for hours; BullMQ/Graphile Worker are limited by your worker process
Graphile Worker requires only PostgreSQL — no Redis, no separate broker, no extra infrastructure cost
BullMQ ships with Bull Board, a real-time queue monitoring UI; Trigger.dev has a built-in cloud dashboard; Graphile Worker requires custom observability tooling
Trigger.dev is Apache 2.0 and self-hostable with Docker + PostgreSQL; BullMQ is MIT; Graphile Worker is MIT
PostgreSQL-native scheduling (via triggers and functions) is Graphile Worker's unique capability — queue jobs from SQL, not just application code
Trigger.dev v3's concurrency controls, fan-out, and realtime logs make it the most developer-friendly managed option

The Background Job Problem in 2026

Most web applications process the same job in different ways depending on urgency and scale:

User clicks "export" → queue a job, respond immediately with "your export is being prepared"
Webhook arrives from Stripe → process it asynchronously so your webhook endpoint doesn't time out
Nightly batch → process 50,000 records, send emails, update aggregates
AI pipeline → run OCR, extract entities, store embeddings — steps that take 2-5 minutes each

Traditional message brokers (Kafka, RabbitMQ) handle massive scale but add significant operational complexity. For most applications, a simpler job queue running against Redis or PostgreSQL is all that is needed.

Platform Overview

	Trigger.dev v3	BullMQ	Graphile Worker
Backend	Managed (PostgreSQL self-host option)	Redis	PostgreSQL
Max job duration	Unlimited	Worker-lifetime	Worker-lifetime
Throughput	High (managed)	1,000-10,000+/sec	100-200/sec
Step functions	Yes	Parent-child jobs	No
Scheduling (cron)	Yes	Yes	Yes
Monitoring UI	Cloud dashboard	Bull Board	DIY
Self-host	Yes	Yes	Yes (it's a library)
Extra infra needed	No (cloud) or PostgreSQL	Redis required	PostgreSQL (existing)
TypeScript support	First-class	First-class	First-class
License	Apache 2.0	MIT	MIT
Pricing	Free + pay-per-run	Free (OSS)	Free (OSS)

Trigger.dev v3: The Managed Job Platform

Trigger.dev v3 was a major architectural shift from v2. Jobs no longer run inside your serverless functions — they run on Trigger.dev's dedicated compute infrastructure, which means no timeout limits. A job processing a 2GB video can run for 30 minutes without hitting Vercel's 5-minute function limit.

The Developer Experience

Trigger.dev v3 feels like writing normal TypeScript functions. Tasks are defined with task(), scheduled with trigger(), and observed in a real-time cloud dashboard:


// Define a task
  id: "process-upload",
  // Retry configuration
  retry: {
    maxAttempts: 3,
    factor: 2,
    minTimeoutInMs: 1_000,
    maxTimeoutInMs: 10_000,
  },
  run: async (payload: { fileKey: string; userId: string }) => {
    logger.log("Processing file", { fileKey: payload.fileKey });

    // Step 1: Download and validate
    const file = await downloadFromS3(payload.fileKey);
    logger.log("File downloaded", { size: file.size });

    // Step 2: Process (can take minutes — no timeout!)
    const result = await runMLPipeline(file);

    // Step 3: Save results
    await saveResults(payload.userId, result);

    return { success: true, recordsProcessed: result.count };
  },
});

// Trigger from your application

await tasks.trigger("process-upload", {
  fileKey: "uploads/document.pdf",
  userId: "user_123",
});

Fan-Out and Batch Processing

Trigger.dev v3 supports batch triggering — create hundreds of parallel tasks in one call:

  id: "batch-notify",
  run: async (payload: { userIds: string[] }) => {
    // Trigger a parallel notification task for each user
    await tasks.batchTrigger(
      "send-notification",
      payload.userIds.map((userId) => ({ payload: { userId } }))
    );
  },
});

Concurrency and Rate Limiting

  id: "send-email",
  // At most 10 concurrent runs of this task
  concurrencyLimit: 10,
  // Rate limit: max 100 per minute
  rateLimit: {
    limit: 100,
    period: "1m",
  },
  run: async (payload: { to: string; subject: string }) => {
    await sendEmail(payload);
  },
});

Trigger.dev v3 Pricing

Tier	Price	Included
Free	$0	2,500 runs/month
Hobby	$5/month	25,000 runs/month
Pro	$20/month	100,000 runs/month + $0.002/additional run
Enterprise	Custom	Unlimited, SLA, SAML

Self-hosting is free with no run limits using Docker + PostgreSQL.

Trigger.dev v3 Limitations

Managed cloud has some latency overhead vs self-hosted infrastructure
Self-hosting requires running the Trigger.dev server (Docker + PostgreSQL)
Not designed for sub-second latency requirements (job start takes ~100ms on managed)
Smaller ecosystem than BullMQ for Node.js patterns

BullMQ: Redis-Backed, High-Throughput Queue

BullMQ is the successor to Bull, built on Redis streams. It has been battle-tested in production since 2019 and handles the most demanding background job workloads in the Node.js ecosystem. The core design principle is maximum throughput and feature richness using Redis as the backend.

Defining and Processing Jobs


const connection = new Redis({
  host: process.env.REDIS_HOST,
  maxRetriesPerRequest: null,
});

// Create a queue
const emailQueue = new Queue("email", { connection });

// Add a job to the queue
await emailQueue.add(
  "send-welcome",
  { userId: "user_123", email: "user@example.com" },
  {
    delay: 5_000,       // 5 second delay before processing
    attempts: 3,        // Retry up to 3 times on failure
    backoff: {
      type: "exponential",
      delay: 1_000,
    },
    removeOnComplete: { count: 1000 },  // Keep last 1000 completed jobs
    removeOnFail: { count: 5000 },      // Keep last 5000 failed jobs
  }
);

// Worker processes jobs
const worker = new Worker(
  "email",
  async (job: Job) => {
    const { userId, email } = job.data;

    await job.updateProgress(25);
    await sendWelcomeEmail(email);
    await job.updateProgress(100);

    return { sent: true };
  },
  { connection, concurrency: 50 }
);

worker.on("completed", (job) => {
  console.log(`Job ${job.id} completed`);
});

worker.on("failed", (job, err) => {
  console.error(`Job ${job?.id} failed: ${err.message}`);
});

Parent-Child Job Dependencies

BullMQ's most powerful feature is parent-child dependency graphs. A parent job only completes after all its children complete:


const flowProducer = new FlowProducer({ connection });

// Parent waits for all children
await flowProducer.add({
  name: "generate-report",
  queueName: "reports",
  data: { reportId: "r123" },
  children: [
    {
      name: "fetch-sales-data",
      queueName: "data-fetching",
      data: { source: "sales_db" },
    },
    {
      name: "fetch-marketing-data",
      queueName: "data-fetching",
      data: { source: "marketing_db" },
    },
    {
      name: "fetch-support-data",
      queueName: "data-fetching",
      data: { source: "support_db" },
    },
  ],
});

Scheduling with Repeatable Jobs

// Run every day at 3am UTC
await emailQueue.add(
  "daily-digest",
  { type: "daily" },
  {
    repeat: {
      pattern: "0 3 * * *",
      tz: "UTC",
    },
  }
);

BullMQ Rate Limiting

BullMQ includes native rate limiting per queue:

const rateLimitedQueue = new Queue("external-api", {
  connection,
  defaultJobOptions: {
    limiter: {
      max: 100,        // Max 100 concurrent
      duration: 1_000, // Per 1000ms window
    },
  },
});

Bull Board: Monitoring UI


const serverAdapter = new ExpressAdapter();

createBullBoard({
  queues: [new BullMQAdapter(emailQueue)],
  serverAdapter,
});

app.use("/queues", serverAdapter.getRouter());
// Visit /queues in browser for real-time queue stats

BullMQ Limitations

Requires Redis — another infrastructure dependency to run, monitor, and pay for
No built-in step function support (use parent-child for workflow dependencies)
Workers are long-running Node.js processes — incompatible with pure serverless deployments
Redis persistence settings require careful tuning to prevent job loss on restart

Graphile Worker: PostgreSQL-Native Job Queue

Graphile Worker has a niche but loyal following: teams that already run PostgreSQL and want zero additional infrastructure for background jobs. Your jobs live in a PostgreSQL table. Workers poll the database and process them. No Redis, no separate broker, no extra service to monitor.

Core Design


const pgPool = new Pool({ connectionString: process.env.DATABASE_URL });

// Define task handlers
const taskList = {
  sendEmail: async (payload: { to: string; subject: string; body: string }) => {
    await emailClient.send(payload);
  },

  generateThumbnail: async (payload: { imageUrl: string; jobId: string }) => {
    const thumbnail = await sharp(await fetchImage(payload.imageUrl))
      .resize(200, 200)
      .toBuffer();
    await uploadToS3(`thumbnails/${payload.jobId}.jpg`, thumbnail);
  },
};

// Start the worker
const runner = await run({
  pgPool,
  taskList,
  concurrency: 5,      // 5 concurrent jobs
  pollInterval: 1_000, // Check for new jobs every 1 second
});

Adding Jobs from Application Code


const workerUtils = await makeWorkerUtils({
  connectionString: process.env.DATABASE_URL,
});

// Queue a job
await workerUtils.addJob("sendEmail", {
  to: "user@example.com",
  subject: "Welcome",
  body: "Thanks for signing up!",
});

// Queue with delay
await workerUtils.addJob(
  "generateThumbnail",
  { imageUrl: "https://...", jobId: "job_123" },
  {
    runAt: new Date(Date.now() + 60_000),  // Run in 60 seconds
    maxAttempts: 3,
    jobKey: "thumbnail-job_123",           // Deduplication key
  }
);

The Killer Feature: Queue Jobs from SQL

Graphile Worker's unique capability is that PostgreSQL functions and triggers can add jobs directly:

-- Queue a job automatically when a new user is inserted
CREATE OR REPLACE FUNCTION queue_welcome_email()
RETURNS TRIGGER AS $$
BEGIN
  PERFORM graphile_worker.add_job(
    'sendEmail',
    json_build_object(
      'to', NEW.email,
      'subject', 'Welcome to our platform!',
      'body', 'Thanks for signing up, ' || NEW.name
    )
  );
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER user_signup_trigger
AFTER INSERT ON users
FOR EACH ROW EXECUTE FUNCTION queue_welcome_email();

This is impossible with Redis-based queues and requires application-layer glue with Trigger.dev or BullMQ.

Graphile Worker Throughput

Graphile Worker is well-tested at 20-100 jobs/second on typical PostgreSQL hardware. Beyond 200 jobs/second, you start hitting PostgreSQL advisory lock contention. For high-throughput workloads, this is a hard ceiling.

Graphile Worker: No Built-in Monitoring

Graphile Worker has no official monitoring UI. Job status lives in the graphile_worker.jobs table — you can query it or build custom dashboards, but there is no equivalent of Bull Board or Trigger.dev's cloud dashboard out of the box.

Failure Handling and Dead Letter Queues

	Trigger.dev v3	BullMQ	Graphile Worker
Retry backoff	Configurable per task	Configurable per job	Configurable
Max attempts	Configurable	Configurable	Configurable
DLQ behavior	Failed jobs in dashboard	Separate "failed" queue	Jobs stay in table with failed status
Error inspection	Real-time in dashboard	Bull Board or custom	Query `_private_data` column
Retry on deploy	Yes	Manual	Yes

Observability and Scheduling Compared

BullMQ with Bull Board and Trigger.dev's cloud dashboard are the strongest for observability. Graphile Worker requires you to query PostgreSQL directly or build your own dashboard.

For cron scheduling, all three support standard cron syntax. Graphile Worker additionally supports PostgreSQL-triggered scheduling, which is unique.

When to Choose Each

Choose Trigger.dev v3 if:

You need jobs to run longer than 15 minutes (AI pipelines, video processing, large file imports)
You want a managed platform with no infrastructure to run
You're already on a serverless stack (Vercel, Cloudflare Workers) without a persistent worker process
You need realtime observability without building custom tooling
Your team is TypeScript-first and values DX over raw throughput

Choose BullMQ if:

You need high throughput: 1,000+ jobs/second
You already run Redis in production
You need complex job dependency graphs (parent-child flows)
You require per-queue rate limiting for external API calls
You're building a system that needs fine-grained job priority controls
Long-running workers are acceptable in your infrastructure

Choose Graphile Worker if:

You already run PostgreSQL and want zero new infrastructure
Your job throughput is below 200/second
You want the ability to queue jobs from PostgreSQL triggers or functions
Your team knows SQL and prefers debugging jobs via SQL queries
Operational simplicity beats monitoring convenience

For more background job and API comparisons, see our Inngest vs Temporal vs Trigger.dev analysis, best background job APIs roundup, and event-driven API patterns guide.

Methodology

This article draws on official Trigger.dev v3 documentation, BullMQ documentation and GitHub discussions, Graphile Worker documentation, community benchmarks from GitHub Discussions (#922, #2458), and DEV Community performance analysis. Throughput figures are from community-reported benchmarks and should be validated against your specific workload.

Gitea vs Forgejo vs GitLab Self-Hosted 2026

Royce — Wed, 18 Mar 2026 05:06:26 +0000

Gitea vs Forgejo vs GitLab Self-Hosted 2026

TL;DR

For self-hosted Git in 2026, the choice comes down to scale and philosophy. Gitea and Forgejo are nearly identical lightweight forges that run on a Raspberry Pi — the difference is governance (company vs. community non-profit) and license (MIT vs. GPL-3.0). GitLab CE is a full DevOps platform that requires 4–8GB RAM minimum but includes native CI/CD, security scanning, container registry, and more. For most teams under 50 people who just need solid Git hosting with basic CI, Forgejo is the recommendation. For teams who need the full GitLab feature surface without the SaaS cost, GitLab CE is worth the heavier footprint.

Key Takeaways

Gitea: MIT, ~44K stars, Go — original lightweight forge, largest third-party ecosystem
Forgejo: GPL-3.0, ~10K stars, Go — community fork of Gitea, non-profit governed, building ActivityPub federation
GitLab CE: MIT, ~24K stars, Ruby/Go — full DevOps platform, 4GB RAM minimum (8GB+ recommended)
Fork history: Forgejo split from Gitea in October 2022 after a for-profit company acquired the project without community consent
Hard fork: Since early 2024, Forgejo is a hard fork — migrations between them may diverge on future versions
GitLab gap: 10–40x more resources than Gitea/Forgejo but covers CI/CD, container scanning, epics, and roadmaps natively

Background: The Forgejo Split

In October 2022, the Gitea project's domains and trademark were quietly transferred to a for-profit company, Gitea Ltd., without community knowledge or approval. Developers who had contributed to Gitea under the assumption it was a community project wrote an open letter objecting. When the company confirmed the direction, a group of core contributors forked the project as Forgejo, placing it under the governance of Codeberg e.V., a German non-profit.

Initially Forgejo was a "soft fork" — functionally identical to Gitea, just with different governance and a more restrictive copyleft license (GPL-3.0 vs MIT). In February 2024, Forgejo formally announced it would become a hard fork, meaning its codebase would diverge from Gitea with features like ActivityPub federation that Gitea has no plans to implement.

This history matters for your decision: if you start on Gitea today, migrating to Forgejo in the future may not be a trivial upgrade once the codebases diverge further.

Feature Comparison Table

Feature	Gitea	Forgejo	GitLab CE
License	MIT	GPL-3.0	MIT
Language	Go	Go	Ruby + Go
GitHub Stars	~44K	~10K	~24K
RAM (idle)	100–200MB	100–200MB	4–8GB+
CI/CD	Gitea Actions (GitHub-compatible YAML)	Forgejo Actions (GitHub-compatible YAML)	GitLab CI/CD (native, extensive)
Container Registry	Yes	Yes	Yes
Package Registry	Yes (npm, PyPI, Maven, etc.)	Yes	Yes
Issue Tracker	Yes	Yes	Yes + Epics, Roadmaps
Wiki	Yes	Yes	Yes
Webhooks	Yes	Yes	Yes
REST API	Yes	Yes	Yes + GraphQL
LDAP/SSO	Yes (LDAP, OAuth)	Yes (LDAP, OAuth)	Yes (LDAP, SAML, OAuth, Kerberos)
Mirror repos	Yes (GitHub, GitLab, etc.)	Yes	Yes
Security scanning	No	No	SAST, DAST, dependency scan
ActivityPub/Federation	No	In development	No
Governance	Gitea Ltd. (company)	Codeberg e.V. (non-profit)	GitLab Inc.
Self-hosted freedom	High (MIT)	Highest (GPL, non-profit)	High (MIT)

Resource Requirements

Gitea and Forgejo

Both Gitea and Forgejo have almost identical resource profiles — they share the same codebase for most functionality.

Minimum: 512MB RAM, 1 CPU core (handles personal projects and small teams)
Comfortable: 1–2GB RAM, 2 CPU cores (teams of 10–30)
With Actions runners: Add 1–2GB RAM per concurrent runner

A $6/month VPS (2 vCPU, 2GB RAM) runs Forgejo comfortably for a team of 20. A Raspberry Pi 4 handles solo or small team use.

GitLab CE

GitLab's resource requirements are substantially higher due to its monolithic architecture running multiple services (Puma, Sidekiq, Gitaly, PostgreSQL, Redis, and more).

Minimum: 4GB RAM, 4 CPU cores (2 cores absolute minimum, degraded performance)
Recommended for 100 users: 8GB RAM, 8 vCPU
Recommended for 1,000 users: 16GB RAM, 8 vCPU
CI/CD runners: Separate machines recommended; each concurrent job adds ~500MB–2GB RAM

GitLab can be made to run in 2GB RAM with careful configuration (memory_constrained_envs settings) but this is not suitable for production use.

Docker Compose

Gitea

version: "3"

networks:
  gitea:
    external: false

services:
  server:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data

Forgejo

Forgejo uses the same Docker Compose structure — just swap the image:

    image: codeberg.org/forgejo/forgejo:latest

Everything else is identical. This is the "soft fork" benefit that still exists today.

GitLab CE

version: '3.6'

services:
  gitlab:
    image: gitlab/gitlab-ce:latest
    container_name: gitlab
    restart: always
    hostname: 'gitlab.yourdomain.com'
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.yourdomain.com'
        gitlab_rails['gitlab_shell_ssh_port'] = 2222
        # Reduce memory usage for smaller servers
        unicorn['worker_processes'] = 2
        postgresql['shared_buffers'] = "256MB"
    ports:
      - '80:80'
      - '443:443'
      - '2222:22'
    volumes:
      - './gitlab/config:/etc/gitlab'
      - './gitlab/logs:/var/log/gitlab'
      - './gitlab/data:/var/opt/gitlab'
    shm_size: '256m'

Note: GitLab CE takes 3–5 minutes to start on first boot as it initializes all services. Check docker logs gitlab for progress.

CI/CD Comparison

Gitea Actions and Forgejo Actions

Both implement GitHub Actions-compatible YAML syntax. If you have existing GitHub Actions workflows, they will largely work without modification. Runners use the same act_runner tool.

# .gitea/workflows/build.yml (works identically as .forgejo/workflows/build.yml)
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci && npm test

Limitations compared to GitLab CI: no built-in caching (must configure S3/MinIO), no native container scanning, no parallel matrix jobs across multiple runners without manual setup.

GitLab CI/CD

GitLab's CI/CD is more mature and built into the platform. Native features include:

SAST (static application security testing)
DAST (dynamic application security testing)
Dependency scanning
Container image scanning
Multi-stage pipelines with artifacts
Environment deployments with rollback
Review apps
Value stream analytics

For teams doing serious DevOps work, the GitLab CI/CD feature set justifies the resource cost.

Migration Paths

Gitea → Forgejo

Currently straightforward: Forgejo accepts Gitea database backups directly. Long-term, as the hard fork diverges, this path may require migration tooling.

Forgejo → Gitea

Same process in reverse, but moving from GPL to MIT means you're giving up governance protections. Data format is identical at present.

Gitea/Forgejo → GitLab CE

GitLab provides a migration tool that imports from Gitea via API:

In GitLab, go to New Project → Import Project → Gitea
Enter your Gitea URL and personal access token
Select repositories to import (includes issues, PRs, milestones)

The import handles code, issues, pull requests, milestones, and labels. CI/CD pipelines must be manually converted from GitHub Actions YAML to GitLab CI YAML (the syntax differs).

GitLab CE → Gitea/Forgejo

No official migration tool from GitLab to Gitea. The Gitea community maintains an unofficial migration script for basic repository data. Issues, CI/CD pipelines, and container registry content require manual work.

When to Choose Each

Choose Gitea if:

You need maximum third-party tool compatibility (VS Code extensions, CI integrations, bots)
MIT license is important for your organization's legal requirements
You want the widest plugin ecosystem
You're already on Gitea and the governance change doesn't concern you

Choose Forgejo if:

You want community-governed, non-profit infrastructure
GPL-3.0 copyleft licensing aligns with your philosophy
You're interested in ActivityPub federation for cross-instance collaboration
You're starting fresh with no existing Gitea investment
You run Codeberg.org or want to align with that community

Choose GitLab CE if:

You need integrated CI/CD without managing separate runner infrastructure
Security scanning (SAST/DAST) is a hard requirement
Your team is 20+ and benefits from epics, roadmaps, and advanced project management
You're migrating from GitLab SaaS to cut costs
You can dedicate 8+ GB RAM to the server

For more on self-hosted Git options, see our guide to self-hosting Forgejo and the best open source GitHub alternatives. If you're evaluating the full self-hosted stack, the homelab software stack guide covers how Git hosting fits with CI/CD, container registries, and monitoring.

Security Considerations

All three platforms handle source code, which is typically among the most sensitive assets in an organization. Each has different security postures worth understanding.

Gitea and Forgejo have a smaller attack surface by design. Fewer services mean fewer vulnerabilities. Both projects release security patches promptly and maintain security advisories. The MIT and GPL-3.0 licenses both allow full code auditing. Running on a private network behind a reverse proxy with fail2ban for SSH brute-force protection is sufficient for most teams.

GitLab CE has more security features built in (secret detection, dependency scanning, SAST) but also a larger attack surface. The Omnibus package bundles dozens of services, any of which could have vulnerabilities. GitLab's security team is large and responsive — CVEs are typically patched within days — but you must stay current with updates. GitLab strongly recommends enabling two-factor authentication for all admin accounts and using instance-level webhook allowlists to prevent SSRF attacks.

For any of the three, the most important security practices are: TLS everywhere (Let's Encrypt via Certbot or Caddy), SSH key authentication only (no password auth), regular backups, and keeping Docker images updated.

Ecosystem and Integrations

Gitea's ecosystem advantage is real and measurable. Because Gitea has been around longer and has a larger user base, many third-party tools have native Gitea integration: VS Code extensions for PR reviews, bots for automatic labeling, migration tools from GitHub, and CI integrations. If you're using tools like Renovate (dependency update bot), Backstage (developer portal), or external CI services like Woodpecker CI, check their Gitea compatibility before committing.

Forgejo's compatibility is high today because the API is still largely identical to Gitea's. Most Gitea-compatible tools work with Forgejo. The divergence in APIs will increase as the hard fork matures, and tool vendors may prioritize Gitea compatibility over Forgejo's newer APIs.

GitLab's ecosystem is the largest, with native integrations for Kubernetes, Terraform, Vault, ArgoCD, and most major CI/CD and DevOps tools. If your organization uses enterprise tools like ServiceNow, Jira, or Salesforce, GitLab has official integrations. The tradeoff is that these integrations are more complex to configure and more likely to break on self-hosted instances after upgrades.

Hosted Alternatives

If managing your own Git server feels like too much overhead, several commercial and community-hosted options exist:

Codeberg.org: Forgejo-based, community-run, free for open source projects. The reference deployment of Forgejo.
Gitea.com: The hosted version of Gitea, maintained by Gitea Ltd.
GitLab.com: GitLab's SaaS offering, free tier available with 5GB storage and shared runners.
Sourcehut (sr.ht): Minimalist approach, git-first, open source, paid plans.

For teams that want the self-hosted control but not the ops burden, managed Gitea/Forgejo hosting providers exist on platforms like DigitalOcean Marketplace and Hetzner's App Platform.

Methodology

Sources consulted: 8
GitHub star data from GitHub.com, March 2026
Resource requirements from official documentation and community benchmarks
Forgejo governance history from forgejo.org and LWN.net coverage
Date: March 2026

Self-Host Immich: Google Photos Alternative 2026

Royce — Wed, 18 Mar 2026 05:06:12 +0000

Self-Host Immich: The Google Photos Alternative That Actually Works in 2026

TL;DR

Immich (94K+ GitHub stars, AGPL-3.0) is the closest self-hosted replacement for Google Photos that exists today. The mobile apps are native quality, face recognition works well enough to use daily, and the Docker Compose setup takes under 30 minutes. With Google Photos storage costs creeping up and growing concerns about AI training on personal photos, Immich has become the default recommendation for anyone moving off cloud photo storage.

Key Takeaways

94K+ GitHub stars — the fastest-growing self-hosted photo project by far, surpassing PhotoPrism and LibrePhotos
Native iOS and Android apps — background sync, share sheets, and offline access that feel like first-party software
ML face recognition — powered by InsightFace, groups photos by person automatically with assignable names
Natural language search — uses CLIP embeddings so you can search "sunset at the beach" and find relevant photos
Hardware-accelerated ML — GPU acceleration for NVIDIA, AMD, OpenVINO, and Apple Silicon reduces indexing time by 10-20x
Google Takeout import — official importer preserves original dates and metadata from exports
4GB RAM minimum — 8GB recommended when ML features are active

Why Immich Beats Google Photos in 2026

Google Photos changed its pricing model in 2021, ending the free unlimited storage tier. Since then, storage costs compound every year, and many users are now hitting the 15GB free limit or paying $2.99–$9.99/month for Google One. More concerning: Google's Terms of Service allow using uploaded content to improve AI services, which is a meaningful privacy consideration for family photos.

Immich addresses both problems: you own the storage and the data never leaves your server.

But "self-hosted photo manager" used to mean accepting significant quality gaps — slow apps, broken sync, face recognition that kind of worked. Immich closed those gaps. The mobile apps for iOS and Android are built with proper background sync that reliably uploads photos without requiring the app to be open. The face recognition groups family members accurately enough that many users have fully replaced their Google Photos workflow.

The timeline view matches Google Photos almost exactly. The memories feature resurfaces photos from years past. Shared albums work. Video transcoding works. Location maps work. At 94K+ GitHub stars as of March 2026, Immich has earned its reputation as the self-hosted photo tool that doesn't require compromises.

Server Requirements

Minimum (Small Library, CPU-Only ML)

2 CPU cores
4GB RAM
Storage: photo library size + 20% overhead for thumbnails and ML model weights (~2GB for models)
OS: any Linux distro with Docker, or macOS/Windows with Docker Desktop

Recommended (Full AI Features, Active Use)

4+ CPU cores
8GB RAM
NVMe or SSD storage (HDD works but thumbnail generation is slow)
Gigabit LAN if doing initial migration of large libraries

GPU Acceleration (Optional)

Immich supports hardware-accelerated ML inference for Smart Search and Face Recognition:

NVIDIA: CUDA via ghcr.io/immich-app/machine-learning:release-cuda
AMD: ROCm via ghcr.io/immich-app/machine-learning:release-rocm
Intel: OpenVINO via ghcr.io/immich-app/machine-learning:release-openvino
Apple Silicon: CoreML via ghcr.io/immich-app/machine-learning:release-armnn

Without GPU acceleration, ML tasks use CPU. On a 4-core machine, indexing 10,000 photos takes approximately 2–4 hours. With a mid-range GPU, the same job completes in 10–20 minutes.

Docker Compose Setup

Create a working directory and download the official config:

mkdir immich && cd immich
wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget https://github.com/immich-app/immich/releases/latest/download/.env.example
cp .env.example .env

Edit .env with your settings:

# Required: set your upload path
UPLOAD_LOCATION=./library

# Required: generate a random secret
DB_PASSWORD=your-strong-password-here

# Optional: timezone
TZ=America/New_York

The full docker-compose.yml from the official repo:

name: immich

services:
  immich-server:
    container_name: immich_server
    image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
    volumes:
      - ${UPLOAD_LOCATION}:/usr/src/app/upload
      - /etc/localtime:/etc/localtime:ro
    env_file:
      - .env
    ports:
      - 2283:2283
    depends_on:
      - redis
      - database
    restart: always
    healthcheck:
      disable: false

  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    env_file:
      - .env
    restart: always
    healthcheck:
      disable: false

  redis:
    container_name: immich_redis
    image: docker.io/redis:6.2-alpine@sha256:2d1463258f2764328496376f5d965f20c6a67f66ea2b06dc42af351f75248792
    healthcheck:
      test: redis-cli ping || exit 1
    restart: always

  database:
    container_name: immich_postgres
    image: docker.io/tensorchord/pgvecto-rs:pg14-v0.2.0@sha256:90724186f0a3517cf6914295b5ab410db9ce23190a2d9d0b9dd6463e3fa298f0
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_DB: ${DB_DATABASE_NAME}
      POSTGRES_INITDB_ARGS: '--data-checksums'
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    healthcheck:
      test: >-
        pg_isready --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USERNAME}" || exit 1;
        Sleeptime=15;
        retries=5;
        while [ $retries -gt 0 ]; do
          sleep $Sleeptime;
          retries=$((retries - 1));
          Sleeptime=10;
          pg_isready --dbname="$${POSTGRES_DB}" --username="$${POSTGRES_USERNAME}" && exit 0;
        done;
        exit 1
      interval: 10s
      start_period: 60s
    restart: always

volumes:
  model-cache:

Start Immich:

docker compose up -d

Access the web UI at http://your-server-ip:2283. On first launch, create an admin account.

Reverse Proxy Setup

Nginx

server {
    listen 80;
    server_name photos.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name photos.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/photos.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/photos.yourdomain.com/privkey.pem;

    client_max_body_size 50000M;

    location / {
        proxy_pass http://127.0.0.1:2283;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Required for video streaming
        proxy_buffering off;
        proxy_read_timeout 600s;
        send_timeout 600s;
    }
}

Traefik (Docker Label)

Add these labels to the immich-server service in your compose file:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.immich.rule=Host(`photos.yourdomain.com`)"
  - "traefik.http.routers.immich.entrypoints=websecure"
  - "traefik.http.routers.immich.tls.certresolver=letsencrypt"
  - "traefik.http.services.immich.loadbalancer.server.port=2283"

Migrating from Google Photos

Step 1: Export with Google Takeout

Go to takeout.google.com, select only Google Photos, and export. Large libraries will be split into multiple .zip files.

Step 2: Use the Official Immich CLI Importer

# Install the CLI
npm install -g @immich/cli

# Log in to your instance
immich login https://photos.yourdomain.com your@email.com yourpassword

# Import a Google Takeout directory (preserves dates from JSON sidecars)
immich upload --recursive /path/to/takeout/Google\ Photos/

The --recursive flag handles the nested folder structure. The CLI reads .json metadata files from Takeout exports and sets correct timestamps. Without this step, all photos would show today's date.

Step 3: Verify and Clean Up

After import, use the Immich web UI to check the Timeline view — photos should appear in chronological order going back to your earliest photos. Run a spot-check on a few years to confirm dates imported correctly.

Backup Strategy

Immich stores photos in a flat directory structure under UPLOAD_LOCATION. Back this up like any other important data.

Recommended approach with restic:

# Install restic
apt install restic

# Initialize a repository (example: local backup to external drive)
restic init --repo /mnt/backup/immich-photos

# Backup photos and database dump
docker exec immich_postgres pg_dump -U postgres immich > /tmp/immich-db.sql
restic -r /mnt/backup/immich-photos backup \
  /path/to/immich/library \
  /tmp/immich-db.sql

# Schedule daily backups (cron)
0 2 * * * /path/to/immich-backup.sh

The Postgres database is small (metadata, thumbnails paths, face data) — the heavy backup is the photo library itself. Store the DB dump alongside the library backup.

Performance Tips

1. Move ML to a separate machine. The immich-machine-learning container can run on a different server via the MACHINE_LEARNING_HOST environment variable. Useful if your NAS is low-power but you have a desktop with a GPU.

2. Enable hardware transcoding for video. Edit your .env:

IMMICH_MEDIA_LOCATION=/usr/src/app/upload

And in the server settings UI, set Hardware Acceleration to NVENC (NVIDIA) or VAAPI (Intel/AMD).

3. Set a thumbnail quality tier. In Administration > Settings > Thumbnail, lower resolution saves disk space with minimal visual impact for library browsing.

4. Exclude duplicates before import. Run the Google Takeout folders through a deduplication tool like fdupes before importing to avoid filling storage with duplicates from multiple Takeout exports.

5. Schedule ML jobs off-peak. In Administration > Jobs, set face detection and smart search to run at night to avoid impacting app responsiveness during day use.

Immich vs PhotoPrism vs LibrePhotos

Feature	Immich	PhotoPrism	LibrePhotos
GitHub Stars	94K+	36K+	3K+
Mobile Apps	Native iOS + Android	PWA only	PWA only
Face Recognition	InsightFace (good)	TensorFlow (decent)	Face.ai (basic)
Natural Language Search	CLIP embeddings	CLIP	Limited
GPU Acceleration	NVIDIA/AMD/Intel/Apple	NVIDIA/Apple	None
Docker Compose	Official, simple	Complex, many options	Moderate
License	AGPL-3.0	AGPL-3.0	MIT

For a deeper comparison, see our full Immich vs PhotoPrism vs LibrePhotos breakdown.

Verdict

Immich is the only self-hosted photo manager that can genuinely replace Google Photos without meaningful quality regressions. The native apps, reliable background sync, face recognition, and CLIP search all work at a level that would feel at home in a commercial product. For anyone paying for Google One storage or concerned about privacy, the 30-minute setup investment pays off immediately.

If you're evaluating self-hosted cloud storage more broadly, see our best self-hosted Google Drive alternatives guide and the homelab software stack guide for the full picture.

Common Setup Issues

Photos not backing up from mobile

The most common issue after initial setup. Check three things: (1) The mobile app requires the server to be accessible on your local network or via a domain with valid TLS — a plain http://192.168.x.x:2283 URL works on Android but iOS requires HTTPS for background sync. (2) Battery optimization settings on Android kill background processes — add Immich to the battery exclusion list. (3) On iOS, grant Immich "Full Access" to Photos in Settings > Privacy > Photos, not just "Selected Photos".

ML jobs running but face recognition not appearing

After initial install, Smart Search and Face Detection jobs run in the background. On a large library, this takes hours or days. Progress is visible in Administration > Jobs. If jobs show "waiting" and never start, check that the immich-machine-learning container is running: docker ps | grep machine-learning. The ML container downloads model weights (~300MB) on first run and needs internet access.

Database migration errors on upgrade

Always stop the stack before upgrading (docker compose down) and never skip major versions. Immich uses Postgres migrations tied to specific releases. Check the release notes on GitHub for any breaking changes before pulling a new tag. Keeping the IMMICH_VERSION pinned to a specific release (e.g., v1.100.0) prevents unintended upgrades when running docker compose pull.

Storage running out faster than expected

Immich generates thumbnails at multiple resolutions for the web UI and mobile apps. For a 50GB photo library, expect 10–20GB of additional storage for thumbnails and transcoded videos. The ML model weights add another 2–3GB. Plan for 130–140% of your raw photo library size as the total storage requirement.

Video playback failing in browser

Immich transcodes videos to web-compatible formats in the background. Original iPhone HEVC videos won't play in Chrome until transcoded. The transcoding queue is visible in Administration > Jobs > Video Conversion. On CPU-only servers, this is slow — a 4-minute 4K video can take 10–20 minutes to transcode. GPU hardware encoding via NVENC dramatically reduces this.

Mobile App Features Worth Knowing

The Immich mobile apps are more capable than the feature list suggests. A few features that aren't obvious:

Background sync configuration: In the app's Backup settings, you can configure sync to happen only on WiFi, only when charging, and only during specific hours. For large libraries, throttling the initial backup prevents your home network from being saturated for days.

Shared albums: You can share albums with other Immich users on the same instance, or generate shareable links for external viewers (no account required). The external share links support optional passwords and expiry dates.

Memories: Every day, Immich surfaces "On this day" memories from past years — the same feature that drives engagement in Google Photos. This runs automatically once your library is indexed.

Map view: If your photos have GPS metadata (all modern smartphones embed this), Immich displays them on an interactive map. Useful for finding photos from a specific trip or location.

Stack similar photos: Immich can group burst shots and similar photos into stacks, showing only the best one in the timeline. This significantly reduces visual clutter for mobile photographers who take multiple shots of the same scene.

Immich for Families

Immich is particularly well-suited for family photo management because of its sharing features. Each family member can have their own account, with their own library of automatically-synced photos. You can create shared albums that multiple people contribute to — the family vacation album that both parents and kids add photos to. The "Memories" feature resurfaces shared moments: on a photo's anniversary, Immich shows it to everyone who has access.

The admin account can manage storage quotas per user, preventing one family member from filling the disk. For families migrating from iCloud Photos, Immich's iOS app provides background sync that replaces the iCloud Photos Library seamlessly — photos upload to your server instead of Apple's.

One important note: Immich is not designed for long-term cold archival. The database and thumbnail structure means you need to run the Docker stack to browse your library. For true long-term archival (disaster-proof, offline copies), supplement Immich with a periodic backup of the raw library/ directory to external storage or a cold storage provider. Your Immich data plus a raw backup of the upload directory gives you both a functional browsing interface and a recovery option if the server dies.

Updating Immich

Immich releases frequently — roughly weekly minor updates. The recommended update process:

cd /path/to/immich
docker compose pull
docker compose up -d

Monitor the release notes at github.com/immich-app/immich/releases before upgrading. Major releases (1.x → 1.(x+1)) may require database migrations that take time on large libraries.

Methodology

Sources consulted: 8
GitHub star data from GitHub.com, March 2026
Docker Compose config from official Immich releases
Date: March 2026