vite-userscript-plugin 2.3.0 → 2.4.0

package/README.md

@@ -111,6 +111,8 @@ import './style.css'
 
 `index.html` is a normal Vite app next to the userscript. `vite` serves it at `/`. `vite build` writes it to `dist/` beside `{fileName}.user.js`.
 
+The plugin sets `build.assetsInlineLimit` very high so userscript assets become data URLs. The HTML app’s assets will too, unless you set `build.assetsInlineLimit` yourself.
+
 > [!WARNING]
 > Keep the page's `<script>` entries distinct from `entry`.
 
@@ -133,7 +135,7 @@ See [examples/sourcemap](./examples/sourcemap).
 | Option | Default | Description |
 | --- | --- | --- |
 | `entry` | — | Userscript entry. Required. |
-| `header` | — | Metablock. Required: `name`, `version`, `match`. Relative `icon` / `require` / `resource` / `supportURL` / `updateURL` / `downloadURL` join `homepage` (`homepageURL` / `website` / `source`). Absolute `http(s):` URLs stay as-is. |
+| `header` | — | Metablock. Required: `name`, `version`, `match`. Relative `icon` / `require` / `resource` / `supportURL` / `updateURL` / `downloadURL` join `homepage` (`homepageURL` / `website` / `source`). Absolute `http(s):` URLs stay as-is. `updateURL` / `downloadURL` of `none` disable updates and are not joined. |
 | `fileName` | sanitized `header.name` | Output base name (`{fileName}.user.js`). |
 | `server.open` | `false` | Open the install target when Vite starts (`true`, `'user'`, `'proxy'`). HMR: `.dev.user.js`. `file`: `.user.js` or `.proxy.user.js`. Vite opens one URL. |
 | `server.prefix` | `'server:'` | Prefix for `@name` in serve mode. `false` disables it. |
@@ -142,10 +144,30 @@ See [examples/sourcemap](./examples/sourcemap).
 | `generate` | — | Rewrite the generated metablock. |
 | `autoMetaUrls` | `false` | Fill empty `updateURL` / `downloadURL` from `homepage` / `homepageURL` / `website` / `source`. |
 | `metaFile` | `true` | Emit `{fileName}.meta.js`. |
+| `external` | — | Keep these packages out of the bundle and load them via `@require`. Keys are specifiers (`jquery`, `vue`). A string value is the CDN URL (global name from the specifier). Pass `{ global, url }` for `$` / `Vue`. Install `@types/…` for `tsc`; do not install the runtime package. See [examples/external-cdn](./examples/external-cdn). |
 
 Everything else on `header` follows the manager metablock (`@grant`, `@require`, `@connect`, …).
 
-In serve mode the header lists every grant. In production the plugin scans the bundle and writes only the grants in use. `grant: "none"` disables GM APIs and is never mixed with the scan.
+```ts
+userscript({
+  entry: 'src/index.ts',
+  header: {
+    name: pkg.name,
+    version: pkg.version,
+    match: 'https://example.com/*',
+  },
+  external: {
+    jquery: {
+      global: '$',
+      url: 'https://cdn.jsdelivr.net/npm/jquery@4.0.0/dist/jquery.min.js',
+    },
+  },
+})
+```
+
+For types without bundling the package: add `@types/jquery` (not `jquery`) and a `d.ts` that references those types. The import type-checks; the plugin maps it to the CDN global. Full setup: [examples/external-cdn](./examples/external-cdn).
+
+In serve mode the header lists every grant. In production the plugin scans the bundle and writes only the grants in use. `window.focus`, `window.close`, and `window.onurlchange` are **not** auto-detected (they collide with DOM APIs) — list them in `header.grant` when you need them. `grant: "none"` disables GM APIs and is never mixed with the scan.
 
 > [!WARNING]
 > Keep `metaFile: true` if you use `autoMetaUrls`. Otherwise `@updateURL` points at a file that is not emitted.
