User Guide / Get Started

Installing Lookbook

These instructions cover installing Lookbook in your Rails project for the first time.

If you are already using Lookbook then head over to the upgrade guide instead for details on how to update your project to the latest version.


Follow the steps below to add Lookbook to your project.

1 Add the gem

Add lookbook to your Gemfile:

group :development do
  gem "lookbook", ">= 2.3.2"

And then bundle install to install Lookbook.

Lookbook can also be run in production - see the docs for details on how to set that up.

2 Mount the Lookbook engine

Next mount Lookbook at a path of your choosing in your config/routes.rb file:

Rails.application.routes.draw do
  if Rails.env.development?
    mount Lookbook::Engine, at: "/lookbook"

The mount path (/lookbook in the example above) will be the URL that the Lookbook UI will be made accessible at within your app.

3 Enable live UI updates

Lookbook requires the listen and actioncable gems to enable live-updating of the UI when changes are made to component or preview files.

These are optional dependencies - if they are not present the only difference is that you will need to manually refresh the Lookbook UI to see any changes that you have made.

Many Rails apps already include these gems. If your project doesn’t you can enable Lookbook live UI updates by including them in the :development group in your Gemfile:

group :development do
  gem "listen"
  gem "actioncable"

No additional configuration is needed once they are installed - Lookbook will detect they are present and enable live updates automatically.

Get Started

Once everything is installed, start your app as normal.

Assuming your app is running on port 3000 and you mounted Lookbook at the path /lookbook then browse to http://localhost:3000/lookbook to view the Lookbook UI.

If this is a new project it will be pretty empty in there until you start creating some components and adding some preview classes.

User Guide

Extending Lookbook