DEV Community: Alessio Michelini

You should stop using high effort for everything in Claude Code

Alessio Michelini — Thu, 29 Oct 2026 14:34:03 +0000

I've noticed something among developers I know who use Claude Code: a lot of them set the effort level to high, xhigh, or even max, and just leave it there, forever.

The reasoning is understandable: "more effort means better code, right?".

Well, not exactly.

In this article I want to share the workflow I use when I build a new feature, or even an entire new project, where I spend a lot of effort (and tokens) when it matters, and very little when it doesn't.

What is effort anyway?

If you haven't played with it yet, effort is a setting in Claude Code that tells the model roughly how much work you want it to put into a task. You can change it at any time with the /effort command:

/effort low
/effort medium
/effort high
/effort xhigh
/effort max

Yes, high is not the top of the scale! With Opus 5.5 you also get xhigh and max, and from what I see these are the levels a lot of people actually use, as "if high is good, max must be better".

But every step up costs more. Taking medium (the default) as the baseline, this is roughly how many tokens each level consumes:

Effort	Tokens compared to `medium`
`low`	~0.7x
`medium` (default)	1x
`high`	~1.5x
`xhigh`	~2.5x
`max`	~5.2x

So if you leave Claude Code on max for everything, you are spending about five times the tokens of the default, and more than seven times what the same task would cost on low. And the extra time adds up just as quickly.

Higher effort doesn't make the model "smarter". What it does is make Claude spend more time verifying its own work, checking edge cases, and making its own judgement calls. Lower effort gives you a quicker, simpler result that you are expected to iterate on.

Think about it like asking a colleague to do something. If you give them a full day, they will try to deliver the most complete version they can, and they will make a lot of decisions on your behalf along the way. If you give them an hour, they will deliver something that does the job and expect you to give feedback.

Neither is wrong, it depends on what you need at that moment.

The problem with "max effort all the time"

When you leave effort on high, xhigh, or max for everything, a few things happen:

You burn a lot more tokens, even for tasks like renaming a variable or adding a field to a form.
You wait longer for every single response.
Claude makes more assumptions for you, which is great when you want it to work autonomously, but not so great when you want to stay in control of what's being built.

That last point is the one that surprised me the most. More effort doesn't automatically mean more of what you wanted, it often means more of what Claude thinks you wanted.

My workflow: plan high, execute lower

So here's what I do instead. I split the work into two very different phases, and I use a different effort level (and sometimes a different model) for each of them.

flowchart TD
    A[Idea] --> B[Plan<br/>Opus 5.5, high effort]
    B --> C[Plan + ADRs]
    C --> D[Execute step N<br/>Opus or Sonnet 5.5, low/medium]
    D --> E{Review}
    E -- needs changes --> D
    E -- looks good --> F[Verify<br/>high effort]
    F --> G{More steps?}
    G -- yes --> D
    G -- no --> H[Done]

Step 1: Plan with high effort

The planning phase is where the hard thinking happens: what are we building, how do the pieces fit together, what are the trade-offs, what could go wrong.

This is exactly where I want the model to think hard, so I use Opus 5.5 with high effort:

claude --model opus

# Then inside the session
/effort high

I also ask Claude to interview me about the feature before writing the plan. This is a small trick that makes a huge difference, as it forces me to answer the questions I didn't think about, and Claude doesn't have to guess.

To do that, I use the grilling skill from Matt Pocock. If you don't know what skills are, they are just markdown files with instructions that Claude Code loads when they are relevant to what you are doing.

What I like about this skill is how structured the interview is:

Claude maps every decision as a tree, where each decision unlocks the ones that depend on it.
It asks the questions in rounds, only the ones that can be answered now, without guessing answers you haven't given yet.
Each question comes numbered and with a recommended answer, so most of the time you can just say "yes" and move on.
Facts it can find by itself, like what's in your codebase, it looks up on its own, and it only asks you about decisions.
It doesn't start doing anything until you both agree there's nothing left to decide.

To install it, just follow the installation steps in the repository, it takes less than a minute.

Then in the planning session I just ask Claude to grill me:

I want to add bookmarks to my blog app, so logged-in users can save
articles and see them in a "Saved" page.
Grill me on this before writing any plan. Once we agree, write a plan
split into small, independent steps.

And a round of questions will look something like this:

❓ Q1 - Anonymous users: Should users who are not logged in see the
bookmark button?

➡️ Show it, but redirect to the login page when clicked.

❓ Q2 - Storage: Should bookmarks be stored server-side, or is
localStorage enough?

➡️ Server-side, so bookmarks follow the user across devices.

This can take a while, and with high effort it does use a good amount of tokens, but it's the best place to spend them, as every question answered here is one less assumption Claude has to make later.

Step 2: Write everything down

The output of the planning session is not code, it's documents. I normally end up with something like this:

.
|-- docs
|   |-- adr
|   |   |-- 001-store-bookmarks-in-postgres.md
|   |   `-- 002-use-swr-for-client-fetching.md
|   `-- plans
|       `-- bookmarks.md
`-- CLAUDE.md

The plan, docs/plans/bookmarks.md, is split into steps, where each step is small enough to be done in a single session:

# Bookmarks feature

## Step 1: Database
- Create a `bookmarks` table (user_id, article_id, created_at)
- Add a unique constraint on (user_id, article_id)
- Write the migration and the rollback

## Step 2: API endpoints
- POST /api/bookmarks
- DELETE /api/bookmarks/:articleId
- GET /api/bookmarks

## Step 3: UI
- Bookmark button on the article page
- "Saved" page listing the bookmarks

For the decisions that need a "why", like choosing a library or a database design, I also ask Claude to write an ADR (Architecture Decision Record). An ADR is just a short markdown file that explains what we decided, why, and what alternatives we considered:

# ADR-002: Use SWR for client-side fetching

## Status
Accepted

## Context
The "Saved" page needs to fetch the bookmarks list and refresh it
when a bookmark is added or removed.

## Decision
Use the SWR hook with Suspense, as we already do in other pages.

## Consequences
- Caching and revalidation for free
- One more dependency in the frontend

If you want to know more about SWR and Suspense, I wrote about it in Using SWR hook with Suspense in React 18.

And finally, things that are important to remember, but that don't really belong in the plan (like "the staging database uses a different port" or "we use pnpm, not npm"), go into Claude's memory, like the CLAUDE.md file. This way they are available in every session, without cluttering the plan.

Step 3: Execute one step at a time, with low or medium effort

Now comes the part where most people keep the effort on high, and where I do the opposite.

For each step of the plan, I start a new session, point it to the plan, and lower the effort to low or medium, depending on how big the step is.

I can keep using Opus 5.5 for this, but for the more straightforward steps I often switch to a cheaper model like Sonnet 5.5:

# Stay on Opus 5.5...
claude --model opus

# ...or switch to Sonnet 5.5 for simpler steps
claude --model sonnet

# Then inside the session
/effort low     # small, well-defined steps
/effort medium  # bigger steps, or ones touching more files

Read docs/plans/bookmarks.md and the ADRs in docs/adr.
Implement Step 2 only. Don't touch anything outside that step.

Why does this work? Because all the hard decisions were already made during the planning phase. Claude doesn't need to think hard about how to design the API, it's written right there in the plan. It just needs to execute it.

Starting a new session for each step also has another advantage: the context is clean. No leftovers from previous steps, no long conversation history to drag along, just the plan, the ADRs, and the code.

If a step turns out to be trickier than expected, I just bump the effort up, or switch back to Opus. No big deal.

Step 4: Review, then verify with high effort

Once a step is done, I review the code myself, to make sure Claude got the gist of what I wanted. If something is off, I iterate, still on the same lower effort.

When I'm happy with it, I switch back to high effort and ask Claude to verify the work: run the tests, look for edge cases, check that nothing else broke.

/effort high

