Lookbook v2.0 beta

[allmarkedup]

🎉 The Lookbook v2.0.0 beta is available for testing now! 🎉

---

Docs: https://v2.lookbook.build (work-in-progress!)

Demo: http://v2-demo.lookbook.build

---

What's New?

🆕 Support for previewing a wider range of component types such as Phlex views and ActionView partials, in addition to ViewComponents.

🆕 Preview embeds for including Lookbook previews on external sites - see some examples here.

🆕 Improved file watching/live updates system with tighter Rails integration to improve reliability and interoperability, including support for forking servers in clustered mode.

🆕 Lots of other under the hood improvements!

You can find a more detailed overview of the changes here.

Upgrading

There are a few breaking changes but they are mostly centred around the Ruby API so are unlikely to affect too many people.

If your app doesn't already include the listen and actioncable gems then you will need to add them to ensure that live updates continue working in development. These were previously bundled with Lookbook but are now optional dependencies.

See the upgrade guide for full details.

Help wanted! 🛟

I'd love to get as many people trying these beta releases as possible.

The file watching system has been rebuilt from scratch and whilst I'm confident that it will solve many of the "Lookbook isn't showing my changes" bugs that people have been running into, it is a big change and there may be a lot of "different-setup edge cases" that need to be flushed out. The more 👀 the better!

If anyone is having any problems with getting the betas working please open an issue or @ me and I'll do my best to help out. And any other comments/suggestions/frustrations would be most welcome too :-)

[Spone]

Congrats on the beta release! Lots of cool new stuff!

Some feedback:

In the preview embeds demo, the theme switch doesn't work for me (Firefox):

But if I start changing the params it triggers the refresh and changes the theme as expected:

[allmarkedup]

Thanks @Spone 😊 I'm glad to finally get people testing it.

I've just tested this and it looks like it's broken in Chrome too so I don't think it's a browser issue. I'll open an issue and dig into it as soon as I can. Cheers!

[swanson]

Having some trouble with the beta and not really sure how to debug. It was working for a bit and then I restarted my Rails server and now loading the /lookbook root page hangs in Chrome. Looks like it is waiting for actioncable to connect but never does?

Eventually the tab freezes and has to be killed because it's taking 100% CPU.

We don't use actioncable (though it is installed via rails) so there might be something on my end that is not setup correctly?

[allmarkedup]

@swanson okay, thanks for the report - I've converted this into an issue (#337) and I'll look into it as soon as I can. It's peculiar that it was working initially and is now hanging, can't think off the top of my head what might be causing that.

If you have a chance could you add a little more info on Rails, ViewComponent and Ruby versions (and any other info that might help debugging!) to the issue I've created? Thank you!

[thutterer]

Hi @allmarkedup, as promised I looked into the 2.0.0.beta.2 this week. Friday afternoon, but still counts 😉

Upgrading our development-mode Lookbook from the latest 1.x to 2.0.0.beta.2 worked without any issues. Docs are really good, too!

I also upgraded our public Lookbook instance that sparked the whole idea of Preview Embeds and integrated the embeds in our design system docs. This is so awesome, literally an idea coming to life 🤩

The only issue I ran into might be totally on our end and might have nothing to do with the lookbook.js, but since it's late and I won't figure this out before the weekend I leave it here, just in case:

• Our DS docs are done as a Nuxt (Vue SPA) app. While the embeds work perfectly fine on a full page load, they don't when I "nuxt navigate" to that page.
• You can actually try it yourself in the review app:
  • https://4456656-review-lookbook-e-vm97y9.design-staging.gitlab.com/components/badge/lookbook should work.
  • Navigate to "Button" in the sidbar and click that "Implementation (Rails)" tab again and the embed won't load.
  • F5 and it works.
• Code can be found at https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/merge_requests/3264 in case you are curious.

Have a nice weekend and again, thanks and congrats to the great beta release 🚀

[allmarkedup]

as promised I looked into the 2.0.0.beta.2 this week. Friday afternoon, but still counts 😉

@thutterer it certainly does - really appreciate you squeezing it in to your week :-)

And very cool indeed to see the embeds running in your review app. Really exciting!

The issue you are seeing is because the lookbook.js script only auto-initialises embeds in the DOM when the page first loads (DOMContentLoaded). As changing tabs in your app is actually reloading the DOM within the tab each time, the embeds will need to be manually initialised when the 'Rails implementation' tab is selected.

The initEmbeds function on the global Lookbook object will initialise any embeds on the page that have not been initialised already:

window.Lookbook.initEmbeds();

Do you have a hook you can use to run that on tab change?

I will definitely add a note about this to the docs. I'll also think about if it make sense to have an opt-in option to watch the DOM for new lookbook-embed elements and initialise them automatically. It would certainly be possible (using MutationObserver) but I'm a little wary of the performance implications of watching the whole DOM...

[thutterer]

Thanks @allmarkedup, running the initEmbeds() everytime the page component got mounted solved it 👍

I will definitely add a note about this to the docs.

Perfect, thanks. I think having this documented is good enough. And actually maybe even better than adding such a opt-in "watch the entire DOM" feature. Since it would be opt-in, it would require documentation as well as the current behavior does. And if enabled, it would likely be less performant than doing it the manual way like now.

[allmarkedup]

@thutterer excellent, glad it sorted the issue for you. Will add a note about that to the docs now. And after a bit of thinking about it I agree about the DOM watching option not being needed, keeps things simple which is always good!