@multiplatform.one/vite-plugin-webext 6.2.0

package/src/index.ts

@@ -0,0 +1,412 @@
+// Vite config factories for the web-extension target of a One platform app.
+//
+// The target lives INSIDE the product app (apps/<name>/webext/) — the same
+// pattern as the GNOME target's vite.config.gnome*.ts — and produces a
+// loadable MV3 extension staging dir:
+//
+//   <stagingDir>/manifest.json
+//   <stagingDir>/dist/views/<view>/index.html   (popup/options/sidepanel/…)
+//   <stagingDir>/dist/background/index.mjs      (service worker / bg script)
+//   <stagingDir>/dist/contentScripts/index.global.js
+//
+// Three vite builds cover the three JS worlds (DOM views, worker, injected
+// content script); `runWebextPrepare` writes the manifest and the dev-mode
+// HMR scaffolding. Hard-won workarounds (workspace source aliases, the
+// one-server-only browser stub, expo type-declaration stubs) come from
+// @multiplatform.one/utils/dev so every product app shares one copy.
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  lookupTamaguiModules,
+  oneServerOnlyBrowserStub,
+  stubExpoTypeDeclarations,
+  workspaceSourceAliases,
+  lookupProjectRoot,
+} from "@multiplatform.one/utils/dev";
+import react from "@vitejs/plugin-react";
+import type { Alias, Plugin, UserConfig } from "vite";
+
+export interface WebextPackageInfo {
+  name: string;
+  displayName?: string;
+  version: string;
+  description?: string;
+}
+
+export interface WebextTargetOptions {
+  /** Absolute path of the webext target source dir (contains views/,
+   *  background/, content_scripts/). */
+  targetDir: string;
+  /** Absolute path of the loadable-extension staging dir (manifest.json +
+   *  dist/). Keep it under the app's dist/ so tree-clean stays green. */
+  stagingDir: string;
+  /** Absolute path to the Tamagui config compiled into the views. */
+  tamaguiConfig: string;
+  /** Package identity for defines and bundle names. */
+  packageInfo: WebextPackageInfo;
+  /** Workspace root (defaults to the git toplevel). */
+  workspaceRoot?: string;
+  /** Views dev-server port. */
+  port?: number;
+  /** Development mode (watch + HMR scaffolding). Defaults to
+   *  NODE_ENV !== "production". */
+  isDev?: boolean;
+  /** Extra defines merged over the factory defaults. */
+  define?: Record<string, unknown>;
+  /** Extra resolve aliases appended after the factory's. */
+  aliases?: Alias[];
+}
+
+const WEBEXT_EXTENSIONS = [
+  ".webext.ts",
+  ".webext.tsx",
+  ".webext.js",
+  ".webext.jsx",
+  ".web.ts",
+  ".web.tsx",
+  ".web.js",
+  ".web.jsx",
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+];
+
+const OPTIMIZE_INCLUDE = [
+  "react",
+  "react-dom",
+  "webextension-polyfill",
+  "@tamagui/core",
+  "@tamagui/web",
+  "tamagui",
+  "react-native-web",
+  "@multiplatform.one/components",
+];
+
+/** shiki's chunk graph (wasm/TLA) can't fold into the single-file iife a
+ *  content script requires. Stub it with an empty module —
+ *  @multiplatform.one/components' highlightCode() catches the missing
+ *  codeToTokens and falls back to plain text. */
+export function shikiStubPlugin(): Plugin {
+  const VIRTUAL_ID = "\0webext-shiki-stub";
+  return {
+    name: "webext-shiki-stub",
+    enforce: "pre",
+    resolveId(id: string) {
+      if (/^shiki(\/.*)?$/.test(id)) return VIRTUAL_ID;
+    },
+    load(id: string) {
+      if (id === VIRTUAL_ID) return "export {}";
+    },
+  };
+}
+
+function resolveDefaults(options: WebextTargetOptions) {
+  const workspaceRoot = options.workspaceRoot ?? lookupProjectRoot();
+  const isDev = options.isDev ?? process.env.NODE_ENV !== "production";
+  const port = options.port ?? (Number(process.env.PORT) || 3303);
+  return { workspaceRoot, isDev, port };
+}
+
+function baseDefine(options: WebextTargetOptions, isDev: boolean): Record<string, unknown> {
+  return {
+    __DEV__: isDev,
+    __NAME__: JSON.stringify(options.packageInfo.name),
+    "process.env.NODE_ENV": JSON.stringify(isDev ? "development" : "production"),
+    global: "globalThis",
+    ...options.define,
+  };
+}
+
+function baseResolve(options: WebextTargetOptions, workspaceRoot: string) {
+  return {
+    alias: [
+      ...Object.entries(workspaceSourceAliases(workspaceRoot)).map(([find, replacement]) => ({
+        find,
+        replacement,
+      })),
+      { find: "react-native", replacement: "react-native-web" },
+      { find: "@", replacement: options.targetDir },
+      ...(options.aliases ?? []),
+    ],
+    extensions: WEBEXT_EXTENSIONS,
+    mainFields: ["browser", "module", "main"],
+  } satisfies UserConfig["resolve"];
+}
+
+function baseOptimizeDeps(): UserConfig["optimizeDeps"] {
+  return {
+    include: OPTIMIZE_INCLUDE,
+    esbuildOptions: {
+      resolveExtensions: WEBEXT_EXTENSIONS,
+      mainFields: ["module", "main"],
+    },
+  };
+}
+
+/** Discover view names — every directory under <targetDir>/views with an
+ *  index.html becomes an extension page (popup, options, sidepanel, …). */
+export function listWebextViews(targetDir: string): string[] {
+  const viewsDir = path.join(targetDir, "views");
+  if (!fs.existsSync(viewsDir)) return [];
+  return fs
+    .readdirSync(viewsDir)
+    .filter((file) => fs.statSync(path.join(viewsDir, file)).isDirectory())
+    .filter((view) => fs.existsSync(path.join(viewsDir, view, "index.html")));
+}
+
+/** The extension pages build (popup/options/sidepanel/devtools…). */
+export async function createWebextViewsConfig(options: WebextTargetOptions): Promise<UserConfig> {
+  const { workspaceRoot, isDev, port } = resolveDefaults(options);
+  const { tamaguiPlugin } = await import("@tamagui/vite-plugin");
+  const views = listWebextViews(options.targetDir);
+  return {
+    root: options.targetDir,
+    base: isDev ? `http://localhost:${port}/` : "/dist/",
+    plugins: [
+      stubExpoTypeDeclarations(),
+      oneServerOnlyBrowserStub(workspaceRoot),
+      react({ jsxRuntime: "automatic" }),
+      tamaguiPlugin({
+        components: lookupTamaguiModules([options.targetDir]),
+        config: options.tamaguiConfig,
+        outputCSS: path.join(options.targetDir, "tamagui.css"),
+      }) as Plugin,
+    ],
+    define: baseDefine(options, isDev),
+    optimizeDeps: baseOptimizeDeps(),
+    esbuild: {
+      jsx: "automatic",
+      target: "esnext",
+    },
+    resolve: baseResolve(options, workspaceRoot),
+    server: {
+      port,
+      hmr: {
+        host: "localhost",
+        protocol: "ws",
+        clientPort: port,
+      },
+      origin: `http://localhost:${port}`,
+      cors: true,
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+      },
+    },
+    build: {
+      watch: isDev ? {} : undefined,
+      outDir: path.join(options.stagingDir, "dist"),
+      emptyOutDir: false,
+      sourcemap: isDev ? "inline" : false,
+      terserOptions: {
+        mangle: false,
+      },
+      rollupOptions: {
+        input: Object.fromEntries(
+          views.map((view) => [view, path.join(options.targetDir, "views", view, "index.html")]),
+        ),
+      },
+    },
+  };
+}
+
+/** The background service-worker (chromium) / background-script (firefox)
+ *  build — a single-file iife, no DOM. */
+export function createWebextBackgroundConfig(options: WebextTargetOptions): UserConfig {
+  const { workspaceRoot, isDev } = resolveDefaults(options);
+  return {
+    root: options.targetDir,
+    plugins: [oneServerOnlyBrowserStub(workspaceRoot)],
+    define: baseDefine(options, isDev),
+    optimizeDeps: baseOptimizeDeps(),
+    esbuild: {
+      jsx: "automatic",
+      target: "esnext",
+    },
+    resolve: baseResolve(options, workspaceRoot),
+    build: {
+      watch: isDev ? {} : undefined,
+      outDir: path.join(options.stagingDir, "dist/background"),
+      cssCodeSplit: false,
+      emptyOutDir: false,
+      sourcemap: isDev ? "inline" : false,
+      lib: {
+        entry: path.join(options.targetDir, "background/main.ts"),
+        name: options.packageInfo.name,
+        formats: ["iife"],
+      },
+      rollupOptions: {
+        output: {
+          entryFileNames: "index.mjs",
+          extend: true,
+        },
+      },
+    },
+  };
+}
+
+/** The content-script build — a single-file iife injected into pages, with
+ *  Tamagui CSS extracted separately (webext.css web-accessible resource). */
+export async function createWebextContentConfig(options: WebextTargetOptions): Promise<UserConfig> {
+  const { workspaceRoot, isDev } = resolveDefaults(options);
+  const { tamaguiPlugin } = await import("@tamagui/vite-plugin");
+  return {
+    root: options.targetDir,
+    plugins: [
+      stubExpoTypeDeclarations(),
+      oneServerOnlyBrowserStub(workspaceRoot),
+      shikiStubPlugin(),
+      tamaguiPlugin({
+        components: lookupTamaguiModules([options.targetDir]),
+        config: options.tamaguiConfig,
+        outputCSS: path.join(options.targetDir, "tamagui.content.css"),
+      }) as Plugin,
+    ],
+    define: {
+      ...baseDefine(options, isDev),
+      process: {
+        env: {
+          NODE_ENV: JSON.stringify(isDev ? "development" : "production"),
+        },
+      },
+    },
+    optimizeDeps: baseOptimizeDeps(),
+    esbuild: {
+      jsx: "automatic",
+      target: "esnext",
+    },
+    resolve: baseResolve(options, workspaceRoot),
+    build: {
+      watch: isDev ? {} : undefined,
+      outDir: path.join(options.stagingDir, "dist/contentScripts"),
+      cssCodeSplit: false,
+      emptyOutDir: false,
+      sourcemap: isDev ? "inline" : false,
+      lib: {
+        entry: path.join(options.targetDir, "content_scripts/index.tsx"),
+        name: options.packageInfo.name,
+        formats: ["iife"],
+      },
+      rollupOptions: {
+        output: {
+          entryFileNames: "index.global.js",
+          extend: true,
+        },
+      },
+    },
+  };
+}
+
+// ── prepare pipeline (manifest + dev HMR scaffolding) ─────────────
+
+export interface WebextPrepareOptions {
+  targetDir: string;
+  stagingDir: string;
+  /** Produces the manifest object (app-owned — permissions, views, icons).
+   *  Typed `object` so interface-typed manifests (webextension-polyfill's
+   *  WebExtensionManifest has no index signature) assign cleanly. */
+  getManifest: () => Promise<object> | object;
+  /** Static files (icons, …) copied verbatim into the staging root.
+   *  Defaults to `<targetDir>/static` when it exists. */
+  staticDir?: string;
+  isDev?: boolean;
+  port?: number;
+  /** Watch manifest/html sources and rewrite on change (dev loop). */
+  watch?: boolean;
+}
+
+/** Copy static extension files (icons, …) into the staging root — the
+ *  staging dir is build output (gitignored), so committed assets live in
+ *  the target source tree instead. */
+export async function copyWebextStatic(options: WebextPrepareOptions): Promise<void> {
+  const staticDir = options.staticDir ?? path.join(options.targetDir, "static");
+  if (!fs.existsSync(staticDir)) return;
+  await fs.promises.mkdir(options.stagingDir, { recursive: true });
+  await fs.promises.cp(staticDir, options.stagingDir, { recursive: true });
+}
+
+export async function writeWebextManifest(options: WebextPrepareOptions): Promise<void> {
+  const manifestPath = path.join(options.stagingDir, "manifest.json");
+  await fs.promises.mkdir(path.dirname(manifestPath), { recursive: true });
+  await fs.promises.writeFile(
+    manifestPath,
+    JSON.stringify(await options.getManifest(), null, 2),
+    "utf-8",
+  );
+}
+
+/** Dev mode: emit view HTML that loads main.tsx from the vite dev server
+ *  (extension pages can't be served BY vite — the html on disk must point
+ *  at it) plus the react-refresh preamble shim. */
+export async function stubWebextIndexHtml(options: WebextPrepareOptions): Promise<void> {
+  const port = options.port ?? 3303;
+  for (const view of listWebextViews(options.targetDir)) {
+    let data = await fs.promises.readFile(
+      path.join(options.targetDir, "views", view, "index.html"),
+      "utf-8",
+    );
+    data = data.replace(
+      "</head>",
+      `  <script type="module" src="http://localhost:${port}/@vite/client"></script>
+  <script type="module" src="/dist/refresh.js"></script>
+</head>`,
+    );
+    data = data
+      .replace(
+        '<script type="module" src="./main.tsx"></script>',
+        `<script type="module" src="http://localhost:${port}/views/${view}/main.tsx"></script>`,
+      )
+      .replace('<div id="app"></div>', '<div id="app">vite server did not start</div>');
+    const outPath = path.join(options.stagingDir, "dist/views", view, "index.html");
+    await fs.promises.mkdir(path.dirname(outPath), { recursive: true });
+    await fs.promises.writeFile(outPath, data, "utf-8");
+  }
+}
+
+export async function writeWebextRefreshScript(options: WebextPrepareOptions): Promise<void> {
+  const port = options.port ?? 3303;
+  const refreshPath = path.join(options.stagingDir, "dist/refresh.js");
+  await fs.promises.mkdir(path.dirname(refreshPath), { recursive: true });
+  await fs.promises.writeFile(
+    refreshPath,
+    `window.__vite_plugin_react_preamble_installed__ = true;
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;
+window.addEventListener('load', () => {
+  import("http://localhost:${port}/@react-refresh")
+    .then((RefreshRuntime) => {
+      if (RefreshRuntime && typeof RefreshRuntime.injectIntoGlobalHook === 'function') {
+        RefreshRuntime.injectIntoGlobalHook(window);
+      }
+    })
+    .catch(console.error);
+});
+`,
+    "utf-8",
+  );
+}
+
+/** One-shot (prod) or watching (dev) prepare: manifest + static assets +
+ *  dev scaffolding. */
+export async function runWebextPrepare(options: WebextPrepareOptions): Promise<void> {
+  const isDev = options.isDev ?? process.env.NODE_ENV !== "production";
+  if (!isDev) {
+    await copyWebextStatic(options);
+    await writeWebextManifest(options);
+    return;
+  }
+  await copyWebextStatic(options);
+  await stubWebextIndexHtml(options);
+  await writeWebextRefreshScript(options);
+  await writeWebextManifest(options);
+  if (options.watch) {
+    const { watch } = await import("chokidar");
+    watch(path.join(options.targetDir, "**/*.html")).on("change", () =>
+      stubWebextIndexHtml(options).catch(console.error),
+    );
+    watch(path.join(options.targetDir, "manifest.ts")).on("change", () =>
+      writeWebextManifest(options).catch(console.error),
+    );
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,75 @@
+import type { Alias, Plugin, UserConfig } from "vite";
+export interface WebextPackageInfo {
+    name: string;
+    displayName?: string;
+    version: string;
+    description?: string;
+}
+export interface WebextTargetOptions {
+    /** Absolute path of the webext target source dir (contains views/,
+     *  background/, content_scripts/). */
+    targetDir: string;
+    /** Absolute path of the loadable-extension staging dir (manifest.json +
+     *  dist/). Keep it under the app's dist/ so tree-clean stays green. */
+    stagingDir: string;
+    /** Absolute path to the Tamagui config compiled into the views. */
+    tamaguiConfig: string;
+    /** Package identity for defines and bundle names. */
+    packageInfo: WebextPackageInfo;
+    /** Workspace root (defaults to the git toplevel). */
+    workspaceRoot?: string;
+    /** Views dev-server port. */
+    port?: number;
+    /** Development mode (watch + HMR scaffolding). Defaults to
+     *  NODE_ENV !== "production". */
+    isDev?: boolean;
+    /** Extra defines merged over the factory defaults. */
+    define?: Record<string, unknown>;
+    /** Extra resolve aliases appended after the factory's. */
+    aliases?: Alias[];
+}
+/** shiki's chunk graph (wasm/TLA) can't fold into the single-file iife a
+ *  content script requires. Stub it with an empty module —
+ *  @multiplatform.one/components' highlightCode() catches the missing
+ *  codeToTokens and falls back to plain text. */
+export declare function shikiStubPlugin(): Plugin;
+/** Discover view names — every directory under <targetDir>/views with an
+ *  index.html becomes an extension page (popup, options, sidepanel, …). */
+export declare function listWebextViews(targetDir: string): string[];
+/** The extension pages build (popup/options/sidepanel/devtools…). */
+export declare function createWebextViewsConfig(options: WebextTargetOptions): Promise<UserConfig>;
+/** The background service-worker (chromium) / background-script (firefox)
+ *  build — a single-file iife, no DOM. */
+export declare function createWebextBackgroundConfig(options: WebextTargetOptions): UserConfig;
+/** The content-script build — a single-file iife injected into pages, with
+ *  Tamagui CSS extracted separately (webext.css web-accessible resource). */
+export declare function createWebextContentConfig(options: WebextTargetOptions): Promise<UserConfig>;
+export interface WebextPrepareOptions {
+    targetDir: string;
+    stagingDir: string;
+    /** Produces the manifest object (app-owned — permissions, views, icons).
+     *  Typed `object` so interface-typed manifests (webextension-polyfill's
+     *  WebExtensionManifest has no index signature) assign cleanly. */
+    getManifest: () => Promise<object> | object;
+    /** Static files (icons, …) copied verbatim into the staging root.
+     *  Defaults to `<targetDir>/static` when it exists. */
+    staticDir?: string;
+    isDev?: boolean;
+    port?: number;
+    /** Watch manifest/html sources and rewrite on change (dev loop). */
+    watch?: boolean;
+}
+/** Copy static extension files (icons, …) into the staging root — the
+ *  staging dir is build output (gitignored), so committed assets live in
+ *  the target source tree instead. */
+export declare function copyWebextStatic(options: WebextPrepareOptions): Promise<void>;
+export declare function writeWebextManifest(options: WebextPrepareOptions): Promise<void>;
+/** Dev mode: emit view HTML that loads main.tsx from the vite dev server
+ *  (extension pages can't be served BY vite — the html on disk must point
+ *  at it) plus the react-refresh preamble shim. */
+export declare function stubWebextIndexHtml(options: WebextPrepareOptions): Promise<void>;
+export declare function writeWebextRefreshScript(options: WebextPrepareOptions): Promise<void>;
+/** One-shot (prod) or watching (dev) prepare: manifest + static assets +
+ *  dev scaffolding. */
+export declare function runWebextPrepare(options: WebextPrepareOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC;0CACsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB;2EACuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,WAAW,EAAE,iBAAiB,CAAC;IAC/B,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;qCACiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;CACnB;AA4BD;;;iDAGiD;AACjD,wBAAgB,eAAe,IAAI,MAAM,CAYxC;AA6CD;2EAC2E;AAC3E,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAO3D;AAED,qEAAqE;AACrE,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAoD/F;AAED;0CAC0C;AAC1C,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,UAAU,CA+BrF;AAED;6EAC6E;AAC7E,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CAgDjG;AAID,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;uEAEmE;IACnE,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IAC5C;2DACuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;sCAEsC;AACtC,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnF;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAQtF;AAED;;mDAEmD;AACnD,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBtF;AAED,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB3F;AAED;uBACuB;AACvB,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBnF"}