chore(release): v0.15.0

BREAKING CHANGE: Renamed undocumented constants:

- `__BROWSER__` → `import.meta.env.BROWSER`
- `__COMMAND__` → `import.meta.env.COMMAND`
- `__MANIFEST_VERSION__` → `import.meta.env.MANIFEST_VERSION`
- `__IS_CHROME__` → `import.meta.env.CHROME`
- `__IS_FIREFOX__` → `import.meta.env.FIREFOX`
- `__IS_SAFARI__` → `import.meta.env.SAFARI`
- `__IS_EDGE__` → `import.meta.env.EDGE`
- `__IS_OPERA__` → `import.meta.env.OPERA`

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## v0.15.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.7...v0.15.0)
+
+### 🚀 Enhancements
+
+- **zip:** ⚠️  Add `includeSources` and rename `ignoredSources` to `excludeSources` ([#378](https://github.com/wxt-dev/wxt/pull/378))
+
+### 🩹 Fixes
+
+- Generate missing sourcemap in `wxt:unimport` plugin ([#381](https://github.com/wxt-dev/wxt/pull/381))
+- ⚠️  Move browser constants to `import.meta.env` ([#380](https://github.com/wxt-dev/wxt/pull/380))
+- Enable inline sourcemaps by default during development ([#382](https://github.com/wxt-dev/wxt/pull/382))
+
+### 📖 Documentation
+
+- Fix typo ([f9718a1](https://github.com/wxt-dev/wxt/commit/f9718a1))
+
+### 🏡 Chore
+
+- Update contributor docs ([eb758bd](https://github.com/wxt-dev/wxt/commit/eb758bd))
+
+#### ⚠️ Breaking Changes
+
+- **zip:** ⚠️  Add `includeSources` and rename `ignoredSources` to `excludeSources` ([#378](https://github.com/wxt-dev/wxt/pull/378))
+- ⚠️  Move browser constants to `import.meta.env` ([#380](https://github.com/wxt-dev/wxt/pull/380))
+
+### ❤️ Contributors
+
+- Nenad Novaković
+
 ## v0.14.7
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.6...v0.14.7)

CONTRIBUTING.md

@@ -57,9 +57,17 @@ pnpm test
 pnpm docs:dev
 ```
 
+## Updating Docs
+
+Documentation is written with VitePress, and is located in the `docs/` directory.
+
+The API reference is generated from JSDoc comments in the source code. If there's a typo or change you want to make in there, you'll need to update the source code instead of a file in the `docs/` directory.
+
 ## Testing
 
-WXT has unit and E2E tests. When making a change or adding a feature, make sure to update the tests or add new ones.
+WXT has unit and E2E tests. When making a change or adding a feature, make sure to update the tests or add new ones, if they exist.
+
+> If they don't exist, feel free to create them, but that's a lot for a one-time contributor. A maintainer might add them to your PR though.
 
 To run tests for a specific file, add the filename at the end of the test command:
 

demo/src/entrypoints/background.ts

@@ -4,10 +4,10 @@ export default defineBackground(() => {
   console.log(browser.runtime.id);
   logId();
   console.log({
-    browser: __BROWSER__,
-    chrome: __IS_CHROME__,
-    firefox: __IS_FIREFOX__,
-    manifestVersion: __MANIFEST_VERSION__,
+    browser: import.meta.env.BROWSER,
+    chrome: import.meta.env.CHROME,
+    firefox: import.meta.env.FIREFOX,
+    manifestVersion: import.meta.env.MANIFEST_VERSION,
     messages,
   });
 

docs/guide/multiple-browsers.md

@@ -115,19 +115,19 @@ Only `defineBackground` and `defineContentScript` support per-browser options ri
 
 To determine the browser or manifest version at runtime, you can use any of the below variables:
 
-- `__BROWSER__`: A string, the target browser, usually equal to the `--browser` flag
-- `__MANIFEST_VERSION__`: A number, either `2` or `3`, depending on the manifest version targetted
-- `__IS_CHROME__`: A boolean equivalent to `__BROWSER__ === "chrome"`
-- `__IS_FIREFOX__`: A boolean equivalent to `__BROWSER__ === "firefox"`
-- `__IS_EDGE__`: A boolean equivalent to `__BROWSER__ === "edge"`
-- `__IS_SAFARI__`: A boolean equivalent to `__BROWSER__ === "safari"`
-- `__IS_OPERA__`: A boolean equivalent to `__BROWSER__ === "opera"`
-- `__COMMAND__`: A string, `"serve"` when running `wxt` for development or `"build"` in all other cases.
+- `import.meta.env.BROWSER`: A string, the target browser, usually equal to the `--browser` flag
+- `import.meta.env.MANIFEST_VERSION`: A number, either `2` or `3`, depending on the manifest version targetted
+- `import.meta.env.CHROME`: A boolean equivalent to `import.meta.env.BROWSER === "chrome"`
+- `import.meta.env.FIREFOX`: A boolean equivalent to `import.meta.env.BROWSER === "firefox"`
+- `import.meta.env.EDGE`: A boolean equivalent to `import.meta.env.BROWSER === "edge"`
+- `import.meta.env.SAFARI`: A boolean equivalent to `import.meta.env.BROWSER === "safari"`
+- `import.meta.env.OPERA`: A boolean equivalent to `import.meta.env.BROWSER === "opera"`
+- `import.meta.env.COMMAND`: A string, `"serve"` when running `wxt` for development or `"build"` in all other cases.
 
 :::info
 These variables are constants defined at build time based on the build target. They do not actually detect which browser the code is running in.
 
-For example, if you build for `--browser chrome` and publish it on Edge, `__BROWSER__` will be `"chrome"`, not `"edge"`. You have to build a separate ZIP for `--browser edge` before `__BROWSER__` will be `"edge"`.
+For example, if you build for `--browser chrome` and publish it on Edge, `import.meta.env.BROWSER` will be `"chrome"`, not `"edge"`. You have to build a separate ZIP for `--browser edge` before `import.meta.env.BROWSER` will be `"edge"`.
 
 If you need to know the actual browser your code is being ran on, you should use a [user agent parser](https://www.npmjs.com/package/ua-parser-js).
 :::

docs/guide/testing.md

@@ -19,7 +19,7 @@ If you want to try to use a different framework for unit tests, you will need to
 - **Auto-imports**: Add `unimport` to your test environment or disable them by setting `imports: false` in your `wxt.config.ts` file
 - **`browser` mock**: Mock the `webextension-polyfill` module globally with `wxt/dist/virtual/mock-browser.js`
 - **[Remote Code Bundling](/guide/remote-code)**: If you use it, configure your environment to handle the `url:` module prefix
-- **Global Variables**: If you consume them, manually define globals provided by WXT (like `__BROWSER__`) by adding them to the global scope before accessing them (`globalThis.__BROWSER__ = "chrome"`)
+- **Global Variables**: If you consume them, manually define globals provided by WXT (like `import.meta.env.BROWSER`) by adding them to the global scope before accessing them (`import.meta.env.BROWSER = "chrome"`)
 - **Import paths**: If you use the `@/` or `~/` path aliases, add them to your test environment
 
 [Here's how Vitest is configured](https://github.com/wxt-dev/wxt/blob/main/src/testing/wxt-vitest-plugin.ts) for reference.

e2e/tests/typescript-project.test.ts

@@ -14,16 +14,19 @@ describe('TypeScript Project', () => {
       ----------------------------------------
       // Generated by wxt
       export {}
-      declare global {
-        const __MANIFEST_VERSION__: 2 | 3;
-        const __BROWSER__: string;
-        const __IS_CHROME__: boolean;
-        const __IS_FIREFOX__: boolean;
-        const __IS_SAFARI__: boolean;
-        const __IS_EDGE__: boolean;
-        const __IS_OPERA__: boolean;
-        const __COMMAND__: "build" | "serve";
-        const __ENTRYPOINT__: string;
+      interface ImportMetaEnv {
+        readonly MANIFEST_VERSION: 2 | 3;
+        readonly BROWSER: string;
+        readonly CHROME: boolean;
+        readonly FIREFOX: boolean;
+        readonly SAFARI: boolean;
+        readonly EDGE: boolean;
+        readonly OPERA: boolean;
+        readonly COMMAND: "build" | "serve";
+        readonly ENTRYPOINT: string;
+      }
+      interface ImportMeta {
+        readonly env: ImportMetaEnv
       }
       "
     `);
@@ -133,7 +136,7 @@ describe('TypeScript Project', () => {
             options?: GetMessageOptions,
           ): string;
           /**
-           * 
+           * No message description.
            *
            * "<browser.i18n.getUiLocale()>"
            */

package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.14.7",
+  "version": "0.15.0",
   "description": "Next gen framework for developing web extensions",
   "engines": {
     "node": ">=18",

src/client/content-scripts/custom-events.ts

@@ -15,10 +15,12 @@ export class WxtLocationChangeEvent extends Event {
  * Returns an event name unique to the extension and content script that's running.
  */
 export function getUniqueEventName(eventName: string): string {
-  // During the build process, __ENTRYPOINT__ is not defined when importing entrypoints to get their
-  // metadata.
+  // During the build process, import.meta.env is not defined when importing
+  // entrypoints to get their metadata.
   const entrypointName =
-    typeof __ENTRYPOINT__ === 'undefined' ? 'build' : __ENTRYPOINT__;
+    typeof import.meta.env === 'undefined'
+      ? 'build'
+      : import.meta.env.ENTRYPOINT;
 
   return `${browser.runtime.id}:${entrypointName}:${eventName}`;
 }

src/client/content-scripts/ui/index.ts

@@ -236,7 +236,9 @@ function mountUi(
  * Load the CSS for the current entrypoint.
  */
 async function loadCss(): Promise<string> {
-  const url = browser.runtime.getURL(`/content-scripts/${__ENTRYPOINT__}.css`);
+  const url = browser.runtime.getURL(
+    `/content-scripts/${import.meta.env.ENTRYPOINT}.css`,
+  );
   try {
     const res = await fetch(url);
     return await res.text();

src/core/builders/vite/index.ts

@@ -44,6 +44,10 @@ export async function createViteBuilder(
     if (config.build.minify == null && wxtConfig.command === 'serve') {
       config.build.minify = false;
     }
+    // Enable inline sourcemaps for the dev command (so content scripts have sourcemaps)
+    if (config.build.sourcemap == null && wxtConfig.command === 'serve') {
+      config.build.sourcemap = 'inline';
+    }
 
     config.plugins ??= [];
     config.plugins.push(

src/core/builders/vite/plugins/entrypointGroupGlobals.ts

@@ -14,7 +14,7 @@ export function entrypointGroupGlobals(
       const define: vite.InlineConfig['define'] = {};
       let name = Array.isArray(entrypointGroup) ? 'html' : entrypointGroup.name;
       for (const global of getEntrypointGlobals(name)) {
-        define[global.name] = JSON.stringify(global.value);
+        define[`import.meta.env.${global.name}`] = JSON.stringify(global.value);
       }
       return {
         define,

src/core/builders/vite/plugins/globals.ts

@@ -10,7 +10,7 @@ export function globals(
     config() {
       const define: vite.InlineConfig['define'] = {};
       for (const global of getGlobals(config)) {
-        define[global.name] = JSON.stringify(global.value);
+        define[`import.meta.env.${global.name}`] = JSON.stringify(global.value);
       }
       return {
         define,

src/core/builders/vite/plugins/unimport.ts

@@ -36,7 +36,11 @@ export function unimport(
       // Don't transform non-js files
       if (!ENABLED_EXTENSIONS.has(extname(id))) return;
 
-      return unimport.injectImports(code, id);
+      const injected = await unimport.injectImports(code, id);
+      return {
+        code: injected.code,
+        map: injected.s.generateMap({ hires: 'boundary', source: id }),
+      };
     },
   };
 }

src/core/utils/building/generate-wxt-dir.ts

@@ -136,7 +136,7 @@ declare module "wxt/browser" {
 
   const overrides = messages.map((message) => {
     return `    /**
-     * ${message.description ?? 'No message description.'}
+     * ${message.description || 'No message description.'}
      *
      * "${message.message}"
      */
@@ -164,8 +164,11 @@ async function writeGlobalsDeclarationFile(
     [
       '// Generated by wxt',
       'export {}',
-      'declare global {',
-      ...globals.map((global) => `  const ${global.name}: ${global.type};`),
+      'interface ImportMetaEnv {',
+      ...globals.map((global) => `  readonly ${global.name}: ${global.type};`),
+      '}',
+      'interface ImportMeta {',
+      '  readonly env: ImportMetaEnv',
       '}',
     ].join('\n') + '\n',
   );

src/core/utils/building/get-internal-config.ts

@@ -241,8 +241,9 @@ function resolveInternalZipConfig(
     sourcesTemplate: '{{name}}-{{version}}-sources.zip',
     artifactTemplate: '{{name}}-{{version}}-{{browser}}.zip',
     sourcesRoot: root,
+    includeSources: [],
     ...mergedConfig.zip,
-    ignoredSources: [
+    excludeSources: [
       '**/node_modules',
       // WXT files
       '**/web-ext.config.ts',
@@ -252,7 +253,7 @@ function resolveInternalZipConfig(
       '**/__tests__/**',
       '**/*.+(test|spec).?(c|m)+(j|t)s?(x)',
       // From user
-      ...(mergedConfig.zip?.ignoredSources ?? []),
+      ...(mergedConfig.zip?.excludeSources ?? []),
     ],
   };
 }

src/core/utils/building/import-entrypoint.ts

@@ -98,6 +98,7 @@ export async function importEntrypointFile<T>(
         { cause: err },
       );
     } else {
+      config.logger.error(err);
       throw Error(`Failed to load entrypoint: ${filePath}`, { cause: err });
     }
   }

src/core/utils/globals.ts

@@ -5,42 +5,42 @@ export function getGlobals(
 ): Array<{ name: string; value: any; type: string }> {
   return [
     {
-      name: surroundInUnderscore('MANIFEST_VERSION'),
+      name: 'MANIFEST_VERSION',
       value: config.manifestVersion,
       type: `2 | 3`,
     },
     {
-      name: surroundInUnderscore('BROWSER'),
+      name: 'BROWSER',
       value: config.browser,
       type: `string`,
     },
     {
-      name: surroundInUnderscore('IS_CHROME'),
+      name: 'CHROME',
       value: config.browser === 'chrome',
       type: `boolean`,
     },
     {
-      name: surroundInUnderscore('IS_FIREFOX'),
+      name: 'FIREFOX',
       value: config.browser === 'firefox',
       type: `boolean`,
     },
     {
-      name: surroundInUnderscore('IS_SAFARI'),
+      name: 'SAFARI',
       value: config.browser === 'safari',
       type: `boolean`,
     },
     {
-      name: surroundInUnderscore('IS_EDGE'),
+      name: 'EDGE',
       value: config.browser === 'edge',
       type: `boolean`,
     },
     {
-      name: surroundInUnderscore('IS_OPERA'),
+      name: 'OPERA',
       value: config.browser === 'opera',
       type: `boolean`,
     },
     {
-      name: surroundInUnderscore('COMMAND'),
+      name: 'COMMAND',
       value: config.command,
       type: `"build" | "serve"`,
     },
@@ -50,17 +50,9 @@ export function getGlobals(
 export function getEntrypointGlobals(entrypointName: string) {
   return [
     {
-      name: surroundInUnderscore('ENTRYPOINT'),
+      name: 'ENTRYPOINT',
       value: entrypointName,
       type: `string`,
     },
   ];
 }
-
-/**
- * Don't hardcode the complete name so that the string litterals in this file aren't replaced during
- * tests (which causes syntax errors), only during builds.
- */
-function surroundInUnderscore(name: string): string {
-  return `__${name}__`;
-}

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

@@ -232,7 +232,8 @@ export const fakeInternalConfig = fakeObjectCreator<InternalConfig>(() => {
     },
     zip: {
       artifactTemplate: '{{name}}-{{version}}.zip',
-      ignoredSources: [],
+      includeSources: [],
+      excludeSources: [],
       sourcesRoot: fakeDir(),
       sourcesTemplate: '{{name}}-sources.zip',
       name: faker.person.firstName().toLowerCase(),

src/core/zip.ts

@@ -62,10 +62,15 @@ export async function zip(config?: InlineConfig): Promise<string[]> {
       saveTo: sourcesZipPath,
       filter(path) {
         const relativePath = relative(internalConfig.zip.sourcesRoot, path);
-        const matchedPattern = internalConfig.zip.ignoredSources.find(
-          (pattern) => minimatch(relativePath, pattern),
+
+        return (
+          internalConfig.zip.includeSources.some((pattern) =>
+            minimatch(relativePath, pattern),
+          ) ||
+          !internalConfig.zip.excludeSources.some((pattern) =>
+            minimatch(relativePath, pattern),
+          )
         );
-        return matchedPattern == null;
       },
     });
     zipFiles.push(sourcesZipPath);

src/types/external.ts

@@ -143,9 +143,22 @@ export interface InlineConfig {
      * @default config.root
      */
     sourcesRoot?: string;
+    /**
+     * [Minimatch](https://www.npmjs.com/package/minimatch) patterns of files to include when
+     * creating a ZIP of all your source code for Firefox. Patterns are relative to your
+     * `config.zip.sourcesRoot`.
+     *
+     * This setting overrides `excludeSources`. So if a file matches both lists, it is included in the ZIP.
+     *
+     * @example
+     * [
+     *   "coverage", // Ignore the coverage directory in the `sourcesRoot`
+     * ]
+     */
+    includeSources?: string[];
     /**
      * [Minimatch](https://www.npmjs.com/package/minimatch) patterns of files to exclude when
-     * creating a ZIP of all your source code for Firfox. Patterns are relative to your
+     * creating a ZIP of all your source code for Firefox. Patterns are relative to your
      * `config.zip.sourcesRoot`.
      *
      * Hidden files, node_modules, and tests are ignored by default.
@@ -155,7 +168,7 @@ export interface InlineConfig {
      *   "coverage", // Ignore the coverage directory in the `sourcesRoot`
      * ]
      */
-    ignoredSources?: string[];
+    excludeSources?: string[];
   };
 
   /**

src/types/globals.d.ts

@@ -1,7 +1,10 @@
-// Globals defined by the vite-plugins/devServerGlobals.ts and utils/globals.ts
-declare const __COMMAND__: 'build' | 'serve';
 declare const __DEV_SERVER_PROTOCOL__: string;
 declare const __DEV_SERVER_HOSTNAME__: string;
 declare const __DEV_SERVER_PORT__: string;
-declare const __MANIFEST_VERSION__: 2 | 3;
-declare const __ENTRYPOINT__: string;
+
+// Globals defined by the vite-plugins/devServerGlobals.ts and utils/globals.ts
+interface ImportMetaEnv {
+  readonly COMMAND: 'build' | 'serve';
+  readonly MANIFEST_VERSION: 2 | 3;
+  readonly ENTRYPOINT: string;
+}

src/types/internal.ts

@@ -40,7 +40,8 @@ export interface InternalConfig {
     name?: string;
     artifactTemplate: string;
     sourcesTemplate: string;
-    ignoredSources: string[];
+    includeSources: string[];
+    excludeSources: string[];
     sourcesRoot: string;
   };
   transformManifest: (manifest: Manifest.WebExtensionManifest) => void;

src/virtual/background-entrypoint.ts

@@ -5,7 +5,7 @@ import { browser } from 'wxt/browser';
 import { keepServiceWorkerAlive } from './utils/keep-service-worker-alive';
 import { reloadContentScript } from './utils/reload-content-scripts';
 
-if (__COMMAND__ === 'serve') {
+if (import.meta.env.COMMAND === 'serve') {
   try {
     const ws = setupWebSocket((message) => {
       if (message.event === 'wxt:reload-extension') browser.runtime.reload();
@@ -13,7 +13,7 @@ if (__COMMAND__ === 'serve') {
         reloadContentScript(message.data);
     });
 
-    if (__MANIFEST_VERSION__ === 3) {
+    if (import.meta.env.MANIFEST_VERSION === 3) {
       // Tell the server the background script is loaded and ready to go
       ws.addEventListener('open', () => {
         const msg = { type: 'custom', event: 'wxt:background-initialized' };

src/virtual/content-script-isolated-world-entrypoint.ts

@@ -5,12 +5,12 @@ import { ContentScriptContext } from 'wxt/client';
 (async () => {
   try {
     const { main, ...options } = definition;
-    const ctx = new ContentScriptContext(__ENTRYPOINT__, options);
+    const ctx = new ContentScriptContext(import.meta.env.ENTRYPOINT, options);
 
     await main(ctx);
   } catch (err) {
     logger.error(
-      `The content script "${__ENTRYPOINT__}" crashed on startup!`,
+      `The content script "${import.meta.env.ENTRYPOINT}" crashed on startup!`,
       err,
     );
   }

src/virtual/content-script-main-world-entrypoint.ts

@@ -7,7 +7,7 @@ import { logger } from '../sandbox/utils/logger';
     await main();
   } catch (err) {
     logger.error(
-      `The content script "${__ENTRYPOINT__}" crashed on startup!`,
+      `The content script "${import.meta.env.ENTRYPOINT}" crashed on startup!`,
       err,
     );
   }

src/virtual/reload-html.ts

@@ -1,7 +1,7 @@
 import { logger } from '../sandbox/utils/logger';
 import { setupWebSocket } from './utils/setup-web-socket';
 
-if (__COMMAND__ === 'serve') {
+if (import.meta.env.COMMAND === 'serve') {
   try {
     setupWebSocket((message) => {
       if (message.event === 'wxt:reload-page') {

src/virtual/unlisted-script-entrypoint.ts

@@ -6,7 +6,7 @@ import { logger } from '../sandbox/utils/logger';
     await definition.main();
   } catch (err) {
     logger.error(
-      `The unlisted script "${__ENTRYPOINT__}" crashed on startup!`,
+      `The unlisted script "${import.meta.env.ENTRYPOINT}" crashed on startup!`,
       err,
     );
   }