feat(experimental): Load entrypoint options with Vite Runtime API (#648)

Author: aklinker1

package.json

@@ -9,7 +9,7 @@
   "scripts": {
     "check": "check && pnpm -r run check",
     "test": "vitest",
-    "test:coverage": "vitest run --coverage.enabled \"--coverage.include=packages/wxt/src/**\" \"--coverage.exclude=packages/wxt/src/core/utils/testing/**\" \"--coverage.exclude=**/*.d.ts\"",
+    "test:coverage": "vitest run --coverage.enabled \"--coverage.include=packages/wxt/src/**\" \"--coverage.exclude=packages/wxt/src/core/utils/testing/**\" \"--coverage.exclude=**/*.d.ts\" \"--coverage.exclude=**/fixtures/**\"",
     "prepare": "simple-git-hooks",
     "prepublish": "pnpm -s build",
     "docs:gen": "typedoc --options docs/typedoc.json",

packages/wxt-demo/wxt.config.ts

@@ -18,4 +18,7 @@ export default defineConfig({
   analysis: {
     open: true,
   },
+  experimental: {
+    viteRuntime: true,
+  },
 });

packages/wxt/e2e/tests/manifest-content.test.ts

@@ -1,33 +1,36 @@
 import { describe, it, expect } from 'vitest';
 import { TestProject } from '../utils';
 
-describe('Manifest Content', () => {
-  it.each([
-    { browser: undefined, outDir: 'chrome-mv3', expected: undefined },
-    { browser: 'chrome', outDir: 'chrome-mv3', expected: undefined },
-    { browser: 'firefox', outDir: 'firefox-mv2', expected: true },
-    { browser: 'safari', outDir: 'safari-mv2', expected: false },
-  ])(
-    'should respect the per-browser entrypoint option with %j',
-    async ({ browser, expected, outDir }) => {
-      const project = new TestProject();
+describe.each([true, false])(
+  'Manifest Content (Vite runtime? %s)',
+  (viteRuntime) => {
+    it.each([
+      { browser: undefined, outDir: 'chrome-mv3', expected: undefined },
+      { browser: 'chrome', outDir: 'chrome-mv3', expected: undefined },
+      { browser: 'firefox', outDir: 'firefox-mv2', expected: true },
+      { browser: 'safari', outDir: 'safari-mv2', expected: false },
+    ])(
+      'should respect the per-browser entrypoint option with %j',
+      async ({ browser, expected, outDir }) => {
+        const project = new TestProject();
 
-      project.addFile(
-        'entrypoints/background.ts',
-        `export default defineBackground({
+        project.addFile(
+          'entrypoints/background.ts',
+          `export default defineBackground({
           persistent: {
             firefox: true,
             safari: false,
           },
           main: () => {},
         })`,
-      );
-      await project.build({ browser });
+        );
+        await project.build({ browser, experimental: { viteRuntime } });
 
-      const safariManifest = await project.getOutputManifest(
-        `.output/${outDir}/manifest.json`,
-      );
-      expect(safariManifest.background.persistent).toBe(expected);
-    },
-  );
-});
+        const safariManifest = await project.getOutputManifest(
+          `.output/${outDir}/manifest.json`,
+        );
+        expect(safariManifest.background.persistent).toBe(expected);
+      },
+    );
+  },
+);

packages/wxt/package.json

@@ -115,6 +115,7 @@
     "json5": "^2.2.3",
     "jszip": "^3.10.1",
     "linkedom": "^0.16.1",
+    "magicast": "^0.3.4",
     "minimatch": "^9.0.3",
     "natural-compare": "^1.4.0",
     "normalize-path": "^3.0.0",

packages/wxt/src/core/builders/vite/__tests__/fixtures/module.ts

@@ -0,0 +1,12 @@
+import { a } from './test';
+
+function defineSomething<T>(config: T): T {
+  return config;
+}
+
+export default defineSomething({
+  option: 'some value',
+  main: () => {
+    console.log('main', a);
+  },
+});

packages/wxt/src/core/builders/vite/__tests__/fixtures/test.ts

@@ -0,0 +1,2 @@
+console.log('Side-effect in test.ts');
+export const a = 'a';

packages/wxt/src/core/builders/vite/__tests__/index.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import { createViteBuilder } from '../index';
+import { fakeResolvedConfig } from '~/core/utils/testing/fake-objects';
+import { createHooks } from 'hookable';
+
+describe('Vite Builder', () => {
+  describe('importEntrypoint', () => {
+    it('should import entrypoints, removing runtime values (like the main function)', async () => {
+      const {
+        default: { main: _, ...expected },
+      } = await import('./fixtures/module');
+      const builder = await createViteBuilder(
+        fakeResolvedConfig({ root: __dirname }),
+        createHooks(),
+      );
+      const actual = await builder.importEntrypoint<{ default: any }>(
+        './fixtures/module.ts',
+      );
+      expect(actual).toEqual(expected);
+    });
+  });
+});

packages/wxt/src/core/builders/vite/index.ts

@@ -203,6 +203,22 @@ export async function createViteBuilder(
   return {
     name: 'Vite',
     version: vite.version,
+    async importEntrypoint(url) {
+      const baseConfig = await getBaseConfig();
+      const envConfig: vite.InlineConfig = {
+        plugins: [
+          wxtPlugins.webextensionPolyfillMock(wxtConfig),
+          wxtPlugins.removeEntrypointMainFunction(wxtConfig, url),
+        ],
+      };
+      const config = vite.mergeConfig(baseConfig, envConfig);
+      const server = await vite.createServer(config);
+      await server.listen();
+      const runtime = await vite.createViteRuntime(server, { hmr: false });
+      const module = await runtime.executeUrl(url);
+      await server.close();
+      return module.default;
+    },
     async build(group) {
       let entryConfig;
       if (Array.isArray(group)) entryConfig = getMultiPageConfig(group);

packages/wxt/src/core/builders/vite/plugins/index.ts

@@ -13,3 +13,4 @@ export * from './webextensionPolyfillMock';
 export * from './excludeBrowserPolyfill';
 export * from './entrypointGroupGlobals';
 export * from './defineImportMeta';
+export * from './removeEntrypointMainFunction';

packages/wxt/src/core/builders/vite/plugins/removeEntrypointMainFunction.ts

@@ -0,0 +1,21 @@
+import { ResolvedConfig } from '~/types';
+import * as vite from 'vite';
+import { normalizePath } from '~/core/utils/paths';
+import { removeMainFunctionCode } from '~/core/utils/transform';
+import { resolve } from 'node:path';
+
+/**
+ * Transforms entrypoints, removing the main function from the entrypoint if it exists.
+ */
+export function removeEntrypointMainFunction(
+  config: ResolvedConfig,
+  path: string,
+): vite.Plugin {
+  const absPath = normalizePath(resolve(config.root, path));
+  return {
+    name: 'wxt:remove-entrypoint-main-function',
+    transform(code, id) {
+      if (id === absPath) return removeMainFunctionCode(code);
+    },
+  };
+}

packages/wxt/src/core/utils/__tests__/transform.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { removeMainFunctionCode } from '../transform';
+
+describe('Transform Utils', () => {
+  describe('removeMainFunctionCode', () => {
+    it.each(['defineBackground', 'defineUnlistedScript'])(
+      'should remove the first arrow function argument for %s',
+      (def) => {
+        const input = `export default ${def}(() => {
+            console.log();
+          })`;
+        const expected = `export default ${def}(() => {})`;
+
+        const actual = removeMainFunctionCode(input).code;
+
+        expect(actual).toEqual(expected);
+      },
+    );
+    it.each(['defineBackground', 'defineUnlistedScript'])(
+      'should remove the first function argument for %s',
+      (def) => {
+        const input = `export default ${def}(function () {
+            console.log();
+          })`;
+        const expected = `export default ${def}(function () {})`;
+
+        const actual = removeMainFunctionCode(input).code;
+
+        expect(actual).toEqual(expected);
+      },
+    );
+
+    it.each([
+      'defineBackground',
+      'defineContentScript',
+      'defineUnlistedScript',
+    ])('should remove the main field from %s', (def) => {
+      const input = `export default ${def}({
+        asdf: "asdf",
+        main: () => {},
+      })`;
+      const expected = `export default ${def}({
+  asdf: "asdf"
+})`;
+
+      const actual = removeMainFunctionCode(input).code;
+
+      expect(actual).toEqual(expected);
+    });
+  });
+});

packages/wxt/src/core/utils/building/find-entrypoints.ts

@@ -19,7 +19,6 @@ import fs from 'fs-extra';
 import { minimatch } from 'minimatch';
 import { parseHTML } from 'linkedom';
 import JSON5 from 'json5';
-import { importEntrypointFile } from '~/core/utils/building';
 import glob from 'fast-glob';
 import {
   getEntrypointName,
@@ -29,11 +28,16 @@ import { VIRTUAL_NOOP_BACKGROUND_MODULE_ID } from '~/core/utils/constants';
 import { CSS_EXTENSIONS_PATTERN } from '~/core/utils/paths';
 import pc from 'picocolors';
 import { wxt } from '../../wxt';
+import { importEntrypointFile } from './import-entrypoint';
 
 /**
  * Return entrypoints and their configuration by looking through the project's files.
  */
 export async function findEntrypoints(): Promise<Entrypoint[]> {
+  // Make sure required TSConfig file exists to load dependencies
+  await fs.mkdir(wxt.config.wxtDir, { recursive: true });
+  await fs.writeJson(resolve(wxt.config.wxtDir, 'tsconfig.json'), {});
+
   const relativePaths = await glob(Object.keys(PATH_GLOB_TO_TYPE_MAP), {
     cwd: wxt.config.entrypointsDir,
   });
@@ -286,7 +290,7 @@ async function getUnlistedScriptEntrypoint({
   skipped,
 }: EntrypointInfo): Promise<GenericEntrypoint> {
   const defaultExport =
-    await importEntrypointFile<UnlistedScriptDefinition>(inputPath);
+    await importEntrypoint<UnlistedScriptDefinition>(inputPath);
   if (defaultExport == null) {
     throw Error(
       `${name}: Default export not found, did you forget to call "export default defineUnlistedScript(...)"?`,
@@ -311,7 +315,7 @@ async function getBackgroundEntrypoint({
   let options: Omit<BackgroundDefinition, 'main'> = {};
   if (inputPath !== VIRTUAL_NOOP_BACKGROUND_MODULE_ID) {
     const defaultExport =
-      await importEntrypointFile<BackgroundDefinition>(inputPath);
+      await importEntrypoint<BackgroundDefinition>(inputPath);
     if (defaultExport == null) {
       throw Error(
         `${name}: Default export not found, did you forget to call "export default defineBackground(...)"?`,
@@ -341,7 +345,7 @@ async function getContentScriptEntrypoint({
   skipped,
 }: EntrypointInfo): Promise<ContentScriptEntrypoint> {
   const { main: _, ...options } =
-    await importEntrypointFile<ContentScriptDefinition>(inputPath);
+    await importEntrypoint<ContentScriptDefinition>(inputPath);
   if (options == null) {
     throw Error(
       `${name}: Default export not found, did you forget to call "export default defineContentScript(...)"?`,
@@ -484,3 +488,9 @@ const PATH_GLOB_TO_TYPE_MAP: Record<string, Entrypoint['type']> = {
 };
 
 const CONTENT_SCRIPT_OUT_DIR = 'content-scripts';
+
+function importEntrypoint<T>(path: string) {
+  return wxt.config.experimental.viteRuntime
+    ? wxt.builder.importEntrypoint<T>(path)
+    : importEntrypointFile<T>(path);
+}

packages/wxt/src/core/utils/building/resolve-config.ts

@@ -152,6 +152,7 @@ export async function resolveConfig(
     alias,
     experimental: defu(mergedConfig.experimental, {
       includeBrowserPolyfill: true,
+      viteRuntime: false,
     }),
     dev: {
       server: devServerConfig,

packages/wxt/src/core/utils/package.ts

@@ -22,5 +22,5 @@ export async function getPackageJson(): Promise<
 }
 
 export function isModuleInstalled(name: string) {
-  return import(name).then(() => true).catch(() => false);
+  return import(/* @vite-ignore */ name).then(() => true).catch(() => false);
 }

packages/wxt/src/core/utils/testing/fake-objects.ts

@@ -295,6 +295,7 @@ export const fakeResolvedConfig = fakeObjectCreator<ResolvedConfig>(() => {
     alias: {},
     experimental: {
       includeBrowserPolyfill: true,
+      viteRuntime: false,
     },
     dev: {
       reloadCommand: 'Alt+R',

packages/wxt/src/core/utils/transform.ts

@@ -0,0 +1,33 @@
+import { ProxifiedModule, parseModule } from 'magicast';
+
+/**
+ * Removes any code used at runtime related to an entrypoint's main function.
+ * - Removes or clears out `main` function from returned object
+ * - TODO: Removes unused imports after main function has been removed to prevent importing runtime modules
+ */
+export function removeMainFunctionCode(code: string): {
+  code: string;
+  map?: string;
+} {
+  const mod = parseModule(code);
+  emptyMainFunction(mod);
+  return mod.generate();
+}
+
+function emptyMainFunction(mod: ProxifiedModule) {
+  if (mod.exports?.default?.$type === 'function-call') {
+    if (mod.exports.default.$ast?.arguments?.[0]?.body) {
+      // Remove body from function
+      // ex: "fn(() => { ... })" to "fn(() => {})"
+      // ex: "fn(function () { ... })" to "fn(function () {})"
+      mod.exports.default.$ast.arguments[0].body.body = [];
+    } else if (mod.exports.default.$ast?.arguments?.[0]?.properties) {
+      // Remove main field from object
+      // ex: "fn({ ..., main: () => {} })" to "fn({ ... })"
+      mod.exports.default.$ast.arguments[0].properties =
+        mod.exports.default.$ast.arguments[0].properties.filter(
+          (prop: any) => prop.key.name !== 'main',
+        );
+    }
+  }
+}

packages/wxt/src/types/index.ts

@@ -312,6 +312,15 @@ export interface InlineConfig {
      * })
      */
     includeBrowserPolyfill?: boolean;
+    /**
+     * When set to `true`, use the Vite Runtime API to load entrypoint options instead of the default, `jiti`.
+     *
+     * Lets you use imported variables and leverage your Vite config to add support for non-standard APIs/syntax.
+     *
+     * @experimental Early access to try out the feature before it becomes the default.
+     * @default false
+     */
+    viteRuntime?: boolean;
   };
   /**
    * Config effecting dev mode only.
@@ -929,6 +938,10 @@ export interface WxtBuilder {
    * Version of tool used to build. Ex: "5.0.2"
    */
   version: string;
+  /**
+   * Import the entrypoint file, returning the default export containing the options.
+   */
+  importEntrypoint<T>(path: string): Promise<T>;
   /**
    * Build a single entrypoint group. This is effectively one of the multiple "steps" during the
    * build process.
@@ -1124,6 +1137,7 @@ export interface ResolvedConfig {
   alias: Record<string, string>;
   experimental: {
     includeBrowserPolyfill: boolean;
+    viteRuntime: boolean;
   };
   dev: {
     /** Only defined during dev command */