Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
160 changes: 49 additions & 111 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,9 @@
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]

A plug and play component playground for Nuxt.
A plug and play component playground for Vue and Nuxt.

<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/7e354f8f-72cb-43ee-bbc3-857bb665e841">
<source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/e743a4c6-4845-4320-9cef-437e3890f05b">
<img alt="Compodium" src="https://github.com/user-attachments/assets/e743a4c6-4845-4320-9cef-437e3890f05b">
</picture>
[Documentation](https://compodium.dev/getting-started)

</div>

Expand All @@ -22,132 +18,76 @@ A plug and play component playground for Nuxt.

## 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.
- **Effortless Setup**: Simple setup process and minimal maintenance, allowing you to focus on building components.
- **No Stories Required**: Analyzes your component code directly, eliminating the need to write stories.
- **Fast**: Built on top of Vite for rapid development and instant feedback, enhancing productivity.
- **DevTools Integration**: Integrates with Vue and Nuxt devtools for a cohesive development experience.
- **UI Library Integrations**: Integrates with popular UI libraries, showcasing examples for locally installed components.
- **Code generation**: Generates up-to-date template code based on component props, ready to copy and use instantly.

## Quick Setup

Install the module to your Nuxt application with one command:
## Installation

```bash
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:

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

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

/* 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
}
}
}
})
```bash [pnpm]
nuxi module add -D @compodium/nuxt
```

### 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:

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

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

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

body {
margin: 0;
padding: 0;
}
1. Install `@compodium/vue`

#compodium-preview {
display: flex;
justify-content: center;
align-items: center;
height: 100vh;
width: 100vw;
padding: 20px;
}
</style>
```bash [pnpm]
pnpm add -D @compodium/vue
```

> [!NOTE]
> Compodium renders outside of your `app.vue` component. This is useful if you need to inject CSS or provide parent components.

### Component Examples
```bash [yarn]
yarn add --dev @compodium/vue
```

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.
```bash [npm]
npm install --save-dev @compodium/vue
```

```bash
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.
```bash [bun]
bun add -D @compodium/vue
```

### Default Props
2. Add the Compodium plugin in your `vite.config.ts`:

You can use the `extendCompodiumMeta` in your component or in examples to pass default values for required properties:
```ts
const props = defineProps<{ label: string }>()
```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'
import { compodium } from '@compodium/vue'

extendCompodiumMeta({
defaultProps: {
label: 'Click me!'
}
export default defineConfig({
plugins: [
vue(),
vueDevTools(),
compodium()
]
})
```
> [!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:

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

3. Include compodium types in your `tsconfig.app.json`

```json [tsconfig.app.json]{6}
{
"include": [
"src/**/*.ts",
"src/**/*.tsx",
"src/**/*.vue",
"node_modules/@compodium/vue/dist/index.d.ts"
],
}
```

## 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](https://github.com/romhml/compodium/tree/main/src/runtime/libs).
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](https://github.com/romhml/compodium/tree/main/packages/examples/src/index.ts).

**Local development**

Expand All @@ -169,10 +109,8 @@ pnpm typechecks

# Run Vitest
pnpm test
pnpm test:watch
```


<!-- Badges -->
[npm-version-src]: https://img.shields.io/npm/v/compodium/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/compodium
Expand Down
8 changes: 5 additions & 3 deletions docs/content/1.getting-started/2.installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,10 @@ navigation.icon: i-lucide-download
pnpm add -D @compodium/nuxt
```
```bash [npm]
npm add -D @compodium/nuxt
npm install --save-dev @compodium/nuxt
```
```bash [yarn]
yarn add -D @compodium/nuxt
yarn add --dev @compodium/nuxt
```
```bash [bun]
bun add -D @compodium/nuxt
Expand Down Expand Up @@ -50,7 +50,7 @@ That's it! You can now access compodium from the Nuxt Devtools or on `/__compodi
pnpm add -D @compodium/vue
```
```bash [npm]
npm add -D @compodium/vue
npm install -D @compodium/vue
```
```bash [yarn]
yarn add -D @compodium/vue
Expand All @@ -65,11 +65,13 @@ bun add -D @compodium/vue
```ts [vite.config.ts]{3,8}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools'
import { compodium } from '@compodium/vue'

export default defineConfig({
plugins: [
vue(),
vueDevTools(),
compodium()
]
})
Expand Down
2 changes: 2 additions & 0 deletions packages/core/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
},
"keywords": [
"nuxt",
"vue",
"vite",
"components",
"documentation"
],
Expand Down
2 changes: 1 addition & 1 deletion packages/vue/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"directory": "packages/vue"
},
"keywords": [
"nuxt",
"vue",
"components",
"documentation"
],
Expand Down
Loading