Forem: Alessio Michelini

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!

Some practical examples on why I prefer Axios over Fetch

Alessio Michelini — Tue, 06 Feb 2024 13:54:37 +0000

I want to be clear from the very start, this is not a post of why "you should always avoid fetch", as for what you do and you know the limitations and how to get around it, and you are happy with that, that's totally ok for me.

But, I often see comments across our team where people ask why we use axios, a library to fetch data from a resource, then using the native fetch library.
And to be fair is a totally valid question in my opinion.

We could argue on the advantages on using one instead of the other and vice-versa, like you don't need any dependencies for fetch (unless you need to support old browsers and use a polyfill) or the other can give you a better degree of tuning, but I'm a practical person and I prefer to show practical examples, and let the code explain why I prefer X over Y.

Let's have this simple case, where you have to fetch some data from an API, and I want to check if the request is successful or not.
Normally I prefer to wrap calls like this into a try..catch statement, so I can catch the error if the request fails:

const axios = require('axios');

const TEST_ENDPOINT = 'https://somedomain.com/api/someendpoint';

(async () => {
  try {
    await fetch(TEST_ENDPOINT);
    console.log('using fetch: all good');
  } catch (error) {
    console.error('using fetch: error');
  }
})();

(async () => {
  try {
    await axios.get(TEST_ENDPOINT);
    console.log('using axios: all good');
  } catch (error) {
    console.error('using axios: error');
  }
})();

My expectation would be that they both act the same, if the request is successful, I'll se the all good message, but if the API returns anything else than a 200 OK status header, it should throw an error.

But if you run the code above, this will happen:

using fetch: all good
using axios: error

Why with fetch I get the all good message?

That's because fetch doesn't throw any error if the request fails, it will just rely on the code to handle that by looking at the response from the request, using either the status or ok properties,
while with axios if a request fails, it will throw an error immediately.
So to make your fetch request works properly, you will need to add some extra code:

(async () => {
  try {
    const result = await fetch(TEST_ENDPOINT);
    if (!result.ok) {
      throw new Error('Not found');
    }
    console.log('using fetch: all good');
  } catch (error) {
    console.error('using fetch: error');
  }
})();

Again, if you are ok to add this extra check, I'm totally ok to use fetch.

Now, let's say that we are expecting the response to be a JSON object, and we want to use that in our code.
With axios, you just need to fetch the data property from the axios response, and it's already a JSON object, no need to do any transformation or call any functions, it's ready to go.

With fetch you have to get the response from the request, and use the json() function to transform the raw data into a JSON object.
When you add with the previous error checking, to do the same exact job, you will have your code that will look like this:

// Fetch
const response = await fetch(TEST_ENDPOINT);
if (response.status !== 200) {
  throw new Error('Not found');
}
const data = await response.json();

// Axios one liner
const { data } = await axios.get(TEST_ENDPOINT);

The code above does the same exact thing, but with axios is one line of code, while with fetch is 5.
And when you build large applications, it can become tedious to keep adding the same controls, unless you create your own wrap function, which again is more code that you have to maintain.

Is this a deal breaker for you? Maybe not, maybe you do just an handful of requests in your application, and that's totally fine to use fetch, especially if you don't want to have more dependencies.

What about doing requests that don't use the GET method?

Let's say I want to send some data to an API?
With fetch you will have something like this:

const yourPostData = {
  name: 'Alessio',
  age: 25,
};

const response = await fetch('https://example.com/profile', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(yourPostData),
});

const result = await response.json();

So you have to pass an object, telling fetch to use the POST method, transform the data into a string, and pass the headers to tell it to encode it as application/json.
Then to read the response we'll need to transform the data back to JSON.

The same above with axios is again, excluding the input data, a one liner code:

const yourPostData = {
  name: 'Alessio',
  age: 25,
};

const { data } = await axios.post('https://example.com/profile', yourPostData);

Personally I prefer to have brevity of code, at the expense of a small dependency. Again, it's more than that, these are just two simple examples to explain my point in the argument, and if you are ok to write more verbose code, or create your own wrapper, that's totally ok.

How to fix huggingface ssh authentication error with git

Alessio Michelini — Thu, 25 Jan 2024 16:21:05 +0000

So I recently started to use huggingface.co to store and retrieve models for our AI project at work, and as it essentially works like any other git repositories, I wanted to clone a model I needed to use, and used the SSH protocol to do so, as I really don't want to enter credentials every time, and it's also a bit more secure overall.
So I added my public SSH Key in the account settings, and went my to clone the repo, expecting to work straight away.

