DEV Community: Peshang Hiwa

Step-by-Step Guide: Creating a Template for Vue 3, Vuetify 3, and Storybook

Peshang Hiwa — Sat, 25 Feb 2023 19:34:17 +0000

When working with Vue 3 and Vuetify 3, configuring Storybook 6 can be a challenge. In fact, it's very common to encounter compatibility issues and integration problems between these frameworks. This can be especially frustrating when trying to use configurations from your own project, such as implementing dark mode in to storybook's Vuetify. Fortunately, there are strategies you can use to simplify the process and streamline your workflow.

In this article, I'll walk you through a comprehensive step-by-step guide to creating a Vue 3 project, integrating it with Vuetify 3, and configuring Storybook on top.

Initializing a Vue 3 project and integrate Vuetify 3 in to it.

Let's start by creating a new Vue 3 project and clean up the built in template inside it.


 BASH
npm init vue@latest

Integrating Vuetify 3 in to the project


 BASH
npm i vuetify
npm i @mdi/font

Create a new file in src/plugins/vuetify.ts, include all the vuetify configurations there and then export it.


 TYPESCRIPT
import { createVuetify } from "vuetify";
import type { ThemeDefinition } from "vuetify";
import "vuetify/styles";
import "@mdi/font/css/materialdesignicons.css";

import * as components from "vuetify/components";
import * as directives from "vuetify/directives";

const lightTheme: ThemeDefinition = {
  dark: false,
  colors: {
    primary: "#d35400",
    secondary: "#8e44ad",
    background: "#ecf0f1",
    error: "#c0392b",
    info: "#2980b9",
    success: "#27ae60",
    warning: "#f1c40f",
  },
};

const darkTheme: ThemeDefinition = {
  dark: true,
  colors: {
    primary: "#d35400",
    secondary: "#8e44ad",
    background: "#2f3640",
    error: "#c0392b",
    info: "#2980b9",
    success: "#27ae60",
    warning: "#f1c40f",
  },
};

export default createVuetify({
  components,
  directives,
  theme: {
    defaultTheme: "light",
    themes: {
      light: lightTheme,
      dark: darkTheme,
    },
  },
});

I have configured Light and Dark theme configurations as well.

And finally import and use the configurations in main.ts



import { createApp } from "vue";
import App from "./App.vue";
import vuetify from "./plugins/vuetify";

createApp(App).use(vuetify).mount("#app");

Installing and configuring storybook



npx storybook init

now storybook is installed and configured automatically within the project when the above script is done.

stories and .storybook directories are generated in to the project as well.

stories contains some basic components so that there are some examples to show when running npm run storybook
You can delete this folder as we don't need it, we'll create a custom component manually.

.storybook includes all the configurations for storybook

Creating a custom component and preparing stories for it.

Our component will be a simple button named MyButton inside src/components directory that will have some basic props:


 HTML
<script setup lang="ts">
import { withDefaults } from "vue";
export type Props = {
  /** Color of the button */
  color?: "primary" | "secondary" | "success" | "info" | "warning" | "error";

  /** To show a loading icon */
  loading?: boolean;

  /** the content of the button */
  content?: string;
};
withDefaults(defineProps<Props>(), {
  loading: false,
  color: "primary",
  content: "Button",
});
</script>

<template>
  <v-btn :color="color" :loading="loading">
    <!-- @slot To put any element inside the button-->
    <slot>
      {{ content }}
    </slot>
  </v-btn>
</template>

Note that the comments in the above example aren't just there for clarification purposes inside our code, but they are being displayed as descriptions for the props and slots by stories automatically.

Now according to our component we'll create a MyButton.stories.ts in the same directory of the component as below:


 Typescript
import MyButton from "./MyButton.vue";

