Getting Started ​

Requirements ​

Viteplay is only available for Vite projects.

It currently only supports Vue based projects, but in the future we plan to support React & Svelte as well. (Maintainers welcome!)

Vue Setup ​

Install these dev dependencies:

npm i -D @viteplay/plugin @viteplay/vue

Then you need to add 2 snippets of code to your vite and vue-router config.

Vite Config ​

In vite.config.ts (or .js) add this:

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

export default defineConfig({
  plugins: [
    vue(),
    viteplay({
      // Path to extract components from
      components: "./components/*/*.vue",
      // Path to extract examples from, relative to component path
      componentExamples: "./examples/*.vue",
      // base route for the development pages
      base: "/dev",
    }),
  ],
})

This will auto-detect all your nested components in the components folder. (see config examples for more examples on different folder structures)

Vue Router ​

Add Vue Router to your project if you haven't already.

In your Vue Router config file, add this:

import { createRouter, createWebHistory } from "vue-router"
import { pages as pagesVitePlay } from "@viteplay/vue/client"
import "@viteplay/vue/dist/style.css"

console.log(`VitePlay routes for development → `, pagesVitePlay)

export const router = createRouter({
  history: createWebHistory(), // or whatever your project has already
  routes: [
    ...pagesVitePlay,
    // your other routes here...
  ],
})

That's all! Now you have a fully auto-generated development environment for your components. Just visit /dev on your localhost server and start writing component examples!

Detecting your components ​

Depending on how you want to organise your components folder, you might need a different setup in viteplay({ ... }) (in vite.config.ts or .js). Please see Config Examples below for an idea for different folder structures.

First time setting up Vue Router? ​

If you hadn't already added vue-router to your Vite project, it's really easy to do so:

1. npm i vue-router
2. Save the snippet above as router.ts (or .js) in your src folder.
3. in src/main.ts (or .js) add import { router } from './router' and createApp(App).use(router) before .mount('#app')
4. in src/App.vue make sure it has <router-view /> in the template.

That's all!

Please check the Vue Router documentation for more information on Vue Router.

Config Examples ​

Here are some examples of common folder structures used in projects, along side the required setup for VitePlay.

One Folder per Component (recommended) ​

The great thing about this folder structure in that you can keep on adding component examples without them getting in the way. It's also easy to add automated test files inside each component folder when necessary. Keeping related files together is highly recommended.

/src
└─ /components
   ├─ /MyButton
   │  ├─ MyButton.vue (or .jsx / .tsx)
   │  └─ /examples
   │     ├─ Basic.vue
   │     └─ Dark Mode.vue
   └─ /MyInput
      ├─ MyInput.vue
      └─ /examples
         ├─ Basic.vue
         └─ Search.vue

// vite.config.ts (or .js)

// in plugins: [ ... ]
viteplay({
  components: "./src/components/*/*.vue", // or .jsx / .tsx
  componentExamples: "./examples/*.vue", // or .jsx / .tsx
})

One Folder per Component — examples with . notation ​

/src
└─ /components
   ├─ /MyButton
   │  ├─ MyButton.vue (or .jsx / .tsx)
   │  ├─ Basic.example.vue
   │  └─ Dark Mode.example.vue
   └─ /MyInput
      ├─ MyInput.vue
      ├─ Basic.example.vue
      └─ Search.example.vue

// vite.config.ts (or .js)

// in plugins: [ ... ]
viteplay({
  components: "./src/components/*/*.vue", // or .jsx / .tsx
  componentExamples: "./*.example.vue", // or .jsx / .tsx
})

All in Components Folder — examples with . notation ​

/src
└─ /components
   ├─ MyButton.vue (or .jsx / .tsx)
   ├─ MyButton.Basic.vue
   ├─ MyButton.Dark Mode.vue
   ├─ MyInput.vue
   ├─ MyInput.Basic.vue
   └─ MyInput.Search.vue

// vite.config.ts (or .js)

// in plugins: [ ... ]
viteplay({
  components: "./src/components/*.vue", // or .jsx / .tsx
  componentExamples: ({ name }) => `./${name}.*.vue`, // or .jsx / .tsx
})

Only Show Specific Components ​

Instead of auto-detecting components, you can also configure VitePlay to only show specific components/examples on the dev page.

/src
└─ /button
   ├─ MyButton.vue (or .jsx / .tsx)
   ├─ Basic.example.vue
   ├─ Dark Mode.example.vue
└─ /input
   ├─ MyInput.vue
   ├─ Basic.example.vue
   └─ Search.example.vue

// vite.config.ts (.js)

// in plugins: [ ... ]
viteplay({
  pages: [
    {
      title: "My Button", // (optional) defaults to the component name
      component: "./src/button/MyButton.vue", // or .jsx / .tsx
      examples: "./*.example.vue", // or .jsx / .tsx
    },
    {
      title: "My Input", // (optional) defaults to the component name
      component: "./src/input/MyInput.vue", // or .jsx / .tsx
      examples: "./*.example.vue", // or .jsx / .tsx
    },
  ],
})