Review the changes for Step 2 against docs/plans/bookmarks.md.
Write tests for the edge cases (duplicate bookmarks, deleting a
bookmark that doesn't exist, unauthenticated requests) and run them.

This is where the extra effort really pays off, as hunting for edge cases is exactly the kind of work where thinking longer finds more problems.

Is this just my opinion?

Partly, yes! But it turns out Anthropic recently published a post on the claude.dev blog, Using Claude Code: Spending your effort, where they tested the same tasks at different effort levels, and a few findings match this workflow pretty well.

The most interesting one for me: when they gave Claude a vague request (like "build a fitness tracker app"), the effort level changed the result dramatically. But when they first had Claude interview them and produce a detailed spec, then implemented that spec at different effort levels, the results were very similar, just at very different speeds.

That's the whole point of planning first: a detailed plan removes most of the guesswork, and when there's no guesswork, you don't need to pay for extra thinking.

The loop they recommend is also very close to what I described above: get interviewed about the spec, implement on low effort, review and iterate, then verify and test on high effort.

To be fair, the same post also shows that higher effort does produce better results on hard problems, especially when there are a lot of hidden edge cases. So it's not that high effort is bad, it's that it's not free, and it's not always the thing that makes the difference.

When you should crank up the effort

As with everything, this is not a rule you should apply blindly. There are cases where I go straight to high, or even max, during execution:

Bugs in an existing codebase. When you don't fully know why something is breaking, you want Claude to reproduce the problem first and verify the fix, not just patch the first thing that looks suspicious.
Security-sensitive code. Things like input sanitisation, authentication, or permissions are full of edge cases, and missing one of them is expensive.
Performance work. Claude needs to measure, test with bigger inputs, and iterate, not just write something that looks fast.
Fully autonomous tasks. If you are not going to be in the loop to review each step, then you want Claude to do the verification on its own.

As a rule of thumb, I start with high, and I move to xhigh or max only when the task is really hard, or when Claude is going to work on its own for a long time without me checking in. Those are the cases where all that extra verification actually pays for itself.

And on the other side, there are cases where even planning on high is overkill: a typo fix, a small refactor, or a one-off script. Just do it on low and move on.

Conclusions

The effort level is not a "quality" knob you set once and forget, it's a budget you spend depending on the task.

So what I'd suggest is:

Plan with a strong model and high effort, and let Claude grill you until there's nothing left to decide.
Write it down: a plan split into steps, ADRs for the important decisions, and memory for everything else.
Execute each step in a fresh session, with low or medium effort, and maybe a cheaper model.
Verify with high effort, where finding edge cases actually matters.

You'll spend fewer tokens, wait less for each response, and in my experience, you'll stay much more in control of what's being built.

How do you use effort levels in Claude Code? I'd love to hear if you have a different approach, so let me know in the comments!

You should use Map instead of object literals for lookup tables

Alessio Michelini — Thu, 22 Oct 2026 11:04:30 +0000

A while ago I wrote an article about using object literals instead of switch statements, and I still think the idea behind it is a good one: map an input to an output, skip the long list of case and break, and keep your code short and readable.

But there's a catch I didn't cover back then, and a reader (thanks Dario!) pointed it out in the comments: plain objects don't only contain the keys you put in them.

So in this article I want to show you what the problem is, and why today I'd reach for a Map instead.

A quick recap

In the previous article we had something like this:

const getAnimalSound = animal => {
  const sounds = {
    dog: 'woof',
    cat: 'meow',
    cow: 'moo',
    default: 'unknown sound',
  };

  return sounds[animal] || sounds.default;
};

console.log(getAnimalSound('dog'));   // 'woof'
console.log(getAnimalSound('tiger')); // 'unknown sound'

Clean, short, and it works. Or at least it looks like it does.

So what's the problem?

Every object you create with {} inherits from Object.prototype. This means that when you read sounds[animal], if JavaScript doesn't find the key on the object itself, it goes up the prototype chain and looks there too.

And Object.prototype has quite a few properties on it, like constructor, toString, valueOf, hasOwnProperty and __proto__.

Let's see what happens if we pass one of those names to our function:

console.log(getAnimalSound('constructor')); // [Function: Object]
console.log(getAnimalSound('toString'));    // [Function: toString]
console.log(getAnimalSound('__proto__'));   // [Object: null prototype] {}

None of those return 'unknown sound'. Because the value we get back is truthy, the || sounds.default fallback never kicks in, and we return something completely unexpected.

Now, you might think "who would ever pass constructor as an animal?". And you are probably right, until that value comes from a query string, a form field, or the body of an API request. Then anybody can pass whatever they want.

It gets worse with functions

In the previous article we also used object literals to dispatch commands:

const executeCommand = command => {
  const commands = {
    greet: () => console.log('Hello there!'),
    farewell: () => console.log('Goodbye!'),
    default: () => console.log('Unknown command'),
  };

  (commands[command] || commands.default)();
};

Let's try a few "commands":

executeCommand('constructor');    // nothing happens, it silently calls Object()
executeCommand('toString');       // nothing happens either
executeCommand('hasOwnProperty'); // TypeError: Cannot convert undefined or null to object

The first two fail silently, which is the worst kind of bug, because you don't even know something went wrong. The last one crashes your function.

And with nested objects

The state machine example is my favourite one:

const stateTransitions = {
  idle: { start: 'loading' },
  loading: { success: 'loaded', error: 'error' },
};

const handleStateTransition = (currentState, action) =>
  stateTransitions[currentState]?.[action] || currentState;

console.log(handleStateTransition('constructor', 'name')); // 'Object'
console.log(handleStateTransition('idle', 'toString'));    // [Function: toString]

Yes, your component is now in the 'Object' state, or worse, its state is a function.

Note
To be clear, this is not prototype pollution. Prototype pollution happens when an attacker manages to write to Object.prototype, for example with obj[key] = value where key is __proto__. Here we are only reading, but it's still a real bug, and it's the reason why security linters like eslint-plugin-security flag obj[variable] lookups.

Enter `Map`

A Map is a built-in collection of key/value pairs, and the important difference is that map.get(key) only returns entries that you explicitly added. There's no prototype chain to walk through, so constructor is just a key like any other, and since you never added it, you get undefined.

Let's rewrite our first example:

const sounds = new Map([
  ['dog', 'woof'],
  ['cat', 'meow'],
  ['cow', 'moo'],
]);

const getAnimalSound = animal => sounds.get(animal) ?? 'unknown sound';

console.log(getAnimalSound('dog'));         // 'woof'
console.log(getAnimalSound('tiger'));       // 'unknown sound'
console.log(getAnimalSound('constructor')); // 'unknown sound' ✅
console.log(getAnimalSound('__proto__'));   // 'unknown sound' ✅

You might have noticed a few other small changes, and they are not random:

The Map is defined outside the function, so we don't rebuild it every time the function is called.
The fallback is no longer stored as a default key, so nobody can "select" it by passing 'default'.
I'm using ?? (nullish coalescing) instead of ||. With ||, a valid value like 0 or an empty string would be replaced by the fallback. With ??, the fallback is used only when the value is null or undefined.

Tip
If you already have an object and you don't want to rewrite it as an array of arrays, you can convert it with new Map(Object.entries(myObject)).

Dispatching functions

The same works for our commands:

const commands = new Map([
  ['greet', () => console.log('Hello there!')],
  ['farewell', () => console.log('Goodbye!')],
  ['time', () => console.log(`Current time: ${new Date().toLocaleTimeString()}`)],
]);

const unknownCommand = () => console.log('Unknown command');

const executeCommand = command => (commands.get(command) ?? unknownCommand)();

executeCommand('greet');          // 'Hello there!'
executeCommand('hasOwnProperty'); // 'Unknown command' ✅

And with parameters, like the calculator from the previous article:

const operations = new Map([
  ['add', (x, y) => x + y],
  ['subtract', (x, y) => x - y],
  ['multiply', (x, y) => x * y],
  ['divide', (x, y) => (y !== 0 ? x / y : 'Cannot divide by zero')],
]);

const calculator = (a, b, operation) => {
  const fn = operations.get(operation);
  return fn ? fn(a, b) : 'Unknown operation';
};

console.log(calculator(5, 3, 'add'));     // 8
console.log(calculator(5, 3, 'valueOf')); // 'Unknown operation' ✅

The state machine

For nested lookups you can nest Maps too:

const stateTransitions = new Map([
  ['idle', new Map([['start', 'loading'], ['reset', 'idle']])],
  ['loading', new Map([['success', 'loaded'], ['error', 'error'], ['cancel', 'idle']])],
  ['loaded', new Map([['refresh', 'loading'], ['clear', 'idle']])],
  ['error', new Map([['retry', 'loading'], ['clear', 'idle']])],
]);

const handleStateTransition = (currentState, action) =>
  stateTransitions.get(currentState)?.get(action) ?? currentState;

let state = 'idle';
state = handleStateTransition(state, 'start');    // 'loading'
state = handleStateTransition(state, 'success');  // 'loaded'
state = handleStateTransition(state, 'toString'); // 'loaded' (unchanged) ✅

I'll be honest, this one is a bit less pretty than the object version. We'll come back to that in a moment.

A bonus with TypeScript

If you use TypeScript, Map has another nice side effect: map.get() always returns T | undefined, so the compiler forces you to handle the missing case.

type Animal = 'dog' | 'cat' | 'cow';

const sounds = new Map<Animal, string>([
  ['dog', 'woof'],
  ['cat', 'meow'],
  ['cow', 'moo'],
]);

const getAnimalSound = (animal: Animal): string =>
  sounds.get(animal) ?? 'unknown sound'; // without ?? TypeScript will complain

When you don't need a `Map`

As always, I don't want you to take this as "never use objects again". There are cases where a plain object is perfectly fine.

When the keys never come from outside your code. If the key is a value you control, for example a TypeScript literal union that you pass around internally, the prototype issue can't really happen. In that case an object with satisfies gives you great type checking:

type Animal = 'dog' | 'cat' | 'cow';

const sounds = {
  dog: 'woof',
  cat: 'meow',
  cow: 'moo',
} satisfies Record<Animal, string>;

Just remember that TypeScript types disappear at runtime: if the value comes from a request or a form, you still need to validate it.

When you only need a quick safety check. If you want to keep the object syntax, Object.hasOwn() checks only the object's own properties, ignoring the prototype chain:

const getAnimalSound = animal =>
  Object.hasOwn(sounds, animal) ? sounds[animal] : 'unknown sound';

This is also a good option for deeply nested tables like the state machine, where nested Maps get a bit noisy.

When you need to serialise the data. JSON.stringify(new Map([['a', 1]])) returns {}, not what you expect. If your lookup table needs to be sent over the wire or saved as JSON, an object is easier to work with.

When switch is simply the better tool. As I mentioned in the previous article, if your conditions involve ranges, complex expressions or intentional fall-through, a switch is still the right choice.

Conclusions

Object literals are still a great idea to replace long switch statements, but when the key comes from user input, a plain object can return things you never put in it, like constructor or toString.

A Map fixes that by design: it only knows the keys you gave it, it works nicely with ??, and with TypeScript it forces you to handle the missing case.

So my rule of thumb today is simple:

If the key comes from outside your code, use a Map.
If the key is fully under your control, an object is fine, and Object.hasOwn() is a cheap safety net if you want one.

I hope this helped you to understand the hidden gotcha of object lookups, and as always any comments are welcome!

Disclaimer

Parts of this article were created with the help of AI.

Stop writing raw SQL in your migrations (most of the time)

Alessio Michelini — Fri, 28 Aug 2026 13:28:34 +0000

Something I keep seeing across teams, especially with people who are getting comfortable with tools like db-migrate or Kysely, is a very specific habit: they reach for raw SQL for everything.

Need to add a column? Raw ALTER TABLE. Need to create a table? Raw CREATE TABLE. Need to add an index? You guessed it, another raw query.

And look, raw SQL is not evil, and I'm not here to tell you to never use it. But when your migration tool gives you a proper schema builder and you skip it to write raw strings for a simple column addition, you're throwing away a lot of the things that make those tools worth using in the first place.

Let me explain why.

First, what does "raw" even look like?

Let's say you want to add a simple email column to a users table. With Kysely, the raw approach tends to look something like this:

import { sql } from 'kysely';

export async function up(db) {
  await sql`ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL`.execute(db);
}

export async function down(db) {
  await sql`ALTER TABLE users DROP COLUMN email`.execute(db);
}

Or with db-migrate, people often do this:

exports.up = function (db) {
  return db.runSql('ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL');
};

exports.down = function (db) {
  return db.runSql('ALTER TABLE users DROP COLUMN email');
};

It works. The migration runs, the column appears, everyone goes home happy.

But the same thing with the builder looks like this in Kysely:

export async function up(db) {
  await db.schema
    .alterTable('users')
    .addColumn('email', 'varchar(255)', (col) => col.notNull())
    .execute();
}

export async function down(db) {
  await db.schema
    .alterTable('users')
    .dropColumn('email')
    .execute();
}

And with db-migrate you don't even need to write SQL at all:

exports.up = function (db) {
  return db.addColumn('users', 'email', {
    type: 'string',
    length: 255,
    notNull: true,
  });
};

exports.down = function (db) {
  return db.removeColumn('users', 'email');
};

At first glance the raw version might even look shorter, so why should you care? Let me give you a few reasons.

Reason 1: you lose portability

This is the big one, and it's the one that bites people the hardest.

When you write VARCHAR(255), SERIAL, AUTO_INCREMENT, BOOLEAN, or NOW() directly in a string, you're hardcoding the dialect of one specific database. The moment you switch, or the moment you run your tests against a different engine than production, things start to break in annoying ways.

If you've read some of my other posts, you'll know I have a soft spot for this problem. In the RETURNING clause post I got bitten by exactly this: RETURNING works great on PostgreSQL, but MySQL/MariaDB only partially support it. Raw SQL assumes you know every quirk of your target engine, forever.

The whole point of the schema builder is that it knows the dialect for you. You say addColumn('active', 'boolean') and Kysely (or db-migrate) figures out whether that becomes a real BOOLEAN, a TINYINT(1), or whatever the engine expects. You describe the intent, the tool handles the syntax.

Reason 2: your `down` migrations get fragile

Here's a subtle one. When you use the builder, the tool understands the structure of the change you're making, and reversing it is often trivial and consistent.

When you write raw SQL, you are responsible for writing a down that perfectly undoes the up, and it's very easy to get lazy or to make a mistake. I've seen plenty of migrations where the up is a carefully crafted raw query and the down is just... empty, or wrong, because nobody wanted to hand-write the reverse.

A broken down migration is one of those things you don't notice until the worst possible moment: you need to roll back in production and suddenly discover your escape hatch doesn't work.

Reason 3: you skip the safety net

Builder methods are typed and validated. In Kysely especially, you get autocomplete and, if you're using TypeScript, the compiler will shout at you when you try to do something that doesn't make sense.

This is the same argument I made in my post about defining objects with type definitions in JSDoc and the one on abstracting nested types in TypeScript: giving your tools enough information to help you is almost always worth it. A raw string is completely opaque. Your editor can't check it, can't complete it, and can't warn you that you typed VARHCAR instead of VARCHAR. You'll only find out at runtime, when the migration blows up.

// Typo city. Nothing catches this until it runs.
await sql`ALTER TABLE users ADD COLUMN emial VARHCAR(255)`.execute(db);

// The builder won't let 'emial' silently become a problem,
// and the column type is a known value, not a free-form string.
await db.schema
  .alterTable('users')
  .addColumn('email', 'varchar(255)')
  .execute();

Reason 4: readability and consistency

If half your migrations are raw SQL and the other half use the builder, reading through your migration history becomes a chore. Every file speaks a slightly different language and the reader has to context-switch constantly.

I made basically the same point in why you shouldn't mix ES modules and CommonJS: pick one style and stick with it. Consistency isn't just aesthetic, it genuinely lowers the mental cost for the next person who has to touch the code (and that next person is very often you, six months from now, with no memory of what you were thinking).

So when should you use raw SQL?

Now, here's the important part, because I don't want you to walk away thinking "raw SQL bad, builder good, the end". That's not the point at all.

Raw SQL is the right tool when the ORM or migration library simply doesn't give you a way to express what you need. And that happens more often than you'd think, especially once you go past basic table shapes. Some examples:

Database-specific features that the builder doesn't wrap, like PostgreSQL extensions (CREATE EXTENSION "uuid-ossp"), custom types with CREATE TYPE ... AS ENUM, or generated columns.
Complex data migrations, where you're not just changing the schema but also transforming existing rows, for example backfilling a new column from old data with a CASE statement.
Concurrent index creation in Postgres (CREATE INDEX CONCURRENTLY), which the builder might not support because it has special transaction requirements.
Triggers, functions, materialized views, and other things that are inherently SQL and have no clean builder equivalent.

In those cases, reaching for raw SQL isn't a shortcut, it's the correct answer. The builder abstraction has a ceiling, and when you hit it, you drop down a level. That's a totally healthy thing to do.

The rule I try to follow is simple:

Use the builder for anything the builder can express. Drop to raw SQL only when the builder can't do the job.

A quick reality check

To be fair, there are a couple of arguments on the other side, and I want to acknowledge them rather than pretend they don't exist:

"I know SQL better than the builder's API." Fair. If you're comfortable with SQL, the builder can feel like an extra layer between you and the thing you already know how to write. But the builder isn't there to teach you SQL, it's there to keep your migrations portable, reversible and checkable.
"My app is tied to one database and always will be." Also fair, and if that's genuinely true, the portability argument loses some weight. But the readability, the safer down migrations, and the type safety still stand. And "we'll never change database" has a funny way of not aging well.

So it's not black and white. It's about defaults. My default is the builder, and raw SQL is the deliberate exception, not the reflex.

Conclusions

Writing raw SQL for a simple ALTER TABLE is a bit like using parseInt when Number would do the job better: it works, but you're reaching for the wrong tool out of habit, and you're quietly giving up things you'd actually like to keep.

Let the builder handle the boring, portable, reversible stuff. Save raw SQL for the moments where the ORM genuinely can't help you, and it'll feel like a precision tool instead of a crutch.

And as always, this is just how I like to do it, not the one and only truth. If you've got a different take, I'd love to hear it in the comments.

DISCLAIMER
I used AI to help me write this article and fix grammar issues.

Why Mermaid is the Best Way to Document Your Architecture in the AI Era

Alessio Michelini — Wed, 25 Feb 2026 11:49:40 +0000

Creating documentation for your project was always a fundamental skill for me, long before LLMs even existed.
Being able to quickly read how to setup a project or what the project is about it's something that every repository should have.
And in the LLMs era, where you need to also tell a model how your project works, without it having to waste tokens reading through your code and figuring things out on its own, it's even more important.

But what changed is how the documentation is consumed. Is no longer for humans-only to be understood, but it's also massively important for machines.

One of the most important aspect we need to document about a project is often the architecture or any flows of how that piece of software you wrote works.

And what's the easiest way to graphically show that? Diagrams.

In the past a common way to do it was using ASCII, so you might have something like this:

┌─────────────┐        ┌─────────────┐        ┌─────────────┐
│   Browser   │ ──────▶│   Backend   │ ──────▶│  Database   │
└─────────────┘        └─────────────┘        └─────────────┘

Simple to read, fairly universal to show it anywhere, it doesn't need any special plugin or software to be read, it just works.

And often an LLM, when you ask to create a diagram, will use just that, as it's easier for a human to read.

But this doesn't mean that, while is effective to humans, is also effective to AI models.

Enter Mermaid.js

Another way to represent the exact same diagram above, is to use a format called mermaid.
It's a very simple format that is supported by Github, Gitlab, Gitea, etc... and that diagram will look like this:

flowchart LR
    Browser --> Backend --> Database

Again, still fairly easy to read, maybe less fancy than the ASCII, but it will render beautifully iin a browser where that format is supported.
You can also zoom in, it scales up to whatever resolution you want, and many other advantages, and the only real disadvantage is the fact that you need something to render it, which is the mermaid renderer.

Another issue is that when you have complex diagram, if you don't render it with mermaid library, it becomes hard to read for humans. Something like this for example:

flowchart TD
    User["👤 User"] --> Browser["🌐 Browser"]
    Browser --> CDN["CDN\n(Static Assets)"]
    Browser --> LB["Load Balancer"]

    LB --> API1["API Server 1"]
    LB --> API2["API Server 2"]

    API1 & API2 --> Cache["Redis Cache"]
    API1 & API2 --> DB[("PostgreSQL")]
    API1 & API2 --> Queue["Message Queue\n(SQS / RabbitMQ)"]

    Queue --> Worker["Background Worker"]
    Worker --> DB

    API1 & API2 --> Auth["Auth Service\n(OAuth / JWT)"]
    API1 & API2 --> ThirdParty["Third Party APIs\n(Email, Payments)"]

You can still understand what's going on, but for a human is harder to read.

So at this point, if you are a human, you could argue against one or the other.
But that's the key: if you are human.

If you are an LLM, it's a completely different story.

But it's not just about AI

Before we even get to the AI angle, mermaid has some very practical advantages for humans too that are worth mentioning.

It lives in your codebase. Because mermaid diagrams are just text, they live right in your markdown files alongside your code. This means they go through the same version control process as everything else — you can review changes in a PR, revert them, and see exactly who changed what and when. Try doing that with a PNG exported from Lucidchart.

Diffs are meaningful. Following on from the above, when somebody updates a diagram, the diff in your PR will show exactly what changed in the flow, not just "image.png was modified". This makes code reviews a lot more useful and transparent.
No extra tooling required. With traditional diagramming tools like Figma, Draw.io or Lucidchart, you need to open a separate application, make your changes, export an image, and then commit it. With mermaid, you just edit the text directly in your markdown file. Your editor, GitHub, and most modern documentation platforms will handle the rendering for you.

It forces you to think in structure. Writing a diagram in mermaid syntax, rather than dragging boxes around a canvas, naturally encourages you to think about the relationships and flow of your system more carefully. It's a bit like the difference between writing pseudocode and drawing boxes freehand — the structured format tends to produce clearer thinking.

LLMs love mermaid

LLMs love mermaid format as it has a lot of key advantages:

Models are trained to understand mermaid format quite extensively
They are more compact and easier to follow the flow
It's more efficient in terms of tokens.

Essentially reading an ASCII diagram for an LLM is a waste of tokens, and it's harder to follow what the diagram is trying to explain, because of extra noise added by the decorative part of the diagram.
Mermaid explains how a diagram works more efficiently.

And where often LLMs have to digest massive amounts of tokens, having an efficient way to digest that information is fundamental.

Mermaid uses way less tokens

So let's compare the same diagram we showed above, and both format, and see what's the difference in tokens:

Diagram using ASCII

Diagram using mermaid

As you can see above, the difference in tokens is massive: 55 tokens for the ASCII versus 10 of the mermaid, and this is a very simple diagram.

But again, what it also matters, apart from the economy of tokens, is the fact that mermaid will be easier to understand for LLMs with way less chances to hallucinate.

Conclusion

Documentation has always been important, but in the AI era, we need to think about two audiences: humans and machines. While ASCII diagrams are universal and need no special tooling to be read, they are noisy and inefficient for LLMs to process.

Mermaid gives you the best of both worlds. It's still readable by humans, it renders beautifully on platforms like GitHub and GitLab, and most importantly, it communicates the same information to an LLM in a fraction of the tokens, with less risk of misinterpretation.

So next time you're documenting your architecture in a README.md or a CLAUDE.md file, skip the ASCII art and reach for Mermaid instead. Your teammates will appreciate it, and your AI tools will thank you for it too.

When and How to Use LRU Cache in Node.js Backend Projects

Alessio Michelini — Fri, 30 Jan 2026 14:09:36 +0000

If you've been working with Node.js for a while, you've probably encountered situations where your application makes repeated requests to fetch the same data, whether from a database, an external API, or some expensive computation. And if you're like me, you've probably thought "there must be a better way to handle this."

Well, there is, and it's called caching. But not just any caching—today we're going to talk about LRU (Least Recently Used) caching and when it makes sense to use it in your Node.js applications.

What is an LRU Cache?

Before we jump into the code, let's understand what an LRU cache actually is.

An LRU cache is a data structure that stores a limited number of items and automatically removes the least recently used items when it reaches its capacity. Think of it like a small notebook where you keep notes, but you only have space for, let's say, 100 pages. When you need to add a new note and the notebook is full, you remove the oldest note you haven't looked at in a while.

The beauty of LRU caching is that it keeps frequently accessed data readily available while automatically discarding data that hasn't been used recently, all without you having to manage it manually.

When should you use LRU Cache?

Let's be practical here. You should use LRU caching when:

1. You're making repeated expensive operations

If you're querying a database for the same data multiple times, or calling an external API that returns relatively static data, caching can save you a lot of time and resources.

For example, let's say you have an e-commerce application where product details don't change very often:

// Without caching - hits the database every time
const getProduct = async (productId) => {
  const product = await db.query('SELECT * FROM products WHERE id = ?', [productId]);
  return product;
};

If 1000 users are viewing the same product, you're making 1000 database calls for the exact same data. That's wasteful.

2. Your data doesn't change frequently

LRU cache works best with data that's relatively static or changes infrequently. Things like:

User profile information
Product catalogs
Configuration settings
API responses that update every few minutes/hours
Computed results from heavy calculations

3. You have memory to spare

Remember, caching means storing data in memory. If your application is already running tight on memory, adding a cache might not be the best idea.

4. You need to limit memory usage

Unlike simple object caching where you might accidentally cache unlimited items and run out of memory, LRU cache has a built-in size limit. When it reaches capacity, it automatically evicts the least recently used items.

When you shouldn't use LRU Cache

Just as important as knowing when to use it, is knowing when not to use it:

1. You're running multiple Node.js processes

This is probably the most important limitation to understand. LRU cache stores data in memory within a single Node.js process. If you're running multiple instances of your application (which you should be doing in production for reliability and performance), each process will have its own separate cache.

Let me explain why this is a problem with a practical example.

Let's say you have 3 Node.js processes running behind a load balancer:

// Process 1, 2, and 3 are all running this code
const userCache = new LRUCache({ max: 100, ttl: 60000 });

const getUser = async (userId) => {
  const cached = userCache.get(userId);
  if (cached) return cached;

  const user = await db.query('SELECT * FROM users WHERE id = ?', [userId]);
  userCache.set(userId, user);
  return user;
};

Now here's what happens:

User makes a request that hits Process 1 → cache miss, fetches from DB, caches it
User makes another request that hits Process 2 → cache miss again! (different process, different cache)
User makes another request that hits Process 3 → cache miss again!

So you're not really caching anything effectively across your application. You're just caching per process, which might give you some benefit, but nowhere near what you'd expect.

Even worse, if you update data in one process and invalidate the cache there, the other processes still have stale data:

// Update happens in Process 1
const updateUser = async (userId, updates) => {
  await db.query('UPDATE users SET ? WHERE id = ?', [updates, userId]);
  userCache.delete(userId); // Only clears cache in Process 1!
};
// Process 2 and 3 still have the old cached data!

This means LRU cache in Node.js is really only suitable for:

Small projects running a single Node.js process
Development environments
Simple scripts or tools that don't need to scale

For production applications that need to scale horizontally, you should use a proper distributed cache like Redis or Memcached instead.

2. Your data changes constantly

If you're caching data that updates every second, you're going to have stale data problems. For example, caching real-time stock prices or live sports scores wouldn't make much sense.

3. Your data is already fast to retrieve

If your operation takes 5 milliseconds, adding a cache might actually slow things down due to the overhead of cache management. Don't optimize what doesn't need optimizing.

4. You need guaranteed fresh data

If you're building a banking application where every transaction must reflect the absolute current state, caching might introduce dangerous inconsistencies.

5. Your data is unique per request

If every request requires different data that's never reused, caching won't help you. For example, caching user-specific data that's only accessed once doesn't make sense.

Let's see it in action

Now that we understand the theory, let's build something practical. We'll use the lru-cache package, which is the most popular LRU cache implementation for Node.js.

First, install the package:

npm install lru-cache

A simple example

Let's say we have a function that fetches user data from a database:

const { LRUCache } = require('lru-cache');
const db = require('./database'); // your database connection

// Create a cache that holds up to 500 items
// Each item expires after 5 minutes
const userCache = new LRUCache({
  max: 500,
  ttl: 1000 * 60 * 5, // 5 minutes in milliseconds
});

const getUser = async (userId) => {
  // Check if we have it in cache
  const cached = userCache.get(userId);
  if (cached) {
    console.log('Cache hit!');
    return cached;
  }

  // Not in cache, fetch from database
  console.log('Cache miss, fetching from DB...');
  const user = await db.query('SELECT * FROM users WHERE id = ?', [userId]);

  // Store in cache for future requests
  userCache.set(userId, user);

  return user;
};

// Usage
const user1 = await getUser(123); // Fetches from DB
const user2 = await getUser(123); // Returns from cache!

A more complex real-world example

Let's build a more practical example with an API that fetches weather data:

const { LRUCache } = require('lru-cache');
const axios = require('axios');

class WeatherService {
  constructor() {
    // Cache weather data for each city
    // Max 100 cities, each cached for 30 minutes
    this.cache = new LRUCache({
      max: 100,
      ttl: 1000 * 60 * 30,
      // Optional: what to do when an item is evicted
      dispose: (value, key) => {
        console.log(`Evicting weather data for ${key}`);
      }
    });
  }

  async getWeather(city) {
    // Create a cache key
    const cacheKey = city.toLowerCase();

    // Try to get from cache
    const cached = this.cache.get(cacheKey);
    if (cached) {
      return {
        ...cached,
        fromCache: true
      };
    }

    // Not in cache, fetch from API
    try {
      const response = await axios.get(
        `https://api.weatherapi.com/v1/current.json`,
        {
          params: {
            key: process.env.WEATHER_API_KEY,
            q: city
          }
        }
      );

      const weatherData = {
        city: response.data.location.name,
        temperature: response.data.current.temp_c,
        condition: response.data.current.condition.text,
        humidity: response.data.current.humidity,
        fetchedAt: new Date().toISOString()
      };

      // Store in cache
      this.cache.set(cacheKey, weatherData);

      return {
        ...weatherData,
        fromCache: false
      };
    } catch (error) {
      console.error('Error fetching weather:', error.message);
      throw new Error('Failed to fetch weather data');
    }
  }

  // Clear cache for a specific city
  clearCity(city) {
    this.cache.delete(city.toLowerCase());
  }

  // Clear entire cache
  clearAll() {
    this.cache.clear();
  }

  // Get cache statistics
  getStats() {
    return {
      size: this.cache.size,
      maxSize: this.cache.max
    };
  }
}

module.exports = WeatherService;

And here's how you'd use it in your Express application:

const express = require('express');
const WeatherService = require('./weatherService');

const app = express();
const weatherService = new WeatherService();

app.get('/weather/:city', async (req, res) => {
  try {
    const { city } = req.params;
    const weather = await weatherService.getWeather(city);
    res.json(weather);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.get('/weather/cache/stats', (req, res) => {
  res.json(weatherService.getStats());
});

app.delete('/weather/cache/:city', (req, res) => {
  const { city } = req.params;
  weatherService.clearCity(city);
  res.json({ message: `Cache cleared for ${city}` });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Now when you call /weather/london multiple times within 30 minutes, only the first request will hit the external API. The rest will be served from cache, making your application faster and reducing API costs.

Advanced features you should know about

The lru-cache package has some really useful features:

Size-based eviction

Instead of limiting by number of items, you can limit by memory size:

const cache = new LRUCache({
  max: 500,
  maxSize: 5000, // total size in arbitrary units
  sizeCalculation: (value) => {
    // Calculate size of each item
    return JSON.stringify(value).length;
  }
});

Update TTL on access

Keep frequently accessed items in cache longer:

const cache = new LRUCache({
  max: 100,
  ttl: 1000 * 60 * 5,
  updateAgeOnGet: true // Reset TTL when item is accessed
});

Custom disposal

Do cleanup when items are evicted:

const cache = new LRUCache({
  max: 100,
  dispose: (value, key, reason) => {
    // Clean up resources, log evictions, etc.
    if (reason === 'evict') {
      console.log(`${key} was evicted due to cache being full`);
    }
  }
});

Some gotchas to watch out for

1. Cache invalidation is hard

The hardest problem in computer science is knowing when to invalidate your cache. If you cache user data and the user updates their profile, you need to clear that cache entry:

const updateUser = async (userId, updates) => {
  await db.query('UPDATE users SET ? WHERE id = ?', [updates, userId]);

  // Don't forget to invalidate the cache!
  userCache.delete(userId);
};

2. Don't cache sensitive data carelessly

Be careful about caching sensitive information. If you're caching user data, make sure you're not exposing one user's data to another:

// Bad: using just productId as key
const cacheKey = productId;

// Better: include user context if permissions matter
const cacheKey = `${userId}:${productId}`;

3. Memory leaks

While LRU cache automatically manages size, you still need to be careful about what you cache. Don't cache huge objects or you'll run out of memory quickly.

Measuring the impact

You should always measure whether caching is actually helping. Here's a simple way to track hit rates:

class CachedService {
  constructor() {
    this.cache = new LRUCache({ max: 100, ttl: 60000 });
    this.stats = {
      hits: 0,
      misses: 0
    };
  }

  async getData(key) {
    const cached = this.cache.get(key);

    if (cached) {
      this.stats.hits++;
      return cached;
    }

    this.stats.misses++;
    const data = await this.fetchData(key);
    this.cache.set(key, data);
    return data;
  }

  getHitRate() {
    const total = this.stats.hits + this.stats.misses;
    if (total === 0) return 0;
    return (this.stats.hits / total * 100).toFixed(2);
  }
}

When to migrate to Redis (or another distributed cache)

Now, here's the thing: LRU cache is great for getting started, but as your application grows, you'll hit its limitations pretty quickly.

Signs you need to move to Redis

You should consider migrating to Redis when:

You're running multiple Node.js processes - This is the big one. As soon as you need to scale horizontally, in-memory caching becomes problematic.
You need cache consistency across instances - If one process updates data, all processes need to see the updated cache.
Your cache needs to survive restarts - LRU cache is ephemeral. When your process restarts, the cache is gone. Redis persists data.
You need more advanced features - Redis offers pub/sub, sorted sets, lists, and many other data structures that LRU cache doesn't have.

The migration is simpler than you think

The good news is that if you've been using LRU cache with a good abstraction layer (like the CachedService examples above), migrating to Redis is straightforward.

Here's how the same weather service would look with Redis:

const redis = require('redis');

class WeatherService {
  constructor() {
    this.redisClient = redis.createClient({
      host: process.env.REDIS_HOST || 'localhost',
      port: process.env.REDIS_PORT || 6379
    });
    this.redisClient.connect();
  }

  async getWeather(city) {
    const cacheKey = `weather:${city.toLowerCase()}`;

    // Try to get from Redis
    const cached = await this.redisClient.get(cacheKey);
    if (cached) {
      return {
        ...JSON.parse(cached),
        fromCache: true
      };
    }

    // Not in cache, fetch from API
    try {
      const response = await axios.get(
        `https://api.weatherapi.com/v1/current.json`,
        {
          params: {
            key: process.env.WEATHER_API_KEY,
            q: city
          }
        }
      );

      const weatherData = {
        city: response.data.location.name,
        temperature: response.data.current.temp_c,
        condition: response.data.current.condition.text,
        humidity: response.data.current.humidity,
        fetchedAt: new Date().toISOString()
      };

      // Store in Redis with 30 minute expiration
      await this.redisClient.setEx(
        cacheKey,
        1800, // 30 minutes in seconds
        JSON.stringify(weatherData)
      );

      return {
        ...weatherData,
        fromCache: false
      };
    } catch (error) {
      console.error('Error fetching weather:', error.message);
      throw new Error('Failed to fetch weather data');
    }
  }

  async clearCity(city) {
    await this.redisClient.del(`weather:${city.toLowerCase()}`);
  }
}

As you can see, the interface is almost identical. The main difference is that Redis operations are asynchronous (they return promises), while LRU cache operations are synchronous.

My recommendation

Start with LRU cache if:

You're building a prototype or small project
You're running a single Node.js process
You want to get something working quickly without infrastructure complexity
You're just learning about caching concepts

Move to Redis when:

You need to scale to multiple processes or servers
You need cache persistence
You need cache sharing across different services
Your project is going to production

Don't feel bad about starting with LRU cache and migrating later. It's a perfectly valid approach, and the patterns you learn with LRU cache transfer directly to Redis.

Measuring the impact

You should always measure whether caching is actually helping. Here's a simple way to track hit rates:

class CachedService {
  constructor() {
    this.cache = new LRUCache({ max: 100, ttl: 60000 });
    this.stats = {
      hits: 0,
      misses: 0
    };
  }

  async getData(key) {
    const cached = this.cache.get(key);

    if (cached) {
      this.stats.hits++;
      return cached;
    }

    this.stats.misses++;
    const data = await this.fetchData(key);
    this.cache.set(key, data);
    return data;
  }

  getHitRate() {
    const total = this.stats.hits + this.stats.misses;
    if (total === 0) return 0;
    return (this.stats.hits / total * 100).toFixed(2);
  }
}

Conclusion

LRU caching is a powerful tool that can significantly improve your application's performance when used correctly. But it's important to understand its limitations, especially around scaling.

The key takeaway: LRU cache is perfect for small projects or single Node.js processes, but becomes problematic at scale.

Here's a quick decision tree:

✅ Use it for expensive operations that return the same data repeatedly
✅ Use it for relatively static data that doesn't change often
✅ Use it when you need automatic memory management
✅ Use it for prototypes and small projects with a single process
✅ Use it to learn caching patterns before moving to Redis
❌ Don't use it for data that changes constantly
❌ Don't use it when operations are already fast
❌ Don't use it for unique, one-time data
❌ Don't use it when you have multiple Node.js processes (use Redis instead)
❌ Don't use it when you need cache consistency across instances

The reality is that most production Node.js applications run multiple processes for reliability and performance. As soon as you spin up a second instance, LRU cache loses much of its effectiveness because each process has its own isolated cache. This leads to cache misses, stale data, and inconsistent behavior.

That said, LRU cache is still valuable:

It's a great learning tool to understand caching concepts
It's perfect for CLI tools, scripts, or single-process applications
It can be useful as a secondary cache layer in front of Redis
It's excellent for local development and testing

Remember, caching is an optimization technique. As with all optimizations, measure first, optimize second. Don't add complexity to your application unless you have data showing it's actually helping.

And when you're ready to scale beyond a single process, the patterns you learned with LRU cache will transfer directly to Redis. The migration path is straightforward, and you'll be glad you started with something simple to understand the fundamentals.

Finally, always remember the two hardest things in computer science: cache invalidation and naming things. Make sure you have a clear strategy for both, especially when dealing with distributed systems!

DISCLAIMER
I used AI to help me out to write this article, mostly for grammar and to create quick samples code.

Redis Commander with Docker and Apple Silicon

Alessio Michelini — Sat, 18 Oct 2025 09:52:33 +0000

If you are here, it's probably because you either updated version of Docker Desktop or Rancher Desktop (or any application that runs Docker containers) and all the sudden a container, in my case redis-commander and you can't figure out why.
I want to be clear, that could be other exotic issues, but the majority of times, and this is not specific to Redis Commander to be fair, the reason is because that specific image was build with a different platform.

If you look at the Dockerfile in that specific project, you will see that it start with this:

FROM alpine:3.21

And if you look at what alpine is, it's just a minimal linux image, with basic support, but by default is built using the amd64 architecture.
And to be clear, there's nothing wrong about it, it's just the default CPU architecture as it's the most common.

But there's the issue if you have an Apple Silicon like me, like any M* processors from Apple.

And when you start docker with the default image like the Alpine one, it will try to run a container that was build from a different architecture than the one your computer is running. Is like to ask to a Japanese person, that doesn't speak any english, to read an english book. He knows what a book is, he knows that's something written there, but it can't understand it.

But don't worry, there's a simple solution. In docker you can just tell that, that specific image, it's written in a different architecture, so it can run it properly, using the platform flag.

So if you want to run Redis Commander with Docker (or any image that has the same issue) with Apple Silicon, you should running like this:

docker run -d \
  --name redis-commander \
  --hostname redis-commander \
  --platform linux/amd64 \
  --restart always \
  -e REDIS_HOSTS=local:redis:6379 \
  -p 8081:8081 \
  ghcr.io/joeferner/redis-commander:latest

Notice the --platform linux/amd64, that's the line that tells Docker to run it with that specific platform, and not the native one of your computer.

Template Literals: Why Indentation Matters (Especially for AI Prompts)

Alessio Michelini — Thu, 14 Aug 2025 10:18:57 +0000

I've heard this argument quite a few times recently, especially in code related to prompt engineering, and sometimes the most trivial things can stir up quite a conversation between developers.

You might see some code like this:

const myFunc = async () => {
  try {
    if (condition) {
      const prompt = `Hello world
                      This is some multiline text
                      More text
`;
    }
  } catch {
    // some stuff here
  }
}

Many developers think that's the right way to write a multiline string, as everything is indented according to the rest of the code. But there are two major issues with this approach.

This is a template literal

While at first glance the indentation might seem to make sense, when using a template literal (the string wrapped with backticks), you don't need to follow the rest of the code's indentation. That's because when that variable is rendered, it will look like this:

Hello world
              This is some multiline text
              More text

As you can see, that doesn't look correct at all — the extra spaces or tabs are taken into account and become part of the actual string content.

Instead, according to the language specifications, you should write the same code like this:

const myFunc = async () => {
  try {
    if (condition) {
      const prompt = `Hello world
This is some multiline text
More text
`;
    }
  } catch {
    // some stuff here
  }
}

Empty spaces count as tokens

Another issue with the original code, especially when dealing with AI prompts, is that extra spaces or tabs count as tokens, which then translates to higher costs.

It might seem like a small thing, but when dealing with large amounts of text, it can start to make a real difference in your AI usage costs.

You can test this yourself by using OpenAI's tokenizer tool. The same text we used above, without the extra spaces, generates 11 tokens, while the one with the extra spaces generates 14 tokens.

With extra spaces

Without extra spaces

The bottom line

When working with template literals, especially for prompt engineering, always remember that what you see in your code editor is exactly what gets sent to the AI model. Those extra spaces and tabs aren't just visual clutter — they're actual content that affects both the quality of your prompts and your costs.

Keep your template literals clean and properly formatted, and your future self (and your budget) will thank you!

Disclaimer: AI was used to reformat this article and correct errors

Secure your .env with dotenvx

Alessio Michelini — Mon, 07 Jul 2025 10:07:24 +0000

It's a fairly common practice to run a project locally and use a .env file to load environmental variables from it. As long it's for local development, that's absolutely fine, then when running the code in any live or test environments you should fallback to actual system variables, never, ever, use .env files in those cases.

But while the above is generally a standard and acceptable practice, it has a very simple issue.

Variables that represents secrets, are not so secret in your local environment, and in the era of AI coding tools, you might expose keys that could be potentially be end up in some LLM and eventually exposed to the internet if you are not careful enough.

I get it, it's a bit of an extreme example, but it could theoretically happen!

In Node.js, but also in other languages, you often use a variation of a dotenv package to load those secrets in your code, but now there's a better alternative: dotenvx!

How to install it

# As a dependency of your project
npm install @dotenvx/dotenvx --save

# globally
npm install --global @dotenvx/dotenvx

# More ways can be found at https://dotenvx.com/docs/install

Some key differences

What it differs from the other non-x package, is the fact that the latter can encrypt your secrets, using a public and private keys.

And instead of being a Node.js package exclusively, you can use it to run a large number of languages, as you can run it as follows:

dotenvx run -- <whatever>

# example
dotenvx run -- node main.js

# or Python
dotenvx run -- python3 main.py

# or Rust
dotenvx run -- cargo run

You get the gist, you can run pretty much (almost) anything with it.

Another advantage is that you don't really need to add it as a dependency in your project, unlike dotenv, you can just run it with npx to run your command and inject the environmental variables, like so:

echo "HELLO=World" > .env
echo "console.log('Hello ' + process.env.HELLO)" > index.js

node index.js
# Hello undefined

npx @dotenvx/dotenvx run -- node index.js
# Hello World

But if you prefer, you can use it as a drop-in replacement for dotenv:

// Before
import { config } from 'dotenv';

// After
import { config } from '@dotenvx/dotenvx';

config();

How to use it

One thing I want to clarify, you don't encrypt the entire .env file, you just encrypt variable by variable, and you don't need to encrypt them all, just the ones you want to keep secure.

So stuff that are not secrets, but just configuration settings, don't really need to be encrypted.

But let's set it in action to better understand how it works.

Let's create a simple .env with a few variables and normally you might have something like this:

PROJECT_NAME="Steve"
PORT=1234
SECRET_KEY="supersecret"

Now, we don't really care if PROJECT_NAME or if the PORT are left in clear, but we really want to protect that secret.

What do you need to do is the following:

npx @dotenvx/dotenvx set SECRET_KEY "supersecret" -f .env

With the above a few things happened.

`.env.keys` created

A new file .env.keys is created. This create the private key that it will be used to encrypt/decrypt our secrets. This file must be added to .gitignore.

A public key is added

On top of your .env file you will see something like this:

#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
#/ public-key encryption for .env files                    /
#/ [how it works](https://dotenvx.com/encryption)          /
#/----------------------------------------------------------/

DOTENV_PUBLIC_KEY="0246dd40acee998b5bbc850c507dfaca0a49245c4da6eb9b0c9ae4219e5d83d292"

This is the public key used in conjunction with the secret one, that dotenvx will use to decrypt the secrets when using dotenvx run -- command.

Your secret key is now encrypted

Where before you had a clear string for your secret, now you have the following:

PROJECT_NAME="Steve"
PORT="1234"
SECRET_KEY="encrypted:BMQJJ2bEACUIPad/jtRIyDi6m0yBYhlcUBFREgvBCTYuLajcCtyJ3hB0PLMnBDY4CWxHphnuCAgobqyzL+LucTV8TAukr8rIPIr8D8me4LIfQu8WHqYj5DXicDKE9U35pOHbFWDbBE3iv2JR"

As you can see, only the SECRET_KEY variable is encrypted, while the other variables are still in clear text.

Working with multiple environments

One really nice feature of dotenvx is how it handles different environments. You can have separate .env files for different environments and encrypt secrets differently for each one.

For example, you might have:

.env for local development
.env.production for production secrets
.env.staging for staging environment

# Encrypt secrets for different environments
npx @dotenvx/dotenvx set SECRET_KEY "local-secret" -f .env
npx @dotenvx/dotenvx set SECRET_KEY "prod-secret" -f .env.production
npx @dotenvx/dotenvx set SECRET_KEY "staging-secret" -f .env.staging

Then you can run your application with the appropriate environment:

# Local development
npx @dotenvx/dotenvx run -- node app.js

# Production
npx @dotenvx/dotenvx run -f .env.production -- node app.js

# Staging
npx @dotenvx/dotenvx run -f .env.staging -- node app.js

A real-world example

Let's say you're building an Express.js application that connects to a database and uses an API key. Your app.js might look like this:

// app.js
import express from 'express';
import { config } from '@dotenvx/dotenvx';

// Load environment variables
config();

const app = express();
const port = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.json({
    message: 'Hello World!',
    environment: process.env.NODE_ENV,
    // Never log secrets in real applications!
    hasDbUrl: !!process.env.DATABASE_URL,
    hasApiKey: !!process.env.API_KEY
  });
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

Your .env file would contain:

NODE_ENV="development"
PORT=3000
DATABASE_URL="encrypted:BK2Jsd9f8h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3jk2h3"
API_KEY="encrypted:AL9Kme4g7j2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1m2l1"

Important security considerations

While dotenvx is much more secure than plain .env files, there are still some best practices to follow:

Always add .env.keys to your .gitignore - This file contains your private key and should never be committed to version control.
Share the .env.keys file securely - When working in a team, you'll need to share the private key securely (through encrypted channels, password managers, or secure key management systems).
Rotate your keys regularly - Just like any other secret, consider rotating your encryption keys periodically.
Still use proper environment variables in production - Even with dotenvx, you should still use proper environment variables or secret management systems in production environments.

What about CI/CD?

In your CI/CD pipeline, you can use dotenvx by either:

Storing the private key as a secret in your CI/CD system and creating the .env.keys file at runtime
Using a dedicated .env.ci file with encrypted secrets specific to your CI environment

# In your CI/CD pipeline
echo $DOTENV_PRIVATE_KEY > .env.keys
npx @dotenvx/dotenvx run -- npm test

Conclusions

As you can see, dotenvx is a much better and more secure alternative to traditional .env files. It provides encryption for sensitive data while maintaining the simplicity of environment files, works across multiple programming languages, and offers flexible deployment options.

The fact that you can selectively encrypt only the secrets you care about, while leaving configuration values in plain text, makes it practical for real-world use.

I highly recommend you check out the project site at https://dotenvx.com/ and give it a try in your next project.

Disclaimer: AI was used to reformat this article and correct errors

Setting up DocMost with Amazon SES SMTP using Docker Compose

Alessio Michelini — Mon, 09 Jun 2025 23:03:14 +0000

If you're setting up DocMost with Docker and need to configure email functionality, you'll probably want to use a reliable SMTP service. Amazon SES (Simple Email Service) is an excellent choice for this, as it's cost-effective, reliable, and integrates well with other AWS services.

In this guide, I'll walk you through the entire process of setting up Amazon SES as your SMTP provider for DocMost running in Docker containers.

What you'll need

Before we start, make sure you have:

An AWS account with appropriate permissions
Docker and Docker Compose installed
A domain you own (for email sending verification)
Basic familiarity with AWS console

Step 1: Setting up Amazon SES

Navigate to Amazon SES

First, log into your AWS console and navigate to Amazon SES. You can find it by searching for "SES" in the services search bar, or under the "Customer Engagement" section.

Verify your email domain

Before you can send emails through SES, you need to verify your domain or email address.

In the SES console, go to Configuration → Verified identities
Click Create identity
Choose Domain if you want to send from any email address on your domain, or Email address for a specific email
Enter your domain name (e.g., example.com)
Follow the verification process by adding the required DNS records to your domain

Note: If you're just testing, you can verify a single email address instead, but for production use, verifying the entire domain is recommended.

Request production access (if needed)

By default, SES starts in "sandbox mode," which means you can only send emails to verified email addresses. For production use, you'll need to request production access:

In the SES console, go to Account dashboard
If you see "Your account is in the Amazon SES sandbox," click Request production access
Fill out the form explaining your use case
Wait for approval (usually takes 24-48 hours)

Step 2: Create SMTP credentials

Now we need to create the actual SMTP credentials that DocMost will use.

Generate SMTP credentials

In the SES console, go to Configuration → SMTP settings
Click Create SMTP credentials
Enter a username for the credentials (e.g., docmost-smtp)
Click Create user
Important: Download the credentials immediately! You won't be able to see the password again

Your SMTP credentials will look something like this:

SMTP Username: AKIAIOSFODNN7EXAMPLE
SMTP Password: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Note the SMTP endpoint

On the same SMTP settings page, you'll see the SMTP endpoint for your AWS region. It will look like:

email-smtp.us-east-1.amazonaws.com (for US East)
email-smtp.eu-west-1.amazonaws.com (for EU West)
And so on for other regions

The port will typically be 587 for STARTTLS or 465 for SSL/TLS.

Step 3: Configure your Docker Compose file

Now we need to configure DocMost to use these credentials. Here's how your docker-compose.yml should look:

version: '3.8'

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: "http://localhost:3000"
      APP_SECRET: "your-secret-key-here"
      DATABASE_URL: "postgresql://docmost:STRONG_DB_PASSWORD@db:5432/docmost"
      REDIS_URL: "redis://redis:6379"

      # Email configuration
      MAIL_DRIVER: smtp
      SMTP_HOST: email-smtp.us-east-1.amazonaws.com
      SMTP_PORT: 587
      SMTP_USERNAME: AKIAIOSFODNN7EXAMPLE
      SMTP_PASSWORD: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
      SMTP_SECURE: "true"
      MAIL_FROM_ADDRESS: hello@yourdomain.com
      MAIL_FROM_NAME: Docmost
    ports:
      - "3000:3000"
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: STRONG_DB_PASSWORD
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: unless-stopped

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

volumes:
  db_data:

Using environment variables (recommended)

Instead of hardcoding credentials in your docker-compose.yml, it's much better to use a .env file:

Create a .env file in the same directory as your docker-compose.yml:

# App configuration
APP_URL=http://localhost:3000
APP_SECRET=your-secret-key-here
DATABASE_URL=postgresql://docmost:STRONG_DB_PASSWORD@db:5432/docmost
REDIS_URL=redis://redis:6379

# Email configuration
MAIL_DRIVER=smtp
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=AKIAIOSFODNN7EXAMPLE
SMTP_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
SMTP_SECURE=true
MAIL_FROM_ADDRESS=hello@yourdomain.com
MAIL_FROM_NAME=Docmost

# Database
POSTGRES_DB=docmost
POSTGRES_USER=docmost
POSTGRES_PASSWORD=STRONG_DB_PASSWORD

Then update your docker-compose.yml to use these variables:

version: '3.8'

services:
  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: ${APP_URL}
      APP_SECRET: ${APP_SECRET}
      DATABASE_URL: ${DATABASE_URL}
      REDIS_URL: ${REDIS_URL}
      MAIL_DRIVER: ${MAIL_DRIVER}
      SMTP_HOST: ${SMTP_HOST}
      SMTP_PORT: ${SMTP_PORT}
      SMTP_USERNAME: ${SMTP_USERNAME}
      SMTP_PASSWORD: ${SMTP_PASSWORD}
      SMTP_SECURE: ${SMTP_SECURE}
      MAIL_FROM_ADDRESS: ${MAIL_FROM_ADDRESS}
      MAIL_FROM_NAME: ${MAIL_FROM_NAME}
    ports:
      - "3000:3000"
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - db_data:/var/lib/postgresql/data
    restart: unless-stopped

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

volumes:
  db_data:

Step 4: Understanding the configuration

Let me explain what each environment variable does:

MAIL_DRIVER: Set to smtp to use SMTP for sending emails
SMTP_HOST: The Amazon SES SMTP endpoint for your region
SMTP_PORT: Usually 587 for STARTTLS or 465 for SSL/TLS
SMTP_USERNAME: The SMTP username you got from SES
SMTP_PASSWORD: The SMTP password you got from SES
SMTP_SECURE: Set to true to enable TLS encryption
MAIL_FROM_ADDRESS: The email address emails will be sent from (must be verified in SES)
MAIL_FROM_NAME: The display name for outgoing emails

Step 5: Start your containers

Now you can start your DocMost instance:

docker-compose up -d

Check the logs to make sure everything started correctly:

docker-compose logs docmost

Step 6: Test email functionality

Once DocMost is running, you can test the email functionality by:

Creating a new user account (this should send a welcome email)
Using the password reset feature
Inviting other users to your workspace

If emails aren't being sent, check the DocMost logs for any SMTP-related error messages.

Troubleshooting common issues

"Username/Password incorrect" errors

Double-check that you're using the SMTP credentials (not your AWS console credentials) and that you've copied them correctly from the SES console.

"Email address not verified" errors

Make sure the email address in MAIL_FROM_ADDRESS is either:

An email address you've verified individually in SES, or
An email address on a domain you've verified in SES

Connection timeout errors

Check that:

Your SMTP_HOST matches your AWS region
Your SMTP_PORT is correct (587 or 465)
Your network allows outbound connections on the SMTP port

Still in sandbox mode

If you're trying to send emails to unverified addresses and getting bounces, you might still be in SES sandbox mode. Either verify the recipient email addresses or request production access.

Security considerations

A few important security notes:

Never commit credentials to version control: Always use .env files and add them to your .gitignore
Use IAM roles when possible: If you're running on EC2, consider using IAM roles instead of SMTP credentials
Rotate credentials regularly: SES SMTP passwords don't expire, but it's good practice to rotate them periodically
Monitor your usage: Keep an eye on your SES usage and set up billing alerts

Conclusion

Setting up DocMost with Amazon SES provides you with a reliable, scalable email solution. The SMTP configuration is straightforward once you have your SES credentials, and using Docker Compose with environment variables keeps your setup clean and secure.

The main thing to remember is that SES requires domain or email verification before you can send emails, and you'll need to request production access if you want to send to unverified email addresses.

Once everything is configured, DocMost will be able to send welcome emails, password reset emails, and notifications to keep your team informed and engaged with your documentation platform.

Disclaimer: AI was used to reformat this article and correct errors

Understanding MCP Servers Across Different Platforms: Claude Desktop vs VS Code vs Cursor

Alessio Michelini — Mon, 28 Apr 2025 14:15:57 +0000

When working with AI assistants like Claude, you may need to set up Model Context Protocol (MCP) servers to extend the capabilities of your AI tools. However, the configuration can vary significantly between different platforms. In this article, I'll break down how to configure MCP servers across Claude Desktop, VS Code, and Cursor, highlighting the key differences and providing practical examples.

What Are MCP Servers?

Model Context Protocol (MCP) servers allow AI assistants to interact with external systems and tools. They act as intermediaries that enable AI models to access data, execute code, or perform actions outside their default capabilities.

Configuration Differences Between Platforms

While Claude Desktop, Cursor, and VS Code all support MCP servers, the syntax and capabilities differ between them.

VS Code Configuration

In VS Code, MCP servers need to be configured with this specific format:

{
  "mcp": {
    "servers": {
      // Your servers configuration goes here
    }
  }
}

Claude Desktop and Cursor Configuration

For Claude Desktop and Cursor, the format is slightly different:

{
  "mcpServers": {
    // Your servers configuration goes here
  }
}

Remote Servers: Platform Limitations

One important distinction is how different platforms handle remote servers. While Cursor supports remote servers through SSE (Server-Sent Events), Claude Desktop has limitations.

For example, this configuration works in Cursor but not in Claude Desktop:

{
  "mcpServers": {
    "photos": {
      "transport": "sse",
      "url": "http://localhost:3001/sse",
      "env": {
        "TRANSPORT": "sse"
      }
    }
  }
}

Solutions for Claude Desktop

If you're using Claude Desktop, you have several alternatives to work around these limitations:

1. Local Command Execution via stdio

The most straightforward way to get MCP servers working in Claude Desktop is to execute them locally using stdio:

{
  "mcpServers": {
    "photos": {
      "command": "node",
      "args": [
        "/path/to/your/server.js"
      ]
    }
  }
}

2. Using NPM Packages

Another option is to create and publish an NPM package, then invoke it with npx:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR-TOKEN>"
      }
    }
  }
}

3. Docker Containers

For more complex setups, you can use Docker containers (requires Docker to be installed):

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR-TOKEN>"
      }
    }
  }
}

