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.
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 settingTComponent
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.