vite-userscript-plugin 2.0.0 → 2.1.1

package/README.md

@@ -83,10 +83,12 @@ Details: [types/README.md](./types/README.md).
 
 `vite` prints `/{fileName}.dev.user.js` — install that URL once. HMR covers code and styles.
 
+`server.file: true` skips HMR. The same `vite` watch-builds `{fileName}.user.js` (headed IIFE), `{fileName}.js`, and `{fileName}.proxy.user.js` (`@require file://` to the IIFE). Install the printed `/{fileName}.user.js` URL (Firefox-safe). The `Proxy` line is for managers that can poll `file://`. See [examples/serve-file](./examples/serve-file).
+
 > [!IMPORTANT]
 > Changing `@match`, `@grant`, or `@name` needs a reinstall.
 
-`vite build` writes `{fileName}.user.js` to `dist/`.
+`vite build` writes `{fileName}.user.js` to `dist/`. One-shot builds do not emit the proxy.
 
 ## Multiple scripts
 
@@ -133,8 +135,9 @@ See [examples/sourcemap](./examples/sourcemap).
 | `entry` | — | Userscript entry. Required. |
 | `header` | — | Metablock. Required: `name`, `version`, `match`. |
 | `fileName` | sanitized `header.name` | Output base name (`{fileName}.user.js`). |
-| `server.open` | `false` | Open the `.dev.user.js` install URL when Vite starts. |
+| `server.open` | `false` | Open the install target when Vite starts. HMR: `.dev.user.js`. `file`: `.user.js` URL. |
 | `server.prefix` | `'server:'` | Prefix for `@name` in serve mode. `false` disables it. |
+| `server.file` | `false` | Watch-build `{fileName}.user.js` + `{fileName}.js` + `{fileName}.proxy.user.js`. Install `.user.js` (or the proxy if `file://` `@require` works). No HMR. |
 | `cssInject` | `'auto'` | How production CSS is injected. `'auto'` uses `GM_addStyle` or a `<style>` node. |
 | `align` | `1` | Extra spaces after the longest `@key`. `false` — one space. |
 | `generate` | — | Rewrite the generated metablock. |
@@ -158,6 +161,7 @@ In serve mode the header lists every grant. In production the plugin scans the b
 | [svelte](./examples/svelte) | SFC `<style>`. |
 | [multiple-entries](./examples/multiple-entries) | Two scripts. |
 | [sourcemap](./examples/sourcemap) | Inline map, HTML page, virtual module. |
+| [serve-file](./examples/serve-file) | `server.file`, install `.user.js` or the proxy from the printed URLs. |
 
 ## FAQ
 
@@ -181,17 +185,22 @@ In serve mode the header lists every grant. In production the plugin scans the b
 ### `@run-at document-start` feels late in dev
 
 > [!NOTE]
-> Serve injects `type="module"` (async). Production is a synchronous IIFE unless you use top-level `await`.
+> Serve injects `type="module"` (async). Production is a synchronous IIFE unless you use top-level `await`. `server.file` uses that IIFE in dev too.
+
+### `file://` `@require` is blocked
+
+> [!NOTE]
+> Firefox extensions cannot read `file://`. Install the printed `{fileName}.user.js` URL instead of the proxy. Tampermonkey on Chromium must allow local file access for the proxy `@require`. Violentmonkey can poll the local IIFE after you install the proxy.
 
 ## Migration from v1
 
 | v1 | v2 |
 | --- | --- |
-| `vite build --watch` | `vite` |
+| `vite build --watch` | `vite` (HMR) or `vite` + `server.file` |
 | `esbuildTransformOptions` | removed |
 | `server.port` | Vite `server.port` |
 | minify on by default | off; set `build.minify` |
-| `*.proxy.user.js` + `file://` | `*.dev.user.js` from Vite |
+| `*.proxy.user.js` + `file://` | `server.file: true`, or HMR `.dev.user.js` |
 | Vite 3–7 | Vite 8 |
 | `scripts` + shared `header` | `userscript([config, config, …])` |
 | `ScriptOptions` | removed |

package/dist/index.d.ts