Best Practices

Based on the available options, here are some recommendations:

For cross-platform compatibility: If you need your configuration to work across all platforms, stick with the local command execution approach.
For simplicity: Using published NPM packages with npx offers a clean solution if you don't want to manage local server files.
For isolation and dependencies: Docker containers provide the best isolation and dependency management but require Docker to be installed.

Conclusion

Understanding the differences in MCP server configurations across platforms is crucial for effectively extending your AI assistants' capabilities. While Claude Desktop has some limitations regarding remote servers, multiple workarounds are available through local execution, NPM packages, or Docker containers.

By selecting the right approach for your specific needs, you can ensure your MCP servers work consistently across Claude Desktop, VS Code, and Cursor, enhancing your AI-assisted development workflow.

Disclaimer: AI was used to reformat this article and correct errors

Single Quotes vs Double Quotes in YAML: How They Differ From JavaScript and TypeScript

Alessio Michelini — Thu, 03 Apr 2025 10:37:07 +0000

Note: AI was used to help me out to clean up the article

When working with YAML files for configuration, one of the most common sources of confusion is understanding how string quoting works. If you're coming from JavaScript or TypeScript, you might assume quotes work the same way, but there are some important differences that can trip you up. Let's look at how string quoting differs between these languages and how to avoid common pitfalls.

