@serwist/vite 8.4.4 → 9.0.0-preview.1

package/src/modules.ts

@@ -0,0 +1,174 @@
+import assert from "node:assert";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type * as SerwistBuild from "@serwist/build";
+
+import type { SerwistViteContext } from "./context.js";
+
+export const loadSerwistBuild = async (): Promise<typeof SerwistBuild> => {
+  // "@serwist/build" is large and makes config loading slow.
+  // Since it is not always used, we only load this when it is needed.
+  try {
+    return await import("@serwist/build");
+  } catch (_) {
+    // We don't have a default export, don't worry.
+    return require("@serwist/build");
+  }
+};
+
+interface BuildResult extends SerwistBuild.GetManifestResult {
+  manifestString: string;
+}
+
+export const injectManifest = async (config: SerwistBuild.ViteInjectManifestOptions): Promise<BuildResult> => {
+  const { validateViteInjectManifestOptions, getFileManifestEntries, stringify } = await loadSerwistBuild();
+  const options = await validateViteInjectManifestOptions(config);
+  const { count, size, manifestEntries, warnings } = await getFileManifestEntries(options);
+  const manifestString = manifestEntries === undefined ? "undefined" : stringify(manifestEntries);
+  return {
+    warnings,
+    size,
+    count,
+    manifestEntries,
+    manifestString,
+  };
+};
+
+export const generateServiceWorker = async (ctx: SerwistViteContext) => {
+  const { format, plugins, rollupOptions } = ctx.options.injectManifestRollupOptions;
+
+  const parsedSwDest = path.parse(ctx.options.injectManifest.swDest);
+
+  let injectManifestResult: BuildResult | undefined = undefined;
+
+  if (ctx.options.injectManifest.injectionPoint) {
+    await ctx.options.integration?.beforeBuildServiceWorker?.(ctx.options);
+    injectManifestResult = await injectManifest(ctx.options.injectManifest);
+  }
+
+  const isProduction = ctx.options.mode === "production";
+  const isDev = ctx.options.mode === "development";
+
+  if ((isProduction && ctx.framework === "sveltekit") || (isDev && !ctx.options.devOptions.bundle)) {
+    if (!injectManifestResult) {
+      throw new Error("injectManifest failed to generate results. This is likely a bug.");
+    }
+
+    const { errors, escapeRegExp, getSourceMapURL, rebasePath, replaceAndUpdateSourceMap, translateURLToSourcemapPaths } = await loadSerwistBuild();
+
+    // Make sure we leave swSrc and swDest out of the precache manifest.
+    for (const file of [ctx.options.injectManifest.swSrc, ctx.options.injectManifest.swDest]) {
+      ctx.options.injectManifest.globIgnores!.push(
+        rebasePath({
+          file,
+          baseDirectory: ctx.options.injectManifest.globDirectory,
+        }),
+      );
+    }
+
+    const injectionPoint = ctx.options.injectManifest.injectionPoint!;
+
+    const globalRegexp = new RegExp(escapeRegExp(injectionPoint), "g");
+
+    let swFileContents: string;
+    try {
+      swFileContents = await fs.readFile(ctx.options.injectManifest.swSrc, "utf8");
+    } catch (error) {
+      throw new Error(`${errors["invalid-sw-src"]} ${error instanceof Error && error.message ? error.message : ""}`);
+    }
+
+    const injectionResults = swFileContents.match(globalRegexp);
+    // See https://github.com/GoogleChrome/workbox/issues/2230
+    if (!injectionResults) {
+      throw new Error(`${errors["injection-point-not-found"]} ${injectionPoint}`);
+    }
+
+    assert(injectionResults.length === 1, `${errors["multiple-injection-points"]} ${injectionPoint}`);
+
+    const filesToWrite: Record<string, string> = {};
+
+    const url = getSourceMapURL(swFileContents);
+    // See https://github.com/GoogleChrome/workbox/issues/2957
+    const { destPath, srcPath, warning } = translateURLToSourcemapPaths(url, ctx.options.injectManifest.swSrc, ctx.options.injectManifest.swDest);
+    if (warning) {
+      injectManifestResult.warnings.push(warning);
+    }
+
+    // If our swSrc file contains a sourcemap, we would invalidate that
+    // mapping if we just replaced injectionPoint with the stringified manifest.
+    // Instead, we need to update the swDest contents as well as the sourcemap
+    // (assuming it's a real file, not a data: URL) at the same time.
+    // See https://github.com/GoogleChrome/workbox/issues/2235
+    // and https://github.com/GoogleChrome/workbox/issues/2648
+    if (srcPath && destPath) {
+      const { map, source } = await replaceAndUpdateSourceMap({
+        originalMap: JSON.parse(await fs.readFile(srcPath, "utf8")),
+        jsFilename: path.basename(ctx.options.injectManifest.swDest),
+        originalSource: swFileContents,
+        replaceString: injectManifestResult.manifestString,
+        searchString: injectionPoint,
+      });
+
+      filesToWrite[ctx.options.injectManifest.swDest] = source;
+      filesToWrite[destPath] = map;
+    } else {
+      // If there's no sourcemap associated with swSrc, a simple string
+      // replacement will suffice.
+      filesToWrite[ctx.options.injectManifest.swDest] = swFileContents.replace(globalRegexp, injectManifestResult.manifestString);
+    }
+
+    for (const [file, contents] of Object.entries(filesToWrite)) {
+      try {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+      } catch (error: unknown) {
+        throw new Error(`${errors["unable-to-make-sw-directory"]} '${error instanceof Error && error.message ? error.message : ""}'`);
+      }
+
+      await fs.writeFile(file, contents);
+    }
+  } else {
+    const define: Record<string, any> = {
+      // Nuxt does some really weird stuff. During the build, they MANUALLY
+      // set browser APIs, such as window, document, location,..., to `undefined`??
+      // Probably some Vue or server stuff. Their `define` doesn't seem to have anything
+      // particularly useful for the service worker anyway, so we don't extend it.
+      ...(ctx.framework === "nuxt" ? undefined : ctx.viteConfig.define),
+      "process.env.NODE_ENV": `"${ctx.options.mode}"`,
+    };
+    if (ctx.options.injectManifest.injectionPoint && injectManifestResult) {
+      define[ctx.options.injectManifest.injectionPoint] = injectManifestResult.manifestString;
+    }
+    const { build } = await import("vite");
+    await build({
+      logLevel: ctx.viteConfig.isProduction ? "info" : "warn",
+      root: ctx.viteConfig.root,
+      base: ctx.viteConfig.base,
+      resolve: ctx.viteConfig.resolve,
+      // Don't copy anything from public folder
+      publicDir: false,
+      build: {
+        sourcemap: ctx.viteConfig.build.sourcemap,
+        lib: {
+          entry: ctx.options.injectManifest.swSrc,
+          name: "app",
+          formats: [format],
+        },
+        rollupOptions: {
+          ...rollupOptions,
+          plugins,
+          output: {
+            entryFileNames: parsedSwDest.base,
+          },
+        },
+        outDir: parsedSwDest.dir,
+        emptyOutDir: false,
+        minify: isProduction || ctx.options.devOptions.minify,
+      },
+      configFile: false,
+      define,
+    });
+  }
+
+  return injectManifestResult;
+};

