https://github.com/drunomics/nuxt-component-preview
https://github.com/drunomics/nuxt-component-preview
Last synced: 10 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/drunomics/nuxt-component-preview
- Owner: drunomics
- Created: 2025-06-13T22:26:54.000Z (12 months ago)
- Default Branch: 1.x
- Last Pushed: 2025-06-14T22:25:34.000Z (12 months ago)
- Last Synced: 2025-07-17T21:13:53.440Z (11 months ago)
- Language: TypeScript
- Size: 154 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Nuxt Component Preview
[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[](https://github.com/drunomics/nuxt-component-preview/actions/workflows/ci.yml)
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]
> A Nuxt module by [drunomics](https://drunomics.com/en) for previewing Vue components in external contexts (like iframes or separate HTML pages). Originally developed for use with decoupled Drupal environments, but can be used with any backend.
- [✨ Release Notes](/CHANGELOG.md)
## Features
- 🎭 **Component Preview Mode**: Conditionally render components for previewing in isolation
- 🚀 **Production Safe**: Inactive by default, only activates when explicitly enabled
- 🎯 **Target Rendering**: Render components to specific DOM elements using CSS selectors
- 🧪 **Testing Ready**: Comprehensive test coverage and playground setup
## Quick Setup
Install the module to your Nuxt application:
```bash
npm install nuxt-component-preview
```
Add it to your `nuxt.config.ts`:
```ts
export default defineNuxtConfig({
modules: [
'nuxt-component-preview',
],
// Optionally configure here
// componentPreview: { ... }
})
```
## Usage
### Rendering Component Previews
To render a component preview, use the `` component in your app.
**Example `app.vue`**
```vue
```
**Important:** Then, when rendering outside of a Nuxt app (e.g., in a static HTML file or external context), you must manually set the runtime config on `window.__NUXT__` before loading the Nuxt entry script to activate it. See the [playground/public/preview-test.html](./playground/public/preview-test.html) for a working example.
#### Example: Setting runtime config in a static HTML file
```html
window.__NUXT__ = window.__NUXT__ || {};
window.__NUXT__.config = {
public: {
componentPreview: true
}
};
```
You can then load the Nuxt entry script as shown in [preview-test.html](./playground/public/preview-test.html).
This setup is ideal for integrating with a Drupal backend (or any backend) that needs to render Nuxt components in isolation, such as for CMS previews or design systems.
**Example: Rendering a component preview via JavaScript**
You can use the `$previewComponent` method on the Nuxt app instance to dynamically render a component into a target element. For example, in a static HTML file:
```html
window.addEventListener('nuxt-component-preview:ready', (event) => {
const { nuxtApp } = event.detail;
console.log('Nuxt Component Preview is ready!');
// Preview TestMarkup component
nuxtApp.$previewComponent(
'TestMarkup',
{
content: `
<div style="color: blue;">
<h2>Rendered HTML Content</h2>
<p>This is <strong>HTML</strong> content rendered through the TestMarkup component.</p>
</div>
`
},
'#preview-target-1'
);
// ...more examples in preview-test.html
});
```
See [playground/public/preview-test.html](./playground/public/preview-test.html) for a full working example including multiple components and targets.
## Testing
This module includes comprehensive tests. To run them:
```bash
npm run test
```
## Releasing
Run command
```bash
npm run release -- --release-as 1.0.0-alpha.1
```
## About
This module is maintained by [drunomics](https://drunomics.com/en) and inspired by the needs of decoupled Drupal projects, such as [nuxtjs-drupal-ce](https://github.com/drunomics/nuxtjs-drupal-ce).
---
[npm-version-src]: https://img.shields.io/npm/v/nuxt-component-preview/latest.svg?style=flat-square
[npm-version-href]: https://npmjs.com/package/nuxt-component-preview
[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-component-preview.svg?style=flat-square
[npm-downloads-href]: https://npmjs.com/package/nuxt-component-preview
[license-src]: https://img.shields.io/npm/l/nuxt-component-preview.svg?style=flat-square
[license-href]: https://npmjs.com/package/nuxt-component-preview
[nuxt-src]: https://img.shields.io/badge/Nuxt-3-green.svg
[nuxt-href]: https://nuxt.com