String Quoting in YAML

In YAML, both single quotes (') and double quotes (") can be used to define strings, but they behave differently:

Double Quotes in YAML

Double-quoted strings in YAML support escape sequences, which means you can use special characters like:

message: "Hello\nWorld"  # Includes a line break
path: "C:\\Program Files\\App"  # Escapes backslashes
special: "Quote \"inside\" a string"  # Escapes quotes

Single Quotes in YAML

Single-quoted strings treat characters literally, with the only exception being that you can escape a single quote by doubling it:

message: 'Hello\nWorld'  # \n appears literally as "\n", not a line break
path: 'C:\Program Files\App'  # Backslashes are preserved as-is
special: 'Quote ''inside'' a string'  # Escape single quotes by doubling them

How This Differs From JavaScript/TypeScript

In JavaScript and TypeScript, both single and double quotes behave almost identically:

const doubleQuoted = "Hello\nWorld";  // Contains a line break
const singleQuoted = 'Hello\nWorld';  // Also contains a line break!

// Both allow escape sequences
const doubleBackslash = "C:\\Program Files\\App";
const singleBackslash = 'C:\\Program Files\\App';

// But you need to escape the quote you're using
const doubleQuoteEscape = "Quote \"inside\" a string";
const singleQuoteEscape = 'Quote \'inside\' a string';

The key difference is that in JavaScript/TypeScript, both quote types support the same escape sequences while in YAML, only double quotes do!

Common Gotchas

This difference often causes issues when:

Working with paths: Windows file paths with backslashes can cause problems

   # Wrong - in double quotes you need to escape backslashes
   windows_path: "C:\Program Files\My App"  # Will be interpreted as "C:Program FilesMy App"

   # Correct approaches
   windows_path1: "C:\\Program Files\\My App"  # Double each backslash
   windows_path2: 'C:\Program Files\My App'    # Use single quotes (safer for paths)
   windows_path3: C:\Program Files\My App      # Unquoted (works for simple paths)

Multiline strings: Newlines are treated differently

   # In double quotes, \n creates an actual line break
   description: "First line\nSecond line"

   # In single quotes, \n is just the characters \ and n
   description: 'First line\nSecond line'  # Will be "First line\nSecond line"

Special characters: Some YAML values need quotes to avoid being interpreted as other types

   # Without quotes, these might be parsed as boolean or numeric values
   value1: "yes"   # String "yes" (not boolean true)
   value2: "no"    # String "no" (not boolean false)
   value3: "1.0"   # String "1.0" (not float 1.0)

Practical Recommendations

Based on these differences, here are some practical tips:

Use single quotes for paths (especially Windows paths) to avoid escaping backslashes
Use double quotes when you need escape sequences like \n, \t, etc.
When in doubt, quote your strings to prevent YAML from interpreting them as non-string values
Be consistent within your project - pick a quoting style and stick with it

In Summary

Unlike JavaScript and TypeScript, where single and double quotes work almost identically, YAML treats them quite differently:

Feature	YAML Single Quotes	YAML Double Quotes	JS/TS Single Quotes	JS/TS Double Quotes
Escape sequences	No (literal)	Yes	Yes	Yes
Escaping quotes	Double it (`''`)	Backslash (`\"`)	Backslash (`\'`)	Backslash (`\"`)
Multiline support	Yes (special syntax)	Yes (with `\n`)	Yes (with `\n`)	Yes (with `\n`)

Understanding these differences is crucial when working with applications that use both JavaScript/TypeScript code and YAML configuration files, such as Kubernetes, Docker Compose, or GitHub Actions workflows.

Happy coding!

Using Object Literals Instead of Switch Statements in JavaScript

Alessio Michelini — Thu, 13 Mar 2025 13:29:01 +0000

Disclaimer
AI was used to create parts of this article and create some of the examples

When writing JavaScript, there are often multiple ways to solve the same problem. One common scenario is implementing conditional logic based on different values. The classic approach is to use a switch statement, but there's a more elegant solution using object literals that I've found to be cleaner and more maintainable in many situations.

The classic switch statement

First, let's remind ourselves how a typical switch statement looks:

const getAnimalSound = animal => {
  switch (animal) {
    case 'dog':
      return 'woof';
    case 'cat':
      return 'meow';
    case 'cow':
      return 'moo';
    case 'fox':
      return 'what does the fox say?';
    default:
      return 'unknown sound';
  }
};

console.log(getAnimalSound('dog')); // 'woof'
console.log(getAnimalSound('fox')); // 'what does the fox say?'
console.log(getAnimalSound('tiger')); // 'unknown sound'

While this works fine, it's quite verbose and requires a lot of case statements, break statements (though we've avoided them here by using return), and it's not very DRY (Don't Repeat Yourself).