package/src/options.ts

@@ -0,0 +1,90 @@
+import path from "node:path";
+import process from "node:process";
+
+import type { ResolvedConfig } from "vite";
+
+import { configureStaticAssets } from "./assets.js";
+import { loadSerwistBuild } from "./modules.js";
+import type { PluginOptions, ResolvedPluginOptions } from "./types.js";
+import { resolveBasePath, slash } from "./utils.js";
+
+export const resolveOptions = async (options: PluginOptions, viteConfig: ResolvedConfig): Promise<ResolvedPluginOptions> => {
+  const {
+    type = "classic",
+    mode = (process.env.NODE_ENV || "production") as "production" | "development",
+    injectRegister = "auto",
+    registerType = "prompt",
+    minify = true,
+    base = viteConfig.base,
+    scope: _scope,
+    swUrl = "/sw.js",
+    includeAssets = undefined,
+    useCredentials = false,
+    disable = false,
+    integration = {},
+    buildBase,
+    devOptions,
+    plugins = [],
+    rollupOptions = {},
+    rollupFormat = "es",
+    ...injectManifest
+  } = options;
+
+  const basePath = resolveBasePath(base);
+  // check typescript service worker for injectManifest strategy
+  const scope = _scope || basePath;
+
+  let assetsDir = slash(viteConfig.build.assetsDir ?? "assets");
+  if (assetsDir[assetsDir.length - 1] !== "/") assetsDir += "/";
+
+  const resolvedDevOptions: ResolvedPluginOptions["devOptions"] = {
+    bundle: true,
+    minify: false,
+    ...devOptions,
+  };
+
+  // remove './' prefix from assetsDir
+  const dontCacheBustURLsMatching = new RegExp(`^${assetsDir.replace(/^\.*?\//, "")}`);
+
+  const { validateViteInjectManifestOptions } = await loadSerwistBuild();
+
+  const validatedInjectManifest = await validateViteInjectManifestOptions(injectManifest);
+
+  const { swSrc, swDest, ...userInjectManifest } = validatedInjectManifest || {};
+
+  const resolvedPluginOptions = {
+    base: basePath,
+    type,
+    mode,
+    injectRegister,
+    registerType,
+    useCredentials,
+    swUrl,
+    injectManifest: {
+      dontCacheBustURLsMatching,
+      ...userInjectManifest,
+      swSrc: path.resolve(viteConfig.root, swSrc),
+      swDest: path.resolve(viteConfig.root, viteConfig.build.outDir, swDest),
+      disablePrecacheManifest: !viteConfig.isProduction,
+    },
+    scope,
+    minify,
+    includeAssets,
+    disable,
+    integration,
+    buildBase: buildBase ?? basePath,
+    injectManifestRollupOptions: {
+      plugins,
+      rollupOptions,
+      format: rollupFormat,
+    },
+    devOptions: resolvedDevOptions,
+  } satisfies ResolvedPluginOptions;
+
+  // calculate hash only when required
+  const calculateHash = !resolvedPluginOptions.disable && resolvedPluginOptions.includeAssets && viteConfig.command === "build";
+
+  if (calculateHash) await configureStaticAssets(resolvedPluginOptions, viteConfig);
+
+  return resolvedPluginOptions;
+};

