@pollora/vite-config 1.0.0 → 1.1.1

package/README.md

@@ -24,6 +24,30 @@ It is a dev dependency of each theme, plugin or module, like `laravel-vite-plugi
 
 `<name>` is the directory name (`Modules/BlocksDemo` → `blocks-demo` for a module).
 
+## A classic theme, a plugin or a Bedrock site
+
+Outside a Pollora project there is no shared `public/` directory to build into. `layout: 'standalone'` builds the package inside itself, where [`pollora/assets`](https://github.com/Pollora/assets) looks for it:
+
+```js
+// wp-content/themes/my-theme/vite.config.js, or web/app/themes/my-theme/vite.config.js
+import { defineConfig } from 'vite';
+import pollora from '@pollora/vite-config';
+
+export default defineConfig({
+    plugins: [pollora({ type: 'theme', layout: 'standalone' })],
+});
+```
+
+| | `layout: 'pollora'` (default) | `layout: 'standalone'` |
+| --- | --- | --- |
+| Build | `public/build/<type>/<name>/` | `build/` in the package |
+| Hot file | `public/<name>.hot` | `hot` at the root of the package |
+| `base` (URLs in the built CSS and chunks) | `/build/<type>/<name>/` | `./`: relative, so the build works wherever WordPress serves the folder from |
+| Dev server | serves under the build path | serves from its root: the hot file holds the origin (`http://localhost:5173`) |
+| Entry points | `resources/assets/app.js`, blocks | the same |
+
+`buildDirectory` (`build`) and `hotFile` (`hot`) rename the two, and `publicDirectory` (`.`) moves the folder they sit in; give the same values to the container on the PHP side (`build_directory`, `hot_file`, `public_path`). The manifest keys do not change (`resources/assets/app.js`), so a file is looked up the same way in both layouts.
+
 ## Options
 
 | Option | Default | |