Enter object literals

Let's refactor the above function using an object literal:

const getAnimalSound = animal => {
  const sounds = {
    dog: 'woof',
    cat: 'meow',
    cow: 'moo',
    fox: 'what does the fox say?',
    default: 'unknown sound'
  };

  return sounds[animal] || sounds.default;
};

console.log(getAnimalSound('dog')); // 'woof'
console.log(getAnimalSound('fox')); // 'what does the fox say?'
console.log(getAnimalSound('tiger')); // 'unknown sound'

The result is the same, but look at how much cleaner and more concise the code is! We've defined an object where each key is a potential value of our animal parameter, and each value is the corresponding sound.

We then use the parameter to access the corresponding property in our object. The || operator provides a fallback if the property doesn't exist (just like our default case in the switch).

Taking it further with functions

Object literals really shine when you need to do more than just return a simple value. Let's say we have a more complex example where we need to perform different operations based on a command:

const executeCommand = command => {
  switch (command) {
    case 'greet':
      console.log('Hello there!');
      break;
    case 'farewell':
      console.log('Goodbye!');
      break;
    case 'time':
      console.log(`Current time: ${new Date().toLocaleTimeString()}`);
      break;
    default:
      console.log('Unknown command');
  }
};

executeCommand('greet'); // 'Hello there!'
executeCommand('time'); // 'Current time: 12:34:56'