package/src/plugins/build.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from "vite";
+
+import type { SerwistViteContext } from "../context.js";
+import type { SerwistViteApi } from "../types.js";
+
+/**
+ * Internal build plugin used by `@serwist/vite`.
+ * @internal
+ * @param ctx
+ * @param api
+ * @returns
+ */
+export const buildPlugin = (ctx: SerwistViteContext, api: SerwistViteApi) => {
+  return <Plugin>{
+    name: "@serwist/vite:build",
+    enforce: "post",
+    apply: "build",
+    closeBundle: {
+      sequential: true,
+      order: ctx.userOptions?.integration?.closeBundleOrder,
+      async handler() {
+        if (!ctx.viteConfig.build.ssr && !ctx.options.disable) {
+          await api.generateSW();
+        }
+      },
+    },
+    async buildEnd(error) {
+      if (error) throw error;
+    },
+  };
+};

package/src/plugins/dev.ts

@@ -0,0 +1,61 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { type Plugin, normalizePath } from "vite";
+
+import type { SerwistViteContext } from "../context.js";
+import type { SerwistViteApi } from "../types.js";
+import { toFs } from "../utils.js";
+
+// This plugin handles the service worker in two ways:
+// - If `devOptions.bundle` is enabled, hook a middleware that bundles the service worker
+// through `api.generateSW()` and returns the result into Vite's dev server.
+// - Otherwise, run `injectManifest` and return the service worker through `async load(id)`. Although
+// `precacheEntries` is always `undefined`, we still do this to check the user's `injectManifest` options
+// in dev mode.
+/**
+ * Internal dev plugin used by `@serwist/vite`.
+ * @internal
+ * @param ctx
+ * @param api
+ * @returns
+ */
+export const devPlugin = (ctx: SerwistViteContext, api: SerwistViteApi): Plugin => {
+  return {
+    name: "@serwist/vite:dev",
+    apply: "serve",
+    configureServer(server) {
+      ctx.devEnvironment = true;
+      server.middlewares.use(async (req, res, next) => {
+        if (!ctx.options.disable && req.url === ctx.options.swUrl) {
+          if (ctx.options.devOptions.bundle) {
+            await api.generateSW();
+            const content = await fs.readFile(ctx.options.injectManifest.swDest, "utf-8");
+            await fs.rm(ctx.options.injectManifest.swDest);
+            res.setHeader("Content-Type", "application/javascript");
+            res.write(content);
+            res.end();
+          } else {
+            res.setHeader("Content-Type", "application/javascript");
+            res.write(`import "${toFs(path.resolve(ctx.options.injectManifest.swSrc))}";`);
+            res.end();
+          }
+        } else {
+          next();
+        }
+      });
+    },
+    async load(id) {
+      if (!ctx.options.disable && !ctx.options.devOptions.bundle) {
+        const swSrcId = normalizePath(ctx.options.injectManifest.swSrc);
+        if (id === swSrcId) {
+          await api.generateSW();
+          const content = await fs.readFile(ctx.options.injectManifest.swDest, "utf-8");
+          await fs.rm(ctx.options.injectManifest.swDest);
+          return content;
+        }
+      }
+      return undefined;
+    },
+  };
+};

