DEV Community: Wolfgang Rathgeb

How SQLite Replaced PostgreSQL as My First Choice

Wolfgang Rathgeb — Mon, 15 Dec 2025 15:19:21 +0000

MySQL, NoSQL, and back to PostgreSQL – that's my journey through the database world in a nutshell. With the rise of NoSQL databases, systems like PostgreSQL added new features and evolved into NoSQL (not only SQL) databases themselves, becoming the perfect all-in-one solution.

SQLite? I found it nice enough for Nextcloud at home when at most 3 users were active simultaneously. A nice tool for getting started, but nothing for production. Or so I thought, until a customer convinced me to use SQLite as the database for his software.

I gave it a shot and refreshed my knowledge: While PostgreSQL and MySQL were trying to compete with NoSQL databases, SQLite was working on features important for production systems: Scaleability, Non-Blocking Writes, Performance.

The Startup That Over-Engineered Too Early

Sometimes we need others to show us the value in something we've overlooked.

For me, that was said customer who had gotten completely stuck. The existing software was built on Clojure and an obscure database system whose name I can barely remember, and was completely stuck. Simple features took months instead of days. Developers with the right skills were impossible to find, and the user base was still tiny.

The plan: We migrated to SvelteKit and SQLite. Simple. Fast. No complex infrastructure to manage and tons of developers in the market. Through pair programming, we introduced the team to SvelteKit and got the new system live. Features flowed easily and the system delivered more than enough performance.

Unfortunately, it was already too late. Follow-up funding failed and too much money had already been burned through the overly complex system.

The lesson: Start simple from day one. Complexity comes naturally and you have to adapt to it, but complexity to cover eventualities that may never occur is ultimately technical debt too. The best code is code you don't need.

Why SQLite Became My Default Choice

For those unfamiliar with SQLite: it's just a file and a library for your preferred programming language. No separate database server. No Docker container. No complex configuration. You add a dependency, point to a file, and you're done.

This simplicity is SQLite's greatest strength. While everyone else is setting up PostgreSQL instances, configuring connection pools, and managing database servers, you're already building features.

Since SQLite runs as an embedded library in your application, network latency is completely eliminated. Every query is a local file operation. Performance is better than you'd think.

Additionally, modern SQLite features like WAL (Write-Ahead Logging) mode handle concurrent reads and writes efficiently – it's not the single-threaded bottleneck many developers assume, and not comparable to direct file access.

The library used is also a decisive factor, as it serves as the main link and handles all operations. Bun recognized this and is trying to significantly boost performance with its own implementation.

Other libraries like libsql – which officially represents a compatible fork – take SQLite to a whole different level and even enable globally scaled systems.

But no matter how good the stability or performance of the library is, one thing remains the deciding factor: SQLite's structure is so simple that migration to another SQL database always remains possible and easy. SQLite gives you plenty of room to breathe until you reach that point.

SQLite in Production: Two Real-World Examples

Shrtn is a URL shortener with one simple goal: to be as simple as possible. Start a single Docker container, mount a volume, done. No Redis server to manage, no PostgreSQL to configure. The data model is simple – one table for links, some auth data, that's it. Could I have used Redis? Sure. But then I would have needed a second container, more configuration, more maintenance overhead. SQLite keeps the entire deployment trivial and handles all redirects without issues.

EmbodiCMS is a Git-based CMS where the actual content lives in Git repositories. SQLite stores the metadata – OAuth accounts, project information, article metadata for filtering and search. The database doesn't hold critical content, just supporting data to make everything work. It's a natural architectural fit: Git handles version-controlled content, SQLite handles the few operational data points. The project is in its early stages and sometimes I wonder about the future, but currently SQLite fulfills all requirements and then some.

Both projects prove the same point: SQLite works in production systems when you focus on real problems instead of theoretical scaling.

When PostgreSQL Is Actually the Better Choice

Don't get me wrong – PostgreSQL is an excellent database. But most applications don't need a large palette of features.

If you need full-text search with trigrams, complex JSON queries, or document management similar to MongoDB, PostgreSQL delivers. These features exist for good reasons. Anyone who has had to implement trigram search themselves will appreciate having it available directly in the database.

But here's the key: Use SQLite until you have a proven need for these features. Most applications never hit SQLite's limits. And when you need to switch, you know exactly which features you're missing and which database system is best for you.

Start with SQLite. Switch when you have real requirements, not theoretical ones.

The Migration Path When You Outgrow SQLite

Eventually, the time may come when you need to migrate away from SQLite. SQLite's simple, essentials-focused structure makes this migration remarkably straightforward.

SQLite focuses on standard SQL and remains compatible at this level with other SQL databases like PostgreSQL, MySQL, OracleDB, or MSSQL. Tools like pgloader make it even easier – no manual dump wrangling required.

To facilitate migration, you should use SQLite in strict mode from the start. Without it, SQLite doesn't validate against the schema and allows arbitrary values in fields. With proper data validation, this shouldn't be a problem, but the headaches aren't worth skipping this configuration.

Additionally and in general, ORMs like Drizzle are extremely helpful for transferring structures, indexes, and other configurations to any SQL database system.

When the actual time for migration arrives, you already have a much clearer picture of the application and aren't guessing anymore, but know exactly what's needed for which feature. You make an informed decision based on real production data, not architectural panic on day one.

Start with SQLite. Build your product. Migrate when you have evidence, not assumptions. That's how you stay focused on building something people actually want to use.

Reliable Puppeteer Container Setup for PDF Generation

Wolfgang Rathgeb — Tue, 02 Sep 2025 14:02:46 +0000

When developing PDF generation for a warehouse management system, I tried using the official Puppeteer container to reduce configuration complexity. I had developed everything locally first, and it worked perfectly.

But when I deployed with the container, all spacing disappeared - margins, padding, everything was compressed. The PDF generation logic still worked, but the layout was completely broken.

Puppeteer Container Spacing Issues

I tried different Puppeteer configurations and researched the problem extensively. After multiple research sessions, AI conversations, and attempts with various configurations, nothing fixed the spacing issues.

Initially, it wasn't clear whether this was a general container problem or something specific to the official Puppeteer container. The simplest way to evaluate this was building my own container with Chromium installed. Most web tutorials were unnecessarily complex, and it turned out that a simple Chromium installation with proper Puppeteer configuration is completely sufficient.

When I tested this approach, the spacing issues disappeared completely, confirming it was specifically a problem with the official Puppeteer container.

My Working Solution

Here's my working Dockerfile that solves the spacing issues. The main part is in the first few lines - the rest is just standard Node.js setup:

# Use the official Node.js LTS image
FROM node:lts AS base
WORKDIR /usr/src/app

