Lookbook renders your Rails components in isolation and documents them at the same time

A Rails engine that renders one component at a time

Lookbook is a UI development environment for Ruby on Rails applications, and the way it is packaged is the first thing to understand.

It is implemented as an isolated Rails Engine, so it mounts into a host application as a route and brings its own controllers, views and assets, without the application having to import anything into its own code. The UI itself is built with ViewComponent, Tailwind and Alpine.

The purpose is stated as combining a powerful component browser and preview system with an integrated documentation engine, to help teams build robust, modular, maintainable user interfaces. Three things in one mount, which is the point. A component browser shows you every component in the codebase and how it looks with different arguments. A preview system lets you render a component in a real page context, including its JavaScript behaviour, and a documentation engine generates the prose around it.

Compatibility is broader than ViewComponent alone. The readme says it is compatible with ViewComponent, Phlex, ActionView partials and more.

That breadth is the interesting design choice. A component browser that only understood one rendering stack would be a toy for that stack, whereas one that can preview a partial and a ViewComponent side by side covers the mixed codebase that most Rails applications actually have.

The gem is MIT licensed, the primary language recorded for the repository is JavaScript, and the last push was on 2026-10-15.

The repository holds the engine, the docs and the tests

The Development section lists what is in the repository, and it is worth noting because the documentation site is not in a separate repository.

There is the Lookbook source code, with the app, lib and config directories, the Lookbook documentation site source code and content in the docs directory, and a test suite with a runnable dummy app in the spec directory.

The documentation site is built using Bridgetown, and the source files are in the ./docs directory. To preview changes locally you can run a development version of the docs site, and the steps are: clone the repo, install the dependencies with bundle install, start the app with bin/docs, and visit http://localhost:4000.

bundle install

bin/docs

So the docs are a Bridgetown site with its own Ruby tooling, living next to the gem it documents. The practical consequence is that a documentation change and a code change are the same pull request and the same review, and a reader who wants to see how a feature is supposed to be used can read the source of the page that says so.

There is also a public demo site at demo.lookbook.build, and the main documentation lives at lookbook.build, which is where the project points for anything beyond the README.

Testing across Ruby and Rails versions with Appraisal

Lookbook uses RSpec, and Appraisal is used to run the tests against different Ruby and Rails versions.

bundle exec appraisal rspec

That is the whole test command, and the matrix behind it is what matters for a library that plugs into other people's applications. A Rails engine has to work against several Rails versions and several Ruby versions, and Appraisal is the tool that generates the separate Gemfiles for each combination, which is why the repository has a gemfiles/ directory and an Appraisals file at the top level.

The dummy app that the tests run against can be viewed by running the bin/dummy command and then browsing to the Lookbook route on port 9292.

bin/dummy

That is a nice touch in a test suite for a development tool, because the subject of the tests is an interface. A dummy app you can open in a browser and click through is how you check that the browser renders, that the previews load, and that a change to the layout did not break the navigation, none of which a unit test covers.

The other tooling in the tree follows the same pattern of a project with a Ruby side and a JavaScript side. There is an .rspec file, a .standard.yml for the standardrb linter, a Rakefile, a Gemfile and a Gemfile.lock, a lookbook.gemspec, a .husky/ directory for git hooks, an .eslintrc.js, a .prettierignore, a .parcelrc and a .postcssrc, and both a .ruby-version and a .tool-versions file for pinning the interpreter.

Parcel builds three separate asset bundles

The front end of Lookbook is built with Parcel, and the package manifest shows the structure of that build, which is the most informative part of the repository for anyone extending the tool.

There are three targets. The app target compiles the iframe script, the index script, the stylesheet and the theme stylesheets into the public assets directory. The embed target compiles a single script with a global output format, and the embed-core target does the same for a smaller core script, both without source maps.