package/src/plugins/main.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+
+import type { Plugin, UserConfig } from "vite";
+
+import { INTERNAL_SERWIST_VIRTUAL, RESOLVED_INTERNAL_SERWIST_VIRTUAL } from "../constants.js";
+import type { SerwistViteContext } from "../context.js";
+import { resolveOptions } from "../options.js";
+import type { SerwistViteApi } from "../types.js";
+
+/**
+ * Internal plugin used by `@serwist/vite`.
+ * @internal
+ * @param ctx
+ * @param api
+ * @returns
+ */
+export const mainPlugin = (ctx: SerwistViteContext, api: SerwistViteApi) => {
+  return <Plugin>{
+    name: "@serwist/vite",
+    enforce: "pre",
+    config() {
+      return <UserConfig>{
+        ssr: {
+          noExternal: [],
+        },
+      };
+    },
+    async configResolved(config) {
+      ctx.viteConfig = config;
+      ctx.userOptions?.integration?.configureOptions?.(config, ctx.userOptions);
+      ctx.options = await resolveOptions(ctx.userOptions, config);
+    },
+    resolveId(id) {
+      if (id === INTERNAL_SERWIST_VIRTUAL) {
+        return RESOLVED_INTERNAL_SERWIST_VIRTUAL;
+      }
+      return undefined;
+    },
+    load(id) {
+      if (id === RESOLVED_INTERNAL_SERWIST_VIRTUAL) {
+        return `export const swUrl = "${path.posix.join(ctx.options.buildBase, ctx.options.swUrl)}";
+export const swScope = "${ctx.options.scope}";
+export const swType = "${ctx.devEnvironment ? "module" : ctx.options.type}";`;
+      }
+      return undefined;
+    },
+    api,
+  };
+};

package/src/rollup.js

@@ -0,0 +1,46 @@
+// @ts-check
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getRollupOptions } from "@serwist/constants/rollup";
+import fg from "fast-glob";
+
+import packageJson from "../package.json" assert { type: "json" };
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const clientEntries = /** @type {Record<string, string>} */ ({});
+
+for (const clientPath of await fg("client/*.ts", { cwd: __dirname })) {
+  const parsedClientPath = path.parse(clientPath);
+  clientEntries[`client/${parsedClientPath.name}`] = path.join("src", clientPath);
+}
+
+const integrationEntries = /** @type {Record<string, string>} */ ({});
+
+for (const integrationPath of await fg("integration/*/index.ts", { cwd: __dirname })) {
+  const parsedClientPath = path.parse(integrationPath);
+  integrationEntries[`${parsedClientPath.dir}/${parsedClientPath.name}`] = path.join("src", integrationPath);
+}
+
+export default getRollupOptions({
+  packageJson,
+  jsFiles: [
+    {
+      input: {
+        index: "src/index.ts",
+        "index.browser": "src/index.browser.ts",
+        "index.worker": "src/index.worker.ts",
+        ...clientEntries,
+        ...integrationEntries,
+      },
+      output: {
+        dir: "dist",
+        format: "esm",
+        entryFileNames: "[name].js",
+        chunkFileNames: "[name].js",
+      },
+      external: ["virtual:internal-serwist"],
+    },
+  ],
+});