But it didn't.

What I was getting was the following error:

git clone git@hf.co:your-org/your-model
Cloning into 'your-model'...
remote: 
remote: ========================================================================
remote: 
remote: ERROR: This action requires authentication.
Make sure your SSH public key is linked with your profile on huggingface.co.
See https://huggingface.co/settings/keys.

remote: 
remote: ========================================================================
remote: 
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

I took me a while to figure it out, I added and remove the same key from the account, checked the permissions (but the key was working fine for Github, so clearly that wasn't the issue, but always better to check anyway).

I tried to follow the steps in this page, and again, everything seemed in order, until I run this command they listed at the end:

ssh -T git@hf.co

# Hi anonymous, welcome to Hugging Face.

And instead of getting the username from the welcome message, as I do from github.com, it was returning an anonimous user.
So I quickly checked if the SSH agent was actually using the key I use for other sites, by running the following command:

ssh-add -l

The above will list all the keys you have in the SSH Agent, and in my case I had other keys, but not the one I was using!

To fix that all you need to do is to run the following command:

ssh-add ~/.ssh/your-key

# Or if you want to use the default id_* key, just do
ssh-add

Ran again the commands above, and finally I could see that my key was used, and I could finally clone the repo!

Always abstract nested types in TypeScript

Alessio Michelini — Thu, 16 Nov 2023 14:28:26 +0000

I've seen this happening multiple times in TypeScript, where you have a complex object, and this object might have nested objects, something like this for example:

interface ComplexObject {
  a: string;
  b: number;
  c: boolean;
  nested: {
    a: string;
    b: number;
    c: boolean;
  }
}

const myObj: ComplexObject = {
  a: 'a',
  b: 1,
  c: true,
  nested: {
    a: 'a',
    b: 1,
    c: true,
  },
};

And while TypeScript will be just fine with this, and no errors will be thrown, because after all that's a valid code to write, the bigger the object will become, the more hard to read the interface will be as a consequence.

Now let's say that we want to have a function that take that object as input, maybe does some interpolation, and perhaps it returns a child of that object, like the nested property for example, and you will have some code like this:

const printObj = (obj: ComplexObject) => {
  // do some stuff
  return obj.nested;
};

Now if you try to inspect with IntelliSense what's the output of that function, you will see something like this:

const printObj: (obj: ComplexObject) => {
    a: string;
    b: number;
    c: boolean;
}

Which is again, correct, but if you start to have a lot of properties, it becomes fairly hard to read.

A better way to handle complex objects like the above, is to abstract all the nested properties into their own interfaces/types.
For example, a way to rewrite the above is to split the code in the following interfaces:

interface ComplexObjectNested {
  a: string;
  b: number;
  c: boolean;
}

interface ComplexObject {
  a: string;
  b: number;
  c: boolean;
  nested: ComplexObjectNested
}

This will help to split the types/interfaces in more logically understandable blocks instead of having a massive one that can become hard to read.
And now if you inspect again the same function with IntelliSense, you will also get a much more readable output:

const printObj: (obj: ComplexObject) => ComplexObjectNested

And you have the added advantage that you can also use the nested interface for other purposes, let's say you want to use it for another function:

const getAFromNested = (nested: ComplexObjectNested) => nested.a;

// And intellisense will interpret this as 
const getAFromNested: (nested: ComplexObjectNested) => string

Forem: Alessio Michelini

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

A public key is added

Your secret key is now encrypted

Working with multiple environments

A real-world example

Important security considerations

What about CI/CD?

Conclusions

Setting up DocMost with Amazon SES SMTP using Docker Compose

What you'll need

Step 1: Setting up Amazon SES

Navigate to Amazon SES

Verify your email domain

Request production access (if needed)

Step 2: Create SMTP credentials

Generate SMTP credentials

Note the SMTP endpoint

Step 3: Configure your Docker Compose file

Using environment variables (recommended)

Step 4: Understanding the configuration

Step 5: Start your containers

Step 6: Test email functionality

Troubleshooting common issues

"Username/Password incorrect" errors

"Email address not verified" errors

Connection timeout errors

Still in sandbox mode

Security considerations

Conclusion

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

What Are MCP Servers?

Configuration Differences Between Platforms

VS Code Configuration

`.env.keys` created