@md-plugins/vite-examples-plugin 0.1.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-present, Jeff Galbraith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# @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:
+
+```bash
+# npm
+npm install @md-plugins/vite-examples-plugin
+
+# yarn
+yarn add @md-plugins/vite-examples-plugin
+
+# pnpm
+pnpm add @md-plugins/vite-examples-plugin
+```
+
+## Usage
+
+### Basic Setup with Vite
+
+To use the `viteExamplesPlugin`, configure it in your Vite project:
+
+```js
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { viteExamplesPlugin } from '@md-plugin/vite-examples-plugin';
+
+export default defineConfig({
+  plugins: [vue(), viteExamplesPlugin('/absolute/path/to/examples')],
+});
+```
+
+### Manual Chunk Splitting with Vite
+
+```js
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { viteExamplesPlugin, viteManualChunks } from 'vite-examples-plugin';
+
+export default defineConfig({
+  plugins: [vue(), viteExamplesPlugin('/absolute/path/to/examples')],
+  build: {
+    chunkSizeWarningLimit: 650,
+    rollupOptions: {
+      output: {
+        manualChunks: viteManualChunks,
+      },
+    },
+  },
+});
+```
+
+## Quasar Framework Configuration
+
+1. Update `quasar.config.(js|ts)`:
+
+```js
+import { viteExamplesPlugin } from '@md-plugin/vite-examples-plugin';
+
+export default defineConfig((ctx) => {
+  // ...
+```
+
+```js
+  build: {
+    vitePlugins: [
+      viteExamplesPlugin(ctx.appPaths.srcDir + '/examples'),
+      // ...
+    ],
+  },
+}
+```
+
+### Manual Chunk Splitting with Quasar
+
+```js
+import {
+  viteExamplesPlugin,
+  viteManualChunks,
+} from '@md-plugins/vite-examples-plugin';
+```
+
+```js
+  build: {
+    extendViteConf(viteConf, { isClient }) {
+      if (ctx.prod && isClient) {
+        if (!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:
+
+```bash
+node_modules/vue/index.js
+src/examples/example1/Example1.vue
+src/examples/example2/Example2.vue
+```
+
+The resulting chunks might look like:
+
+```bash
+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
+
+```bash
+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:
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+throw new Error('targetFolder is not defined');
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/dist/index.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Creates a Vite plugin for handling Markdown examples.
+ *
+ * This function sets up the target folder for example files and returns a function
+ * that creates the actual Vite plugin. The returned plugin resolves and loads
+ * example code based on the production or development environment.
+ *
+ * @param path - The path to the directory containing the example files.
+ *               This path will be used as the target folder for resolving examples.
+ *
+ * @returns A function that creates a Vite plugin. This function takes a boolean
+ *          parameter indicating whether the build is in production mode and
+ *          returns the configured Vite plugin object.
+ */
+declare function viteExamplesPlugin(path: string): (isProd: boolean) => {
+    name: string;
+    enforce: 'pre';
+    resolveId(id: string): string | undefined;
+    load(id: string): string | undefined;
+};
+
+/**
+ * A function to determine the manual chunk name for a given module ID.
+ *
+ * @param id - The module ID to analyze.
+ * @returns A string representing the chunk name or `undefined`.
+ */
+declare function viteManualChunks(id: string): string | undefined;
+
+export { viteExamplesPlugin, viteManualChunks };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Creates a Vite plugin for handling Markdown examples.
+ *
+ * This function sets up the target folder for example files and returns a function
+ * that creates the actual Vite plugin. The returned plugin resolves and loads
+ * example code based on the production or development environment.
+ *
+ * @param path - The path to the directory containing the example files.
+ *               This path will be used as the target folder for resolving examples.
+ *
+ * @returns A function that creates a Vite plugin. This function takes a boolean
+ *          parameter indicating whether the build is in production mode and
+ *          returns the configured Vite plugin object.
+ */
+declare function viteExamplesPlugin(path: string): (isProd: boolean) => {
+    name: string;
+    enforce: 'pre';
+    resolveId(id: string): string | undefined;
+    load(id: string): string | undefined;
+};
+
+/**
+ * A function to determine the manual chunk name for a given module ID.
+ *
+ * @param id - The module ID to analyze.
+ * @returns A string representing the chunk name or `undefined`.
+ */
+declare function viteManualChunks(id: string): string | undefined;
+
+export { viteExamplesPlugin, viteManualChunks };

package/dist/index.mjs

@@ -0,0 +1,68 @@
+import { join } from 'node:path';
+import { globSync } from 'tinyglobby';
+
+const moduleIdRE = /^examples:/;
+const resolvedIdPrefix = "\0examples:";
+let targetFolder = "";
+function devLoad(id) {
+  if (id.startsWith(resolvedIdPrefix)) {
+    const query = `'/src/examples/${id.substring(id.indexOf(":") + 1)}/*.vue'`;
+    return `export const code = import.meta.glob(${query}, { eager: true })
+export const source = import.meta.glob(${query}, { query: '?raw', import: 'default', eager: true })`;
+  }
+  return void 0;
+}
+function prodLoad(id) {
+  if (id.startsWith(resolvedIdPrefix)) {
+    const exampleId = id.substring(id.indexOf(":") + 1);
+    const files = globSync("*.vue", { cwd: join(targetFolder, exampleId) });
+    const importList = files.map(
+      (entry) => entry.substring(0, entry.length - 4)
+    );
+    const importStatements = importList.map(
+      (entry) => `import ${entry} from 'app/src/examples/${exampleId}/${entry}.vue'
+import Raw${entry} from 'app/src/examples/${exampleId}/${entry}.vue?raw'`
+    ).join("\n");
+    const exportStatements = importList.map((entry) => `${entry},Raw${entry}`).join(",");
+    return importStatements + `
+export {${exportStatements}}`;
+  }
+  return void 0;
+}
+function vitePlugin(isProd) {
+  if (!targetFolder) {
+    throw new Error("targetFolder is not defined");
+  }
+  return {
+    name: "markdown-examples",
+    enforce: "pre",
+    // before vue
+    resolveId(id) {
+      if (moduleIdRE.test(id)) {
+        return "\0" + id;
+      }
+      return void 0;
+    },
+    load: isProd ? prodLoad : devLoad
+  };
+}
+function viteExamplesPlugin(path) {
+  targetFolder = path;
+  return vitePlugin;
+}
+
+const vendorRE = /node_modules[\\/](vue|@vue|quasar|vue-router)[\\/](.*)\.(m?js|css|sass)$/;
+const exampleRE = /examples:([a-zA-Z0-9]+)$|src[\\/]examples[\\/]([a-zA-Z0-9-]+)/;
+function viteManualChunks(id) {
+  if (vendorRE.test(id)) {
+    return "vendor";
+  }
+  const examplesMatch = exampleRE.exec(id);
+  if (examplesMatch !== null) {
+    const name = examplesMatch[1] || examplesMatch[2];
+    return `e.${name}`;
+  }
+  return void 0;
+}
+
+export { viteExamplesPlugin, viteManualChunks };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@md-plugins/vite-examples-plugin",
+  "version": "0.1.0-alpha.1",
+  "description": "A Vite plugin for @md-plugins for handling imported examples in markdown files.",
+  "keywords": [
+    "markdown-it",
+    "quasarframework",
+    "vue",
+    "utils",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/md-plugins",
+  "bugs": {
+    "url": "https://github.com/md-plugins/md-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/md-plugins/md-plugins.git"
+  },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "./dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tinyglobby": "^0.2.10"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "clean": "rm -rf dist"
+  }
+}