We can refactor this using an object literal with functions as values:

const executeCommand = command => {
  const commands = {
    greet: () => console.log('Hello there!'),
    farewell: () => console.log('Goodbye!'),
    time: () => console.log(`Current time: ${new Date().toLocaleTimeString()}`),
    default: () => console.log('Unknown command')
  };

  // Execute the command if it exists, otherwise execute the default command
  (commands[command] || commands.default)();
};

executeCommand('greet'); // 'Hello there!'
executeCommand('time'); // 'Current time: 12:34:56'

Again, we've reduced verbosity and made the code more maintainable. Each command is clearly associated with its implementation, and there's no need for break statements.

More complex examples

You can also handle more complex cases, where you might need to access the context or pass parameters to the functions:

const calculator = (a, b, operation) => {
  const operations = {
    add: (x, y) => x + y,
    subtract: (x, y) => x - y,
    multiply: (x, y) => x * y,
    divide: (x, y) => y !== 0 ? x / y : 'Cannot divide by zero',
    default: () => 'Unknown operation'
  };

  return (operations[operation] || operations.default)(a, b);
};

console.log(calculator(5, 3, 'add')); // 8
console.log(calculator(5, 3, 'multiply')); // 15
console.log(calculator(5, 0, 'divide')); // 'Cannot divide by zero'
console.log(calculator(5, 3, 'power')); // 'Unknown operation'