export default {
  title: "MyButton",
  component: MyButton,
  argTypes: {
    color: {
      control: {
        options: [
          "primary",
          "secondary",
          "success",
          "info",
          "warning",
          "error",
        ],
      },
    },
    loading: {
      control: {
        type: "boolean",
      },
    },
    content: {
      control: {
        type: "text",
      },
    },
  },
};

const Template = (args) => ({
  components: { MyButton },
  setup() {
    return { args };
  },
  template: '<MyButton v-bind="args" content="click me"/>',
});

export const Primary = Template.bind({});
Primary.args = {
  color: "primary",
};

export const Secondary = Template.bind({});
Secondary.args = {
  color: "secondary",
};

export const WithLoading = Template.bind({});
WithLoading.args = {
  color: "error",
  loading: true,
};

before running storybook we'll need to add some configurations to .storybook directory as well.

Storybook configurations for vuetify

In order for vuetify to work inside storybook, some extra configurations are required.

First we need to have our own wrapper to run storybook on top it, for this purpose we'll create a file named storyWrapper.vue inside .storybook and it'll include all the HTML skeletons that are required for vuetify to run on it such as v-app:



<template>
  <v-app :theme="themeName">
    <v-main>
      <slot name="story"></slot>
    </v-main>
  </v-app>
</template>

<script>
export default {
  props: {
    themeName: String,
  },
};
</script>

Now we need to create a custom decorator for storybook so that it knows how to replace it's default wrapper with our own custom one, our decorator is named withVuetifyTheme.decorator.js inside .storybook folder.
Any custom configurations related to vuetify can be added in to this file, in our case it'll be only configuring themes.

Then we need to import and render the wrapper in an h function iside our decorator file.


 TYPESCRIPT
import { h } from "vue";
import StoryWrapper from "./storyWrapper.vue";

export const DEFAULT_THEME = "light";

export const withVuetifyTheme = (storyFn, context) => {
  // Pull our global theme variable, fallback to DEFAULT_THEME
  const themeName = context.globals.theme || DEFAULT_THEME;
  const story = storyFn();

  return () => {
    return h(
      StoryWrapper,
      // give themeName to StoryWrapper as a prop
      { themeName },
      {
        story: () => h(story, { ...context.args }),
      }
    );
  };
};

Now that our decorator is done, we only have to import it in the preview.js file as below:


 TYPESCRIPT
import { withVuetifyTheme } from "./withVuetifyTheme.decorator";
import { app } from "@storybook/vue3";
import vuetify from "../src/plugins/vuetify";

app.use(vuetify);

export const parameters = {
  actions: { argTypesRegex: "^on[A-Z].*" },
  controls: {
    expanded: true,
    sort: "requiredFirst",
  },
  docs: {
    inlineStories: false,
  },
};

export const globalTypes = {
  theme: {
    name: "vuetify.theme.defaultTheme",
    description: "Global theme for components",
    toolbar: {
      icon: "paintbrush",
      // Array of plain string values or MenuItem shape (see below)
      items: [
        { value: "light", title: "Light", left: "🌞" },
        { value: "dark", title: "Dark", left: "🌛" },
      ],
      // Change title based on selected value
      dynamicTitle: true,
    },
  },
};

export const decorators = [withVuetifyTheme];

Note that we have created a theme globalType to render a button on the toolbar of storybook in order to switch between themes for vuetify.

And now our storybook is configured with vuetify and is ready to be run:



npm run storybook

As it's clear on the toolbar you can as well switch between themes.

The repository for this project is available here, you can directly download/use the template for your project.

Thanks for reading

Publishing a Vue 3 - Typescript Component Library to GitHub Packages

Peshang Hiwa — Sun, 29 Jan 2023 20:09:48 +0000

When it comes to working in a team or an organization it often involves reusing a collection of repositories or code-bases(components) in multiple projects again and again.
To make it easier for every developer out there to access and utilize these components, it's usually recommended to publish these components to the NPM registry as public open source projects that can be reused.
However, if the components are private and only used within the scope of the organization, the best option is to use Github packages.

