Creating a Playground and a Storybook for Components

We have components and tests, but until now, we've been unable to see them in action. It's time to create a playground for two key reasons:

1. Testing: We need to test our components in a real environment to ensure they work as expected. Writing a page with all components, their props, and slots helps create the best API and implement it efficiently. This approach minimizes frequent refactoring by providing a comprehensive view of the components.
2. Visualizing: Visualizing components is essential. While Tailwind CSS simplifies styling, it's impossible to fully grasp a component through code, especially complex ones with numerous variants or slots. A playground allows us to see components in action and test them in various scenarios.

Setting Up the Playground ​

First, create a new folder named playground at the root of your project.

mkdir playground

Then, create a new Vite project in this folder, which will depend on our component library. Being in a monorepo simplifies this process.

cd playground && pnpm create vite --template vue-ts

Name this project vue.

Before installing dependencies, update the pnpm-workspace.yaml to include the playground/vue package. This allows the playground to access the component library.

packages:
  - 'packages/*'
  - 'playground/*'

Install the playground dependencies:

pnpm install

In this Vue.js playground, remove unnecessary files, folders, and content:

rm -rf .vscode .public src/{assets,components}
echo "<template></template>" > src/App.vue
echo "" > src/style.css

Remove the .vscode folder, public folder, assets and components folders in src, and the content of App.vue and style.css.

Now, install the component library in the playground:

pnpm add ../../packages/huchet-vue

This command installs the component library by creating a symlink to it in node_modules. Thus, any import made in the playground resolves to the component library in the monorepo, allowing real-time changes during development.

Start the watch script in the huchet-vue package folder and the dev script in the playground/vue folder. Any change in the component library will reflect in the playground.

Using the Playground ​

With the component library installed in the playground, you can start using it.

In the src/App.vue file, import the Button component and use it:

<script lang="ts" setup>
import { Button } from '@barbapapazes/huchet-vue'
</script>

<template>
  <div class="flex gap-6 p-6">
    <Button label="Hello World" />
    <Button label="Hello World" variant="outline" />
  </div>
</template>

To view the result, start Vite in the playground:

pnpm dev

Then, start Vite in the component library:

pnpm watch

In your browser, you should see two buttons, unstyled.

Styling the Playground ​

Our components are unstyled. To reduce bundle size and allow user-side generation, we don't deliver CSS with the component library.

We will use Tailwind CSS 4, even though it's not released yet, because it comes with a Vite plugin that simplifies usage and no more breaking changes are expected.

pnpm i -D tailwindcss@next @tailwindcss/vite@next

Then, register the Tailwind CSS plugin in the vite.config.ts file:

import Tailwindcss from '@tailwindcss/vite'
import Vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Vue(),
    Tailwindcss(), 
  ],
})

In the src/style.css, import Tailwind CSS styles:

@import "tailwindcss";

Automatically, the buttons are styled as expected.

The Storybook Histoire ​

Sometimes a playground isn't enough. You need to document your components, visualize them in various scenarios, and isolate them to ensure issues stem from the component, not integration. This is where a storybook comes in.

We will use Histoire, a Storybook-like tool that's lightweight, based on Vite, and optimized for Vue.js.

Setting Up Histoire ​

Setting up Histoire is simple, especially with Tailwind CSS 4.

First, create a new folder from the root of the project:

mkdir .histoire && cd .histoire && echo '{\n"name": "huchet-vue-histoire",\n"private": true\n}' > package.json

Add the folder to the workspace:

echo "  - .histoire" >> ../pnpm-workspace.yaml

Install Histoire and Tailwind CSS:

pnpm i -D histoire @histoire/plugin-vue @vitejs/plugin-vue vue tailwindcss@next @tailwindcss/vite@next

Histoire uses a configuration file named histoire.config.ts, which we'll create in the .histoire folder:

touch histoire.config.ts

The configuration includes multiple keys:

• plugins: Plugins for Histoire, such as the Histoire Vue plugin.
• storyMatch: Files to match for creating stories, like the *.story.vue files.
• setupFile: Setup file to use with Histoire, where we'll create a setup.ts.
• theme: Personalization options like title, logo, favicon for the Histoire interface.
• vite: Vite configuration utilizing the Vue and Tailwind CSS plugins.

import { resolve } from 'node:path'
import { HstVue } from '@histoire/plugin-vue'
import Tailwind from '@tailwindcss/vite'
import Vue from '@vitejs/plugin-vue'
import { defineConfig } from 'histoire'

export default defineConfig({
  plugins: [HstVue()],

  storyMatch: [
    resolve(__dirname, '../packages/huchet-vue/src/**/*.story.vue'),
  ],

  setupFile: resolve(__dirname, 'setup.ts'),

  theme: {
    title: 'Huchet Vue',
  },

  vite: {
    plugins: [
      Vue(),
      Tailwind(),
    ],
    server: {
      fs: {
        allow: ['..'],
      },
    },
  },
})

Since the stories are in the component library, we must explicitly instruct Histoire to look for them in the packages/huchet-vue/src folder using the storyMatch key. Meanwhile, we permit the Histoire server to access the parent folder via the server.fs.allow key, preventing file accessibility issues.

To implement Tailwind CSS in Histoire, import the CSS in the setup.ts file, similar to the playground:

touch setup.ts style.css
echo "import './style.css';" > setup.ts
echo "@import 'tailwindcss';" > style.css

To begin with Histoire, add three scripts to the package.json:

{
  "scripts": {
    "dev": "histoire dev",
    "build": "histoire build",
    "serve": "histoire serve"
  }
}

Now, we can start Histoire:

pnpm dev

Creating a Story ​

Returning to packages/huchet-vue, we can create our first story file, Button/Button.story.vue:

touch src/Button/Button.story.vue

Histoire offers predefined components for crafting a story with variants.

1. Story: The main component for creating a story.
2. Variant: A component to create a variant of a component within the story.

In our scenario, we create a story in Button.story.vue with two variants: solid and outline.

<script lang="ts" setup>
import { logEvent } from 'histoire/client'
import Button from './Button.vue'
</script>

<template>
  <Story>
    <Variant title="Solid">
      <Button variant="solid" label="Hello World" @click="logEvent('Click', $event)" />
    </Variant>
    <Variant title="Outline">
      <Button variant="outline" label="Hello World" @click="logEvent('Click', $event)" />
    </Variant>
  </Story>
</template>

And it works!

However, a major issue persists: the Story and Variant components are not recognized by our editor.

Adding Histoire Types ​

Fortunately, we can resolve this issue easily as Histoire provides the necessary tools.

Histoire introduces a new TypeScript context within our project, so we need to create a new TSConfig file in the packages/huchet-vue folder:

touch tsconfig.story.json

This file extends tsconfig.app.json but captures only the story.vue files and a new histoire.d.ts file:

{
  "extends": "./tsconfig.app.json",
  "compilerOptions": {
    "moduleResolution": "node"
  },
  "include": [
    "histoire.d.ts",
    "src/**/*.story.vue"
  ],
  "exclude": []
}

Create the histoire.d.ts file:

touch histoire.d.ts

Reference Histoire's types in this file:

/// <reference types="@histoire/plugin-vue/components" />

Register the new TSConfig in the tsconfig.json:

{
  "files": [],
  "references": [
    {
      "path": "./tsconfig.app.json"
    },
    {
      "path": "./tsconfig.node.json"
    },
    {
      "path": "./tsconfig.story.json"
    }
  ]
}

Update tsconfig.app.json with an exclude option to avoid overlapping TSConfig capture:

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "include": [
    "src/**/*.ts",
    "src/**/*.vue"
  ],
  "exclude": [
    "src/**/*.story.vue"
  ]
}

In the next article, we will enhance integration with the Vue.js ecosystem by creating a resolver for Unplugin Vue Component and a Nuxt module.