🚨 You are viewing the legacy v1.x docs. See the new v2 documentation →


Some common problems that people run into when using Lookbook.

If you are running into problems and nothing here is relevant then head over to the Lookbook repo and open an issue or discussion to get help from the community.

🚨 Forking servers - changes not showing up

Lookbook does not play nicely when using a forking server such as Puma in clustered mode (i.e. with a WEB_CONCURRENCY value of > 1). This is due to a limitation of the underlying library that is used to watch for changes.

If running in clustered mode, any changes made to preview files or components will not appear in Lookbook without restarting the server.

This can be fixed by setting WEB_CONCURRENCY=1 so that the server does not run in clustered mode. Not always the best solution but there is no other way around this issue at the current time.

🚨 Template error in preview window

When previewing components, if you are seeing an ActionView::Template::Error error with (something similar to) the following message:

No route matches {:action=>"preview", :controller=>"lookbook/previews", :path=>"path_to/current_component"}

Then it may be being caused by the use of link_to tag helpers in your preview layout (if you have specified one) or your application layout.

Due to the way Lookbook renders the layout, some forms of link_to arguments do not currently work and will cause the error described above.

To fix the issue you can either use one of the link_to forms that work (see below) or remove the links from your layout (and perhaps use a preview-specific layout if you are currently using the default application layout).

<%= link_to "Click here", "/foo/bar" %>  ✅ works

<%= link_to "Click here", edit_thing_path(@thing.id) %>  ✅ works

<%= link_to "Click here", locale: :en %>  ❌ doesn't work

<%= link_to "Click here", controller: "demo", action: "index" %>  ❌ doesn't work