@pollora/vite-config 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RuBee group (https://rubee.group)
+
+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

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @pollora/vite-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Vite configuration shared by [Pollora](https://pollora.dev) themes, plugins and modules: where each one builds, its hot file, a dev server that works inside DDEV or Docker, its Gutenberg blocks, Tailwind CSS v4 and a page reload on Blade changes.
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import pollora from '@pollora/vite-config';
+
+export default defineConfig({
+    plugins: [pollora({ type: 'module' })],
+});
+```
+
+It is a dev dependency of each theme, plugin or module, like `laravel-vite-plugin`. Nothing is shared at build time: each package keeps its own `package.json`, build and hot file, and pins its own version.
+
+## What `type` sets
+
+| `type` | Build directory (served by the framework) | Hot file | Default port | Extra |
+| --- | --- | --- | --- | --- |
+| `theme` | `public/build/theme/<name>` | `public/<name>.hot` | 5173 | `theme.json` generated from the `@theme` tokens (`wordpressThemeJson`) |
+| `plugin` | `public/build/plugin/<name>` | `public/<name>.hot` | 5174 | Page reload on `.php` changes |
+| `module` | `public/build/module/<kebab-name>` | `public/<kebab-name>.hot` | 5175 | Page reload on `.php` changes |
+
+`<name>` is the directory name (`Modules/BlocksDemo` → `blocks-demo` for a module).
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `type` | required | `theme`, `plugin` or `module` |
+| `name` | directory name | Name the build is served under |
+| `input` | `resources/assets/app.js` when it exists | Entries besides blocks |
+| `blocks` | `true` | Build `resources/views/blocks/*/{index,view}.{js,jsx,ts,tsx}` and `{editor,style}.css`, and add `@roots/vite-plugin`'s `wordpressPlugin` |
+| `tailwind` | `true` | Add `@tailwindcss/vite` |
+| `themeJson` | `{ baseThemeJsonPath: './theme.json' }` | Options for `wordpressThemeJson` (themes), or `false` |
+| `wordpress` | `{}` | Options for `wordpressPlugin` |
+| `port` | `VITE_PORT`, else the type's port | Dev server port |
+| `refresh` | `[]` | Extra paths that reload the page |
+| `reloadOn` | theme: `['.blade.php']`, plugin and module: `['.blade.php', '.php']` | File endings whose change reloads the page (a block theme adds `.html`) |
+| `assets` | theme: `resources/assets/{images,fonts}/**` | Static assets copied to the build |
+| `publicDirectory` | the project's `public/`, relative to the package | |
+| `root` | working directory | Package root |
+
+## Requirements
+
+Node 20.19+, `vite` 7 or 8, `laravel-vite-plugin` 2 or 3. `@tailwindcss/vite` and `@roots/vite-plugin` are needed when Tailwind CSS, blocks or `theme.json` generation are on.
+
+## License
+
+MIT, © [RuBee group](https://rubee.group).

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "@pollora/vite-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@pollora/vite-config",
+    "version": "1.0.0",
+    "description": "Vite configuration shared by Pollora themes, plugins and modules",
+    "license": "MIT",
+    "author": "RuBee group (https://rubee.group)",
+    "homepage": "https://pollora.dev",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Pollora/vite-config.git"
+    },
+    "keywords": ["pollora", "vite", "wordpress", "laravel", "tailwindcss"],
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "default": "./src/index.js"
+        }
+    },
+    "files": ["src"],
+    "engines": {
+        "node": ">=20.19"
+    },
+    "scripts": {
+        "test": "node --test test/*.test.js"
+    },
+    "dependencies": {
+        "glob": "^11.0.0"
+    },
+    "peerDependencies": {
+        "@roots/vite-plugin": "^2.0.0",
+        "@tailwindcss/vite": "^4.0.0",
+        "laravel-vite-plugin": "^2.0.0 || ^3.0.0",
+        "vite": "^7.0.0 || ^8.0.0"
+    },
+    "peerDependenciesMeta": {
+        "@roots/vite-plugin": { "optional": true },
+        "@tailwindcss/vite": { "optional": true }
+    },
+    "devDependencies": {
+        "@roots/vite-plugin": "^2.0.0",
+        "@tailwindcss/vite": "^4.2.3",
+        "laravel-vite-plugin": "^3.0.1",
+        "tailwindcss": "^4.2.3",
+        "vite": "^8.0.9"
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,37 @@
+import type { PluginOption } from 'vite';
+
+export interface PolloraOptions {
+    /** What is being built: sets the build directory, hot file and default port */
+    type: 'theme' | 'plugin' | 'module';
+    /** Name it is served under (build/<type>/<name>); defaults to the directory name, kebab-cased for a module */
+    name?: string;
+    /** Package root; defaults to the current working directory */
+    root?: string;
+    /** Entries besides blocks; defaults to resources/assets/app.js when it exists */
+    input?: string[];
+    /** The project's public directory, relative to the package root */
+    publicDirectory?: string;
+    /** Dev server port; defaults to VITE_PORT, else 5173 (theme), 5174 (plugin), 5175 (module) */
+    port?: number;
+    /** Build the blocks in resources/views/blocks (default true) */
+    blocks?: boolean;
+    /** Add @tailwindcss/vite (default true) */
+    tailwind?: boolean;
+    /** Options for @roots/vite-plugin's wordpressThemeJson, or false to skip it (themes only) */
+    themeJson?: Record<string, unknown> | false;
+    /** Options for @roots/vite-plugin's wordpressPlugin, used when there are blocks */
+    wordpress?: Record<string, unknown>;
+    /** File endings that reload the whole page in development; .blade.php for themes, plus .php for plugins and modules */
+    reloadOn?: string[];
+    /** Extra paths that reload the page in development */
+    refresh?: string[];
+    /** Static assets copied to the build (laravel-vite-plugin's assets option) */
+    assets?: string[];
+}
+
+export default function pollora(options: PolloraOptions): PluginOption[];
+export { pollora };
+
+export function kebab(name: string): string;
+export function blockEntries(root: string): Record<string, string>;
+export function devServer(port: number): Record<string, unknown>;

package/src/index.js

@@ -0,0 +1,199 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { globSync } from 'glob';
+import laravel, { refreshPaths } from 'laravel-vite-plugin';
+
+/**
+ * Where each kind of Pollora package builds, relative to the project root, and
+ * how far its own root sits below the project's public directory.
+ */
+const TYPES = {
+    theme: {
+        // themes/<name>
+        publicDirectory: '../../public',
+        port: 5173,
+        reloadOn: ['.blade.php'],
+        assets: ['resources/assets/images/**', 'resources/assets/fonts/**'],
+    },
+    plugin: {
+        // public/content/plugins/<name>
+        publicDirectory: '../../../../public',
+        port: 5174,
+        reloadOn: ['.blade.php', '.php'],
+        assets: [],
+    },
+    module: {
+        // Modules/<Name>
+        publicDirectory: '../../public',
+        port: 5175,
+        reloadOn: ['.blade.php', '.php'],
+        assets: [],
+    },
+};
+
+const BLOCK_ENTRIES = [
+    './resources/views/blocks/*/{index,view}.{js,jsx,ts,tsx}',
+    './resources/views/blocks/*/{editor,style}.css',
+];
+
+const DEFAULT_INPUT = ['./resources/assets/app.js'];
+
+/**
+ * Turn a directory name into the slug the framework serves a module under:
+ * BlocksDemo → blocks-demo, as Str::kebab() does.
+ */
+export function kebab(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+}
+
+/**
+ * Vite entries of every block script and stylesheet, keyed by path so blocks
+ * sharing a file name never overwrite each other.
+ */
+export function blockEntries(root) {
+    return globSync(BLOCK_ENTRIES, { cwd: root, posix: true })
+        .sort()
+        .reduce((entries, file) => {
+            entries[file.replace(/^\.\//, '').replace(/\.\w+$/, '')] = file;
+            return entries;
+        }, {});
+}
+
+function baseUrl() {
+    return process.env.APP_URL || process.env.DDEV_PRIMARY_URL || 'http://localhost';
+}
+
+function isDocker() {
+    return Boolean(process.env.IS_DOCKER || process.env.DOCKER_ENV || process.env.DDEV_PRIMARY_URL);
+}
+
+/**
+ * Dev server reachable from the site: inside DDEV or Docker it listens on every
+ * interface and announces the site's own host, elsewhere it serves localhost.
+ */
+export function devServer(port) {
+    const url = baseUrl();
+    const isHttps = url.startsWith('https');
+    const hostname = new URL(url).hostname;
+    const common = {
+        port,
+        strictPort: true,
+        cors: {
+            origin: '*',
+            methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+            credentials: true,
+        },
+    };
+
+    if (isDocker()) {
+        return {
+            ...common,
+            host: '0.0.0.0',
+            origin: `${url}:${port}`,
+            hmr: { protocol: isHttps ? 'wss' : 'ws', host: hostname },
+        };
+    }
+
+    return {
+        ...common,
+        https: isHttps,
+        host: isHttps ? hostname : 'localhost',
+        hmr: { protocol: isHttps ? 'wss' : 'ws', host: hostname },
+    };
+}
+
+function resolvePort(option, fallback) {
+    const port = option ?? process.env.VITE_PORT;
+
+    return port === undefined || port === '' ? fallback : Number(port);
+}
+
+/**
+ * The Vite plugins a Pollora theme, plugin or module builds with.
+ *
+ * @param {import('./index').PolloraOptions} options
+ * @returns {import('vite').PluginOption[]}
+ */
+export default function pollora(options = {}) {
+    const type = options.type;
+
+    if (!TYPES[type]) {
+        throw new Error(`@pollora/vite-config: "type" must be one of ${Object.keys(TYPES).join(', ')}, got ${JSON.stringify(type)}.`);
+    }
+
+    const defaults = TYPES[type];
+    const root = path.resolve(options.root ?? process.cwd());
+    const directoryName = path.basename(root);
+    const name = options.name ?? (type === 'module' ? kebab(directoryName) : directoryName);
+    // Relative to the package root: laravel-vite-plugin strips a leading slash
+    const publicDirectory = options.publicDirectory ?? defaults.publicDirectory;
+    const buildDirectory = path.join('build', type, name);
+    const base = `/build/${type}/${name}`;
+    const port = resolvePort(options.port, defaults.port);
+
+    const blocks = options.blocks === false ? {} : blockEntries(root);
+    const hasBlocks = Object.keys(blocks).length > 0;
+    const input = (options.input ?? DEFAULT_INPUT.filter((file) => fs.existsSync(path.join(root, file))));
+
+    // File endings that reload the whole page in development (block themes add .html)
+    const reloadOn = options.reloadOn ?? defaults.reloadOn;
+    const refresh = [
+        // A literal resources/views/** turns every block JSX change into a full reload
+        ...refreshPaths.filter((refreshPath) => refreshPath !== 'resources/views/**'),
+        'resources/views/**/*.blade.php',
+        ...(reloadOn.includes('.php') ? ['app/**/*.php'] : []),
+        ...(options.refresh ?? []),
+    ];
+
+    const plugins = [
+        {
+            name: 'pollora:config',
+            config: () => ({
+                base,
+                build: { emptyOutDir: false },
+                server: devServer(port),
+            }),
+        },
+    ];
+
+    if (options.tailwind !== false) {
+        plugins.push(import('@tailwindcss/vite').then((module) => module.default()));
+    }
+
+    plugins.push(laravel({
+        input: [...input, ...Object.values(blocks)],
+        publicDirectory,
+        // Written from the working directory, unlike the build directory resolved from the root
+        hotFile: path.resolve(root, publicDirectory, `${name}.hot`),
+        buildDirectory,
+        refresh,
+        assets: options.assets ?? defaults.assets,
+    }));
+
+    if (type === 'theme' && options.themeJson !== false) {
+        plugins.push(import('@roots/vite-plugin').then(({ wordpressThemeJson }) => wordpressThemeJson({
+            baseThemeJsonPath: './theme.json',
+            ...(options.themeJson ?? {}),
+        })));
+    }
+
+    if (hasBlocks) {
+        plugins.push(import('@roots/vite-plugin').then(({ wordpressPlugin }) => wordpressPlugin(options.wordpress ?? {})));
+    }
+
+    plugins.push({
+        name: 'pollora:blade-reload',
+        handleHotUpdate({ file, server }) {
+            if (reloadOn.some((extension) => file.endsWith(extension))) {
+                server.ws.send({ type: 'full-reload', path: '*' });
+            }
+        },
+    });
+
+    return plugins;
+}
+
+export { pollora };