Storybook Setup & Tour

[00:00:00]
>> One of the really cool things is that Storybook is framework agnostic. It will work with React, obviously. It is written in React, and that's probably just like jQuery before it, usually the first and primary target. We use Svelte at Temporal and so we use Storybook with Svelte.

[00:00:18]
It has support for Vue, Web Components, Angular, I think even Ember, right? So for whatever you use, Storybook will apply for it. Like I said, I chose React cuz it was the lingua franca. But again, we're not really doing all that much specifics along the way. And so what's really cool is at any given point, you can run this npc storybook@latest init in your repo.

[00:00:47]
And what Storybook will do is it will go in and basically it has some heuristics also known as looking at your package.json to figure out what framework using. And it will install the kind of different pieces that, whether it's at Storybook/Svelte, at Storybook/React, at Storybook/Lit, what have you, Web Components, all of that will work.

[00:01:08]
And so you don't necessarily need to think about do much configuration differently. It will put a default thing in there as well. But one of the other things that we can do as well is there's this idea of Storybook sandboxes which basically very quickly creates a Storybook. Which is a lot of times if I'm trying out something new or something along those lines and I wanna pull it into a repo, that will work as well.

[00:01:29]
And that will give you a little bit of sense of a brand new storybook. So let's just go take a look at that for a second. And we'll kinda just see what we start out with and get a sense of default stuff that I might otherwise, blow away very quickly.

[00:01:44]
So I can run this npx @latest. Now, if you need a particular version, choose the particular version. In our case, we are going to do @latest. At the time of this recording, 8.08 is the latest version. Storybook 8 came out last month. So we will discuss some things that are kinda brand new to Storybook and have the latest and greatest versions in here as well.

[00:02:09]
So we'll go ahead and run this @storybooklatest, and one of the great things and the reason I kinda bring this up early is we are gonna just start with a very simple React app. But if one wanted to see what it might look like across all of the different supported frameworks, you can also go ahead and pick something and just see the general structure.

[00:02:29]
And one of the things I encourage you to do kind of in between various parts is look at a few different versions and notice that it doesn't really matter, right? The idea of a server, there's slightly different flavours, right, based on the unique characteristics. But genuinely speaking, one could stare at the Storybooks story and forget which framework they are looking at.

[00:02:56]
We'll be using transcript today as well. The logic there being, if one is gonna try to build a reusable and consistent design system, having some of the type safety and hints to make sure people are using it the way that it should be used is probably useful. And also if one does not use Typescript, untypescripting stuff is just don't put the types in, right?

[00:03:20]
It's easier to look at Typescript and reverse engineer JavaScript, then go the other way, cuz there are some unique characteristics, some ceremony that we have to do to support TypeScript. I wanna make sure that if you use TypeScript, that is a thing. I'll go ahead and just use the Svelte one real quick just to show you that it's all basically the same.

[00:03:40]
It will go ahead and install the sandbox. And this will give us a nice tour of some of the stuff we are gonna implement along the way as well. So Storybook has a few component pieces to it. It's got the idea of a story, right, which is just basically a version of your component with some amount of arguments, parameters, props, settings, what have you.

[00:04:02]
Also supports MDX, which is Markdown plus React. The reason I mention this is even if you use Svelte, or Ember, or Angular, or what have you, MDX, there's still a little bit of React that kinds creeps in no matter what. You don't necessarily need to React. As a Storybook 8, it's not even a dependency gets added to your package.json.

[00:04:23]
It's actually through the build process just kinda baked into Storybook. But we can go ahead and, You can see that I've got the versions here as well. And then we'll go ahead and do it. They use yarn, I use pnpm, you can use npm, whatever makes you happiest, cool.

[00:04:50]
He says, As yarn doesn't work for me, but it's fine. You can use npm install as well, it doesn't matter. So by default, it will go ahead and create you some NPM scripts, run NPM, run Storybook, or PNPM Storybook, whatever makes you happiest, and it will go ahead and start up in port 6006.

[00:05:22]
And you can create a bunch of things in a Storybook file. This is an MDX file, which is, again, Markdown plus React, which lets you embed components or have some amount of logic and Javascript in your Markdown files. You can embed like, okay, I wanna talk about this component and how it should be used, right?

