L
👀
kbook
About
Lookbook provides a ready-to-go UI for navigating, inspecting and interacting with ViewComponent previews. It uses (and extends) ViewComponent's in-built component preview functionality and is intended to integrate seamlessly with existing ViewComponent libraries.
The goal is to (eventually) give a Storybook-like development experience for ViewComponents, but hopefully with a more 'Railsy' feel and without having to learn a whole new DSL.
Lookbook uses RDoc/Yard-style comment tags to extend the capabilities of ViewComponent's preview functionality whilst maintaining compatability with the standard ViewComponent preview class format, so you can add or remove Lookbook at any time without having to rewrite any code.
⚠️ PLEASE NOTE! Lookbook is very much a work in progress at the moment. There may be breaking changes on point-releases before a 1.0 version is ready.⚠️
Current features
-
👀 Navigate your component previews with ease! -
🔍 Filter/search previews by name -
🖥 Resizable, responsive preview window -
🔦 Highlighted preview source code (with one-click copy to clipboard) -
🔦 Highlighted HTML output -
📝 Add notes via comments in the preview file - markdown supported -
🚀 Live UI, auto-updates when component or previews files are updated -
🙈 Supports 'hidden' previews and examples
Future plans and ideas
Check out the feature request issues) to get a feel for some of the potential features coming to Lookbook in the future. And please suggest your own if you have anything you'd like to see added!
Lookbook demo
If you want to have a quick play with Lookbook, the easiest way is to give the demo app a spin. It's a basic Rails/ViewComponent app with a few test components included to tinker with.
The demo app repo contains instructions on how to get it up and running.
Installing
Lookbook is current a work in progress and has not been published as a Gem yet.
If you wish to play with it in it's current state you can include it directly from Github using the instructions below.
1. Add as a dependency
In your Gemfile add:
gem "lookbook", '>= 0.1', git: "https://github.com/allmarkedup/lookbook", branch: "main"
This line should be placed below wherever you have specified the view_component gem.
2. Mount the Lookbook engine
You then need to mount the Lookbook engine (at a path of your choosing) in your routes.rb file:
Rails.application.routes.draw do
# any other routes...
if Rails.env.development?
mount Lookbook::Engine, at: "/lookbook"
end
end
The at property determines the root URL that the Lookbook UI will be served at.
If you would like to expose the Lookbook UI in production as well as in development, just remove the
if Rails.env.development?wrapper from the mount statement.
Then you can start your app as normal and navigate to http://localhost:3000/lookbook (or whatever mount path you specified) to view your component previews in the Lookbook UI.
Usage
You don't need to do anything special to create ViewComponent previews for Lookbook.
Lookbook will use the ViewComponent configuration options for your project to find and render your components so you don't need to configure anything separately (unless you want to tweak the behaviour or look of Lookbook itself).
If you are new to ViewComponent development, checkout the ViewComponent docs on how to get started developing your components.
Lookbook uses the exact same preview files as 'regular' ViewComponent previews, so using preview templates, custom layouts and even bespoke preview controllers should all work just the same.
Comment tags
Lookbook uses Yard-style tags in class and method comments to extract additional information about previews, examples and components.
Tags are just strings identified by their @ prefix - for example @hidden. Tags are always placed in a comment above the relevant preview class or example method. The comments can still contain any other text, and multiple tags can be included in any one comment. For example:
# This is a class-level comment.
# @hidden
class MyClass
# This is a method-level comment.
# @hidden
def my_method
end
end
Some tags can also require additional arguments. Further informatin on the tags Lookbook uses are detailed in the docs below.
🔦
Viewing source code and rendered HTML output
Lookbook displays the source code of the current preview (or the contents of preview template, if one is being used), right underneath the rendered preview itself:
You can also inspect the HTML output of the rendered preview (without any of the layout cruft):
All code panels have a 'copy-to-clipboard' button at the top right of the panel, just click it to copy the un-highlighted code to your clipboard.
📝
Adding notes to previews
Lookbook lets you add notes to your preview examples which are then displayed in the inspector panel. They look something like this:
Notes are generated from comments above example methods in your preview files. Below is an example of two preview examples that both have notes:
class ButtonComponentPreview < ViewComponent::Preview
# Add notes as comments above the example methods.
# Multi-line is just fine and **markdown** is supported too!
#
# It's a good place to put usage and implementation instructions
# for people browsing the component previews in the UI.
def default
render ButtonComponent.new(text: "Click me")
end
# Each preview example has it's own notes, extracted from the method comments.
def danger
render ButtonComponent.new(text: "Don't do it!", theme: :danger)
end
end
📝
Hiding previews and examples
Sometimes you may want a preview or an individual example to be 'hidden' in the Lookbook UI. This means that the preview or example will not show up in the navigation, but will still be accessible via it's URL.
To hide a preview or example, the @hidden comment tag is used:
Hiding a preview
To hide an entire preview, include the @hidden tag in a class comment:
# @hidden
class MyComponentPreview < ViewComponent::Preview
# examples here....
end
Hiding an example
To hide an individual example, include the @hidden tag in the appropriate method comment:
class MyComponentPreview < ViewComponent::Preview
# Hidden Example
# ----------
# You won't see this in the nav!
#
# @hidden
def hidden_example
# example code...
end
def a_visible_example
# example code...
end
# @hidden
def another_hidden_example
# example code...
end
end
Configuration
Lookbook uses ViewComponent's configuration options for anything to do with previews, paths and general setup, so you won't need to duplicate any settings.
However the following Lookbook-specific config options are also available:
UI auto-refresh
Disable/enable the auto-updating of the Lookbook UI when files change. Enabled by default.
config.lookbook.auto_refresh = false # default is true
By default Lookbook will listen for changes in any preview directories as well as in the components directory itself.
If you wish to add additional paths to listen for changes in, you can use the listen_paths option:
config.lookbook.listen_paths << Rails.root.join('app/other/directory')
Contributing
Lookbook is very much a small hobby/side project at the moment. I'd love to hear from anyone who is interested in contributing but I'm terrible at replying to emails or messages, so don't be surprised if I take forever to get back to you. It's not personal
However, I'm a frontend developer - not a Rails dev - so any thoughts, advice or PRs on how to improve the codebase will be always much appreciated.
Developing on a local version of Lookbook
The quickest way to get a development version of Lookbook up and running is to use the lookbook-demo app and link it to a local version of the Lookbook gem:
Initial setup:
- Clone this repository somewhere on your machine -
git clone [email protected]:allmarkedup/lookbook.git - Also pull down the lookbook-demo repository to your machine
- In the
Gemfileof thelookbook-demorepository, replacegem "lookbook", '>= 0.1', git: "https://github.com/allmarkedup/lookbook", branch: "main"withgem "lookbook", path: "../path/to/lookbook"(use the path to your local copy of lookbook) - Install dependencies - from the root of the parent project run
bundle install
Starting development
- From within the
lookbookroot directory run the comandnpm run dev(this will make sure the CSS/JS is recompiled if/when you make changes to the UI) - From within the
lookbook-demoroot directory runnpm run start- this will start a server and build the demo assets
Point your browser to http://localhost:3000/lookbook to see the UI. You can then make and test changes to the Lookbook code in your local copy of lookbook repo. PRs are welcome if you add anything useful :-)
Note that changes to files in the Lookbook
lib/directory will require a server restart in order to have them applied.
License
The gem is available as open source under the terms of the MIT License.
91 Jan 3, 2023
37 Nov 16, 2022
2 Apr 15, 2022
9 Dec 17, 2022
7 Oct 24, 2022
19 Dec 15, 2022
162 Jan 3, 2023
13 Nov 10, 2022
425 Dec 28, 2022
5 Dec 15, 2022
4 May 12, 2022
1 Feb 26, 2022
1 Jan 2, 2023
4 Mar 14, 2022
26 Jan 4, 2023
8 Aug 5, 2022
15 Sep 28, 2022
3 Apr 16, 2022
3 Dec 31, 2022