DEV Community

Bishwas Bhandari
Bishwas Bhandari

Posted on

I rewrote Mermaid integration for Svelte 5 - Turns out everyone's been doing it wrong

#webdev #javascript #programming #svelte

Two weeks ago I was building docs for a client project and needed some flowcharts. Simple, right? Wrong.

Spent 3 hours fighting with existing Mermaid solutions. Configs breaking, themes not switching properly, SSR throwing fits. At one point I actually considered just drawing the diagrams in Figma and embedding images like some kind of barbarian.

That's when it hit me - we've all been treating Mermaid like it's 2019. Import a library, fight with initialization, pray it works with your build system. But this is Svelte 5. We have runes now. Why are we still coding like peasants?

So I built @friendofsvelte/mermaid - the way diagrams should work in 2025.

<script>
  import { Mermaid } from '@friendofsvelte/mermaid';

  const architecture = `graph TD
    A[Old way: Fight configs] --> B[Waste 3 hours]
    B --> C[Settle for broken solution]

    D[New way: Just works] --> E[Ship features]
    E --> F[Happy developers]`;
</script>

<Mermaid string={architecture} />
Enter fullscreen mode Exit fullscreen mode

Here's what I learned building this

Everyone's overthinking Mermaid integration. The existing solutions try to handle every possible edge case, every framework, every version. Result? Bloated APIs that feel foreign in Svelte.

Runes changed everything. The internal state management is so clean now. What used to take 50 lines of reactive statements is now 5 lines of $state and $derived.

Theming was the real pain point. Most solutions make you fight CSS variables or override styles. This component just accepts a theme prop and handles the rest.

What this actually does

  • Themes that switch instantly - Dark mode, custom colors, no flicker
  • Proper TypeScript - Full type safety, intelligent completion
  • All diagram types - Flowcharts, sequence, Gantt, user journeys, the works
  • Error handling that helps - Actually tells you what's wrong with your diagram syntax
  • Responsive by default - Works on phones without you thinking about it

The controversial part

Most Mermaid integrations are solving the wrong problem. They focus on compatibility and features instead of developer experience. But here's the thing - if your diagram component feels like work to use, you're less likely to document things properly.

Good documentation tools should disappear. You should think about your content, not your tooling.

Real talk: Why this matters

I've seen too many projects with terrible docs because the diagram tooling was a nightmare. Teams skip flowcharts, avoid sequence diagrams, and end up with docs that nobody understands.

When adding diagrams is as easy as writing markdown, teams actually document things. And that makes better software.

Try it yourself

Site: https://mermaid-cjv.pages.dev/
Install: npm install @friendofsvelte/mermaid

Svelte 5 only - because backward compatibility is the enemy of progress.

What I'm building next

This is part of a bigger documentation toolkit I'm working on. Thinking about components for API docs, interactive code examples, maybe even live demo embedding.

The goal? Make documentation so smooth that teams actually want to write it.

What kind of diagrams are you adding to your projects? Anyone else frustrated with how complicated this stuff has become?

Top comments (0)