If you're building web apps with Blazor, you've probably wished for something like Storybook, a UI component catalog for browsing and developing components in isolation. The problem is, Storybook doesn't support Blazor. So I built one from scratch.
I'm the developer of "Blazing Story" (Mozilla Public License 2.0), a Storybook clone reimplemented entirely in Blazor. I first released it in March 2023, presented it at local conference events, but never wrote about it as a technical article until now. This is the story of how and why I built it.
🔍 What Is Storybook?
For component-based front-end frameworks like Angular, React, Vue, and Svelte, there's an open source library called "Storybook" (MIT License).
Storybook: Frontend workshop for UI development
Storybook is a frontend workshop for building UI components and pages in isolation. Thousands of teams use it for UI development, testing, and documentation. It's open source and free.
storybook.js.org
Storybook provides what's commonly called a "UI component catalog," which is a web UI that works alongside your existing front-end project.
For each component, you write a small JavaScript (TypeScript) file called a "story" that describes how the component should be rendered. Storybook then displays all those stories together in its web UI.
In the Storybook UI, you can see how to use each component, inspect its markup, and explore what parameters it accepts, all without touching the main application. You can change parameters on the fly and immediately see how the component looks. This makes it easy for everyone on the team to share knowledge about which components are available and how to use them, helping the whole team move faster.
Storybook also works as a development workbench for individual components. Instead of developing inside a full application, you can focus on a single component in isolation. This makes it an excellent platform for end-to-end testing per component, and a natural target for screenshot-based visual regression testing (VRT). In fact, Chromatic (the company behind Storybook) offers a SaaS product that lets you deploy your Storybook project for team collaboration and automated visual regression tests on every deployment.
As you can see, Storybook has become an essential part of modern component-based front-end development.
⚡ What Is Blazor?
"Blazor" is an open source framework by Microsoft for building various web applications, including SPAs, using C#.
Blazor supports several hosting models. Blazor WebAssembly, for example, compiles your C# code to MSIL binary and runs it directly in the browser using a CLR reimplemented on top of WebAssembly. In other words, .NET assemblies (.dll files) run right inside your browser. That's how Blazor WebAssembly delivers single-page applications.
Like other modern frameworks, Blazor is component-based. You write components in .razor files, mixing HTML with C# code. Think of it as the C# equivalent of JSX (or TSX).
In a real-world Blazor application, you may occasionally need to call JavaScript code, but for the most part everything is implemented in C#. And since Blazor doesn't transpile C# to JavaScript but instead uses .NET assemblies at the binary level, the development ecosystem is exactly the same as any other .NET project. You don't need to know anything about JavaScript bundlers. Blazor lets you build rich, interactive web applications entirely in C#.
😔 The Problem: No Storybook for Blazor
Since Blazor is a component-based framework, it's natural to want the same kind of UI component catalog that Storybook provides.
Storybook Doesn't Support Blazor
Unfortunately, Storybook doesn't support Blazor, and it's easy to understand why.
Blazor brings a full .NET runtime into the browser, which is a completely different world from what Storybook expects. A Blazor build outputs .NET assembly files containing MSIL binary code. Storybook, on the other hand, expects importable JavaScript modules. The two simply can't work together.
There's a Workaround, But...
Blazor does allow you to instantiate a component from the JavaScript side and mount it to a DOM element. You can even wrap it as a Web Components custom element for use in other JS frameworks. So technically, it might be possible to use Blazor components inside Storybook.
But would Blazor developers actually want that?
You chose Blazor specifically to build web apps in C#. Having to learn the JavaScript ecosystem just to use Storybook, and worse, having to write stories in JavaScript or TypeScript, defeats a big part of the purpose. It's a significant burden.
So what else can we do?
💡 What If We Reimplemented Storybook in Blazor?
That's the conclusion I eventually reached.
Introducing Blazing Story
So I went ahead and did it. I started in December 2022, and about three months later, in March 2023, I released the first version: "Blazing Story".
Overview | Blazing Story
The clone of "Storybook" for Blazor, a frontend workshop for building UI components and pages in isolation.
blazingstory.github.io
With Blazing Story, you get a full UI component catalog experience for Blazor development, just like Storybook.
A live demo is available on GitHub Pages. Feel free to open it and see it in action:
https://jsakamoto.github.io/BlazingStory/?path=/custom/configure-your-project
The Goal: Match Storybook Pixel by Pixel
Blazing Story is designed to look exactly like Storybook visually. The key thing is: I basically didn't look at Storybook's source code. I did reuse Storybook's icon images (SVG), which are available under the MIT License, but everything else I built by comparing pixels in the browser by eye, writing my own DOM structure and CSS to match.
As a result, Blazing Story's screen looks nearly identical to Storybook's at the pixel level, but the underlying DOM structure is completely different. I used color picker tools and browser dev tools to match colors and fonts, and URL routing follows Storybook's specification.
The way you write stories is inspired by Storybook, but it's its own format, with stories written in .razor files.
⚠️ Limitations of a Personal Project
Blazing Story is a personal project, so it naturally has far more limitations than the original Storybook.
Development capacity is the biggest difference. I develop it alone, in the gaps between work and daily life. Even three years after the initial release, many features remain unimplemented, and there are likely bugs that haven't been reported yet. There's also the natural question of what happens if I lose motivation.
Blazing Story also can't use Storybook's plugin ecosystem, which makes sense since it runs on the .NET runtime rather than JavaScript. And the SaaS services Chromatic offers for Storybook are not available either.
Does Blazing Story Still Have a Reason to Exist?
Given all those limitations, you might wonder whether Blazing Story is worth using.
I believe it is.
For one thing, it's a UI component catalog you can use right now in your Blazor development, without waiting for Storybook to add Blazor support (which, realistically, may never happen).
I also think Blazing Story is a compelling showcase for what Blazor can do. It proves that you can build a Storybook equivalent, a sophisticated developer tooling application, entirely in Blazor. On performance: yes, Blazor WebAssembly has the well-known drawback of a slow initial load. But as you can see in the live demo, it's not slow enough to hurt practical usability. And the fact that a single developer was able to reach a first release of something like Storybook in just three months speaks to Blazor's development productivity.
📝 Summary
In modern front-end development, Storybook has become a go-to tool for component-driven development, knowledge sharing, and testing. But Blazor, the framework that lets you build web apps in C#, can't use it.
So I developed and released "Blazing Story" as an open source project: a UI component catalog for Blazor that reimplements Storybook 100% in Blazor. You can start using it in your Blazor project today.
Being a personal project, there are real concerns about missing features and long-term sustainability. Even so, I believe it has a clear reason to exist, both as a practical solution available today and as proof that Blazor is capable of building applications at this level.
If Blazing Story can be even a little helpful in your Blazor development, nothing would make me happier as its author. ❤️
Top comments (0)