Component driven design is one of the best things to come out of the ReactJS framework, and Storybook is an excellent way for a team to collaborate on new features while also conforming to a team style guide.
In a codebase, it’s easy for the different erb files to quickly become a mess when using a utility-style framework like Tailwind CSS. In no time at all, your app loses one of the essential elements of style.
Consistency.
View Components along with Storybook, can help solve this issue while also providing an excellent collaboration experience with your team members.
Why use Storybook with View Components
The main reason is that you can test edge cases with your design. For example, you might want to see what it looks like with different languages or different text when making a button.
- Test edge cases with your design dynamically
- Share your style guide with your team, including your managers, product managers and designers, so that they can iterate on it
- Document use cases
- Test components for accessibility issues.
If I have convinced you at all, feel free to follow along.
1. Set up a rails app (Optional)
Experienced Rails developers usually read this blog. I’m assuming that you are adding this to an existing app.
If not, run the following command:
rails new Storybook
2. Install the necessary gems
To note. As of writing, there is no generator for the View Component Storybook gem, but I imagine there will be soon. Below is a summary of all the notes I took while investigating the gem. Hopefully, everything is there for you to get up and running to experience Storybook for yourself.
bundle add view_component
bundle add view_component_storybook
Add require "view_component/storybook/engine"
to config/application.rb
# config/application.rb
require_relative 'boot'
require 'rails/all'
require "view_component/storybook/engine"
....
Add */*.stories.json
to .gitignore
2. Configure Asset Hosts
If your view components depend on Javascript, CSS or other assets served by the Rails application, you will need to configure asset_hosts
appropriately for your various environments. For local development, this is a simple as adding to config/development.rb
:
Rails.application.configure do
config.action_controller.asset_host = 'http://localhost:3000'
end
Naturally, you can do the same for staging and production.
3. Install Storybook via yarn
- Add Storybook server as a dev dependency. The Storybook Controls addon isn’t needed but comes recommended.
yarn add @storybook/server @storybook/addon-controls --dev
- Add an NPM script to your package.json to start your Storybook later.
// package.json
{
"scripts": {
"storybook": "start-storybook"
}
}
- Create a folder called
.storybook
. It is a dotfolder. From the command line, do the following:
mkdir .storybook
- Create a file called .storybook/main.js file to configure Storybook to find the JSON stories the gem creates. Also, configure the Controls addon:
touch .storybook/main.js
// .storybook/main.js
module.exports = {
stories: ['../test/components/**/*.stories.json'],
// stories: ['../spec/components/**/*.stories.json'], if using RSpec
addons: [
'@storybook/addon-controls',
],
};
- Create the .storybook/preview.js file to configure Storybook with the Rails application URL to call for the HTML content of the stories
touch .storybook/preview.js
//.storybook/preview.js
export const parameters = {
server: {
url: `http://localhost:3000/rails/stories`,
},
};
4. Your First StoryBook Component
ViewComponent::Storybook::Stories
provides a way to preview components in Storybook. Suppose our app has a ButtonComponent
that takes a button_text
parameter:
class ButtonComponent < ViewComponent::Base
def initialize(button_text:)
@button_text = button_text
end
end
We can write a stories describing the ButtonComponent.
So in spec/components/stories or test/components/stories, put in the following
class ButtonComponentStories < ViewComponent::Storybook::Stories
story(:with_short_text) do
constructor(title: "my title")
end
story(:with_long_text) do
constructor(title: "my title")
end
end
5. Generate Storybook JSON
Generate the Storybook JSON stories by running the rake task:
rake view_component_storybook:write_stories_json
Now you should be able to start the rails app and run the Storybook rails s yarn storybook # in separate tab
Configuration (RSpec Only)
By Default ViewComponent::Storybook expects to find stories in the folder test/components/stories
. This can be configured by setting stories_path
in config/application.rb
. For example if you’re using RSpec you might set the following configuration:
config.view_component_storybook.stories_path = Rails.root.join("spec/components/stories")
Gotcha’s
I had to add rack-cors gem and configure wildcard access for development.
bundle add rack-cors
In config/development.rb, I added the following lines:
# config/development.rb
config.action_controller.asset_host = 'http://localhost:5000'
config.middleware.insert_before 0, Rack::Cors do
allow do
origins '*'
resource '/rails/stories/*', :headers => :any, :methods => [:get]
end
end
Another Gotcha, I ran into. After you update the HTML for the component, you have to rerun the rake task.
Conclusion
There you have it. Hopefully, this has gotten you up and running in under 10 minutes. If not, feel free to reach out to me to see if I can help. Also, be sure to check out the docs. This gem is still under development and was even updated while I was writing this article.
Happy coding.
Top comments (0)