@@ -35,6 +59,10 @@ It is a dev dependency of each theme, plugin or module, like `laravel-vite-plugi
 | `tailwind` | `true` | Add `@tailwindcss/vite` |
 | `themeJson` | `{ baseThemeJsonPath: './theme.json' }` | Options for `wordpressThemeJson` (themes), or `false` |
 | `wordpress` | `{}` | Options for `wordpressPlugin` |
+| `layout` | `'pollora'` | `'pollora'` (a Pollora project) or `'standalone'` (a classic theme, a plugin, Bedrock) |
+| `publicDirectory` | the type's directory in a Pollora project, `.` when standalone | The public directory the build and hot file sit in, relative to the package root |
+| `buildDirectory` | `build` (standalone only) | Build directory, relative to the public directory |
+| `hotFile` | `hot` (standalone only) | Hot file, relative to the public directory |
 | `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`) |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pollora/vite-config",
-    "version": "1.0.0",
+    "version": "1.1.1",
     "description": "Vite configuration shared by Pollora themes, plugins and modules",
     "license": "MIT",
     "author": "RuBee group (https://rubee.group)",

package/src/index.d.ts

@@ -9,8 +9,17 @@ export interface PolloraOptions {
     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 */
+    /**
+     * `pollora` (default): a Pollora project, built under its public directory as build/<type>/<name>.
+     * `standalone`: a classic theme, a plugin or a Bedrock site: built inside the package, into build/, with a hot file at its root.
+     */
+    layout?: 'pollora' | 'standalone';
+    /** The project's public directory, relative to the package root; the package root itself (`.`) for a standalone layout */
     publicDirectory?: string;
+    /** Standalone layout: the build directory, relative to the public directory (default `build`) */
+    buildDirectory?: string;
+    /** Standalone layout: the hot file, relative to the public directory (default `hot`) */
+    hotFile?: 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) */
@@ -32,6 +41,17 @@ export interface PolloraOptions {
 export default function pollora(options: PolloraOptions): PluginOption[];
 export { pollora };
 
+export function layoutOf(settings: {
+    layout?: 'pollora' | 'standalone';
+    type: 'theme' | 'plugin' | 'module';
+    name: string;
+    root: string;
+    publicDirectory?: string;
+    buildDirectory?: string;
+    hotFile?: string;
+}): { publicDirectory: string; buildDirectory: string; hotFile: string; base: string | null };
+
 export function kebab(name: string): string;
 export function blockEntries(root: string): Record<string, string>;
 export function devServer(port: number): Record<string, unknown>;
+export function usesWsOption(version?: string): boolean;

package/src/index.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { globSync } from 'glob';
+import { version as viteVersion } from 'vite';
 import laravel, { refreshPaths } from 'laravel-vite-plugin';
 
 /**
@@ -70,6 +71,16 @@ function isDocker() {
     return Boolean(process.env.IS_DOCKER || process.env.DOCKER_ENV || process.env.DDEV_PRIMARY_URL);
 }
 
+/**
+ * Vite 8.3.1 moved the WebSocket options from `server.hmr` to `server.ws` and
+ * deprecated the old place; earlier versions only know `server.hmr`.
+ */
+export function usesWsOption(version = viteVersion) {
+    const [major, minor, patch] = version.split('.').map((part) => parseInt(part, 10));
+
+    return major > 8 || (major === 8 && (minor > 3 || (minor === 3 && patch >= 1)));
+}
+
 /**
  * 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.
@@ -78,6 +89,8 @@ export function devServer(port) {
     const url = baseUrl();
     const isHttps = url.startsWith('https');
     const hostname = new URL(url).hostname;
+    const socket = { protocol: isHttps ? 'wss' : 'ws', host: hostname };
+    const websocket = usesWsOption() ? { ws: socket } : { hmr: socket };
     const common = {
         port,
         strictPort: true,
@@ -93,7 +106,7 @@ export function devServer(port) {
             ...common,
             host: '0.0.0.0',
             origin: `${url}:${port}`,
-            hmr: { protocol: isHttps ? 'wss' : 'ws', host: hostname },
+            ...websocket,
         };
     }
 
@@ -101,7 +114,7 @@ export function devServer(port) {
         ...common,
         https: isHttps,
         host: isHttps ? hostname : 'localhost',
-        hmr: { protocol: isHttps ? 'wss' : 'ws', host: hostname },
+        ...websocket,
     };
 }
 
@@ -111,6 +124,39 @@ function resolvePort(option, fallback) {
     return port === undefined || port === '' ? fallback : Number(port);
 }
 
+const LAYOUTS = ['pollora', 'standalone'];
+
+/**
+ * Where a package builds, and where its dev server is announced.
+ *
+ * `pollora` is a Pollora project: every package builds under the project's
+ * public directory, as build/<type>/<name> with a <name>.hot file beside it.
+ * `standalone` is a classic theme, a plugin or a Bedrock site, which have no
+ * shared public directory: the package builds inside itself, into `build/`
+ * with a `hot` file at its root, and `base` is relative so the built CSS and
+ * chunks find each other wherever WordPress serves the folder from.
+ *
+ * @param {object} settings
+ * @returns {{ publicDirectory: string, buildDirectory: string, hotFile: string, base: string|null }}
+ */
+export function layoutOf({ layout, type, name, root, publicDirectory, buildDirectory, hotFile }) {
+    if (layout === 'standalone') {
+        return {
+            publicDirectory: publicDirectory ?? '.',
+            buildDirectory: buildDirectory ?? 'build',
+            hotFile: path.resolve(root, publicDirectory ?? '.', hotFile ?? 'hot'),
+            base: null,
+        };
+    }
+
+    return {
+        publicDirectory: publicDirectory ?? TYPES[type].publicDirectory,
+        buildDirectory: path.join('build', type, name),
+        hotFile: path.resolve(root, publicDirectory ?? TYPES[type].publicDirectory, `${name}.hot`),
+        base: `/build/${type}/${name}`,
+    };
+}
+
 /**
  * The Vite plugins a Pollora theme, plugin or module builds with.
  *
@@ -124,14 +170,23 @@ export default function pollora(options = {}) {
         throw new Error(`@pollora/vite-config: "type" must be one of ${Object.keys(TYPES).join(', ')}, got ${JSON.stringify(type)}.`);
     }
 
+    const layout = options.layout ?? 'pollora';
+
+    if (!LAYOUTS.includes(layout)) {
+        throw new Error(`@pollora/vite-config: "layout" must be one of ${LAYOUTS.join(', ')}, got ${JSON.stringify(layout)}.`);
+    }
+
     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 { publicDirectory, buildDirectory, hotFile, base } = layoutOf({
+        layout, type, name, root,
+        publicDirectory: options.publicDirectory,
+        buildDirectory: options.buildDirectory,
+        hotFile: options.hotFile,
+    });
     const port = resolvePort(options.port, defaults.port);
 
     const blocks = options.blocks === false ? {} : blockEntries(root);
@@ -151,8 +206,9 @@ export default function pollora(options = {}) {
     const plugins = [
         {
             name: 'pollora:config',
-            config: () => ({
-                base,
+            // A standalone build is relative to wherever it is served from; its dev server serves from the root
+            config: (config, { command }) => ({
+                ...(base === null ? (command === 'build' ? { base: './' } : {}) : { base }),
                 build: { emptyOutDir: false },
                 server: devServer(port),
             }),
@@ -167,7 +223,7 @@ export default function pollora(options = {}) {
         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`),
+        hotFile,
         buildDirectory,
         refresh,
         assets: options.assets ?? defaults.assets,