In this case, we're passing the a and b parameters to whichever operation function is selected.

When to use object literals vs switch

While object literals offer a cleaner syntax in many cases, there are situations where a switch statement might still be preferable:

When your case conditions aren't simple matches (e.g., they involve ranges or complex expressions)
When you need to "fall through" multiple cases intentionally
When your cases need access to variables in the surrounding scope

But for simple mapping between inputs and outputs or actions, object literals often provide a more elegant solution.

A practical real-world example

Let's say you're building a simple state machine for a UI component, where you need to handle different actions based on the current state:

const handleStateTransition = (currentState, action) => {
  const stateTransitions = {
    idle: {
      start: 'loading',
      reset: 'idle'
    },
    loading: {
      success: 'loaded',
      error: 'error',
      cancel: 'idle'
    },
    loaded: {
      refresh: 'loading',
      clear: 'idle'
    },
    error: {
      retry: 'loading',
      clear: 'idle'
    }
  };

  return stateTransitions[currentState]?.[action] || currentState;
};

let state = 'idle';
state = handleStateTransition(state, 'start'); // 'loading'
state = handleStateTransition(state, 'success'); // 'loaded'
state = handleStateTransition(state, 'clear'); // 'idle'
state = handleStateTransition(state, 'invalidAction'); // 'idle' (unchanged)

