feat: type-safe import.meta.env.BROWSER with new targetBrowers config (#1574)

Co-authored-by: Aaron <aaronklinker1@gmail.com>
2025-04-14 21:25:04 +08:00
parent 61b42ef326
commit b9e72358ac
7 changed files with 35 additions and 1 deletions
@@ -42,6 +42,8 @@ WXT provides some custom environment variables based on the current command:
 | `import.meta.env.EDGE`             | `boolean` | Equivalent to `import.meta.env.BROWSER === "edge"`    |
 | `import.meta.env.OPERA`            | `boolean` | Equivalent to `import.meta.env.BROWSER === "opera"`   |

+You can set the [`targetBrowsers`](/api/reference/wxt/interfaces/InlineConfig#targetbrowsers) option to make the `BROWSER` variable a more specific type, like `"chrome" | "firefox"`.
+
 You can also access all of [Vite's environment variables](https://vite.dev/guide/env-and-mode.html#env-variables):

 | Usage                  | Type      | Description                                                                 |
@@ -3,6 +3,7 @@ import { presetUno } from 'unocss';

 export default defineConfig({
  srcDir: 'src',
+  targetBrowsers: ['chrome', 'firefox', 'safari'],
  manifest: {
    permissions: ['storage'],
    default_locale: 'en',
@@ -396,6 +396,19 @@ describe('TypeScript Project', () => {
    expect(output).toContain('./example.ts');
  });

+  it('should set correct import.meta.env.BROWSER type based on targetBrowsers', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html', '<html></html>');
+    project.setConfigFileConfig({
+      targetBrowsers: ['firefox', 'chrome'],
+    });
+
+    await project.prepare();
+
+    const output = await project.serializeFile('.wxt/types/globals.d.ts');
+    expect(output).toContain('readonly BROWSER: "firefox" | "chrome";');
+  });
+
  // TODO: Once a module has been published, use it here for testing - local files are never added to the .wxt/wxt.d.ts file
  it.todo(
    'should add modules from NPM to the TS project if they have a configKey',
@@ -70,6 +70,12 @@ export async function resolveConfig(
  if (debug) logger.level = LogLevels.debug;

  const browser = mergedConfig.browser ?? 'chrome';
+  const targetBrowsers = mergedConfig.targetBrowsers ?? [];
+  if (targetBrowsers.length > 0 && !targetBrowsers.includes(browser)) {
+    throw new Error(
+      `Current target browser \`${browser}\` is not in your \`targetBrowsers\` list!`,
+    );
+  }
  const manifestVersion =
    mergedConfig.manifestVersion ??
    (browser === 'firefox' || browser === 'safari' ? 2 : 3);
@@ -197,6 +203,7 @@ export async function resolveConfig(

  return {
    browser,
+    targetBrowsers,
    command,
    debug,
    entrypointsDir,
@@ -12,7 +12,10 @@ export function getGlobals(
    {
      name: 'BROWSER',
      value: config.browser,
-      type: `string`,
+      type:
+        config.targetBrowsers.length === 0
+          ? 'string'
+          : config.targetBrowsers.map((browser) => `"${browser}"`).join(' | '),
    },
    {
      name: 'CHROME',
@@ -235,6 +235,7 @@ export const fakeResolvedConfig = fakeObjectCreator<ResolvedConfig>(() => {

  return {
    browser,
+    targetBrowsers: [],
    command,
    entrypointsDir: fakeDir(),
    modulesDir: fakeDir(),
@@ -108,6 +108,12 @@ export interface InlineConfig {
   * "chrome"
   */
  browser?: TargetBrowser;
+  /**
+   * Target browsers to support. When set, `import.meta.env.BROWSER` will be narrowed to a string literal type containing only the specified browser names.
+   *
+   * @default []
+   */
+  targetBrowsers?: TargetBrowser[];
  /**
   * Explicitly set a manifest version to target. This will override the default manifest version
   * for each command, and can be overridden by the command line `--mv2` or `--mv3` option.
@@ -1311,6 +1317,7 @@ export interface ResolvedConfig {
  mode: string;
  command: WxtCommand;
  browser: TargetBrowser;
+  targetBrowsers: TargetBrowser[];
  manifestVersion: TargetManifestVersion;
  env: ConfigEnv;
  logger: Logger;