package/src/types.ts

@@ -0,0 +1,207 @@
+import type { ManifestEntry, ViteInjectManifestOptions } from "@serwist/build";
+import type { RollupOptions } from "rollup";
+import type { BuildOptions, Plugin, ResolvedConfig } from "vite";
+
+export type InjectManifestVitePlugins = string[] | ((vitePluginIds: string[]) => string[]);
+export interface CustomInjectManifestOptions extends Omit<ViteInjectManifestOptions, "disablePrecacheManifest"> {
+  /**
+   * The URL to the service worker.
+   * @default "/sw.js"
+   */
+  swUrl?: string;
+  /**
+   * Configure the format to use in the Rollup build.
+   *
+   * @default 'es'
+   */
+  rollupFormat?: "es" | "iife";
+  /**
+   * Since `v0.15.0` you can add plugins to build your service worker.
+   *
+   * When using `injectManifest` there are 2 builds, your application and the service worker.
+   * If you're using custom configuration for your service worker (for example custom plugins) you can use this option to configure the service worker build.
+   * Both configurations cannot be shared, and so you'll need to duplicate the configuration, with the exception of `define`.
+   *
+   * **WARN**: this option is for advanced usage, be aware that you may break your application build.
+   */
+  plugins?: Plugin[];
+  /**
+   * Since `v0.15.0` you can add custom Rollup options to build your service worker: we expose the same configuration to build a worker using Vite.
+   */
+  rollupOptions?: Omit<RollupOptions, "plugins" | "output">;
+}
+
+export interface SerwistViteHooks {
+  beforeBuildServiceWorker?: (options: ResolvedPluginOptions) => void | Promise<void>;
+  closeBundleOrder?: "pre" | "post" | null;
+  configureOptions?: (viteOptions: ResolvedConfig, options: PluginOptions) => void | Promise<void>;
+}
+
+export interface DevOptions {
+  /**
+   * Whether the service worker should be bundled in development mode.
+   *
+   * [Many browsers still do not support ES Modules in service workers.](https://caniuse.com/mdn-api_serviceworker_ecmascript_modules) However, in development
+   * mode, certain frameworks, such as SvelteKit, do not bundle the service worker. As a result, trying to register that service worker on browsers lacking
+   * support, such as Firefox or Safari, will fail, but doing so on browsers not lacking support will not fail. This option is provided to prevent that from
+   * happening. What the plugin does is intercepting any request to the service worker (requests for `swUrl`) and returning a bundled one.
+   */
+  bundle?: boolean;
+  minify?: BuildOptions["minify"];
+}
+
+/**
+ * Plugin options.
+ */
+export interface BasePluginOptions {
+  /**
+   * Build mode
+   *
+   * @default
+   * process.env.NODE_ENV // or "production" if undefined
+   */
+  mode?: "development" | "production";
+  /**
+   * The service worker type.
+   *
+   * @default "classic"
+   */
+  type?: WorkerType;
+  /**
+   * The scope to register the Service Worker
+   *
+   * @default `viteOptions.base`
+   */
+  scope?: string;
+  /**
+   * Inject the service worker register inlined in the index.html
+   *
+   * If set to "auto", depends on whether you used the `import { registerSW } from 'virtual:pwa-register'`
+   * it will do nothing or use the `script` mode
+   *
+   * `"inline"` - inject a simple register, inlined with the generated html
+   *
+   * `"script"` - inject `<script/>` in `<head>` with `src` attribute to a generated script to register the service worker
+   *
+   * `"script-defer"` - inject `<script defer />` in `<head>`, with `src` attribute to a generated script to register the service worker
+   *
+   * `null` - do nothing. You will need to register the service worker yourself or import `registerSW` from `virtual:pwa-register`.
+   *
+   * @default "auto"
+   */
+  injectRegister: "inline" | "script" | "script-defer" | "auto" | null | false;
+  /**
+   * Mode for the virtual register.
+   * This is NOT available if `injectRegister` is set to `"inline"` or `"script"`
+   *
+   * `"prompt"` - you will need to show a popup/dialog to the user to confirm the reload.
+   *
+   * `"autoUpdate"` - when new content is available, the new service worker will update caches and reload all browser
+   * windows/tabs with the application open automatically, it must take the control for the application to work
+   * properly.
+   *
+   * @default "prompt"
+   */
+  registerType?: "prompt" | "autoUpdate";
+  /**
+   * Minify the generated manifest
+   *
+   * @default true
+   */
+  minify: boolean;
+  /**
+   * Whether to add the `crossorigin="use-credentials"` attribute to `<link rel="manifest">`
+   * @default false
+   */
+  useCredentials?: boolean;
+  /**
+   * Override Vite's base options for `@serwist/vite`.
+   *
+   * @default viteOptions.base
+   */
+  base?: string;
+  /**
+   * `public` resources to be added to the PWA manifest.
+   *
+   * You don't need to add `manifest` icons here, it will be auto included.
+   *
+   * The `public` directory will be resolved from Vite's `publicDir` option directory.
+   */
+  includeAssets: string | string[] | undefined;
+  /**
+   * Whether Serwist should be disabled.
+   *
+   * @default false
+   */
+  disable: boolean;
+  /**
+   * `@serwist/vite` integration.
+   */
+  integration?: SerwistViteHooks;
+  /**
+   * When Vite's build folder is not the same as your base root folder, configure it here.
+   *
+   * This option will be useful for integrations like `vite-plugin-laravel` where Vite's build folder is `public/build` but Laravel's base path is `public`.
+   *
+   * This option will be used to configure the path for the service worker, "registerSW.js" and the web manifest assets.
+   *
+   * For example, if your base path is `/`, then, in your Laravel PWA configuration use `buildPath: '/build/'`.
+   *
+   * By default: `vite.base`.
+   */
+  buildBase?: string;
+}
+
+export interface PluginOptions extends Partial<BasePluginOptions>, CustomInjectManifestOptions {
+  devOptions?: DevOptions;
+}
+
+export interface InjectManifestRollupOptions {
+  format: "es" | "iife";
+  plugins: Plugin[];
+  rollupOptions: RollupOptions;
+}
+
+export interface ResolvedPluginOptions extends Required<BasePluginOptions>, Required<Pick<CustomInjectManifestOptions, "swUrl">> {
+  injectManifest: ViteInjectManifestOptions;
+  injectManifestRollupOptions: InjectManifestRollupOptions;
+  devOptions: Required<DevOptions>;
+}
+
+export interface ShareTargetFiles {
+  name: string;
+  accept: string | string[];
+}
+
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/Manifest/launch_handler#launch_handler_item_values
+ */
+export type LaunchHandlerClientMode = "auto" | "focus-existing" | "navigate-existing" | "navigate-new";
+
+export type Display = "fullscreen" | "standalone" | "minimal-ui" | "browser";
+export type DisplayOverride = Display | "window-controls-overlay";
+export type IconPurpose = "monochrome" | "maskable" | "any";
+
+// biome-ignore lint/complexity/noBannedTypes: We intentionally have this.
+type Nothing = {};
+
+/**
+ * type StringLiteralUnion<'maskable'> = 'maskable' | string
+ * This has auto completion whereas `'maskable' | string` doesn't
+ * Adapted from https://github.com/microsoft/TypeScript/issues/29729
+ */
+export type StringLiteralUnion<T extends U, U = string> = T | (U & Nothing);
+
+export interface SerwistViteApi {
+  /**
+   * Is the plugin disabled?
+   */
+  disabled: boolean;
+  extendManifestEntries(fn: ExtendManifestEntriesHook): void;
+  /*
+   * Generate the service worker.
+   */
+  generateSW(): Promise<void>;
+}
+
+export type ExtendManifestEntriesHook = (manifestEntries: (string | ManifestEntry)[]) => (string | ManifestEntry)[] | undefined;

package/src/utils-types.ts

@@ -0,0 +1 @@
+export type Optional<T, U extends keyof T> = Omit<T, U> & Partial<Pick<T, U>>;