This implementation is much cleaner than a massive switch statement with nested conditions, and it makes the state machine's logic very clear and easy to modify.

Conclusions

Object literals provide a powerful alternative to switch statements in JavaScript, offering several advantages:

More concise and readable code
Better performance in many cases (browsers can optimize object lookups)
Easier to maintain and extend
No need for break statements or worrying about fall-through behavior

Next time you find yourself reaching for a switch statement, consider whether an object literal might make your code cleaner and more maintainable. It's a simple but effective technique that I use frequently in my JavaScript projects.

I hope this helps you write cleaner and more elegant code!

DEV Community: Alessio Michelini

You should stop using high effort for everything in Claude Code

What is effort anyway?

The problem with "max effort all the time"

My workflow: plan high, execute lower

Step 1: Plan with high effort

Step 2: Write everything down

Step 3: Execute one step at a time, with low or medium effort

Step 4: Review, then verify with high effort

Is this just my opinion?

When you should crank up the effort

Conclusions

You should use Map instead of object literals for lookup tables

A quick recap

So what's the problem?

It gets worse with functions

And with nested objects

Enter Map

Dispatching functions

The state machine

A bonus with TypeScript

When you don't need a Map

Conclusions

Disclaimer

Stop writing raw SQL in your migrations (most of the time)

First, what does "raw" even look like?

Reason 1: you lose portability

Reason 2: your down migrations get fragile

Reason 3: you skip the safety net

Reason 4: readability and consistency

So when should you use raw SQL?

A quick reality check

Conclusions

Why Mermaid is the Best Way to Document Your Architecture in the AI Era

Enter Mermaid.js

But it's not just about AI

LLMs love mermaid

Mermaid uses way less tokens

Conclusion

When and How to Use LRU Cache in Node.js Backend Projects

What is an LRU Cache?

When should you use LRU Cache?

1. You're making repeated expensive operations

2. Your data doesn't change frequently

3. You have memory to spare

4. You need to limit memory usage

When you shouldn't use LRU Cache

1. You're running multiple Node.js processes

2. Your data changes constantly

3. Your data is already fast to retrieve

4. You need guaranteed fresh data

5. Your data is unique per request

Let's see it in action

A simple example

A more complex real-world example

Advanced features you should know about

Size-based eviction

Update TTL on access

Custom disposal

Some gotchas to watch out for

1. Cache invalidation is hard

2. Don't cache sensitive data carelessly

3. Memory leaks

Measuring the impact

When to migrate to Redis (or another distributed cache)

Signs you need to move to Redis

The migration is simpler than you think

My recommendation

Measuring the impact

Conclusion

Redis Commander with Docker and Apple Silicon

Template Literals: Why Indentation Matters (Especially for AI Prompts)

This is a template literal

Empty spaces count as tokens

The bottom line

Secure your .env with dotenvx

How to install it

Some key differences

How to use it

.env.keys created

Enter `Map`

When you don't need a `Map`

Reason 2: your `down` migrations get fragile

`.env.keys` created