# Install Chromium manually
RUN apt-get update && apt-get install -y \
    chromium \
    && rm -rf /var/lib/apt/lists/*

# Multi-stage build for dependencies
FROM base AS install
RUN mkdir -p /temp/dev
COPY package.json package-lock.json /temp/dev/
RUN cd /temp/dev && npm ci

RUN mkdir -p /temp/prod
COPY package.json package-lock.json /temp/prod/
RUN cd /temp/prod && npm ci --production

FROM base AS prerelease
COPY --from=install /temp/dev/node_modules node_modules
COPY . .

ENV NODE_ENV=production
RUN npm run build

FROM base AS release
# Skip Puppeteer's bundled Chromium since we installed our own
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

COPY --from=install /temp/prod/node_modules node_modules
COPY --from=prerelease /usr/src/app/build .
COPY --from=prerelease /usr/src/app/package.json .

ENV PORT=3733
EXPOSE 3733/tcp
USER node
ENTRYPOINT ["node", "./index.js"]

When Puppeteer starts, it won't find its bundled Chrome version, so you need to tell it which browser to use. If you're using different environments with different Chrome installations, you can set this via environment variables. For local installations, setting the executablePath is not necessary.

The key configuration change in your Puppeteer code:

const browser = await puppeteer.launch({
  executablePath: "/usr/bin/chromium",
  args: ["--no-sandbox"],
});

Note: --no-sandbox reduces security when processing untrusted content. For internal applications like warehouse systems, this trade-off is usually acceptable.

Updating Chromium Version

Keep in mind that Docker will use the cache for builds, so Chromium probably won't be updated with each build. This is fine for development because you save build time, but for production you'll want the current version:

docker build -t your-image-name --no-cache .

Choosing the Right Git Branching Strategy for Your Team

Wolfgang Rathgeb — Sat, 16 Aug 2025 21:11:28 +0000

Git Flow is a proven framework, but unlike Git itself, it's not a set standard. Just because it's well-documented and has excellent tool support doesn't mean other git branching techniques couldn't improve your performance much better – Git Flow could cost more than you think.

I've implemented Git Flow in teams multiple times, and in all cases it was an improvement. But when things change, the tools have to change sometimes too.

The pattern is clear: teams often choose Git Flow because it sounds professional, not because they analysed whether it solves their actual problems. Here's how to choose more intentionally based on my experience.

TL;DR: Quick Decision Matrix

Risk Level	Small Team (2-4)	Medium+ Team (4+)
Low Risk Tolerance (Poor testing, compliance, can't break production)	Simplified Git Flow	Simplified- / Git Flow
High Risk Tolerance (Good testing, can handle brief issues)	Trunk-based / GitHub Flow	GitHub Flow

Want to understand the reasoning behind these recommendations? Read on for the detailed analysis.

Why Git Workflow Structure Matters

Your team's structure and working style should drive your git branching strategy choice, not the other way around. Every development team needs some git workflow structure. The key question: which approach actually fits your team's constraints?

Several factors influence this choice for development teams:

Testing Maturity – Strong automated tests enable faster workflows. Manual testing requires more structured release processes.

Risk Tolerance – Can your team afford brief production issues, or does any downtime create serious problems? This depends on your testing confidence, but also regulatory requirements, financial impact, and business criticality.

Deployment Frequency – Daily deployments need different team coordination than scheduled releases.

Team Structure – Your team size, experience levels, and working relationships matter more than you think. Small experienced teams coordinate naturally. Large or mixed-experience teams need formal processes.

Multiple Version Maintenance – Supporting different customer versions simultaneously breaks most standard workflows.

Tool Constraints – GitHub's basic merge capabilities work differently than Bitbucket's Git Flow integration.

We'll focus on the three most fundamental factors for development teams: testing maturity, risk tolerance, and team structure. We'll examine testing maturity and risk tolerance together because of their similarity for most teams.

Testing Maturity & Risk Tolerance: The Foundation of Workflow Choice

Testing confidence directly shapes what git workflow risks your team can accept. Development teams with strong automated testing can use faster, simpler workflows. Teams without solid testing need workflow barriers to prevent chaos. The key insight: you can reduce workflow complexity by investing in better testing practices first.

However, testing quality isn't the only factor. Regulatory requirements, financial impact, and business criticality also constrain your team's choices.

I've seen this dynamic play out across different projects. At an education platform with insufficient automated tests and poor manual testing, Git Flow couldn't solve our underlying quality problems. While it improved stability, the fundamental issues remained - structure alone wasn't enough when the quality foundation was missing.

A public sector project showed a different pattern. With no automated tests but solid manual testing processes, Git Flow provided necessary release structure and worked well for organising deployments. However, even this success came with hidden costs. Developers frequently had to context-switch back to fix old code days later when manual testing found issues, destroying team focus and momentum. We improved this by using available testing capacity to test during the development phase rather than only at release time.

The lesson for development teams: Git Flow can organise existing quality processes, but it cannot replace missing ones. Rather than adding workflow complexity to manage poor feedback loops, invest in better testing practices first. This enables simpler, more efficient workflows long-term.

Team Structure: Coordination Complexity Drives Process Needs

Your team's structure determines coordination complexity. This directly affects how much formal process your git branching strategy needs. Team size matters, but experience levels and working relationships matter more.

At a startup with 2-3 experienced developers who knew each other well, trunk-based development or GitHub Flow worked perfectly (never forget the other factors). But with a monolith codebase and 4+ mixed-experience developers, our team needed formal processes.

In large development teams, trunk-based approaches generally become problematic. Check the other factors to make the right decision for your team.

Multiple Version Maintenance: When Git Flow Gets Complex

Git Flow assumes linear progression: develop → release → main → next cycle. But maintaining multiple versions for different customers breaks this model entirely. When your team needs to backport fixes to v1.5, v2.1, and v3.0 simultaneously, Git Flow's dual-branch structure becomes unwieldy.

At the education platform, we needed to transition away from Git Flow when version maintenance became necessary. But I argued against making the change at that time - the timing was too chaotic with pandemic-related stress to add a workflow change on top of everything else. People need capacity to execute such processes. Even though the Git workflow would have become simpler, the transition itself would have been another major burden. This experience confirmed that workflow changes need stability windows. Better to stabilise first, then evolve when the team has bandwidth for change.

Most Git Flow tooling doesn't support multi-version scenarios well. Your development team ends up with complex cherry-picking workflows and coordination overhead. This defeats the purpose of having a structured process.

For teams maintaining multiple versions: Consider branch-per-version strategies instead of trying to force Git Flow into a model it wasn't designed for.

Git Flow Complexity: Hidden Coordination Overhead

Git Flow looks simple in theory but requires sophisticated tooling for development teams to use properly. Desktop clients like SourceTree or GitKraken support the branching operations fine. But they don't help with pull request workflows that most teams rely on.

The problem: Git Flow's dual-branch model needs coordinated merging. Hotfixes must reach both main AND develop. Release branches need proper handling. Feature branches require dual-branch coordination. Only Bitbucket has proper integration for this - and even then, your team sometimes has to do manual steps with hotfixes.

With GitHub or GitLab, development teams end up with manual coordination steps that people forget. This creates merge conflicts and missed updates. The alternative is building CI/CD pipeline automation to handle the missing coordination. But this adds complexity most teams don't expect when choosing Git Flow.

main     o---------o-------o
          \       /       /
release    \     o-------o
            \   /       /
develop      o-o-------o
              \       /
feature        o-----o

GitHub Flow: Simple and Fast

GitHub Flow works with a single main branch representing production. Development teams create feature branches from main, develop changes, merge back via pull request, and deploy immediately. This eliminates coordination complexity entirely.

main     o---------o--------o
          \       / \      /
feature    o-----o   o-o--o

This git branching strategy works well when your team has solid automated testing and can tolerate briefly buggy versions whilst fixes deploy. The fast feedback loop and minimal overhead make it ideal for development teams with good testing discipline and acceptable risk tolerance.

The limitation: No formal release process for stakeholder review or coordinated deployments. If your team needs testing phases or scheduled releases, GitHub Flow becomes problematic.

Trunk-Based Development: Minimal Branching

Trunk-based development means your entire team commits directly to main. Only viable for solo developers or very small, highly coordinated teams (2-3 people doing pair programming). Most development teams should start with GitHub Flow instead.

main     o-o-o-o-o-o-o-o-o

Simplified Git Flow: The Middle Ground

Based on my experience with Git Flow's coordination problems across multiple development teams, I invented this simplified approach. It keeps the release structure whilst eliminating the dual-branch complexity. Your team works directly with main as the integration branch, creating release branches when ready for formal testing and stakeholder review.

main        o-----o---o---o---o---o-----o---o
             \   /     \       /   \   /   /
feature       o-o       \     /     o-o   /
                         \   /           /
release-1.0               o-o           /  (tag v1.0, deploy, delete branch)
                             \         /
hotfix-1.0.1                  o-------o  (tag v1.0.1, merge back to main)

The workflow for development teams: Branch from main when ready to create a release. Test and review on the release branch. Tag the release branch commit itself. Deploy from that tagged commit, then delete the release branch. For hotfixes, branch from the specific tag you need to fix, then merge back to main.

Benefits for your team: Formal release process without dual-branch coordination. Works with basic tooling. Eliminates the develop/main synchronisation overhead. Tools like changeset can help manage versioning, tags, and changelogs automatically. You get Git Flow's structure with much simpler coordination.

Don't Fear Changing Your Workflow

The technical part of switching git workflows is trivial for development teams - Git doesn't care about your branch names or merging patterns. The real challenge is organisational: achieving team acceptance, retraining habits, and managing the transition period.

The most important measure for any development team: does your git branching strategy help your team or constantly fight against you? Some friction is normal - that's the price of having a versioning tool, and it's worth it. But if your team is fighting the workflow more than benefiting from it, it's time to evolve.

Start somewhere reasonable for your team, learn what works for your specific situation, then adjust based on reality rather than theory. Your development team isn't locked into the first choice forever.

How Type Branding Solved an 'Impossible' TypeScript Problem

Wolfgang Rathgeb — Fri, 08 Aug 2025 14:47:40 +0000

When I started building object transformation pipelines, I had a primary goal: write code that's easy to read and change. Complex, nested transformations slow down development, make debugging painful, and turn simple changes into archaeology expeditions.

I was tired of seeing patterns like this throughout codebases:

// "Organized" version - functions exist, but still verbose
const addAge = (user: User) => ({ ...user, age: calculateAge(user.birthDate) });
const addEmailValidation = (user: User) => ({
  ...user,
  emailValid: user.email.includes("@"),
});
const addPermissions = (user: User) => ({
  ...user,
  permissions: getUserPermissions(user.role),
});

const processUser = (user: RawUser) => {
  const withAge = addAge(user);
  const withValidation = addEmailValidation(withAge);
  const withPermissions = addPermissions(withValidation);
  return withPermissions;
};

Sure, functions exist. But look at all those intermediate variables! Each step needs a meaningful name, and you're constantly tracking variables - reading assignments, remembering what each contains, finding where they're used next, and following the chain of function calls.

What I wanted was something that reads like a recipe:

// Clear, step-by-step transformation
const processUser = pipe(addAge, addEmailValidation, addPermissions);

Sequential flow. Each step obvious. Easy to add, remove, or reorder transformations. Code that tells you what it does, not how it's nested.

The final piece: write generic transformation functions once, compose them into readable pipelines everywhere with complete type safety.

TypeScript had other plans.

The Mysterious Loss of Type Information with TypeScript's Generic Functions

Building a pipe function in TypeScript is already challenging. Getting the type system to understand what flows through a reduce operation, inferring correct return types, handling async/sync mixing—that's a whole technical adventure on its own (and probably deserves its own article).

But I figured I could work around those pipe implementation details. The real problem came when I tried to build the actual transformation functions.

My approach seemed straightforward:

// Write once, use with any object that has the right properties
const addAge = <T extends { birthDate: Date }>(person: T) => ({
  age: calculateAge(person.birthDate),
});

const addEmailValidation = <T extends { email: string }>(data: T) => ({
  emailValid: data.email.includes("@"),
});

// Use with different types
const user: User = {
  id: 1,
  name: "Max",
  email: "max@example.com",
  birthDate: new Date("1990-01-01"),
};
const customer: Customer = {
  customerId: "C123",
  email: "test@company.com",
  birthDate: new Date("1985-05-15"),
  tier: "premium",
};

const processData = pipe(addAge, addEmailValidation);

The vision was simple: generic functions that work with any compatible type, preserving all original properties while adding new ones.

But TypeScript had different ideas:

const result1 = processData(user);
// Type: { emailValid: boolean }
// Expected: User & { age: number } & { emailValid: boolean }

const result2 = processData(customer);
// Type: { emailValid: boolean }
// Expected: Customer & { age: number } & { emailValid: boolean }

TypeScript lost track of everything. The original User type? Gone. The age property from the first transformation? Overwritten. My Customer with all its properties? Reduced to a single boolean.

The functions worked perfectly at runtime—JavaScript executed correctly and all properties were preserved. But TypeScript's type system had no idea what was happening in the pipeline.

Attempting TypeScript Generic Type Detection

The problem was clear, but the solution wasn't. How do you tell a type system "this function should merge, not replace" when it has no way to understand that distinction?

I tried several approaches to bridge this gap:

// Attempt 1: Use conditional types to detect generics
type IsGeneric<T> = T extends <U>(arg: U) => any ? true : false;
// Doesn't work - TypeScript can't introspect function generics like this

// Attempt 2: Universal generic constraints
type SmartPipe<T extends Record<string, any>> = <F extends (input: T) => any>(
  fn: F,
) => F extends (input: T) => infer R ? (input: T) => T & R : F;
// TypeScript couldn't make the leap from "might be generic" to "should merge"

Even when you try to define a function within a generic type, you run into limitations:

// This WOULD work at the type level
type AddAge<T extends { birthDate: Date }> = (input: T) => T & { age: number };

// You can use it, but you have to set the generic when you use it:
const addAgeForUser: AddAge<User> = (person) => ({
  age: calculateAge(person.birthDate),
});

The limitation is that you have to concrete the generic type T when you USE the type. You can't have a "non-prepared" type that works dynamically with any compatible input.

The normal generic function approach works fine individually:

const addAge = <T extends { birthDate: Date }>(
  person: T,
): T & { age: number } => ({
  age: calculateAge(person.birthDate),
});

But T cannot be defined inside the type system in a way that allows the pipe system to automatically infer the relationship between input and output types during composition.

The fundamental issue kept surfacing: there was no automatic way to tell the type system "this generic function should merge its result with the input."

That's when I remembered the __brand pattern I'd seen before. If TypeScript couldn't detect the intent automatically, maybe I could mark functions explicitly. The wrapper function became the vehicle for carrying the type information the pipe system needed.

The Solution: Type Branding for Automatic Detection

The breakthrough came when I stopped fighting TypeScript's limitations and started working with them. If the type system couldn't automatically detect function intent, what if I made that intent explicit?

The answer was branding functions so the pipe system could recognize them automatically:

export function enrich<const FI extends AnyObject | undefined, FO>(
  fu: (args: FI) => FO
): GMerge<FI, FO> {
  return (/* implementation */) as GMerge<FI, FO>;
}

