Compodium

A plug and play component playground for Nuxt.

Try it live!

Warning

This project is in its early stages and will evolve. Expect frequent updates and potential changes. Feedback is welcome!

Features

• Easy Setup and Use: Easily integrates into your Nuxt app with minimal configuration. Customize only when needed by creating examples or defining default props.
• HMR Support: Enables real-time updates with HMR for faster development.
• Default UI Collections: Comes with pre-configured collections for your UI libraries.

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add compodium

That's it! You can now access Compodium from the nuxt devtools or /__compodium__/devtools.

Configuration

Configure Compodium in your Nuxt project by customizing the settings in your nuxt.config.ts file. Below is the default configuration, which you can modify to suit your needs:

export default defineNuxtConfig({
  compodium: {
    /* Customize compodium's base directory */
    dir: 'compodium/',

    /* List of glob patterns to exclude components */
    exclude: [],

    /* Whether to include default collections for third-party libraries. */
    includeLibraryCollections: true,

    extras: {
      ui: {
        /* If true, Compodium's UI will match your Nuxt UI color theme */
        matchColors: true
      }
    }
  }
})

Preview Component

Compodium renders your components in an isolated preview component that is mounted into your Nuxt application. You can customize this preview component by creating your own in compodium/preview.vue.

Here's the default preview component you can start from:

<template>
  <div id="compodium-preview">
    <slot />
  </div>
</template>

<style>
html {
  background: var(--ui-bg, white);
}

html.dark {
  background: var(--ui-bg, #18181b);
}

body {
  margin: 0;
  padding: 0;
}

#compodium-preview {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 100vh;
  width: 100vw;
  padding: 20px;
}
</style>

Note

Compodium renders outside of your app.vue component. This is useful if you need to inject CSS or provide parent components.

Component Examples

You can provide examples for your components in the compodium/examples/ folder. Examples will be matched to components based on the filename. Each example must be named after its corresponding component, followed by the Example keyword and an optional label.

compodium
└── examples
    ├── BaseInputExampleDisabled.vue    # Will be added to the BaseInput component.
    ├── BaseButtonExample.vue           # Will be the main example for the BaseButton component.
    └── BaseButtonExampleWithLabel.vue  # Will be added to the BaseButton component.

Default Props

You can use the extendCompodiumMeta in your component or in examples to pass default values for required properties:

const props = defineProps<{ label: string }>()

extendCompodiumMeta({
  defaultProps: {
    label: 'Click me!'
  }
})

Warning

extendCompodiumMeta is a macro that is evaluated at compile time. As such, you can only use literal values, and can't reference variables.

Alternatively, you can specify default properties for your components in your app.config.ts file:

export default defineAppConfig({
  compodium: {
    components: {
      baseButton: {
        label: 'Click me!'
      }
    }
  }
})

Contribution

Contributions are welcome! ♥️

Currently, one way you can contribute is by adding examples for your favorite component library. You can find the Nuxt UI collection and examples here.

Local development

# Install dependencies
pnpm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Run ESLint
pnpm lint

# Run typechecks 
pnpm typechecks 

# Run Vitest
pnpm test
pnpm test:watch