[00:05:42]
These are all really important parts of the design system. Nobody wants to watch me write documentation live, trust me. But we'll kinda discuss how to do that and some of the best practices around that, as well as we have this idea of various different permutations of a button.

[00:05:59]
This is kind of the default setup. And so you can see, you can actually include documentation about how to actually use this component, right? What are the props that it takes? And tweak all of these things live, which is both great for the documentation and proliferation of your design system.

[00:06:18]
Also, I'm not gonna lie to you, I'm gonna start taking all the component pieces, start with a story and develop that various, all the different permutations on one monitor in my editor on the other monitor is an incredibly productivr workflow as well. We will kind of pay some homage to more of the kind of philosophy of design systems as we talk about the stuff as well, right?

[00:06:46]
You can start with buttons, you can put entire pages into Storybook, right? And we'll show at the end how to do stuff. Yeah, but this thing, it automatically does a fetch call to something, cool. We can actually load that data. No, but this needed the context API or what have you, or some surrounding ceremony, right, whether it's Svelte context or React context, it doesn't really matter, right?

[00:07:08]
We'll show you how to do that. I have some written pieces to even include mock server, so you can actually have like real deal data as you're developing, right? In ours, it's kind of our open source project. We have basically stored simulated API calls. We can actually see with real data how all of these components compare with our website.

[00:07:32]
We use Contentful as our CMS, right? So our Storybook is hooked up to Contentful so we can actually see, okay, just the blog card component with the latest blog post before we actually hit Publish and see all of these things. So for us, we use it not only for our design system pieces, but as a integral part of our deployment process, right?

[00:07:51]
Every time we open up a PR, it not only builds a version of the website that we can go visit, but it also builds a version of the Storybook. So I can send just those pieces to designers on my team and see just those unique pieces and get feedback on just these things.

[00:08:05]
And we can actually like, okay, maybe in the application today on a new design system component, it's a button that has a very short string, right? But we can write stories that have a button with a very long string, right? We can actually have all these pieces and play see it all, right, which stops a lot of the churn in our code base as well.

[00:08:22]
So in a story, we've got either the documentation page or these kinds of individual stories here as well. You've got the various controls you can like, is this a primary button or not? You can change the label. So if you wanted to see what does this look, it gets really long, right?

[00:08:42]
You can do that as well and kinda manipulate and play around with all these things, changing the background color of the button, in this case, changing the size. And we'll look at how to set up these controls, how to customize them, and all of those things as well.

[00:08:54]
The other thing you'll notice is that you can actually keep track of the actions and look at all those things you can actually put in stuff. If you've used something like jest for kinda having spies and subs, you can actually run those as well. Be like, did the at click function actually get called with the things that I expected them to get called?

[00:09:17]
You can actually check and validate those things, right, outside the context of your app and also run automated tests around that and all of these permutations to make sure you didn't break some subtle use case. That wasn't maybe the page you were staring at at the time. And kinda make sure that you don't accidentally cause regressions throughout your code base.

[00:09:37]
You can also have different presets and these are kind of different stories plural file. You can have different individual stories that have these components set up different ways so that you don't have to go through and necessarily tweak everything every time you wanna see something. Here are all the common use cases, I can take a look at them.

[00:09:57]
So the other things we'll talk about today are visual aggression testing, which is saying like, hey, I'm changing some stuff. Usually, there's some things you expect to change, right? But for me, I joked the other day when we were teaching workshop that the code base that was a great Greenfield brand new project three years ago is now three years old, right?

[00:10:23]
Which means there are all sorts of little edge cases and stuff along those lines, and there's a lot of need and opportunity to refactor. There's parts of the code base where this was a good idea when we did it and then the product changed directions and there's archaeological layers.

[00:10:39]
And so we were implementing dark mode of last six weeks, right? And there's a lot of pieces that we're refactoring a lot, the ability to have a visual regression test to make sure did the things that I change. The things I don't wanna change, they shouldn't change, right, and it's impossible to check all those things one by one.

[00:11:00]
And so with our Storybook integration, we can actually roll that all together, make sure that nothing's changing that we don't expect to change as well. Okay, so this is kind of what a beginning Storybook looks like. You can see we've got the nav bar, we've got buttons, you can create even full pages in here as well.

[00:11:18]
This is like with the logged in and logged out experience, which is really great kind of to work with design on these things as well.