export type GMerge<I, O> = GMergeFunction<I, O> & {
  __brand: "GMerge";  // This is the detection key
};

The same branding approach works for pick() and omit() functions too:

// GType = GMerge | GPick | GOmit
F[X] extends GType  // Does this function have any brand?
  ? GQueue<F[X], PrevReturn<...>>  // Yes: use branded logic
  : ReturnType<F[X]>               // No: use transformation logic

Now the pipe automatically distinguishes between different function types without you having to think about it:

When you write:

const processUser = pipe(
  validateInput, // No brand: transforms
  enrich(addAge), // GMerge brand: merges
  pick(["id", "name", "age"]), // GPick brand: picks
  omit(["tempField"]), // GOmit brand: omits
  formatForAPI, // No brand: transforms
);

The pipe automatically applies the correct type behavior for each function based on its brand, without you having to specify anything beyond the wrapper function.

The Original Vision: Finally Achieved

Remember what started this whole journey? I wanted to write generic transformation functions once and use them everywhere, preserving all type information through complex pipelines.

That "impossible" dream? It finally works:

// Write once, generic transformation functions
const addTimestamp = enrich(<T extends AnyObject>(obj: T) => ({
  timestamp: new Date(),
}));

const addMetadata = enrich(<T extends AnyObject>(obj: T) => ({
  version: "1.0",
  processed: true,
}));

// Use with any compatible type
const user: User = { id: 1, name: "John", email: "john@example.com" };
const customer: Customer = {
  customerId: "C123",
  tier: "premium",
  email: "test@company.com",
};
const product: Product = { sku: "P456", name: "Widget", price: 29.99 };

// Same pipeline works with all three types
const processAny = pipe(addTimestamp, addMetadata);

const processedUser = processAny(user);
// Type: User & { timestamp: Date } & { version: string; processed: boolean }

const processedCustomer = processAny(customer);
// Type: Customer & { timestamp: Date } & { version: string; processed: boolean }

const processedProduct = processAny(product);
// Type: Product & { timestamp: Date } & { version: string; processed: boolean }

Every property preserved. Every type correctly inferred. The generic functions work with any object shape while maintaining complete type safety.

This is the "write once, use everywhere" vision that seemed impossible with TypeScript's limitations - now working perfectly. The GMerge branding system enables automatic detection while preserving generic context through the pipe.

The Cost and Benefits

Let's be honest about what this solution costs and what you get in return.

