tonka-vite-plugin 1.10.0 → 1.21.0

package/README.md

@@ -1 +1,85 @@
-# inertia-vite-plugin
+# Tonka Vite Plugin 🔌
+
+The official Vite plugin for the [**Tonka Framework**](https://clicalmani.github.io/tonka).
+
+This plugin automates the configuration of Vite for applications using **InertiaJS** and **React**. It handles the tedious setup of entry points, build directories, SSR (Server-Side Rendering), and asset manifest generation, ensuring your frontend and backend work together seamlessly.
+
+## 🌟 Features
+
+*   ⚙️ **Zero-Config Setup**: Automatically configures input files, output directories, and the manifest (`manifest.json`) required by the backend.
+*   🚀 **SSR Support**: Built-in configuration for Server-Side Rendering to enable instant initial page loads.
+*   🔄 **HMR Ready**: Supports React Fast Refresh configuration.
+*   🛣️ **Smart Aliases**: Defaults to a clean `@` alias for your project root or custom paths.
+*   📦 **TypeScript**: Fully typed with TypeScript for a great developer experience.
+
+## 📦 Installation
+
+Since this is a local plugin specific to your Tonka setup, copy the plugin file into your project root.
+
+1.  Create a file named `tonka-vite-plugin.ts` (or `.js`) in your project root.
+2.  Paste the code provided in the documentation into this file.
+
+## 🚀 Quick Start
+
+Import the plugin into your `vite.config.ts` to activate it.
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tonka from './tonka-vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    tonka({
+      // Entry points for the build
+      input: ['resources/css/app.css', 'resources/js/app.tsx'],
+      
+      // Enable Server-Side Rendering
+      ssr: 'resources/js/ssr.tsx',
+      
+      // Enable React Fast Refresh
+      refresh: true,
+    }),
+    react(),
+  ],
+});
+```
+
+## ⚙️ Configuration Options
+
+The plugin accepts a configuration object to customize its behavior.
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `input` | `string \| string[] \| Record` | `['resources/css/app.css', 'resources/js/app.tsx']` | The entry points for the build. Maps to `rollupOptions.input`. |
+| `ssr` | `string \| false` | `false` | The entry point file for the SSR build. Set to the path of your SSR entry file (e.g., `resources/js/ssr.tsx`) to enable SSR. |
+| `refresh` | `boolean` | `false` | Enables support for React Fast Refresh (HMR). Note: The actual script injection is handled by the backend `@vite` directive. |
+| `outDir` | `string` | `'public/build'` | The directory where the compiled assets will be output. |
+| `assetsDir` | `string` | `'assets'` | The directory inside `outDir` to place assets. |
+| `manifest` | `boolean` | `true` | Whether to generate a `manifest.json` file in the output directory. Required for the backend `@vite` directive. |
+| `alias` | `Record<string, string>` | `{ '@': '.' }` | Path aliases for module resolution. |
+
+## 🔍 How it Works
+
+### 1. Build Configuration
+When you run `npm run build`, the plugin automatically configures Rollup (the bundler inside Vite) to output your files to `public/build` (or your specified `outDir`) and generates a `manifest.json` that maps your source files (e.g., `resources/js/app.tsx`) to their hashed filenames (e.g., `app.a1b2c.js`).
+
+### 2. SSR Support
+If you provide an `ssr` entry point, the plugin configures Vite to perform a second build specifically for the server. This allows your backend (Tonka) to render the initial page state on the server for faster load times and SEO.
+
+### 3. Integration with Backend
+The plugin prepares the assets, but the **injection** of the `<script>` tags into the HTML is handled by your backend (Tonka) via the `@vite` Blade directive. This ensures that the correct script source is used:
+*   **Dev**: Points to `http://localhost:5173/@vite/client` (for HMR).
+*   **Prod**: Points to `/build/assets/xxxxx.js` (using the manifest).
+
+## 🛠️ Development vs Production
+
+**In Development:**
+The plugin ensures the dev server runs on port 5173 and resolves aliases correctly. It relies on the backend to proxy requests or inject the client script.
+
+**In Production:**
+The plugin is essential to correctly generate the `manifest.json`. Without this plugin generating the manifest, your backend would fail to locate the compiled `.js` files after a build.
+
+## 📝 License
+
+MIT

package/bin/index.ts

