@md-plugins/vite-examples-plugin

A Vite plugin that facilitates handling Vue example files in both development and production modes. The plugin allows you to load and transform example components and their raw source code for usage in your application.

Features

• Supports loading Vue example files dynamically during development.
• Generates import and export statements for Vue example files in production.
• Easily handles raw and compiled component imports.
• Enables seamless integration of example files into your project.

Installation

Install the plugin via your preferred package manager:

1# with pnpm
2pnpm add @md-plugins/vite-examples-plugin
3# with yarn
4yarn add @md-plugins/vite-examples-plugin
5# with npm
6npm install @md-plugins/vite-examples-plugin

Usage

Basic Setup with Vite

To use the viteExamplesPlugin, configure it in your Vite project:

1import { defineConfig } from 'vite'
2import vue from '@vitejs/plugin-vue'
3import { viteExamplesPlugin, viteManualChunks } from 'vite-examples-plugin'
4
5export default defineConfig(({ mode }) => {
6  const isProduction = mode === 'production'
7
8  return {
9    plugins: [
10      vue(),
11      viteExamplesPlugin({ isProd: isProduction, path: '/absolute/path/to/examples' }),
12    ],
13  }
14})

Manual Chunk Splitting with Vite

1import { defineConfig } from 'vite'
2import vue from '@vitejs/plugin-vue'
3import { viteExamplesPlugin, viteManualChunks } from 'vite-examples-plugin'
4
5export default defineConfig(({ mode }) => {
6  const isProduction = mode === 'production'
7
8  return {
9    plugins: [
10      vue(),
11      viteExamplesPlugin({ isProd: isProduction, path: '/absolute/path/to/examples' }),
12    ],
13    build: {
14      chunkSizeWarningLimit: 650,
15      rollupOptions: {
16        output: {
17          manualChunks: viteManualChunks,
18        },
19      },
20    },
21  },
22})

Quasar Framework Configuration

1. Update quasar.config.(js|ts):

1import { viteExamplesPlugin } from '@md-plugin/vite-examples-plugin';
2
3export default defineConfig((ctx) => {
4  // ...

1  build: {
2    vitePlugins: [
3      viteExamplesPlugin({ isProd: ctx.isProd, path: ctx.appPaths.srcDir + '/examples' }),
4      // ...
5    ],
6  },
7}

Manual Chunk Splitting with Quasar

1import { viteExamplesPlugin, viteManualChunks } from '@md-plugins/vite-examples-plugin'

1  build: {
2    extendViteConf(viteConf, { isClient }) {
3      if (ctx.prod && isClient) {
4        viteConf.build = viteConf.build || {}
5        viteConf.build.chunkSizeWarningLimit = 650
6        viteConf.build.rollupOptions = {
7          output: { manualChunks: viteManualChunks },
8        }
9      }
10    },
11  }

How viteManualChunks Works

The viteManualChunks function analyzes the module ID and assigns it to a specific chunk:

1. Vendor Chunk: Files from node_modules matching libraries like vue, @vue, quasar, and vue-router are assigned to the vendor chunk.

2. Examples Chunk: Example files matching the pattern examples:<name> or located in src/examples/<name> are grouped into chunks named e.<name>.

Example

Given the following files:

1node_modules/vue/index.js
2src/examples/example1/Example1.vue
3src/examples/example2/Example2.vue

The resulting chunks might look like:

1vendor.js         // Contains Vue, Quasar, Vue Router, etc.
2e.example1.js     // Contains Example1.vue
3e.example2.js     // Contains Example2.vue

This helps facilitate loading and chunking in your application for your examples.

Example Folder Structure

1src/
2  examples/
3    example1/
4      Example1.vue
5    example2/
6      Example2.vue

How It Works

The plugin provides two modes of operation based on the environment:

Development Mode

During development, the plugin uses Vite's import.meta.glob to dynamically load Vue example components and their raw source code:

1export const code = import.meta.glob('/src/examples/example1/*.vue', {
2  eager: true,
3})
4export const source = import.meta.glob('/src/examples/example1/*.vue', {
5  query: '?raw',
6  import: 'default',
7  eager: true,
8})

Production Mode

In production, the plugin preloads example components and their raw source code, generating import and export statements:

1import Example1 from 'app/src/examples/example1/Example1.vue'
2import RawExample1 from 'app/src/examples/example1/Example1.vue?raw'
3
4export { Example1, RawExample1 }

Development Notes

The plugin is structured with the following components:

1. devLoad Function Generates dynamic imports for example files during development.

2. prodLoad Function Creates preloaded import and export statements for example files in production.

3. vitePlugin Function Constructs the Vite plugin with resolveId and load methods.

4. viteExamplesPlugin Function Sets the target folder and initializes the plugin.

Error Handling

If the targetFolder is not defined when the plugin is initialized, an error will be thrown:

1throw new Error('targetFolder is not defined')

Documentation

In case this README falls out of date, please refer to the documentation for the latest information.

License

This project is licensed under the MIT License. See the LICENSE file for details.