The Costs:

Runtime overhead - Each enriched function adds a wrapper call and object spread operation. In performance-critical loops processing thousands of objects per second, this could matter.

Learning curve - Your team needs to understand when to use enrich() vs regular transformation functions. It's another pattern to learn and remember.

Can't remove properties - enrich() only adds or modifies properties. To remove properties, you need omit() functions or regular transformations. (The pipe-and-combine library (npm) includes omit() and pick() functions that use the same branding system for type-safe property removal.)

Function specialization - Instead of flexible functions that can add, modify, or remove as needed, you now have specialized function types with specific behaviors.

But here's the key insight: Most of the complexity happens at compile time, not runtime. All the complex type logic - GMerge, GQueue, conditional types, generic inference - gets erased when TypeScript compiles to JavaScript. The actual runtime cost is just wrapper functions and object spreading.

The Benefits:

Readability - The Primary Win - This is the biggest advantage. Pipelines read like business processes:

const processNewUser = pipe(
  validateUserInput,
  addAge,
  addWelcomeTimestamp,
  assignDefaultPermissions,
  sendWelcomeEmail,
  formatForDatabase,
);

Even non-developers can understand this flow. Compare that to nested function calls or imperative code with intermediate variables. The business logic becomes immediately obvious.

Reduced documentation needs - When code reads like business requirements, you need far less external documentation. Good function names eliminate the need to explain what the process does.

Faster development - Write generic transformation functions once, use them everywhere with complete type safety.

Maintainability - Easy to add, remove, or reorder transformation steps without breaking types.

For most applications, the development speed gains far outweigh the runtime costs. You're trading microseconds for hours of developer time and significantly more maintainable code.

Why I Replaced i18next with Paraglide.js

Wolfgang Rathgeb — Sun, 27 Jul 2025 13:57:00 +0000

Often your first choice is not your best one. Investing hours in comparing tools and reading documentation can be annoying, and most i18n libraries look pretty similar anyway. So my decision fell quickly to the popular choice: i18next.

But as always, I kept my eyes open and discovered Paraglide.js - which approaches i18n very differently from other tools.

The JavaScript world is evolving toward smarter bundling - away from shipping unused code toward build-time optimization. While websites keep getting bigger and more complex, the tooling has gotten more precise about what actually reaches users.

Here's why I made the switch.

Move from Runtime to Build Time

i18next follows the traditional i18n approach: handle everything at runtime. Every time a user loads your page, it:

Loads translation files from the server
Parses JSON structures
Handles key lookups and interpolation
Processes pluralization rules

This works fine and has been the standard for years. But modern build tools opened up a different possibility.

Paraglide.js shifts most of the work to build time. During compilation, it generates individual JavaScript functions for each translation key.

// i18next: runtime processing
t("welcome_user", { name: "John" });

// Paraglide.js: pre-generated function call
welcome_user({ name: "John" });

Both systems still check the current locale at runtime - users can switch languages. But while i18next also parses translation keys and handles interpolation with every call, Paraglide.js pre-compiles this work into ready-to-use functions.

If you're using a build tool like Vite, this happens automatically. Your users download the final functions instead of translation processing logic.

Reducing Bundle Size by Over 40KB

40KB might not sound significant - "websites weigh over 1MB nowadays anyway," you might think. But every KB affects Core Web Vitals and mobile performance. Modern build tools have become precise about eliminating unnecessary overhead for good reason.

40KB just to handle translations. That's enough space for thousands of actual translated strings - probably your entire app's content in multiple languages. Paraglide.js reduces this to ~2KB.

The difference comes down to philosophy: ship results, not processing engines.

Migration is mostly find-and-replace work:

Find: t\(['"`]([^'"`]+)['"`](?:,\s*(\{[^}]+\}))?\)
Replace: $1($2)

Converts both:

t('welcome_message') → welcome_message()
t('welcome_user', { name: 'John' }) → welcome_user({ name: 'John' })

Don't Care About Translation File Size - Just Shake the Tree

Here's the best part: forget about worrying if your translation files get too big or whether you need to reduce them for load speed - it happens automatically.

Before (i18next):

// All translations ship to users
{
  "welcome_message": "Welcome!",
  "admin_panel_title": "Admin Dashboard",
  "debug_info": "Debug mode active",
  "unused_feature": "Feature not implemented",
  // ... 200+ more translations
}

After (Paraglide.js):

// Only import what you actually use
import { welcome_message } from "./messages";
// admin_panel_title, debug_info, unused_feature automatically eliminated

With i18next, users download all translations whether they're used or not. With Paraglide.js, the logic is no longer hidden from build tools - they can finally do what they're designed for: optimizing your code. Your translation files stay complete, but users only get what your code actually imports.

Bonus: you can reuse comprehensive translation files between projects without worrying about bloat. Keep everything, ship only what's needed.

TypeScript Support as a Bonus

Since Paraglide.js generates TypeScript-compatible code, you get native TypeScript support automatically when you import them directly. Real autocomplete, real parameter checking, real compile-time errors - no type generation needed.

import { welcome_user, item_count } from "./messages";

welcome_user({ name: "John" }); // Autocomplete suggests 'name' parameter
item_count({ count: "5" }); // TypeScript error: 'count' should be number

TypeScript can be slow picking up new translations, which becomes noticeable when adding many translations quickly.

Why I Prefer Build Time Over Runtime

This comes down to a fundamental principle of software development: do things once, reuse the result. Why process the same translations the same way hundreds, thousands, or millions of times when you could do it once?

With i18next, every user on every page load processes translations identically. With Paraglide.js, this work happens once during build - then gets reused by every user forever.

Even though computing power is cheap nowadays, this philosophy still improves user experience. Why make users' devices do work that could have been done on your build server? Why ship processing logic when you could ship the result?

It's not just about performance - it's about doing things right. Build-time optimization follows the core principle: write once, run everywhere.

Paraglide.js Setup: Type-Safe i18n Without Framework Lock-in

Wolfgang Rathgeb — Sun, 06 Jul 2025 22:53:00 +0000

Most i18n solutions work across frameworks, but they come with tradeoffs. Runtime overhead, complex configuration, or weak TypeScript integration. You get flexibility, but you sacrifice performance or developer experience.

Paraglide.js is different. Compile-time translation generation means zero runtime overhead, full type safety, and a dead-simple API. No complex configuration, no runtime bundle bloat, no guessing which translation keys exist.

Version 2.0 introduced a framework-agnostic Vite plugin that automatically triggers builds when translations change, eliminating the manual compilation step required in v1.

I use Paraglide in production on dropanote.de, built with my own site builder. Here's why it works better than the alternatives, and how to set it up.

Core Setup

Start with the init command:

npx @inlang/paraglide-js@latest init

This creates your project configuration and translation file structure. Then add the Vite plugin to your vite.config.ts:

import { paraglideVitePlugin } from "@inlang/paraglide-js/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    paraglideVitePlugin({
      project: "./project.inlang",
      outdir: "./src/lib/paraglide",
    }),
  ],
});

Translation Files

The init command creates a messages/ directory with your translation files. Each locale gets its own JSON file:

messages/
├── en.json
└── de.json

Your English translations in messages/en.json:

{
  "hello": "Hello",
  "welcome": "Welcome to our site",
  "nav_home": "Home",
  "nav_about": "About"
}

German translations in messages/de.json:

{
  "hello": "Hallo",
  "welcome": "Willkommen auf unserer Website",
  "nav_home": "Startseite",
  "nav_about": "Über uns"
}

When you build your project, Paraglide generates TypeScript functions for each translation key.

Basic Usage

Start your dev server and the Vite plugin will automatically generate your translation functions:

npm run dev

Then import the generated message functions:

import * as m from "./src/lib/paraglide/messages";

Use your translations with full type safety:

// Simple messages
m.hello(); // "Hello" or "Hallo"
m.welcome(); // "Welcome to our site" or "Willkommen auf unserer Website"

// Nested keys
m.nav_home(); // "Home" or "Startseite"
m.nav_about(); // "About" or "Über uns"

For language switching, import the locale functions:

import { setLocale, getLocale } from "./src/lib/paraglide/runtime";

Switch languages programmatically:

setLocale("de");
console.log(m.hello()); // "Hallo"

setLocale("en");
console.log(m.hello()); // "Hello"

// Check current locale
console.log(getLocale()); // "en"

Your editor provides autocomplete for all translation keys, and TypeScript catches typos at compile time.

Parameters in Translations

Your translations can accept dynamic values using curly brace placeholders:

In your translation files:

{
  "greeting": "Hello {name}!",
  "item_count": "You have {count} items in your cart",
  "user_profile": "Welcome back, {first_name} {last_name}"
}

In your code:

import * as m from "./src/lib/paraglide/messages";

m.greeting({ name: "Alice" }); // "Hello Alice!"
m.item_count({ count: 5 }); // "You have 5 items in your cart"
m.user_profile({
  first_name: "John",
  last_name: "Doe",
}); // "Welcome back, John Doe"

TypeScript enforces the required parameters - you'll get compile errors if you forget them or use the wrong names.

Framework Integration

The beauty of Paraglide is that it works identically across frameworks. The same import, the same functions, the same API:

import * as m from "./src/lib/paraglide/messages";
import { setLocale } from "./src/lib/paraglide/runtime";

In vanilla JavaScript:

import * as m from "./src/lib/paraglide/messages";
import { setLocale } from "./src/lib/paraglide/runtime";

document.getElementById("title").textContent = m.welcome();

// Language switching
document.getElementById("lang-de").addEventListener("click", () => {
  setLocale("de");
  updateUI();
});

function updateUI() {
  document.getElementById("title").textContent = m.welcome();
  document.getElementById("nav-home").textContent = m.nav_home();
}

In React:

function Welcome() {
  return <h1>{m.welcome()}</h1>;
}

In Vue:

<template>
  <h1>{{ m.welcome() }}</h1>
</template>

In Svelte:

<h1>{m.welcome()}</h1>

No framework-specific wrappers, no different APIs to learn. The same translation functions work everywhere because they're just JavaScript functions.

Advanced Configuration Options

Language Detection Strategy

Configure how Paraglide determines the user's language:

paraglideVitePlugin({
  project: "./project.inlang",
  outdir: "./src/lib/paraglide",
  strategy: [
    "url",
    "cookie",
    "header",
    "localStorage",
    "sessionStorage",
    "baseLocale",
  ],
});

Available strategies:

url - checks the URL path (/de/about)
cookie - checks for a language cookie
header - checks Accept-Language header (SSR)
localStorage - checks browser local storage
sessionStorage - checks browser session storage
baseLocale - falls back to your default language

Paraglide tries these strategies in order until it finds a valid locale. If none match, it uses your baseLocale.

Custom Output Directory

Change where generated files are placed:

paraglideVitePlugin({
  project: "./project.inlang",
  outdir: "./src/i18n", // Custom location
});

Then import from your custom path:

import * as m from "./src/i18n/messages";

Conclusion

Bundle size matters. Every kilobyte of JavaScript affects your page load times, especially on mobile devices.

Traditional i18n libraries ship their entire runtime to the browser - parsers, formatters, and configuration logic. Paraglide compiles everything at build time, so your users only download the actual translated strings as simple JavaScript functions.

This was the main reason I switched to Paraglide for my frontend-rendered sites. When every byte counts for performance, zero-runtime overhead makes a real difference.

Server-side rendering? The bundle size advantage matters less. But for client-side apps, SPAs, and any frontend-heavy project, Paraglide's compile-time approach delivers measurable performance benefits.

The type safety and framework flexibility are nice bonuses. The smaller bundles are why it's worth the switch.

Know Your Dealer: npm's Security Features You're Not Using

Wolfgang Rathgeb — Sat, 05 Jul 2025 04:46:58 +0000

I trust 700+ strangers with my production code. You probably do too.

Every time you run npm install, you're essentially saying "here, random people on the internet, please have access to my filesystem, network, and potentially my users' data." And honestly? That's fine. It's how the modern web works.

npm didn't just make JavaScript development possible – it made it scalable. The ability to pull in battle-tested solutions instead of reinventing every wheel turned JavaScript from a toy language into the backbone of the internet.

But here's the thing: npm gave you security tools. You're just not using them.

The trust equation that actually works

Let me be clear: I'm not here to scare you away from npm. I use pnpm myself (which is built on the same ecosystem), and I install packages daily. The JavaScript ecosystem's strength IS its openness.

But there's a difference between informed trust and blind faith.

Informed trust: "I install packages, and I know what I'm installing."
Blind faith: "I install packages and hope for the best."

The tools to move from blind faith to informed trust are already sitting in your terminal. You just need to use them.

npm audit: Your dependency background check

Let's start with the obvious one you've probably ignored: npm audit.

npm audit

This command scans your dependency tree against the Node Security Advisory database. It's free, it's built-in, and it finds real vulnerabilities.

What you'll typically see:

found 12 vulnerabilities (3 low, 6 moderate, 2 high, 1 critical)
run `npm audit fix` to fix them, or `npm audit` for details

The brutal truth: Most projects have vulnerabilities. That's not necessarily a crisis – it's information.

Understanding what npm audit actually tells you

Not all vulnerabilities are created equal:

Critical/High: These matter. Fix them.
Moderate: Fix them when convenient, but don't panic.
Low: Usually noise, but worth understanding.

The key is context. A vulnerability in a development-only testing library? Probably fine. A vulnerability in your authentication middleware? Not fine.

# See details, not just summary
npm audit --audit-level=moderate

# Focus on production dependencies only
npm audit --production

# Get machine-readable output for automation
npm audit --json

When npm audit fix actually works (and when it doesn't)

npm audit fix

This auto-updates packages to secure versions. It works about 60-70% of the time for simple cases.

When it works: Minor version updates that don't break APIs.
When it doesn't: Major version changes, peer dependency conflicts, or packages that simply haven't been updated.

Pro tip: Always run your tests after npm audit fix. Auto-updates can break things.

For stubborn vulnerabilities:

# See what would happen without doing it
npm audit fix --dry-run

# Force major version updates (dangerous)
npm audit fix --force

npm outdated: Know what you're missing

Here's a command I actually use regularly:

npm outdated

This shows you which packages have newer versions available. It's not directly about security, but outdated packages are often vulnerable packages.

The output tells you:

Current version installed
Wanted version (respects your semver range)
Latest version available
Where it's defined (package.json vs. dependency)

My workflow:

npm outdated monthly
Update patch versions automatically
Research major version updates before applying

The dependency tree: Understanding what you actually installed

npm ls

This shows your complete dependency tree. Prepare to be surprised by how deep it goes.

# Just top-level dependencies
npm ls --depth=0

# Find specific packages
npm ls package-name

# Production dependencies only
npm ls --production

Why this matters: You might think you installed 10 packages, but you actually installed 200. Each one is a potential attack vector.

package-lock.json: Your security anchor

That package-lock.json file? It's not just for reproducible builds – it's a security feature.

Without package-lock.json: npm install might pull different versions each time.
With package-lock.json: You get exactly the same dependency tree every time.

Security implication: A malicious package can't sneak into your project through a dependency update if your lockfile pins the exact versions.

# Use this in CI/CD
npm ci

# Not this
npm install

npm ci installs exactly what's in your lockfile and fails if package.json and lockfile are out of sync.

Practical security workflow that doesn't suck

Here's what I actually do (and what you should probably do):

Before adding new packages:

# Check the package health
npm view package-name

# Look at download stats, maintainers, dependencies
npm view package-name downloads
npm view package-name dependencies

Monthly maintenance:

# Check for vulnerabilities
npm audit

# Check for outdated packages
npm outdated

# Update what makes sense
npm update

Before releases:

# Full security check
npm audit --audit-level=low

# Ensure clean lockfile
npm ci

The tools npm gives you (that you're probably not using)

npm view: Research before you install

npm view express
npm view express versions --json
npm view express repository

npm explain: Understand why packages are there

npm explain lodash

This tells you which of your dependencies pulled in lodash, so you understand your dependency chain.

npm doctor: Health check your setup

npm doctor

Checks if your npm installation is healthy and properly configured.

When to worry (and when not to)

Worry about:

Critical vulnerabilities in production dependencies
Packages that haven't been updated in 2+ years
Dependencies with excessive permissions
Maintainers who disappear

Don't panic about:

Low-severity vulnerabilities in dev dependencies
Prototype pollution warnings (usually not exploitable)
Having "a lot" of dependencies (that's normal)

Red flags that actually matter

After years of using npm/pnpm, here are the actual warning signs:

Package red flags:

Weekly downloads under 1000 (unless it's very niche)
Last published more than 2 years ago
Maintainer list is empty or suspicious
Recent version jumps (1.2.3 → 15.0.0) without clear changelog

Dependency red flags:

Packages that pull in hundreds of sub-dependencies
Packages that require network access during install
Packages with vague descriptions or no documentation

The honest assessment

npm's security model isn't perfect. Supply chain attacks happen. Packages get compromised. Maintainers make mistakes or disappear.

But the alternative – writing everything from scratch – isn't realistic. The JavaScript ecosystem's power comes from its openness and collaboration.

The goal isn't perfect security (impossible) or zero dependencies (impractical). The goal is informed decisions.

Your action plan

This week:

Run npm audit on your main project
Check npm outdated and update what makes sense
Add npm ci to your deployment process

Monthly:

npm audit && npm outdated
Research and update major dependencies
Remove packages you're not actually using

Before major releases:

Full audit with npm audit --audit-level=low
Verify production dependencies with npm ls --production
Test everything after updates

Know your dealer

npm is an incredible tool that democratized code sharing and made modern web development possible. The fact that you can pull in battle-tested solutions with a single command is genuinely amazing.

But like any powerful tool, it works best when you understand what it's actually doing.

You don't need to become a security expert or audit every line of code in your node_modules. You just need to use the tools npm already gives you.

Know your dealer. Know what they're selling you. Make informed decisions.

Your future self (and your users) will thank you.

Using pnpm instead of npm? These principles apply there too – just replace npm with pnpm in the commands.

Fedora CoreOS Setup Guide – Ignition Files Without the Frustration

Wolfgang Rathgeb — Fri, 30 May 2025 16:40:21 +0000

Fedora CoreOS setup usually doesn't fail because of complexity, but because of the missing entry point. The documentation is comprehensive - perfect as a reference, but not ideal for the first setup. Anyone who only occasionally installs CoreOS often faces the question: How do you actually get the Ignition file into the system? That's exactly what this guide explains.

This article shows how to build a working Fedora CoreOS system from scratch. The Ignition file is created step by step – with SSH access and everything needed to get started. The structure is relatively simple and easy to understand, with just one SSH public key for the core user.

CoreOS works differently than traditional Linux installations – everything is defined upfront instead of configured afterwards. Once understood, the approach is convincing.

TL;DR - Quick Reference:

Create Ignition file: Write YAML file with SSH key (config.bu)
Convert to JSON: docker run --rm -i quay.io/coreos/butane:release --strict < config.bu > config.ign
Start HTTP server: python3 -m http.server 8000 in directory with .ign file
Find IP address: ip addr show | grep "inet " | grep -v 127.0.0.1 (Linux)
Boot CoreOS ISO and install: sudo coreos-installer install /dev/sda --ignition-url http://IP:8000/config.ign --insecure-ignition
Reboot - CoreOS is ready to go

Creating the Ignition File

The Ignition file is a JSON file that describes the complete system before it gets installed. Instead of creating users and configuring SSH keys after installation, everything happens automatically during the first boot.

The easiest way is to write a human-readable YAML file and then convert it to JSON using Butane. For getting started, a minimal setup with SSH access for the default user is sufficient:

# config.bu
variant: fcos
version: 1.6.0
passwd:
  users:
    - name: core
      ssh_authorized_keys:
        - "ssh-rsa AAAAB3NzaC1yc2EAAAA... your-public-key"

That's it. Three lines of configuration define SSH access for the default user core. The variant: fcos specifies that this is for Fedora CoreOS, the version determines the schema. CoreOS comes with the core user already preconfigured – it just needs an SSH key.

This YAML file (with .bu extension) is then converted with Butane to a .ign JSON file that CoreOS understands.

From YAML to JSON – The Butane Conversion

The YAML file is human-readable, but CoreOS only understands JSON. That's where Butane comes in – a tool that handles the conversion and also checks the syntax.

Butane runs easiest as a container. With Docker or Podman:

docker run --rm -i quay.io/coreos/butane:release --strict < config.bu > config.ign

Alternatively, Butane can also be installed as a local binary if Docker is not available.

The --strict parameter ensures that Butane aborts on errors instead of ignoring warnings.

The result is a config.ign file in JSON format that Ignition understands:

{
  "ignition": {
    "version": "3.5.0"
  },
  "passwd": {
    "users": [
      {
        "name": "core",
        "sshAuthorizedKeys": ["ssh-rsa AAAAB3NzaC1yc2EAAAA... your-public-key"]
      }
    ]
  }
}

This .ign file is what CoreOS reads during the first boot.

Getting the Ignition File into the Installation

Now we have the Ignition file - but how do we make it available to CoreOS during installation? This is where many people fail. CoreOS starts without prior configuration and needs the Ignition file already during the first boot.

There are several ways, but the easiest is via URL. CoreOS can load the Ignition file from a web server. This sounds complicated, but with a local HTTP server it's done in minutes.

Local HTTP Server with Python

Python has a built-in HTTP server. In the directory with the config.ign file:

# Python 3
python3 -m http.server 8000

# Python 2 (if Python 3 is not available)
python -m SimpleHTTPServer 8000

You can find the IP address of your machine depending on the system:

# Linux
ip addr show | grep "inet " | grep -v 127.0.0.1

# macOS
ifconfig | grep "inet " | grep -v 127.0.0.1

# Windows (PowerShell)
ipconfig | findstr "IPv4"

If the IP is for example 192.168.1.100, then the Ignition file is available at http://192.168.1.100:8000/config.ign.

Alternative Methods

USB stick: The Ignition file can also be provided on a USB stick
Cloud providers: With cloud providers, the file is usually provided via their metadata service
Network boot: With PXE boot, the file can be provided via TFTP

For getting started, the HTTP server is the most straightforward approach.

Performing the CoreOS Installation

Download ISO

The Fedora CoreOS ISO is needed for installation. It's available on the official download page. The "Bare Metal & Virtualized" variant is right for our purposes.

Write the ISO to a USB stick or mount it in a VM. CoreOS boots directly into a live environment – no installation wizard, just a terminal.

Installation

The live environment automatically logs in as the core user. The coreos-installer command handles the installation:

sudo coreos-installer install /dev/sda --ignition-url http://192.168.1.100:8000/config.ign --insecure-ignition

The important parameters:

/dev/sda – Target drive (VMs usually use /dev/vda)
--ignition-url – URL to the Ignition file
--insecure-ignition – Required for HTTP without SSL

Use lsblk to show all drives if unclear which is the right one.

What Happens During Installation?

The installer fetches the Ignition file, partitions the disk, and installs the CoreOS image. The Ignition file gets integrated into the system and executes during the first real boot.

Takes only a few minutes. After reboot, the HTTP server can be stopped and is no longer needed.

Installing docker-compose

After installation, tools like vim or docker-compose are missing. The first reflex is dnf install as usual with Fedora – but that doesn't work. CoreOS has an immutable filesystem, the root system is read-only.

Software is installed via rpm-ostree:

# Install software
sudo rpm-ostree install vim docker-compose

# Reboot required
sudo systemctl reboot

After reboot, the software is available. The system remains stable and can be easily rolled back if there are problems.

Most software runs as containers – CoreOS is optimized for that. Only system tools like vim or docker-compose are installed directly.

Why Fedora CoreOS?

CoreOS is optimized for container workloads. The immutable system prevents drift and makes updates predictable. Rolling releases keep the system automatically up to date.

For pure container environments, CoreOS is leaner than a full Fedora. Fewer installed packages mean less attack surface and less maintenance overhead.

The system boots fast and runs stable. Updates happen automatically in the background, a reboot activates the new version. If there are problems, rollback to the previous version is possible.

CoreOS makes sense for everyone who primarily wants to run containers. For traditional software installation, a standard Fedora is better suited.

Conclusion

The Fedora CoreOS setup is not complicated, but different from what you're used to. The critical point is getting the Ignition file into the installation. A Python HTTP server solves this elegantly.

The switch from dnf to rpm-ostree takes some getting used to. But rpm-ostree isn't needed that often anyway, since everything runs in containers.

CoreOS is suitable for container workloads and minimal systems. Linux beginners should first gain experience with standard Fedora – CoreOS is a specialized tool.

The test on Raspberry Pi is still pending, but could be interesting.

Self-Host Your Own URL Shortener with Zero Database Setup

Wolfgang Rathgeb — Tue, 27 May 2025 15:35:54 +0000

Self-hosting shouldn't require a PhD in DevOps. After trying various URL shorteners that demanded complex database setups and endless configuration files, I built shrtn.io – a lightweight, self-hosted URL shortener that actually respects your time.

Why Another URL Shortener?

Most self-hosted solutions require MySQL/PostgreSQL setup, complex configurations, and heavy resource usage. shrtn.io takes a different approach:

SQLite by default – No database server required
SvelteKit-powered – Lightning fast and resource-efficient
Single Docker container – Deploy in seconds
Flexible deployment – Docker, Cloudflare Workers, or traditional hosting

Key Features That Actually Matter

Privacy-First Design

Flexible access control: public access, private (login required), or public-only
Restrict access by email addresses or domains
Disable public interface for complete privacy
Hide user login when running in public-only mode
Your data stays on your server

Smart Link Protection

Automatic DNS verification
Blocks internal/private IP addresses by default
Configurable security policies
Allow internal links via feature flag

Developer-Friendly

Multiple database options: SQLite, libSQL, Turso, Cloudflare D1
Custom domain support
Configurable TTL limits
Clean API design

Getting Started (The Easy Way)

Docker (Recommended):

docker run -d \
   -p 3001:3001 \
   --name my-shrtn \
   -v ~/shrtn-data:/data \
   -e ORIGIN=https://url.example.com \
   -e PUBLIC_INSTANCE_MODE=PUBLIC_ONLY
   cordlesswool/shrtn

Cloudflare Workers:
Deploy directly to Cloudflare's edge network with D1 database integration.

That's it. No database installation, no complex environment files, no headaches.

Setup a private instance

Check out the setup guide at https://shrtn.io/setup to configure a private instance. All you need to do is set PUBLIC_INSTANCE_MODE=PRIVATE and configure an email provider.

Why Self-Host Your URL Shortener?

Control your data – No third-party analytics harvesting
Custom domains – Perfect branding for your links
No rate limits – Create as many links as you need
Privacy compliance – GDPR/CCPA friendly by design
No vendor lock-in – Export your data anytime

What's Next?

shrtn.io started as a side project but has grown to over 45 stars on GitHub (and counting!). The focus remains on simplicity and developer experience – features that solve real problems without bloat.

Try shrtn.io today: https://shrtn.io

GitHub: Check out the setup guide and contribute to the project

Self-hosting should be simple. URL shortening should be private. shrtn.io delivers both.

Paraglide 2.0 Migration – From Framework Glue to Clean Abstraction

Wolfgang Rathgeb — Wed, 07 May 2025 08:11:00 +0000

From time to time, it's necessary to bring all dependencies up to date. Most of them update easily. Paraglide.js? Definitely not.

This post is not just a dry migration guide — it’s also about the headaches, surprises, and a few decisions you’ll have to make if you’re already deep into a SvelteKit project like I am with shrtn.io. And while we’re at it: Paraglide’s approach to minimalism still makes me smile — even if it makes the docs a bit too... minimal at times.

That said, version 2.0 is a huge step forward. The documentation is better, the architecture is more maintainable, and the framework independence finally feels real. But not everything is an upgrade — especially not the developer experience when removing some of the SvelteKit-specific helpers.

If you're here just for the code, feel free to skip ahead.

TL;DR

✓ Paraglide 2.0 drops framework-specific packages — use the new Vite plugin.

→ You’ll need to clean up old imports, configs, and the <ParaglideJS> wrapper.

! Language switching now requires data-sveltekit-reload or a manual setLocale().

>> Overall: Fewer moving parts, more clarity — but less convenience in some spots. Otherwise, buckle up: here’s what it took to get Paraglide 2.0 running cleanly in production.

What's New in Paraglide 2.0

Paraglide 2.0 brings several core changes and improvements:

Updated to the inlang SDK v2, now with support for variants (e.g. pluralization).
Unified API, works across frameworks without the need for framework-specific bindings.
Supports all major i18n strategies, including cookie, URL, domain, local storage, and session-based resolution.

Additional Improvements

Nested message keys: Organize translations in structured hierarchies.
Auto-imports: Translation keys accessed via m.key no longer require a manual import.
Flexible key naming: Supports arbitrary key names (even emojis) via m["🍌"]().
Incremental migration: You can gradually adopt Paraglide 2.0 in existing projects.
Multi-tenancy support: Routing can now vary by domain.
Compiler API exposed: Enables advanced automation or custom tooling.
Customizable routing strategies: Choose or mix strategies like cookie or URL.
Experimental per-locale bundle splitting: Potential for reduced bundle sizes.
Framework-agnostic SSR middleware: Works with SvelteKit, Next.js, and others.

Step 1: Native Vite Plugin

Paraglide.js now ships with a framework-agnostic Vite plugin. No more need for framework-specific packages like @inlang/paraglide-sveltekit. I’m also using it in production on dropanote.de, my own personal website built with embodi — which had no specific Paraglide framework plugin. So having a framework-agnostic plugin is a real win here.

Install the new package and remove the old SvelteKit-specific dependency:

pnpm add @inlang/paraglide-js
pnpm remove @inlang/paraglide-sveltekit

Update your vite.config.ts:

import { paraglideVitePlugin } from "@inlang/paraglide-js/vite";
import { defineConfig } from "vitest/config";
import { sveltekit } from "@sveltejs/kit/vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [
    paraglideVitePlugin({
      project: "./project.inlang",
      outdir: "./src/lib/paraglide",
      strategy: ["url", "cookie", "baseLocale"],
    }),
    tailwindcss(),
    sveltekit(),
  ],
  test: {
    include: ["src/**/*.{test,spec}.{js,ts}"],
  },
});

The strategy option defines the language resolution order. This is new in Paraglide 2.0.

And yes — this plugin now works across frameworks. That’s actually a big win if you’re aiming for portability or want to reduce tech-specific glue code.

Step 2: New Naming Convention

Paraglide 2.0 introduces a few opinionated renamings. You’ll need to touch both the config and your code.

Update project.inlang/settings.json:

{
  "$schema": "https://inlang.com/schema/project-settings",
- "sourceLanguageTag": "en",
+ "baseLocale": "en",
- "languageTags": ["en", "de"],
+ "locales": ["en", "de"],
- "modules": [
-   "https://cdn.jsdelivr.net/npm/@inlang/message-lint-rule-empty-pattern@latest/dist/index.js",
-   "https://cdn.jsdelivr.net/npm/@inlang/message-lint-rule-missing-translation@latest/dist/index.js",
-   "https://cdn.jsdelivr.net/npm/@inlang/message-lint-rule-without-source@latest/dist/index.js",
-   "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@latest/dist/index.js",
-   "https://cdn.jsdelivr.net/npm/@inlang/plugin-m-function-matcher@latest/dist/index.js"
- ],
+ "modules": [
+   "https://cdn.jsdelivr.net/npm/@inlang/plugin-message-format@4/dist/index.js",
+   "https://cdn.jsdelivr.net/npm/@inlang/plugin-m-function-matcher@2/dist/index.js"
+ ],
  "plugin.inlang.messageFormat": {
-   "pathPattern": "./messages/{languageTag}.json"
+   "pathPattern": "./messages/{locale}.json"
  }
}

Also update your imports:

// Before:
import { languageTag } from "$lib/paraglide/runtime";

// After:
import { getLocale } from "$lib/paraglide/runtime";

The renaming makes things more consistent — and since you're upgrading anyway, now’s a good time for a bit of cleanup. A few search-and-replace rounds, maybe a lint check, and you're done.

Step 3: Remove `i18n.ts`

Yep, it’s gone. Delete src/lib/i18n.ts. If that sounds harmless — it’s not. This file was probably imported across your app.

Here’s how to replace its functionality:

`hooks.server.ts`

Replace i18n.handle() with:

import { paraglideMiddleware } from "$lib/paraglide/server";

const paraglideHandle: Handle = ({ event, resolve }) =>
  paraglideMiddleware(
    event.request,
    ({ request: localizedRequest, locale }) => {
      event.request = localizedRequest;
      return resolve(event, {
        transformPageChunk: ({ html }) => html.replace("%lang%", locale),
      });
    },
  );

Replace i18n.reroute() with:

import type { Reroute } from "@sveltejs/kit";
import { deLocalizeUrl } from "$lib/paraglide/runtime";

export const reroute: Reroute = (request) => {
  return deLocalizeUrl(request.url).pathname;
};

`+layout.svelte`

The <ParaglideJS> component is gone too. RIP.

- <ParaglideJS {i18n}>
    {@render children()}
- </ParaglideJS>

This one hurts. The wrapper used to handle links and localization. Now, you're on your own — you’ll need to wrap links with localizeHref() or localizeUrl().

import { redirect } from "@sveltejs/kit";
import type { PageServerLoad } from "./$types";
import { localizeHref } from "$lib/paraglide/runtime";

export const load: PageServerLoad = () => {
  redirect(302, localizeHref("/"));
};

This works — but doesn’t feel like progress. What used to be automatic now needs to be handled manually, and that includes setting up language-aware routing and keeping link consistency across layouts. It adds responsibility without offering much in return, at least not immediately.

Step 4: Language Switching

To switch languages manually — for example, in a language selector or after clicking a custom flag icon:

import { setLocale } from "$lib/paraglide/runtime";
setLocale("en");

If you want to support language switching via links — especially in a way that SvelteKit recognizes during navigation — make sure to include the data-sveltekit-reload attribute. Without it, the routing won’t fully reset, and language state might not update as expected:

<a
  data-sveltekit-reload
  rel="alternate"
  hreflang="en"
  href={localizeHref(page.url.pathname, { locale: 'en' })}>
  EN
</a>
<a
  data-sveltekit-reload
  rel="alternate"
  hreflang="de"
  href={localizeHref(page.url.pathname, { locale: 'de' })}>
  DE
</a>

Or use setLocale() and a preventDefault() if you want to stay in SPA-land — just make sure the updated locale is reflected in the URL as well, or the app might not behave as expected when reloading or sharing links.

If you forget this step, SvelteKit might continue rendering the page in the previous language even after setLocale() is called, especially after navigation or reloads. In short: data-sveltekit-reload ensures your intent is fully respected. Your call.

Migration Notes & Pitfalls

Here are a few things that caught me off guard or took more time than expected:

~> Removing <ParaglideJS> breaks existing localization logic — you’ll need to rebuild it manually.

! Missing data-sveltekit-reload can lead to language switches silently failing.

# Key renaming (languageTags → locales, etc.) touches a lot of files — don’t underestimate it.

Conclusion

The upgrade to Paraglide.js 2.0 brings fewer files, fewer dependencies, and more architectural clarity. But with that comes less convenience — especially if you relied on the opinionated SvelteKit integrations.

Still, it’s worth the switch. You’ll end up with:

a framework-independent i18n system
strong type safety
and less vendor lock-in

Paraglide isn’t doing the magic for you anymore. Whether that’s a good thing depends on what you value: convenience or control. You now need to be more explicit — which can feel tedious, but also results in code that's easier to reason about and maintain in the long run.

How to use generics in pipe-and-combine

Wolfgang Rathgeb — Thu, 05 Dec 2024 20:00:38 +0000

This is the second article about pipe-and-combine and will go more in depth and the newest feature added with version 0.7.x - using generics in pipes.

The problem

First, it helps to understand the problem. When you use a generic function you just fine what you need to handle, but maybe you just want to add something and the upcoming function needs a value from the beginning. By default, TypeScript does not follow the hole line when you define something like this:

type pipe = <
  A, B, C, D
  fu1: (data: A) => B,
  fu2: (data: B) => C,
  fu3: (data: C) => D
>(fu1, fu2, fu3) => (data: A) => D

If all these functions are generic like <T extends { n: number }>(data: T) => { ...data, b: !!data.n} TypeScript will follow only one step. So A of fu1 is defined as {n: number}' and B as{a: number, b: boolean}'. This is fine if the next function only needs stuff that is explicitly defined, but if you need something from fu1 in fu3 that is not mentioned in fu2 but is piped through it, TypeScript will tell you that this value does not exist.

The second problem is that you cannot access the generic value of any function to define the input more clearly.

If we know that all functions will merge all the time, we could do something like

type Pipe = <
  A, B, C, D
  fu1: (data: A) => B,
  fu2: (data: B) => B & C,
  fu3: (data: C) => B & C & D
>(fu1, fu2, fu3) => (data: A) => B & C & D

But then really all functions have to merge or the type will not match again.

G is the solution

UPDATE: g was renamed to enrich in version 0.9.0

Before you think in the wrong direction, G does not stand for God, it is not that powerful...

Ok, back to what g really does and why we need it: Logically, it is a merge function. It calls your function and merges the output with the given object.

//GMerge is the type returned by the function g
type GMerge<I, O> = ((data: I) => I & O) & {
  Brand: "GMerge";
};

import { g } from pipe-and-combine;
g(<T extends { n: number }>(data: T) => ({ b: !!data.n}));
// The return value will be of type GMerge
// When executed, g will call your function and merge the result with the data passed to g.

Logically, the function is very simple, but the important part is the branding. With this, pipe-and-combine knows how to handle it and how to define the type. So you will have the real type and not just the minimal one required by the function before.

How to remove values

Besides the g function witch merge, there is an omit and pick that you can use directly in your pipe, but they are also generic and handled in a special way.

import {pipe, omit, pick} from 'pipe-and-combine';

// remove the attributes a and b from the object
pipe(omit('a', 'b'))

// Pick the attributes a and b from the object and return a object with those attributes
pipe(pick('a', 'b'))

Additional

There are several other functions already implemented that you can read about on the npm page, and more will be added in the future. As you can read in the first article on `pipe-and-combine', even as the library grows, by using pipeing instead of chaining, unused code could be shaken off (tree shaking).

Pipe the shit

Wolfgang Rathgeb — Mon, 02 Dec 2024 20:49:55 +0000

I've got lots of ideas for this article, but I'm not sure where to start. If you're interested in making code more readable and using tree shaking, you should definitely check out the article.

If you've ever developed with JavaScript, you've probably come across this type of code.

const someInstance = new Class();
someInstance.do('jump').some().thing('dance').and().read();

I like this style because it could be very easy to read and you see what is connected. Plus, you don't have to move data from one function to another because it's all saved in the instance.

On top of the fact that this only works if the functions aren't async, there's another issue. It's not going to be easy to tree shake the content if you're not using it. If you use this in the client, you have to move the whole library with all the connected functions, which is a huge overhead.

So, how can we keep things readable, use async functions and let Vite and co. tree shake all unused code?

The answer's right there in the headline: "pipe."

From a functional standpoint, implementing pipe is pretty straightforward. However, the types did pose a challenge. I've put everything together into a library and published it on npm. pipe-and-combine.

const inc = (by: number) => (x: number) => x + by;
const dec = (by: number) => (x: number) => x - by;
const multiplyBy = (by: number) => (x: number) => x * by;
const divideBy = (by: number) => (x: number) => x / by;
const toStr = () => (x: number) => x.toString();

// prepare the pipeline
const pipeline = pipe(inc(2), multiplyBy(7), dec(7), divideBy(3), toStr())

// Executing the pipeline
pipeline(7)

One advantage is that it's not tied to any object, so you can use any function as long as the input and output match the function before and after.

The example I've given is pretty simple, but at least you can pipe everything. You'll have the same options as with chaining and classes. Generic functions might be a little more tricky, but there's a solution. I'll cover this in more detail in another article.