@@ -0,0 +1,101 @@
+import type { Plugin, UserConfig } from 'vite';
+import { fileURLToPath, URL } from 'node:url';
+import path from 'path';
+import { TonkaPluginOptions } from '../lib';
+
+/**
+ * Tonka Vite Plugin
+ * 
+ * A Vite plugin specifically designed for the Tonka Framework.
+ * It automates the configuration for Inertia.js, SSR, and asset paths.
+ * 
+ * @param options - Configuration options for the plugin
+ * @returns A Vite plugin object
+ */
+export default function tonkaPlugin(options: TonkaPluginOptions = {}): Plugin {
+  // Determine the base directory of the project
+  const root = process.cwd();
+
+  return {
+    name: 'tonka-vite-plugin',
+
+    /**
+     * The `config` hook is called before the user config is resolved.
+     * We use it to inject default settings and handle the Tonka-specific structure.
+     */
+    config: (userConfig: UserConfig, { command }) => {
+      // 1. Handle Inputs
+      // If the user doesn't provide inputs, we assume the standard structure.
+      // Note: We cast to 'any' here to satisfy Rollup's strict typing for input.
+      const input: any = options.input || {
+        'resources/css/app.css': undefined, // CSS entry
+        'resources/js/app.tsx': undefined,   // Main JS entry
+      };
+
+      // 2. Handle Output Directory
+      // Default to 'public/build' if not specified
+      const outDir = options.outDir || path.resolve(root, 'public/build');
+
+      // 3. Handle Manifest
+      // Ensure manifest is generated unless explicitly disabled
+      const manifest = options.manifest !== false ? 'manifest.json' : false;
+
+      // 4. Handle SSR
+      // If ssr is false, we ensure we don't set the ssr config.
+      const ssrBuild = options.ssr ? options.ssr : false;
+
+      return {
+        build: {
+          outDir: outDir,
+          manifest: manifest,
+          assetsDir: options.assetsDir || 'assets',
+          
+          // Rollup options
+          rollupOptions: {
+            input: input,
+          },
+          
+          // Server-Side Rendering configuration
+          ssr: ssrBuild,
+          
+          // Source maps: enabled in dev, disabled in prod (optional optimization)
+          sourcemap: command === 'serve',
+        },
+
+        // 5. Resolve Aliases
+        resolve: {
+          // Merge user aliases with defaults
+          alias: options.alias || {
+            // Default alias: '@' points to the root of the project
+            // You can also point it to 'resources' or 'public' based on your preference.
+            '@': path.resolve(root, '.'),
+          },
+        },
+
+        // 6. Optimize dependencies
+        // Pre-bundle common dependencies to speed up dev server start
+        optimizeDeps: {
+          include: ['react', 'react-dom', '@inertiajs/react', 'axios'],
+          exclude: [],
+        },
+      };
+    },
+
+    /**
+     * The `transformIndexHtml` hook allows modifying the HTML index file.
+     * This can be used to inject the @vite/client script for HMR if needed.
+     */
+    transformIndexHtml(html) {
+      // If refresh is enabled, we could inject the HMR client here.
+      // However, in a typical Inertia setup (like Tonka), this is often
+      // handled by the server-side Blade/PHP template (@vite directive).
+      // We leave this placeholder for future enhancements.
+      if (options.refresh) {
+        // Implementation note: Injecting @vite/client usually requires
+        // knowing the exact module path, which varies. 
+        // For now, we trust the server-side directive.
+      }
+      return html;
+    },
+  };
+}

package/index.ts

@@ -0,0 +1,2 @@
+import tonkaPlugin from './bin';
+export default tonkaPlugin;

package/lib/index.d.ts

@@ -1 +1,45 @@
-/// <reference types="typescript" />
+/**
+ * Interface for the options passed to the Tonka plugin.
+ * This defines the shape of the configuration object in `vite.config.ts`.
+ */
+export interface TonkaPluginOptions {
+  /**
+   * Entry points for the build.
+   * Can be an array of file paths or an object (for named chunks).
+   */
+  input?: string | string[] | Record<string, string>;
+
+  /**
+   * The entry point for Server-Side Rendering (SSR).
+   * Provide a file path string to enable SSR, or false to disable it.
+   */
+  ssr?: string | false;
+
+  /**
+   * Whether to enable React Fast Refresh (HMR).
+   * If true, the plugin may attempt to configure HMR settings.
+   */
+  refresh?: boolean;
+
+  /**
+   * The output directory for the production build.
+   * Defaults to 'public/build'.
+   */
+  outDir?: string;
+
+  /**
+   * The directory inside `outDir` for assets.
+   */
+  assetsDir?: string;
+
+  /**
+   * Path aliases (e.g., '@' to point to the root or resources).
+   */
+  alias?: Record<string, string>;
+  
+  /**
+   * Whether to generate a manifest.json file.
+   * Defaults to true for production.
+   */
+  manifest?: boolean;
+}

package/package.json

@@ -1,24 +1,23 @@
-{
-  "name": "tonka-vite-plugin",
-  "version": "1.10.0",
-  "description": "Tonka vite plugin for Inertia",
-  "main": "index.js",
-  "types": "./lib/index.d.ts",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/clicalmani/inertia-vite-plugin.git"
-  },
-  "keywords": [
-    "Inertia",
-    "vite"
-  ],
-  "author": "@clicalmani",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/clicalmani/inertia-vite-plugin/issues"
-  },
-  "homepage": "https://github.com/clicalmani/inertia-vite-plugin#readme"
-}
+{
+  "name": "tonka-vite-plugin",
+  "version": "1.21.0",
+  "description": "A Vite plugin for Inertia.js that provides automatic page imports and enhanced development experience.",
+  "main": "index.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clicalmani/inertia-vite-plugin.git"
+  },
+  "keywords": [
+    "Inertia",
+    "vite"
+  ],
+  "author": "@clicalmani",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/clicalmani/inertia-vite-plugin/issues"
+  },
+  "homepage": "https://github.com/clicalmani/inertia-vite-plugin#readme"
+}

package/bin/index.js

@@ -1,12 +0,0 @@
-import fs from 'fs';
-export default function(source) {
-    return {
-        name: 'rollup-plugin-tonka-vite',
-        transformIndexHtml: {
-          order: 'pre',
-          async handler() {
-            return await fs.promises.readFile(source, 'utf8');
-          }
-        }
-      }
-}