BlazingStory: A Blazor Component Development Game Changer

I was recently introduced to BlazingStory, an open-source project, by jsakamoto. BlazingStory is a Blazor-focused counterpart to StoryBook a javascript frontend tool for building UI components, in isolation.

5 min readSep 5, 2023

The primary goal of this blog post is to share my learnings of BlazingStory while explore its various features.

Explore the Possibilities

Before diving into the details, take a look the creator’s, jsakamotos, demo which showcases examples of a buttons and ratings component.

Below is an example of a component that makes use of a variety of controls that Blazing Story offers:

Here is my repo with the components featured in this blog. End-to-end testing using Playwright within this repo is covered in another blog.

Getting Started

The BlazingStory repo provides a very comprehensive README. To get started, we need to :

Install the BlazingStory template by running the following command

dotnet new install BlazingStory.ProjectTemplates

2. Create a new project using the Blazing Story template.

Add a CSS / JS script files

We can include script or link tags in the wwwroot > iframe.html file (not the index.html file) to enhance our project with additional functionality. I implemented Bootstrap.

Add a Story

To showcase a component within a BlazingStory project, we must create a corresponding Story for it. This is where we can define the controls and various variations of the component.

In this example, I will create a story for a pre-existing PlaceHolder component. The component provides a ghost screen to show what the actual screen will look like once the data is loaded.

Add a PlaceHolder.stories.razor component in the project we created now, note that the stories keyword is essential for BlazingStory.
Use @attribute to specify a folder structure to locate the component when running the project:

@attribute [Stories("Lists/PlaceHolder")]

Connect the stories component to the Blazor component by adding a Stories element and setting TComponent to the component we wish to try out:

...
<Stories TComponent="PlaceHolder">

Components can have multiple variations, each defined inside a Story element with a unique name. For example:

...
<Stories TComponent="PlaceHolder">     
  <Story Name="Default">

Display the component by referencing it within the Template element:

@attribute [Stories("Lists/PlaceHolder")]  
<Stories TComponent="PlaceHolder">
     <Story Name="Default">
         <Template>
             <PlaceHolder></PlaceHolder>
         </Template>
     </Story>
 </Stories>

Interactive Components with Parameters

To be able to toggle the appearance/behaviours of the component we can add [Parameters] to our Blazor component. These parameters should be passed from the story to the component using @attributes:

...
  <Template>
     <PlaceHolder @attributes="context.Args"></PlaceHolder>
  </Template>

But why manually enter colors when we can use a color control? Let’s explore that in the next section.

Controls

In the PlaceHolder.stories.razor file we can specify the controls to use for [Parameters], including Booleans, Selections, ColorPicker and more.

To add a color picker to the above example, add ArgType element to the PlaceHolder.stories.razor file, specify the parameter in the For lambda expression and select the control type - too easy! :

@attribute [Stories("Lists/PlaceHolder")]
<Stories TComponent="PlaceHolder">
    <ArgType For="_ => _!.Color"
             Control="ControlType.Color" />
    
    <Story>...

Docs

One of BlazingStory’s standout features is its automatic documentation generation. To enable this feature, set GenerateDocumentationFile to True in your project file:

<Project Sdk="Microsoft.NET.Sdk.BlazorWebAssembly">

    <PropertyGroup>
        <TargetFramework>net8.0</TargetFramework>
        <Nullable>enable</Nullable>
        <ImplicitUsings>enable</ImplicitUsings>
       <GenerateDocumentationFile>True</GenerateDocumentationFile>
    </PropertyGroup>    <ItemGroup>
        <PackageReference Include="BlazingStory" 
...

When adding parameters to our component, we can easily add a few notes regarding the parameter.

/// <summary>
/// Set a color of the background.
/// </summary>
[Parameter]
public string Color { get; set; }

These notes will display in the Docs page :

Show code / Copy code

The number of parameters can become rather long, instead of having to add it in manually, we can add it to the story and use the show code button!

But its not showing all the parameters! Lets fix that.

Lets go back to the stories file and add the parameters with values we want to display in the Show code / Copy section

 ...
    <Story Name="Default">
        <Template>
            <PlaceHolder Color="#0d6efd" TextColor="#fff"
                         PlaceHolderColor="#fff"
                         NumberOfColumns=4
                         NumberOfRows=4
                         @attributes="context.Args"></PlaceHolder>
        </Template>
    </Story>
</Stories>

Result :

The component with all the parameters with default values are ready to be copied!

Summary

While BlazingStory is still in its early stages of development, I believe it will become an important tool for Blazor developers like myself. It will enable us to create and test components in a simplified environment. I’ll definitely bookmark this repository! I hope you see the benefit of using it too!

Here is my repo with the components featured in this blog. End-to-end testing using Playwright within this repo is covered in another blog.