@@ -161,6 +183,7 @@ In serve mode the header lists every grant. In production the plugin scans the b
 | [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. |
+| [external-cdn](./examples/external-cdn) | `@types/jquery` only; runtime `$` from a CDN `@require`. |
 
 ## FAQ
 

package/dist/index.d.ts

@@ -63,18 +63,33 @@ type HeaderConfig = {
    */
   'author'?: string;
   /**
+   * Script homepage. Also the base for relative `icon`, `iconURL`,
+   * `defaulticon`, `icon64`, `icon64URL`, `require`, `resource`, `supportURL`,
+   * `updateURL`, and `downloadURL`. Absolute `http(s):` URLs stay as-is.
+   * `updateURL` / `downloadURL` of `none` are not joined.
+   *
+   * Fallback order: `homepage`, `homepageURL`, `website`, `source`.
+   *
    * @see https://www.tampermonkey.net/documentation.php#meta:homepage
    */
   'homepage'?: string;
   /**
+   * Alias of `homepage`. Used as the relative-URL base when `homepage` is empty.
+   *
    * @see https://www.tampermonkey.net/documentation.php#meta:homepage
    */
   'homepageURL'?: string;
   /**
+   * Alias of `homepage`. Used as the relative-URL base when `homepage` and
+   * `homepageURL` are empty.
+   *
    * @see https://www.tampermonkey.net/documentation.php#meta:homepage
    */
   'website'?: string;
   /**
+   * Alias of `homepage`. Used as the relative-URL base when `homepage`,
+   * `homepageURL`, and `website` are empty.
+   *
    * @see https://www.tampermonkey.net/documentation.php#meta:homepage
    */
   'source'?: string;
@@ -124,13 +139,17 @@ type HeaderConfig = {
    */
   'noframes'?: boolean;
   /**
+   * `none` disables update checks. It is not joined with homepage.
+   *
    * @see https://www.tampermonkey.net/documentation.php#meta:updateURL
    */
-  'updateURL'?: string;
+  'updateURL'?: 'none' | (string & {});
   /**
+   * `none` disables update checks (pinned / non-latest installs). It is not joined with homepage.
+   *
    * @see https://www.tampermonkey.net/documentation.php#meta:downloadURL
    */
-  'downloadURL'?: string;
+  'downloadURL'?: 'none' | (string & {});
   /**
    * @see https://www.tampermonkey.net/documentation.php#meta:supportURL
    */
@@ -176,6 +195,22 @@ interface HeaderGenerateContext {
   userscript: string;
   mode: HeaderMode;
 }
+interface ExternalRequire {
+  /**
+   * Global name the `@require` script assigns (e.g. `$`, `Vue`).
+   */
+  global: string;
+  /**
+   * Absolute URL added to `@require`.
+   */
+  url: string;
+}
+type UserscriptExternal = Record<string, string | ExternalRequire>;
+interface ResolvedExternal {
+  specifier: string;
+  global: string;
+  url: string;
+}
 /**
  * One userscript. Pass an object, or an array of these, to {@link UserscriptPluginConfig}.
  */
@@ -224,12 +259,21 @@ interface UserscriptConfig {
    * @default true
    */
   metaFile?: boolean;
+  /**
+   * Keep these packages out of the bundle and load them via `@require`.
+   * Keys are specifiers (`jquery`, `vue`). A string value is the CDN URL; the
+   * global name is derived from the specifier. Pass `{ global, url }` for `$` / `Vue`.
+   *
+   * Install `@types/…` (or a types-only package) for `tsc`. Do not install the
+   * runtime package — serve maps the specifier to the CDN global, build rewrites
+   * the import. See `examples/external-cdn`.
+   */
+  external?: UserscriptExternal;
 }
 type UserscriptPluginConfig = UserscriptConfig | UserscriptConfig[];
 interface ResolvedScript {
   entry: string;
   fileName: string;
-  iifeName: string;
   header: HeaderConfig;
   server: {
     open: ResolvedServerOpen;
@@ -240,9 +284,10 @@ interface ResolvedScript {
   generate?: (ctx: HeaderGenerateContext) => string;
   autoMetaUrls: boolean;
   metaFile: boolean;
+  external: ResolvedExternal[];
 }
 //#endregion
 //#region src/plugin.d.ts
 declare function UserscriptPlugin(config: UserscriptPluginConfig): Plugin[];
 //#endregion
-export { type HeaderConfig, type HeaderGenerateContext, type ResolvedScript, type ResolvedServerOpen, type ServerConfig, type ServerOpen, type UserscriptConfig, type UserscriptPluginConfig, UserscriptPlugin as default };
+export { type ExternalRequire, type HeaderConfig, type HeaderGenerateContext, type ResolvedExternal, type ResolvedScript, type ResolvedServerOpen, type ServerConfig, type ServerOpen, type UserscriptConfig, type UserscriptExternal, type UserscriptPluginConfig, UserscriptPlugin as default };

package/dist/index.js

@@ -54,7 +54,7 @@ const gmIdentifiers = [
 ];
 //#endregion
 //#region src/grants/scan.ts
-const grantMatchers = grants.map((grant) => ({
+const grantMatchers = grants.filter((grant) => !grant.startsWith("window.")).map((grant) => ({
 	grant,
 	pattern: new RegExp(`\\b${grant.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`)
 }));
@@ -74,15 +74,11 @@ function withServeGrants(header) {
 		grant: [.../* @__PURE__ */ new Set([...header.grant ?? [], ...grants])]
 	};
 }
-function withBuildGrants(header, code, extraGrants = []) {
+function withBuildGrants(header, code) {
 	if (header.grant === "none") return header;
 	return {
 		...header,
-		grant: removeDuplicates([
-			...defineGrants(code),
-			...removeDuplicates(header.grant),
-			...extraGrants
-		])
+		grant: removeDuplicates([...defineGrants(code), ...removeDuplicates(header.grant)])
 	};
 }
 //#endregion
@@ -118,16 +114,17 @@ function resolveHomePage(header) {
 	const trimmed = homePage.trim();
 	return trimmed === "" ? void 0 : trimmed;
 }
-function isResolvableHeaderPath(value) {
+function isResolvableHeaderPath(value, field) {
 	const trimmed = value.trim();
 	if (!trimmed) return false;
+	if ((field === "updateURL" || field === "downloadURL") && trimmed.toLowerCase() === "none") return false;
 	if (ABSOLUTE_URL_RE.test(trimmed) || trimmed.startsWith("//") || trimmed.startsWith("/")) return false;
 	return true;
 }
-function containsResolvableHeaderPath(value) {
-	if (typeof value === "string") return isResolvableHeaderPath(value);
+function containsResolvableHeaderPath(value, field) {
+	if (typeof value === "string") return isResolvableHeaderPath(value, field);
 	if (!Array.isArray(value)) return false;
-	return value.some((item) => typeof item === "string" && isResolvableHeaderPath(item));
+	return value.some((item) => typeof item === "string" && isResolvableHeaderPath(item, field));
 }
 function containsResolvableResourcePath(resource) {
 	if (!Array.isArray(resource)) return false;
@@ -137,7 +134,7 @@ function containsResolvableResourcePath(resource) {
 }
 function listHomepageRelativeFields(header) {
 	const fields = [];
-	for (const key of HOMEPAGE_RELATIVE_FIELDS) if (containsResolvableHeaderPath(header[key])) fields.push(key);
+	for (const key of HOMEPAGE_RELATIVE_FIELDS) if (containsResolvableHeaderPath(header[key], key)) fields.push(key);
 	if (containsResolvableResourcePath(header.resource)) fields.push("resource");
 	return fields;
 }
@@ -148,12 +145,12 @@ function resolvePublicFileUrl(header, fileName) {
 		return new URL(fileName, ensureTrailingSlash(homePage)).href;
 	} catch {}
 }
-function resolveHeaderUrlValue(header, value) {
+function resolveHeaderUrlValue(header, value, field) {
 	if (typeof value === "string") {
-		if (!isResolvableHeaderPath(value)) return value;
+		if (!isResolvableHeaderPath(value, field)) return value;
 		return resolvePublicFileUrl(header, value.trim()) ?? value;
 	}
-	if (Array.isArray(value)) return value.map((item) => typeof item === "string" ? resolveHeaderUrlValue(header, item) : item);
+	if (Array.isArray(value)) return value.map((item) => typeof item === "string" ? resolveHeaderUrlValue(header, item, field) : item);
 	return value;
 }
 function resolveResourceUrls(header, resource) {
@@ -169,7 +166,7 @@ function resolveResourceUrls(header, resource) {
 function applyHomepageRelativeUrls(header) {
 	if (!resolveHomePage(header)) return header;
 	const next = { ...header };
-	for (const key of HOMEPAGE_RELATIVE_FIELDS) if (next[key] != null) Object.assign(next, { [key]: resolveHeaderUrlValue(next, next[key]) });
+	for (const key of HOMEPAGE_RELATIVE_FIELDS) if (next[key] != null) Object.assign(next, { [key]: resolveHeaderUrlValue(next, next[key], key) });
 	if (next.resource != null) next.resource = resolveResourceUrls(next, next.resource);
 	return next;
 }
@@ -311,21 +308,86 @@ function isAsset(item) {
 	return item.type === "asset";
 }
 //#endregion
+//#region src/build/graph.ts
+function importedChunkIds(chunk, includeDynamic = true) {
+	if (!includeDynamic) return [...chunk.imports];
+	return [...chunk.imports, ...chunk.dynamicImports ?? []];
+}
+function walkImportedChunks(chunk, bundle, options = {}) {
+	const includeDynamic = options.includeDynamic ?? true;
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (current) => {
+		for (const fileName of importedChunkIds(current, includeDynamic)) {
+			if (seen.has(fileName)) continue;
+			const dep = bundle[fileName];
+			if (!dep || !isChunk(dep) || dep.isEntry) continue;
+			seen.add(fileName);
+			visit(dep);
+			result.push({
+				fileName,
+				chunk: dep
+			});
+		}
+	};
+	visit(chunk);
+	return result;
+}
+function collectImportedChunkIds(chunk, bundle) {
+	return new Set(walkImportedChunks(chunk, bundle).map((item) => item.fileName));
+}
+function inlineImportedChunks(chunk, bundle) {
+	return walkImportedChunks(chunk, bundle).map(({ chunk: dep }) => dep.code.endsWith("\n") ? dep.code : `${dep.code}\n`).join("");
+}
+function namespaceLiteral(chunk) {
+	return `{ ${(chunk.exports ?? []).map((name) => {
+		if (name === "default") return "default: undefined";
+		return /^[a-z_$][\w$]*$/i.test(name) ? name : `${JSON.stringify(name)}: undefined`;
+	}).join(", ")} }`;
+}
+function replaceDynamicImportCalls(code, fileName, namespace) {
+	const replacement = `Promise.resolve(${namespace})`;
+	const baseName = fileName.split("/").pop() ?? fileName;
+	const candidates = [
+		fileName,
+		`./${fileName}`,
+		baseName,
+		`./${baseName}`
+	];
+	let next = code;
+	for (const name of new Set(candidates)) {
+		const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		next = next.replace(new RegExp(`\\bimport\\s*\\(\\s*(?:/\\*[\\s\\S]*?\\*/\\s*)?(['"])${escaped}\\1\\s*\\)`, "g"), replacement);
+	}
+	return next;
+}
+function rewriteInlinedDynamicImports(code, chunk, bundle) {
+	let next = code;
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (current) => {
+		for (const fileName of current.dynamicImports ?? []) {
+			if (seen.has(fileName)) continue;
+			seen.add(fileName);
+			const dep = bundle[fileName];
+			if (!dep || !isChunk(dep)) continue;
+			visit(dep);
+			next = replaceDynamicImportCalls(next, fileName, namespaceLiteral(dep));
+		}
+	};
+	visit(chunk);
+	if (next.includes("__vitePreload")) return `function __vitePreload(fn){return fn();}\n${next}`;
+	return next;
+}
+//#endregion
 //#region src/build/css.ts
 const defaultCssInjector = `(function (css) {
   var style = document.createElement('style')
   style.textContent = css
   ;(document.head || document.documentElement).appendChild(style)
 })`;
-function collectImportedCss(chunk, bundle, seen = /* @__PURE__ */ new Set()) {
+function collectImportedCss(chunk, bundle) {
 	const files = [...chunk.viteMetadata?.importedCss ?? []];
-	for (const imported of chunk.imports) {
-		if (seen.has(imported)) continue;
-		const dep = bundle[imported];
-		if (!dep || !isChunk(dep) || dep.isEntry) continue;
-		seen.add(imported);
-		files.push(...collectImportedCss(dep, bundle, seen));
-	}
+	for (const { chunk: dep } of walkImportedChunks(chunk, bundle)) files.push(...dep.viteMetadata?.importedCss ?? []);
 	return files;
 }
 function collectCss(chunk, bundle) {
@@ -346,6 +408,94 @@ function createCssInject(css) {
 	return `${defaultCssInjector}(${JSON.stringify(css)});\n`;
 }
 //#endregion
+//#region src/build/external.ts
+function resolveExternals(external) {
+	if (!external) return [];
+	return Object.entries(external).map(([specifier, value]) => {
+		if (typeof value === "string") return {
+			specifier,
+			url: value,
+			global: toIdentifier(specifier)
+		};
+		return {
+			specifier,
+			url: value.url,
+			global: value.global
+		};
+	});
+}
+function toRequireList$1(value) {
+	if (value == null) return [];
+	return Array.isArray(value) ? value.map(String) : [String(value)];
+}
+function mergeRequireUrls(header, urls) {
+	if (!urls.length) return header;
+	const merged = [...toRequireList$1(header.require)];
+	for (const url of urls) if (!merged.includes(url)) merged.push(url);
+	return {
+		...header,
+		require: merged
+	};
+}
+function withExternalRequires(header, externals) {
+	return mergeRequireUrls(header, externals.map((item) => item.url));
+}
+function normalizeNamedImports(inner) {
+	return inner.split(",").map((part) => {
+		const trimmed = part.trim();
+		if (!trimmed) return trimmed;
+		const asMatch = trimmed.match(/^([a-z_$][\w$]*)\s+as\s+([a-z_$][\w$]*)$/i);
+		if (asMatch) return `${asMatch[1]}: ${asMatch[2]}`;
+		return trimmed;
+	}).filter(Boolean).join(", ");
+}
+const IDENT = "([a-z_$][\\w$]*)";
+const IDENT_FLAGS = "i";
+function rewriteImportClause(clause, globalName) {
+	const trimmed = clause.trim();
+	const star = trimmed.match(new RegExp(`^\\*\\s+as\\s+${IDENT}$`, IDENT_FLAGS));
+	if (star?.[1]) return star[1] === globalName ? "" : `const ${star[1]} = ${globalName};`;
+	const defaultStar = trimmed.match(new RegExp(`^${IDENT}\\s*,\\s*\\*\\s+as\\s+${IDENT}$`, IDENT_FLAGS));
+	if (defaultStar?.[1] && defaultStar[2]) return [defaultStar[1] === globalName ? "" : `const ${defaultStar[1]} = ${globalName};`, defaultStar[2] === globalName ? "" : `const ${defaultStar[2]} = ${globalName};`].filter(Boolean).join(" ");
+	const defaultNamed = trimmed.match(new RegExp(`^${IDENT}\\s*,\\s*\\{([^}]+)\\}$`, IDENT_FLAGS));
+	if (defaultNamed?.[1] && defaultNamed[2] != null) {
+		const named = `const { ${normalizeNamedImports(defaultNamed[2])} } = ${globalName};`;
+		if (defaultNamed[1] === globalName) return named;
+		return `const ${defaultNamed[1]} = ${globalName}; ${named}`;
+	}
+	const named = trimmed.match(/^\{([^}]+)\}$/);
+	if (named?.[1] != null) return `const { ${normalizeNamedImports(named[1])} } = ${globalName};`;
+	if (/^[a-z_$][\w$]*$/i.test(trimmed)) return trimmed === globalName ? "" : `const ${trimmed} = ${globalName};`;
+	return `const ${trimmed} = ${globalName};`;
+}
+function rewriteExternalImports(code, externals) {
+	let next = code;
+	for (const { specifier, global: globalName } of externals) {
+		const quoted = `["']${specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']`;
+		next = next.replace(new RegExp(`(^|\\n)import\\s*${quoted}\\s*;?`, "g"), "$1");
+		next = next.replace(new RegExp(`(^|\\n)import\\s+type\\s+[\\s\\S]*?\\s+from\\s*${quoted}\\s*;?`, "g"), "$1");
+		next = next.replace(new RegExp(`(^|\\n)import\\s+([\\s\\S]*?)\\s+from\\s*${quoted}\\s*;?`, "g"), (_match, lead, clause) => {
+			const rewritten = rewriteImportClause(clause, globalName);
+			return rewritten ? `${lead}${rewritten}` : lead;
+		});
+	}
+	return next;
+}
+function mergeRolldownExternal(user, specifiers) {
+	if (!specifiers.length) return user;
+	if (typeof user === "function") {
+		const specSet = new Set(specifiers);
+		return (id, importer, isResolved) => {
+			if (specSet.has(id)) return true;
+			return user(id, importer, isResolved);
+		};
+	}
+	let list = [];
+	if (Array.isArray(user)) list = [...user];
+	else if (user != null) list = [user];
+	return [...list, ...specifiers];
+}
+//#endregion
 //#region src/build/iife.ts
 const SOURCE_MAPPING_URL_RE = /\/\/[#@]\s*sourceMappingURL=\S+/g;
 function stripSourceMappingUrl(code) {
@@ -357,11 +507,15 @@ function stripImports(code) {
 function stripExports(code) {
 	return code.replace(/^export\s+\{[\s\S]*?\}\s+from\s+["'][^"']+["']\s*;?\s*$/gm, "").replace(/^export\s+\*\s+from\s+["'][^"']+["']\s*;?\s*$/gm, "").replace(/^export\s+\{[\s\S]*?\};?\s*$/gm, "").replace(/^export\s+default\s+/gm, "").replace(/^export\s+async\s+function/gm, "async function").replace(/^export\s+function/gm, "function").replace(/^export\s+class/gm, "class").replace(/^export\s+(const|let|var)/gm, "$1");
 }
+function stripDynamicImports(code) {
+	return code.replace(/\bimport\s*\(\s*(?:\/\*[\s\S]*?\*\/\s*)?["'][^"']+["']\s*\)/g, "Promise.resolve({})");
+}
 function stripModuleSyntax(code) {
-	return stripExports(stripImports(code));
+	return stripExports(stripImports(stripDynamicImports(code)));
 }
 function isAlreadyIife(code) {
-	return !/^\s*(?:import|export)\s/m.test(code) && /\(\s*(?:async\s+)?function\b/.test(code);
+	const trimmed = code.trimStart();
+	return !/^\s*(?:import|export)\s/m.test(code) && /^\(\s*(?:async\s+)?function\b/.test(trimmed);
 }
 function ensureIife(code) {
 	const withoutMap = stripSourceMappingUrl(code);
@@ -379,7 +533,7 @@ function toRequireList(value) {
 	return Array.isArray(value) ? value.map(String) : [String(value)];
 }
 function createWatchProxyHeader(script, jsAbsPath) {
-	const header = withServeGrants({ ...script.header });
+	const header = withServeGrants(withExternalRequires(script.header, script.external));
 	return {
 		...header,
 		require: [...toRequireList(header.require), toFileRequireUrl(jsAbsPath)]
@@ -402,35 +556,6 @@ function toRequireFileName(fileName) {
 }
 //#endregion
 //#region src/build/apply.ts
-function importedChunkIds(chunk) {
-	return [...chunk.imports, ...chunk.dynamicImports ?? []];
-}
-function inlineImportedChunks(chunk, bundle, seen = /* @__PURE__ */ new Set()) {
-	let prelude = "";
-	for (const imported of chunk.imports) {
-		if (seen.has(imported)) continue;
-		const dep = bundle[imported];
-		if (!dep || !isChunk(dep) || dep.isEntry) continue;
-		seen.add(imported);
-		prelude += inlineImportedChunks(dep, bundle, seen);
-		prelude += dep.code.endsWith("\n") ? dep.code : `${dep.code}\n`;
-	}
-	return prelude;
-}
-function collectImportedChunks(chunk, bundle) {
-	const files = /* @__PURE__ */ new Set();
-	const walk = (current) => {
-		for (const imported of importedChunkIds(current)) {
-			if (files.has(imported)) continue;
-			const dep = bundle[imported];
-			if (!dep || !isChunk(dep) || dep.isEntry) continue;
-			files.add(imported);
-			walk(dep);
-		}
-	};
-	walk(chunk);
-	return files;
-}
 function collectImportedCssFiles(fileNames, bundle) {
 	const files = /* @__PURE__ */ new Set();
 	for (const fileName of fileNames) {
@@ -448,8 +573,13 @@ 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 offsetUserscriptMap(options) {
+	const wrapOffset = isAlreadyIife(stripSourceMappingUrl(options.body)) ? 0 : 1;
+	const lineOffset = countHeaderLines(options.headerPrefix ?? "") + countHeaderLines(options.cssPrelude) + wrapOffset + countHeaderLines(options.inlined);
+	return stripVendorSourcesContent(offsetSourceMap(options.map, lineOffset, options.fileName));
+}
 function createHeadedUserscript(script, options) {
-	const headerConfig = withBuildGrants(script.header, options.wrapped);
+	const headerConfig = withBuildGrants(withExternalRequires(script.header, script.external), options.wrapped);
 	const prefix = `${generateHeader(headerConfig, {
 		align: script.headerAlign,
 		autoMetaUrls: script.autoMetaUrls,
@@ -460,9 +590,14 @@ function createHeadedUserscript(script, options) {
 	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));
+		const map = offsetUserscriptMap({
+			map: options.map,
+			fileName: nextFileName,
+			cssPrelude: options.cssPrelude,
+			inlined: options.inlined,
+			body: options.body,
+			headerPrefix: prefix
+		});
 		nextCode = `${stripSourceMappingUrl(nextCode).replace(/\n+$/g, "\n")}//# sourceMappingURL=${toInlineSourceMappingUrl(map)}\n`;
 	}
 	return {
@@ -490,7 +625,7 @@ function applyUserscriptBundle(bundle, config, context) {
 	const keptChunks = new Set(otherEntryFiles);
 	for (const fileName of otherEntryFiles) {
 		const chunk = bundle[fileName];
-		if (chunk && isChunk(chunk)) for (const dep of collectImportedChunks(chunk, bundle)) keptChunks.add(dep);
+		if (chunk && isChunk(chunk)) for (const dep of collectImportedChunkIds(chunk, bundle)) keptChunks.add(dep);
 	}
 	const keptCss = collectImportedCssFiles(keptChunks, bundle);
 	const leftoverChunks = [];
@@ -500,7 +635,7 @@ function applyUserscriptBundle(bundle, config, context) {
 		const { css, files: cssFiles } = collectCss(chunk, bundle);
 		for (const cssFile of cssFiles) if (!keptCss.has(cssFile)) leftoverAssets.push(...withSourceMaps([cssFile]));
 		const cssPrelude = css ? createCssInject(css) : "";
-		const body = `${inlined}${chunk.code}`;
+		const body = rewriteExternalImports(rewriteInlinedDynamicImports(`${inlined}${chunk.code}`, chunk, bundle), script.external);
 		const wrapped = ensureIife(body);
 		const code = `${cssPrelude}${wrapped}`;
 		const emitFileProxy = Boolean(context.emitProxy && context.outDir && script.server.file);
@@ -517,9 +652,13 @@ function applyUserscriptBundle(bundle, config, context) {
 			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));
+				chunk.map = offsetUserscriptMap({
+					map: chunk.map,
+					fileName: requireName,
+					cssPrelude,
+					inlined,
+					body
+				});
 				nextCode = `${stripSourceMappingUrl(nextCode).replace(/\n+$/g, "\n")}//# sourceMappingURL=${toInlineSourceMappingUrl(chunk.map)}\n`;
 			}
 			chunk.code = nextCode;
@@ -651,7 +790,6 @@ function toResolvedScript(config) {
 	return {
 		entry: config.entry,
 		fileName,
-		iifeName: toIdentifier(fileName),
 		header: config.header,
 		server: {
 			open: resolveServerOpen(config.server?.open, file),
@@ -661,7 +799,8 @@ function toResolvedScript(config) {
 		headerAlign: config.headerAlign ?? 1,
 		generate: config.generate,
 		autoMetaUrls: config.autoMetaUrls ?? false,
-		metaFile: config.metaFile ?? true
+		metaFile: config.metaFile ?? true,
+		external: resolveExternals(config.external)
 	};
 }
 function collectAutoMetaUrlsWarnings(config) {
@@ -713,6 +852,28 @@ function resolvePluginConfig(config) {
 	return { scripts };
 }
 //#endregion
+//#region src/serve/external.ts
+const EXTERNAL_MODULE_PREFIX = `\0${PLUGIN_NAME}:external:`;
+function toExternalModuleId(specifier) {
+	return `${EXTERNAL_MODULE_PREFIX}${specifier}`;
+}
+function matchExternalModuleId(id) {
+	if (!id.startsWith(EXTERNAL_MODULE_PREFIX)) return;
+	return id.slice(EXTERNAL_MODULE_PREFIX.length);
+}
+function findResolvedExternal(scripts, specifier) {
+	for (const script of scripts) {
+		const hit = script.external.find((item) => item.specifier === specifier);
+		if (hit) return hit;
+	}
+}
+function listExternalSpecifiers(scripts) {
+	return [...new Set(scripts.flatMap((script) => script.external.map((item) => item.specifier)))];
+}
+function renderExternalModule(globalName) {
+	return `const api = globalThis[${JSON.stringify(globalName)}];\nexport default api;\n`;
+}
+//#endregion
 //#region src/serve/gm-shim.ts
 function shouldShimModule(id) {
 	const cleanId = id.split("\0").pop() ?? id;
@@ -812,14 +973,17 @@ import ${JSON.stringify(entryPath)};
 }
 //#endregion
 //#region src/serve/wrapper.ts
+function matchUserscriptPath(url, fileName, suffix) {
+	return (url.split("?")[0] ?? "") === `/${fileName}${suffix}`;
+}
 function matchDevUserscript(url, fileName) {
-	return (url.split("?")[0] ?? "") === `/${fileName}.dev.user.js`;
+	return matchUserscriptPath(url, fileName, ".dev.user.js");
 }
 function matchProxyUserscript(url, fileName) {
-	return (url.split("?")[0] ?? "") === `/${toProxyFileName(fileName)}`;
+	return matchUserscriptPath(url, fileName, ".proxy.user.js");
 }
 function matchFileUserscript(url, fileName) {
-	return (url.split("?")[0] ?? "") === `/${fileName}.user.js`;
+	return matchUserscriptPath(url, fileName, ".user.js");
 }
 function toInstallFileName(fileName, kind) {
 	return {
@@ -838,17 +1002,17 @@ function toServeEntryPath(root, entry) {
 	const absolute = resolve(root, entry);
 	return `/${relative(root, absolute).split(sep).join(posix.sep)}`;
 }
-function applyServeHeader(header, prefix) {
-	return withServeGrants({
+function applyServeHeader(header, prefix, externals = []) {
+	return withServeGrants(withExternalRequires({
 		...header,
 		name: prefix === false ? header.name : `${prefix}${header.name}`
-	});
+	}, externals));
 }
 function generateDevWrapper(options) {
 	const clientUrl = `${options.origin}/@vite/client`;
 	const entryUrl = `${options.origin}${options.entryPath}`;
 	const bootstrapUrl = `${options.origin}${REACT_BOOTSTRAP_PATH}?entry=${encodeURIComponent(options.entryPath)}`;
-	const copies = gmIdentifiers.map((id) => `if (typeof ${id} !== 'undefined') gm.${id} = ${id};`).join("\n  ");
+	const copies = [...gmIdentifiers.map((id) => `if (typeof ${id} !== 'undefined') gm.${id} = ${id};`), ...(options.externals ?? []).map((item) => `if (typeof ${item.global} !== 'undefined') root.${item.global} = ${item.global};`)].join("\n  ");
 	const injectTarget = options.reactPreamble ? bootstrapUrl : entryUrl;
 	const clientInject = options.reactPreamble ? "" : `
   if (!root.${VITE_CLIENT_FLAG}) {
@@ -873,14 +1037,15 @@ ${clientInject}
 `;
 }
 function generateDevUserscript(options) {
-	return `${generateHeader(applyServeHeader(options.script.header, options.prefix), {
+	return `${generateHeader(applyServeHeader(options.script.header, options.prefix, options.script.external), {
 		...options.headerOptions,
 		fileName: options.script.fileName,
 		mode: "serve"
 	})}\n\n${generateDevWrapper({
 		origin: options.origin,
 		entryPath: toServeEntryPath(options.root, options.script.entry),
-		reactPreamble: options.reactPreamble
+		reactPreamble: options.reactPreamble,
+		externals: options.script.external
 	})}`;
 }
 function findDevScript(url, scripts) {
@@ -994,6 +1159,49 @@ function configureDevServer(server, resolved, reactPreamble) {
 	};
 }
 //#endregion
+//#region src/serve/watch-queue.ts
+function createDebouncedSingleFlight(task, delay, onError) {
+	let timer;
+	let running = false;
+	let queued = false;
+	const run = async () => {
+		if (running) {
+			queued = true;
+			return;
+		}
+		running = true;
+		try {
+			while (true) {
+				queued = false;
+				await task();
+				if (!queued) break;
+			}
+		} catch (error) {
+			onError(error);
+		} finally {
+			running = false;
+			if (queued) {
+				queued = false;
+				run();
+			}
+		}
+	};
+	return {
+		schedule: () => {
+			clearTimeout(timer);
+			timer = setTimeout(() => {
+				timer = void 0;
+				run();
+			}, delay);
+		},
+		cancel: () => {
+			clearTimeout(timer);
+			timer = void 0;
+		},
+		pending: () => running || queued || timer != null
+	};
+}
+//#endregion
 //#region src/plugin.ts
 function absolutizeEntries(config, root) {
 	return { scripts: config.scripts.map((script) => ({
@@ -1047,30 +1255,34 @@ function UserscriptPlugin(config) {
 			server.config.logger.error(String(error));
 			return;
 		}
-		let timer;
+		const scheduler = createDebouncedSingleFlight(run, 80, (error) => {
+			server.config.logger.error(String(error));
+		});
 		const onChange = (file) => {
 			if (file.startsWith(outDirAbs)) return;
-			clearTimeout(timer);
-			timer = setTimeout(() => {
-				run().catch((error) => {
-					server.config.logger.error(String(error));
-				});
-			}, 80);
+			scheduler.schedule();
 		};
 		server.watcher.on("change", onChange);
 		server.watcher.on("add", onChange);
-		const closeServer = server.close.bind(server);
-		server.close = async () => {
+		let cleaned = false;
+		const cleanup = () => {
+			if (cleaned) return;
+			cleaned = true;
+			scheduler.cancel();
 			server.watcher.off("change", onChange);
 			server.watcher.off("add", onChange);
-			clearTimeout(timer);
+		};
+		server.httpServer?.once("close", cleanup);
+		const closeServer = server.close.bind(server);
+		server.close = async () => {
+			cleanup();
 			return closeServer();
 		};
 	};
 	return [
 		{
 			name: `${PLUGIN_NAME}:config`,
-			config(userConfig) {
+			config(userConfig, env) {
 				const { input, hasHtml } = resolvePluginBuildInput(userConfig, resolved.scripts);
 				const scriptNames = new Set(resolved.scripts.map((script) => script.fileName));
 				userConfig.build ??= {};
@@ -1080,11 +1292,25 @@ function UserscriptPlugin(config) {
 				const userEntryFileNames = userOutput && !Array.isArray(userOutput) ? userOutput.entryFileNames : void 0;
 				const openScript = resolved.scripts.find((script) => script.server.open);
 				const openPath = openScript?.server.open ? toInstallPath(openScript.fileName, openScript.server.open) : void 0;
+				const specifiers = listExternalSpecifiers(resolved.scripts);
+				const rolldownOptions = {
+					input,
+					output: {
+						format: "es",
+						entryFileNames: (chunkInfo) => {
+							if (scriptNames.has(chunkInfo.name)) return "[name].js";
+							if (typeof userEntryFileNames === "function") return userEntryFileNames(chunkInfo);
+							if (typeof userEntryFileNames === "string") return userEntryFileNames;
+							return "assets/[name]-[hash].js";
+						}
+					}
+				};
+				if (env.command === "build" && specifiers.length) rolldownOptions.external = mergeRolldownExternal(userConfig.build.rolldownOptions.external, specifiers);
 				return {
 					appType: userConfig.appType ?? (hasHtml ? "spa" : "custom"),
 					optimizeDeps: {
 						entries: Object.values(input),
-						exclude: [VIRTUAL_MODULE_ID]
+						exclude: [VIRTUAL_MODULE_ID, ...specifiers]
 					},
 					server: {
 						cors: userConfig.server?.cors ?? true,
@@ -1093,18 +1319,7 @@ function UserscriptPlugin(config) {
 					build: {
 						minify: userConfig.build?.minify ?? false,
 						assetsInlineLimit: userConfig.build?.assetsInlineLimit ?? Number.MAX_SAFE_INTEGER,
-						rolldownOptions: {
-							input,
-							output: {
-								format: "es",
-								entryFileNames: (chunkInfo) => {
-									if (scriptNames.has(chunkInfo.name)) return "[name].js";
-									if (typeof userEntryFileNames === "function") return userEntryFileNames(chunkInfo);
-									if (typeof userEntryFileNames === "string") return userEntryFileNames;
-									return "assets/[name]-[hash].js";
-								}
-							}
-						}
+						rolldownOptions
 					}
 				};
 			},
@@ -1119,9 +1334,15 @@ function UserscriptPlugin(config) {
 			name: `${PLUGIN_NAME}:virtual`,
 			resolveId: (id) => {
 				if (id === "virtual:vite-userscript-plugin") return RESOLVED_VIRTUAL_MODULE_ID;
+				if (command === "serve" && findResolvedExternal(resolved.scripts, id)) return toExternalModuleId(id);
 			},
 			load: (id) => {
 				if (id === RESOLVED_VIRTUAL_MODULE_ID) return renderVirtualModule(createClientSnapshot(resolved.scripts, command));
+				const specifier = matchExternalModuleId(id);
+				if (!specifier) return;
+				const external = findResolvedExternal(resolved.scripts, specifier);
+				if (!external) return;
+				return renderExternalModule(external.global);
 			}
 		},
 		{

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vite-userscript-plugin",
   "type": "module",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "author": {
     "name": "Vitalij Ryndin",
     "url": "https://github.com/crashmax-dev"
@@ -52,7 +52,8 @@
     "eslint-plugin-format": "2.0.1",
     "prettier-plugin-css-order": "2.2.0",
     "svelte": "5.57.0",
-    "tsdown": "0.22.14",
+    "taze": "21.1.0",
+    "tsdown": "0.23.0",
     "turbo": "2.10.12",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "vite": "8.2.2",
@@ -66,7 +67,8 @@
     "build:examples": "turbo run build --filter=./examples/*",
     "test": "vitest",
     "test:ui": "vitest --ui --watch",
-    "type-check": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p scripts/tsconfig.json && turbo run type-check --filter=./examples/*",
+    "type-check": "tsc --noEmit -p tsconfig.json && turbo run type-check --filter=./examples/*",
+    "check-update": "taze major -Irl",
     "sync-types": "node scripts/sync-types.ts",
     "lint": "eslint . --cache",
     "lint:fix": "eslint . --fix --cache"