Getting started
Installation
Rails Installation
- In
Gemfile
, add:gem "view_component" gem "view_component_storybook"
- In
.gitignore
, add:**/*.stories.json
- In
config/application.rb
, add:require 'view_component' require 'view_component/storybook'
Storybook Installation
- Add Storybook Server as a dev dependency.
yarn add @storybook/server @storybook/addon-controls --dev
Storybook Controls addon isn’t required but is strongly recommended.
-
Add an NPM script to start Storybook. In
package.json
, add:{ "scripts": { "storybook": "start-storybook" } }
-
Configure Storybook to find the json stories that the gem creates. Create
.storybook/main.js
,module.exports = { stories: ["../test/components/**/*.stories.json"], addons: ["@storybook/addon-controls"], };
-
Configure Storybook with the Rails application url to call for the html content of the stories. Create
.storybook/preview.js
export const parameters = { server: { url: `http://localhost:3000/rails/stories`, }, };
Quick start
Create a ViewComponent
Use the component generator to create a new ViewComponent.
bin/rails generate component Example title
invoke test_unit
create test/components/example_component_test.rb
create app/components/example_component.rb
create app/components/example_component.html.erb
This generates a new component:
# app/components/example_component.rb
class ExampleComponent < ViewComponent::Base
def initialize(title:)
@title = title
end
end
Add a template for the new component:
<%# app/components/example_component.html.erb %>
<span title="<%= @title %>"><%= content %></span>
Write a story for ExampleComponent
# test/components/stories/example_component_stories.rb
class ExampleComponentStories < ViewComponent::Storybook::Stories
story :hello_world do
constructor(title: "my title") do
"Hello World!"
end
end
end
Generating Storybook Stories JSON
Generate the Storybook JSON stories by running the rake task:
rake view_component_storybook:write_stories_json
Start the Rails app and Storybook
In separate shells start the Rails app and Storybook
rails s
yarn storybook
The second command will open the Storybook app in your browser rendering your ExampleComponent story!
Implementation
When Storybook calls the Rails app for the html story content the ViewComponent::Storybook passes the string “my title” to the component constructor and “Hello World!” as the component content. Effectively the component is rendered in a view as:
<%= render(ExampleComponent.new(title: "my title")) do %>
Hello, World!
<% end %>
Returning the rendered html to Storybook:
<span title="my title">Hello, World!</span>
Dynamic Stories with Controls
Storybook isn’t just for rendering static stories. Storybook controls enable dynamic stories with variable inputs. ViewComponent Storybook exposes a similar api to describe dynamic inputs to component stories. For example add the text
control to make title
and content
dynamic:
# test/components/stories/example_componeont_stories.rb
class ExampleComponentStories < ViewComponent::Storybook::Stories
story :hello_world do
constructor(title: text("my title"))
content(text("Hello World!"))
end
end
This adds text controls to the Storybook Controls panel. Changing the values re-renders the compoent.
Available controls and their options are documented on the Controls page.