"targets": {
  "app": {
    "source": [
      "./assets/js/iframe.js",
      "./assets/js/index.js",
      "./assets/css/lookbook.css",
      "./assets/css/themes/indigo.css",
      "./assets/css/themes/blue.css",
      "./assets/css/themes/zinc.css",
      "./assets/css/themes/green.css",
      "./assets/css/themes/rose.css"
    ],
    "distDir": "./public/lookbook-assets"
  }
}

The three targets exist because Lookbook is used in two ways. The app target is the browser you mount, and the embed targets are for embedding Lookbook previews inside another tool, such as an editor or a documentation page, where a self-contained global script is what you need.

The themes are generated rather than written by hand. There is a themes:generate script that runs bin/generate-themes, a watch mode that reruns it when files in the theme directory change, and the five colour themes in the list, indigo, blue, zinc, green and rose, are the output of that generator.

The alias block in the manifest maps short paths onto the source directories, so the JavaScript can import from @helpers, @lib and @components without long relative paths, and the components alias points into the app components directory, which is how the browser's own UI shares code with the engine.

Releases run through Release It! and need two permissions

Lookbook uses Release It! to automate the release process, and running npm run release starts the publishing flow, walking through all the steps from picking a version number to publishing the updated gem.

The release process section then states the two permissions it needs, and they are a useful signal of how a gem like this is published. Publishing a release requires write permissions for the lookbook-hq/lookbook repository and 2FA publish permissions for Lookbook on RubyGems.

The reason the second one matters is that a gem published from a shared repository is a supply chain surface, and the modern RubyGems flow expects two factor authorisation on the publishing credential. A project that cannot publish without one person is a project with a bus problem, so a documented two permission setup is a sign of a project that has thought about that.

The release history shows an irregular cadence. v2.3.15 came on 2026-08-31, v2.3.14 on 2025-12-17 and v2.3.13 on 2025-08-18. So there is a gap of about eight months between 2.3.14 and 2.3.15, and a shorter gap of about four months before that, with a recent release landing in the summer of 2026.

For a project that describes itself as un-funded, that cadence is what to expect, and it is the reason to read the changelog before pinning a version rather than assuming a new release is imminent.

An un-funded project with a public demo and an open door

Lookbook is an un-funded open source project, and the contributing section says contributions of all types and sizes are most welcome.

That sentence is doing something specific. Lookbook is infrastructure that a team depends on, it is maintained without a company behind it, and the way that stays true is by having more people able to maintain it. The repository asks you to read the Contributing guide before your first contribution and to start a discussion if anything is unclear, and the discussions area is the stated place to do that.

The project was created by Mark Perkins, and the readme credits the contributors with the phrase that the project continues to grow and improve thanks to the ideas, suggestions and hard work of all of these excellent humans.

The gem is available on RubyGems as lookbook, and the version in the package manifest matches the latest release at 2.3.15.

There is also a public demo site, and for a UI development tool that is more than a courtesy. Component browsers are visual, and a screenshot of somebody else's browser tells you less than opening it and clicking through the states yourself, which is exactly what the demo site is for.

The last piece of the repository worth noting is the top level layout, which shows the scope. There is app/, lib/, config/ and public/ for the engine, assets/ for the JavaScript and CSS sources, theme/ for the theme generator input, bin/ for the executable scripts, docs/ for the Bridgetown site, spec/ for the tests and the dummy app, and the standard Ruby and JavaScript tooling files around them.

Editorial conclusion

Adopt Lookbook when your team writes a lot of ViewComponent or Phlex code and the cost of rendering a component inside the full application is slowing you down, since the browser shows each one in isolation with its props. Do not adopt it for an application with a handful of templates, because the engine and the asset pipeline are real weight for a small surface. Verify first which rendering stack you use, since compatibility with ViewComponent, Phlex and plain ActionView partials is not identical, and that the Ruby and Rails versions your app runs are among the ones the Appraisal matrix covers.

Frequently asked questions

Official sources

1. License: MIT
2. lookbook-hq/lookbook on GitHub
3. Project website
4. README
5. Releases