@md-plugins/vite-examples-plugin v0.1.0-alpha.29

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

# with pnpm
pnpm add @md-plugins/vite-examples-plugin
# with yarn
yarn add @md-plugins/vite-examples-plugin
# with npm
npm install @md-plugins/vite-examples-plugin

Usage

Basic Setup with Vite

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

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { viteExamplesPlugin, viteManualChunks } from 'vite-examples-plugin'

export default defineConfig(({ mode }) => {
  const isProduction = mode === 'production'

  return {
    plugins: [
      vue(),
      viteExamplesPlugin({ isProd: isProduction, path: '/absolute/path/to/examples' }),
    ],
  }
})

Manual Chunk Splitting with Vite

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { viteExamplesPlugin, viteManualChunks } from 'vite-examples-plugin'

export default defineConfig(({ mode }) => {
  const isProduction = mode === 'production'

  return {
    plugins: [
      vue(),
      viteExamplesPlugin({ isProd: isProduction, path: '/absolute/path/to/examples' }),
    ],
    build: {
      chunkSizeWarningLimit: 650,
      rollupOptions: {
        output: {
          manualChunks: viteManualChunks,
        },
      },
    },
  },
})

Quasar Framework Configuration

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

import { viteExamplesPlugin } from '@md-plugin/vite-examples-plugin';

export default defineConfig((ctx) => {
  // ...

  build: {
    vitePlugins: [
      viteExamplesPlugin({ isProd: ctx.isProd, path: ctx.appPaths.srcDir + '/examples' }),
      // ...
    ],
  },
}

Manual Chunk Splitting with Quasar

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

  build: {
    extendViteConf(viteConf, { isClient }) {
      if (ctx.prod && isClient) {
        viteConf.build = viteConf.build || {}
        viteConf.build.chunkSizeWarningLimit = 650
        viteConf.build.rollupOptions = {
          output: { manualChunks: viteManualChunks },
        }
      }
    },
  }

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:

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

The resulting chunks might look like:

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

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

Example Folder Structure

src/
  examples/
    example1/
      Example1.vue
    example2/
      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:

export const code = import.meta.glob('/src/examples/example1/*.vue', {
  eager: true,
})
export const source = import.meta.glob('/src/examples/example1/*.vue', {
  query: '?raw',
  import: 'default',
  eager: true,
})

Production Mode

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

import Example1 from 'app/src/examples/example1/Example1.vue'
import RawExample1 from 'app/src/examples/example1/Example1.vue?raw'

export { 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:

throw 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.