In this article, I'll guide you through the process of publishing a Vue 3 component library built with typescript to Github Packages, which includes the following steps:

Creating a Vue.js 3 project using Vite
Building a component of the library
Configuring Vite to package the library for publishing
Setting up Github Actions for automated publishing to Github Packages
Testing the component as a dependency in another project

Creating a Vue.js 3 project using Vite

To create a Vue 3 project using Vite, you need to initialize a Vite project in your desired directory by running this script in your command line.

npm create vite@latest

Make sure to complete the next couple steps to generate your project.
I'll name my project github-packages-ui-library and select Vue and typescript as the technologies.

Then go to the project directory and install the project dependencies using NPM (or your preferred package manager)

cd github-packages-ui-library
npm install

If you open the project now you'll get to see a fully scaffolded project that looks like this:

Now clean up the project by removing all the unnecessary files and extra codes like style files, prebuilt HelloWorld.vue component and etc...

Building a component of the library

Next I am going to build one of the components of the library as a test component and export it, whereas you can built as many components as you want.

The component needs to be in the /src/components directory and I am going to name it BaseButton.vue as shown below

<script setup lang="ts">
import { computed } from "vue";
type BaseButtonProps = {
  size?: number;
  color?: string;
};

const props = withDefaults(defineProps<BaseButtonProps>(), {
  size: 16,
  color: "skyblue",
});

const fontSize = computed(() => `${props.size}px`);
</script>

<template>
  <button id="baseButton">
    <slot />
  </button>
</template>

<style>
#baseButton {
  padding: 1rem 2rem;
  cursor: pointer;
  border: none;
  background-color: v-bind(color);
  font-size: v-bind(fontSize);
}
</style>

The component is a simple button that accepts two props, both fully typed with TypeScript: color, which must be a string, and size, which must be a number. Additionally, it has a default slot.

Next, we'll create an index.ts file in the /src directory.
This file will act as a central location to export all the library components from, as shown below.

// /src/index.ts 
export { default as BaseButton } from "./components/BaseButton.vue";

Now we can import the components from index.ts and use them like this example in /src/App.vue

<script setup lang="ts">
import { BaseButton } from "./index";
</script>

<template>
  <BaseButton> Click me </BaseButton>
</template>

And now our library is ready to be configured as a package in which we'll do in the next step

Configuring Vite to package the library for publishing

Next, we'll update the vite.config.ts file to implement the packaging process as follows:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import path from "path";

import cssInjectedByJsPlugin from "vite-plugin-css-injected-by-js";

export default defineConfig({
  plugins: [vue(), cssInjectedByJsPlugin()],
  resolve: {
    alias: {
      "@/": new URL("./src/", import.meta.url).pathname,
    },
  },

  build: {
    cssCodeSplit: true,
    target: "esnext",
    lib: {
      entry: path.resolve(__dirname, "src/index.ts"),
      name: "GithubPackagesUiLibrary",
      fileName: (format) => `github-packages-ui-library.${format}.js`,
    },

    rollupOptions: {
      external: ["vue"],
      output: {
        globals: {
          vue: "Vue",
        },
      },
    },
  },
});

Notice that both name(written in PascalCase) and fileName(written in kebab-case) are the actual name of our project, so you should replace it with your project name too

If you encountered Cannot find path or Cannot find __diranme error you will need to install @types/node as dev dependency to solve the issue

npm install -D @types/node

and you also need to install vite-plugin-css-injected-by-js as dev dependency in order to include all the CSS codes of the project in to the build

npm install -D vite-plugin-css-injected-by-js

Next we need to update the tsconfig.json file as follows:

{
  "compilerOptions": {
    "baseUrl": "./",
    "target": "esnext",
    "useDefineForClassFields": true,
    "module": "esnext",
    "moduleResolution": "node",
    "isolatedModules": true,
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "paths": {
      "@/*": ["src/*"]
    },
    "lib": ["esnext", "dom", "dom.iterable", "scripthost"],
    "skipLibCheck": true,
    "outDir": "dist",
    "declaration": true
  },
  "include": ["vite.config.*", "env.d.ts", "src/**/*", "src/**/*.vue"]
}

And tsconfig.node.json as follows:

{
  "compilerOptions": {
    "composite": true,
    "module": "ESNext",
    "moduleResolution": "Node",
    "allowSyntheticDefaultImports": true
  },
  "include": ["vite.config.ts"]
}

Next We need to update our package.json file to support our packaging as follows:

{
  "files": [
    "dist"
  ],
  "main": "./dist/github-packages-ui-library.umd.js",
  "module": "./dist/github-packages-ui-library.es.js",
  "exports": {
    ".": {
      "import": "./dist/github-packages-ui-library.es.js",
      "require": "./dist/github-packages-ui-library.umd.js"
    }
  },
  "types": "./dist/types/index.d.ts",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com/@peshanghiwa"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/peshanghiwa/github-packages-ui-library"
  },
  "scripts": {
    "dev": "vite",
    "build": "vite build && vue-tsc --emitDeclarationOnly && mv dist/src dist/types",
    "preserve": "vite build",
    "serve": "vite preview --port 5050",
    "typecheck": "vue-tsc --noEmit",
    "preview": "vite preview",
    "test": "exit 0"
  },
  "name": "@peshanghiwa/github-packages-ui-library",
  "version": "0.0.0",
  "type": "module",
  "dependencies": {
    "vue": "^3.2.45"
  },
  "devDependencies": {
    "@types/node": "^18.11.18",
    "@vitejs/plugin-vue": "^4.0.0",
    "typescript": "^4.9.3",
    "vite": "^4.0.0",
    "vue-tsc": "^1.0.11"
  }
}

You must replace all the github-packages-ui-library with the name of your library and peshanghiwa with your own github username in the above file (You must include the @ character too in the username: @YOURUSERNAME)

and lastly create a .npmrc in the root directory as follows:

@peshanghiwa:registry=https://npm.pkg.github.com

and replcae peshanghiwa with your github username

Setting up Github Actions for automated publishing to Github Packages

Next we need to create a github actions to generate and automate the building and publishing of our package into github packages registry

Create a .github/workflows/release-package.yml in the root directory as below

name: Github Packages UI Library Actions

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
      - run: npm ci
      - run: npm test

  publish-gpr:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      packages: write
      contents: read
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 16
          registry-url: https://npm.pkg.github.com/
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

This is a sample of Github Actions workflow that will run two jobs for us: build and publish-gpr to build and publish the package to Github Packages Registry.

The action will trigger each time code is pushed to the main branch, but you can modify this behavior by referring to Github Actions Workflow Syntax.

After pushing the final changes to the main branch, the Github Actions workflow will automatically start. You can monitor the workflow's progress in the Actions section of the Github page.

As shown in the image above, both jobs ran successfully and the library is now registered in Github Packages. To verify, you can check the main repository page and see that a "Packages" section has been added to the sidebar, as shown in the below image.

Testing the component as a dependency in another project

Our package is now on Github Packages and ready to be used privately in another project or repository, accessible only by us. To use it, we need to generate a Github token for this purpose.
Go to the Developer Settings and generate a token with only the read:packages permission, as shown in the following image.

Now create another vue.js project so that we can install our package at.
Next create a .npmrc file in the root directory of the newly created vue.js project and paste the follwoing code:

@peshanghiwa:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GENERATED_GITHUB_TOKEN_HERE

change the peshanghiwa to your github username and paste your secret github token too

Next you can install your package using npm in the terminal as below:

npm install @peshanghiwa/github-packages-ui-library

And you can now import and use the package just like any other dependency in your project as shown below:

The build includes complete typescript support and the props are properly typed.