@@ -146,7 +146,8 @@ type HeaderConfig = {
 };
 interface ServerConfig {
   /**
-   * Open the `.dev.user.js` install URL when the Vite server starts.
+   * Open the install target when Vite starts.
+   * HMR: `.dev.user.js` URL. `file`: `{fileName}.user.js` URL.
    *
    * @default false
    */
@@ -158,6 +159,14 @@ interface ServerConfig {
    * @default 'server:'
    */
   prefix?: string | false;
+  /**
+   * Watch-build into `outDir`: `{fileName}.user.js`, headerless `{fileName}.js`,
+   * and `{fileName}.proxy.user.js` with `@require file://` pointing at the IIFE.
+   * Install `/{fileName}.user.js` (Firefox-safe) or the proxy URL. No HMR for this script.
+   *
+   * @default false
+   */
+  file?: boolean;
 }
 type HeaderMode = 'serve' | 'build' | 'meta';
 interface HeaderGenerateContext {
@@ -229,6 +238,7 @@ interface ResolvedScript {
   server: {
     open: boolean;
     prefix: string | false;
+    file: boolean;
   };
   cssInject: CssInject;
   align: number | false;

package/dist/index.js

@@ -1,8 +1,10 @@
 import { basename, posix, relative, resolve, sep } from "node:path";
+import { build } from "vite";
 import { Buffer } from "node:buffer";
-import { existsSync } from "node:fs";
-import openLink from "open";
+import { pathToFileURL } from "node:url";
+import { existsSync, readFileSync } from "node:fs";
 import { styleText } from "node:util";
+import openLink from "open";
 //#region src/names.ts
 function sanitizeFileName(name) {
 	return name.replace(/[<>:"/\\|?*\u0000-\u001F]+/g, "-").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "") || "userscript";
@@ -326,6 +328,37 @@ function ensureIife(code) {
 	return `(${/\bawait\b/.test(stripped) ? "async function" : "function"} () {\n${stripped}\n})();\n`;
 }
 //#endregion
+//#region src/build/proxy.ts
+function toFileRequireUrl(absPath) {
+	return pathToFileURL(absPath).href;
+}
+function toRequireList(value) {
+	if (value == null) return [];
+	return Array.isArray(value) ? value.map(String) : [String(value)];
+}
+function createWatchProxyHeader(script, jsAbsPath) {
+	const header = withServeGrants({ ...script.header });
+	return {
+		...header,
+		require: [...toRequireList(header.require), toFileRequireUrl(jsAbsPath)]
+	};
+}
+function generateWatchProxy(script, jsAbsPath) {
+	return generateHeader(createWatchProxyHeader(script, jsAbsPath), {
+		align: script.align,
+		autoMetaUrls: false,
+		fileName: script.fileName,
+		generate: script.generate,
+		mode: "serve"
+	});
+}
+function toProxyFileName(fileName) {
+	return `${fileName}.proxy.user.js`;
+}
+function toRequireFileName(fileName) {
+	return `${fileName}.js`;
+}
+//#endregion
 //#region src/build/apply.ts
 function importedChunkIds(chunk) {
 	return [...chunk.imports, ...chunk.dynamicImports ?? []];
@@ -373,10 +406,33 @@ function withSourceMaps(fileNames) {
 function findScriptForChunk(chunk, fileName, scripts) {
 	return scripts.find((script) => chunk.name === script.fileName || fileName === `${script.fileName}.js` || fileName === `${script.fileName}.user.js`);
 }
+function createHeadedUserscript(script, options) {
+	const headerConfig = withBuildGrants(script.header, options.wrapped, options.extraGrants);
+	const prefix = `${generateHeader(headerConfig, {
+		align: script.align,
+		autoMetaUrls: script.autoMetaUrls,
+		fileName: script.fileName,
+		generate: script.generate,
+		mode: "build"
+	})}\n\n`;
+	const nextFileName = `${script.fileName}.user.js`;
+	let nextCode = `${prefix}${options.code}`;
+	if (options.map) {
+		const wrapOffset = isAlreadyIife(stripSourceMappingUrl(options.body)) ? 0 : 1;
+		const lineOffset = countHeaderLines(prefix) + countHeaderLines(options.cssPrelude) + wrapOffset + countHeaderLines(options.inlined);
+		const map = stripVendorSourcesContent(offsetSourceMap(options.map, lineOffset, nextFileName));
+		nextCode = `${stripSourceMappingUrl(nextCode).replace(/\n+$/g, "\n")}//# sourceMappingURL=${toInlineSourceMappingUrl(map)}\n`;
+	}
+	return {
+		headerConfig,
+		code: nextCode.endsWith("\n") ? nextCode : `${nextCode}\n`
+	};
+}
 function deleteBundleFiles(bundle, fileNames) {
 	for (const fileName of fileNames) delete bundle[fileName];
 }
-function applyUserscriptBundle(bundle, config, emitMeta) {
+function applyUserscriptBundle(bundle, config, context) {
+	const { emitFile } = context;
 	const userscriptEntries = [];
 	const otherEntryFiles = [];
 	for (const [fileName, item] of Object.entries(bundle)) {
@@ -405,27 +461,36 @@ function applyUserscriptBundle(bundle, config, emitMeta) {
 		const body = `${inlined}${chunk.code}`;
 		const wrapped = ensureIife(body);
 		const extraGrants = css && script.cssInject === "auto" ? ["GM_addStyle"] : [];
-		const headerConfig = withBuildGrants(script.header, wrapped, extraGrants);
 		const code = `${cssPrelude}${wrapped}`;
-		const prefix = `${generateHeader(headerConfig, {
-			align: script.align,
-			autoMetaUrls: script.autoMetaUrls,
-			fileName: script.fileName,
-			generate: script.generate,
-			mode: "build"
-		})}\n\n`;
-		const nextFileName = `${script.fileName}.user.js`;
-		let nextCode = `${prefix}${code}`;
-		if (chunk.map) {
-			const wrapOffset = isAlreadyIife(stripSourceMappingUrl(body)) ? 0 : 1;
-			const lineOffset = countHeaderLines(prefix) + countHeaderLines(cssPrelude) + wrapOffset + countHeaderLines(inlined);
-			chunk.map = stripVendorSourcesContent(offsetSourceMap(chunk.map, lineOffset, nextFileName));
-			nextCode = `${stripSourceMappingUrl(nextCode).replace(/\n+$/g, "\n")}//# sourceMappingURL=${toInlineSourceMappingUrl(chunk.map)}\n`;
-		}
+		const emitFileProxy = Boolean(context.emitProxy && context.outDir && script.server.file);
 		leftoverAssets.push(`${fileName}.map`);
-		chunk.code = nextCode;
-		chunk.fileName = nextFileName;
-		if (script.metaFile) emitMeta(`${script.fileName}.meta.js`, generateHeader(headerConfig, {
+		const headed = createHeadedUserscript(script, {
+			body,
+			code,
+			cssPrelude,
+			extraGrants,
+			inlined,
+			map: chunk.map,
+			wrapped
+		});
+		if (emitFileProxy) {
+			const requireName = toRequireFileName(script.fileName);
+			let nextCode = code.endsWith("\n") ? code : `${code}\n`;
+			if (chunk.map) {
+				const wrapOffset = isAlreadyIife(stripSourceMappingUrl(body)) ? 0 : 1;
+				const lineOffset = countHeaderLines(cssPrelude) + wrapOffset + countHeaderLines(inlined);
+				chunk.map = stripVendorSourcesContent(offsetSourceMap(chunk.map, lineOffset, requireName));
+				nextCode = `${stripSourceMappingUrl(nextCode).replace(/\n+$/g, "\n")}//# sourceMappingURL=${toInlineSourceMappingUrl(chunk.map)}\n`;
+			}
+			chunk.code = nextCode;
+			chunk.fileName = requireName;
+			emitFile(toProxyFileName(script.fileName), `${generateWatchProxy(script, resolve(context.outDir, requireName))}\n`);
+			emitFile(`${script.fileName}.user.js`, headed.code);
+			continue;
+		}
+		chunk.code = headed.code;
+		chunk.fileName = `${script.fileName}.user.js`;
+		if (script.metaFile) emitFile(`${script.fileName}.meta.js`, generateHeader(headed.headerConfig, {
 			align: script.align,
 			autoMetaUrls: script.autoMetaUrls,
 			fileName: script.fileName,
@@ -443,12 +508,16 @@ function applyUserscriptBundle(bundle, config, emitMeta) {
 const VIRTUAL_MODULE_ID = "virtual:vite-userscript-plugin";
 const RESOLVED_VIRTUAL_MODULE_ID = `\0${VIRTUAL_MODULE_ID}`;
 function createClientSnapshot(scripts, command) {
-	const suffix = command === "serve" ? ".dev.user.js" : ".user.js";
-	return scripts.map((script) => ({
-		name: script.header.name,
-		version: script.header.version,
-		file: `${script.fileName}${suffix}`
-	}));
+	return scripts.map((script) => {
+		let suffix = ".dev.user.js";
+		if (command === "build") suffix = ".user.js";
+		else if (script.server.file) suffix = ".user.js";
+		return {
+			name: script.header.name,
+			version: script.header.version,
+			file: `${script.fileName}${suffix}`
+		};
+	});
 }
 function renderVirtualModule(scripts) {
 	return `export const scripts = ${JSON.stringify(scripts)}\n`;
@@ -540,7 +609,8 @@ function toResolvedScript(config) {
 		header: config.header,
 		server: {
 			open: config.server?.open ?? false,
-			prefix: config.server?.prefix ?? "server:"
+			prefix: config.server?.prefix ?? "server:",
+			file: config.server?.file ?? false
 		},
 		cssInject: config.cssInject ?? "auto",
 		align: config.align ?? 1,
@@ -594,9 +664,13 @@ function shimModule(code, id) {
 }
 //#endregion
 //#region src/serve/logger.ts
-function formatInstallLine(installUrl) {
+function formatInstallLine(installUrl, label = "Userscript") {
 	const coloredUrl = styleText("cyan", installUrl.replace(/:(\d+)\//, (_match, port) => `:${styleText("bold", port)}/`));
-	return `  ${styleText("green", "➜")}  ${styleText("bold", "Userscript")}: ${coloredUrl}`;
+	const padded = label.padEnd(10);
+	return `  ${styleText("green", "➜")}  ${styleText("bold", padded)}: ${coloredUrl}`;
+}
+function formatRebuildLine(elapsedMs) {
+	return `${styleText("green", "Userscript rebuilt")} ${styleText("dim", `(${elapsedMs}ms)`)}`;
 }
 function formatFaqHint() {
 	return `${`  ${styleText("green", "➜")}  ${styleText("bold", "FAQ")}: `}${styleText("cyan", FAQ_URL)}\n`;
@@ -660,8 +734,19 @@ import ${JSON.stringify(entryPath)};
 function matchDevUserscript(url, fileName) {
 	return (url.split("?")[0] ?? "") === `/${fileName}.dev.user.js`;
 }
-function toInstallUrl(origin, fileName) {
-	return `${origin.replace(/\/$/, "")}/${fileName}.dev.user.js`;
+function matchProxyUserscript(url, fileName) {
+	return (url.split("?")[0] ?? "") === `/${toProxyFileName(fileName)}`;
+}
+function matchFileUserscript(url, fileName) {
+	return (url.split("?")[0] ?? "") === `/${fileName}.user.js`;
+}
+function toInstallUrl(origin, fileName, kind = "dev") {
+	const names = {
+		dev: `${fileName}.dev.user.js`,
+		proxy: toProxyFileName(fileName),
+		user: `${fileName}.user.js`
+	};
+	return `${origin.replace(/\/$/, "")}/${names[kind]}`;
 }
 function toServeEntryPath(root, entry) {
 	const absolute = resolve(root, entry);
@@ -713,7 +798,13 @@ function generateDevUserscript(options) {
 	})}`;
 }
 function findDevScript(url, scripts) {
-	return scripts.find((script) => matchDevUserscript(url, script.fileName));
+	return scripts.find((script) => !script.server.file && matchDevUserscript(url, script.fileName));
+}
+function findProxyScript(url, scripts) {
+	return scripts.find((script) => script.server.file && matchProxyUserscript(url, script.fileName));
+}
+function findFileUserscript(url, scripts) {
+	return scripts.find((script) => script.server.file && matchFileUserscript(url, script.fileName));
 }
 function createDevUserscript(options) {
 	return generateDevUserscript({
@@ -760,6 +851,22 @@ function configureDevServer(server, resolved, reactPreamble) {
 			writeScript(res, createReactBootstrapModule(entry));
 			return;
 		}
+		const fileScript = findFileUserscript(url, resolved.scripts);
+		if (fileScript) {
+			const userJsPath = resolve(server.config.root, server.config.build.outDir, `${fileScript.fileName}.user.js`);
+			try {
+				writeScript(res, readFileSync(userJsPath, "utf8"));
+			} catch {
+				res.statusCode = 404;
+				res.end();
+			}
+			return;
+		}
+		const proxyScript = findProxyScript(url, resolved.scripts);
+		if (proxyScript) {
+			writeScript(res, `${generateWatchProxy(proxyScript, resolve(server.config.root, server.config.build.outDir, toRequireFileName(proxyScript.fileName)))}\n`);
+			return;
+		}
 		const script = findDevScript(url, resolved.scripts);
 		if (!script) {
 			next();
@@ -779,7 +886,14 @@ function configureDevServer(server, resolved, reactPreamble) {
 		let origins = [];
 		if (urls) origins = urls.local.length ? urls.local : urls.network;
 		const printInstall = () => {
-			for (const origin of origins) for (const script of resolved.scripts) info(formatInstallLine(toInstallUrl(origin, script.fileName)));
+			for (const origin of origins) for (const script of resolved.scripts) {
+				if (script.server.file) {
+					info(formatInstallLine(toInstallUrl(origin, script.fileName, "user")));
+					info(formatInstallLine(toInstallUrl(origin, script.fileName, "proxy"), "Proxy"));
+					continue;
+				}
+				info(formatInstallLine(toInstallUrl(origin, script.fileName)));
+			}
 			info(formatFaqHint());
 		};
 		const logger = createAfterLocalLogger(info, urls?.local.length ?? 0, printInstall);
@@ -797,7 +911,7 @@ function configureDevServer(server, resolved, reactPreamble) {
 		if (!toOpen.length) return;
 		queueMicrotask(() => {
 			const origin = resolveServerOrigin(server.resolvedUrls);
-			for (const script of toOpen) openLink(toInstallUrl(origin, script.fileName));
+			for (const script of toOpen) openLink(toInstallUrl(origin, script.fileName, script.server.file ? "user" : "dev"));
 		});
 	});
 }
@@ -813,6 +927,68 @@ function UserscriptPlugin(config) {
 	let resolved = resolvePluginConfig(config);
 	let reactPreamble = false;
 	let command = "serve";
+	let isWatch = false;
+	let mode = "production";
+	let outDir = "";
+	let fileWatchStarted = false;
+	const shouldEmitProxy = () => {
+		return isWatch || mode === "development";
+	};
+	const startFileWatchBuild = async (server) => {
+		if (command === "build" || fileWatchStarted) return;
+		fileWatchStarted = true;
+		const outDirAbs = resolve(server.config.root, server.config.build.outDir);
+		let firstBuild = true;
+		const run = async () => {
+			const isRebuild = !firstBuild;
+			const started = Date.now();
+			await build({
+				configFile: server.config.configFile ?? false,
+				root: server.config.root,
+				mode: server.config.mode,
+				logLevel: "silent",
+				clearScreen: false,
+				plugins: server.config.configFile ? void 0 : [UserscriptPlugin(config)],
+				build: {
+					outDir: server.config.build.outDir,
+					emptyOutDir: firstBuild,
+					minify: server.config.build.minify,
+					sourcemap: server.config.build.sourcemap,
+					write: true,
+					reportCompressedSize: false
+				}
+			});
+			firstBuild = false;
+			if (isRebuild) server.config.logger.info(formatRebuildLine(Date.now() - started), { timestamp: true });
+		};
+		try {
+			await run();
+		} catch (error) {
+			fileWatchStarted = false;
+			server.config.logger.error(`[${PLUGIN_NAME}] Failed to start file-mode watch build`);
+			server.config.logger.error(String(error));
+			return;
+		}
+		let timer;
+		const onChange = (file) => {
+			if (file.startsWith(outDirAbs)) return;
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				run().catch((error) => {
+					server.config.logger.error(String(error));
+				});
+			}, 80);
+		};
+		server.watcher.on("change", onChange);
+		server.watcher.on("add", onChange);
+		const closeServer = server.close.bind(server);
+		server.close = async () => {
+			server.watcher.off("change", onChange);
+			server.watcher.off("add", onChange);
+			clearTimeout(timer);
+			return closeServer();
+		};
+	};
 	return [
 		{
 			name: `${PLUGIN_NAME}:config`,
@@ -870,6 +1046,7 @@ function UserscriptPlugin(config) {
 			apply: "serve",
 			configureServer(server) {
 				configureDevServer(server, resolved, reactPreamble);
+				if (resolved.scripts.some((script) => script.server.file)) startFileWatchBuild(server);
 			}
 		},
 		{
@@ -887,13 +1064,23 @@ function UserscriptPlugin(config) {
 			name: `${PLUGIN_NAME}:build`,
 			apply: "build",
 			enforce: "post",
+			configResolved(viteConfig) {
+				isWatch = Boolean(viteConfig.build.watch);
+				mode = viteConfig.mode;
+				outDir = resolve(viteConfig.root, viteConfig.build.outDir);
+			},
 			generateBundle(_options, bundle) {
-				applyUserscriptBundle(bundle, resolved, (fileName, source) => {
-					this.emitFile({
-						type: "asset",
-						fileName,
-						source
-					});
+				isWatch = this.meta.watchMode || isWatch;
+				applyUserscriptBundle(bundle, resolved, {
+					emitFile: (fileName, source) => {
+						this.emitFile({
+							type: "asset",
+							fileName,
+							source
+						});
+					},
+					emitProxy: shouldEmitProxy(),
+					outDir
 				});
 			}
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vite-userscript-plugin",
   "type": "module",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "author": {
     "name": "Vitalij Ryndin",
     "url": "https://github.com/crashmax-dev"