wxt 0.16.11 → 0.17.0

package/dist/{chunk-YH7RSTGT.js → chunk-FD7GO6WM.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.16.11";
+var version = "0.17.0";
 
 // src/core/utils/paths.ts
 import systemPath from "node:path";

package/dist/cli.js

@@ -2181,7 +2181,7 @@ function getChunkSortWeight(filename) {
 import pc4 from "picocolors";
 
 // package.json
-var version = "0.16.11";
+var version = "0.17.0";
 
 // src/core/utils/log/printHeader.ts
 import { consola as consola2 } from "consola";
@@ -3204,8 +3204,8 @@ async function createServer(inlineConfig) {
     transformHtml(url, html, originalUrl) {
       return builderServer.transformHtml(url, html, originalUrl);
     },
-    reloadContentScript(contentScript) {
-      server.ws.send("wxt:reload-content-script", contentScript);
+    reloadContentScript(payload) {
+      server.ws.send("wxt:reload-content-script", payload);
     },
     reloadPage(path8) {
       server.ws.send("wxt:reload-page", path8);
@@ -3306,9 +3306,14 @@ function reloadContentScripts(steps, server) {
       const js = [getEntrypointBundlePath(entry, wxt.config.outDir, ".js")];
       const cssMap = getContentScriptsCssMap(server.currentOutput, [entry]);
       const css = getContentScriptCssFiles([entry], cssMap);
-      server.reloadContentScript(
-        mapWxtOptionsToRegisteredContentScript(entry.options, js, css)
-      );
+      server.reloadContentScript({
+        registration: entry.options.registration,
+        contentScript: mapWxtOptionsToRegisteredContentScript(
+          entry.options,
+          js,
+          css
+        )
+      });
     });
   } else {
     server.reloadExtension();

package/dist/{index-h54vKikt.d.cts → index-Du5Xv5e8.d.cts}

@@ -471,14 +471,18 @@ interface WxtDevServer extends Omit<WxtBuilderServer, 'listen' | 'close'>, Serve
     /**
      * Tell the extension to restart a content script.
      *
-     * @param contentScript The manifest definition for a content script
+     * @param payload Information about the content script to reload.
      */
-    reloadContentScript: (contentScript: Omit<Scripting.RegisteredContentScript, 'id'>) => void;
+    reloadContentScript: (payload: ReloadContentScriptPayload) => void;
     /**
      * Grab the latest runner config and restart the browser.
      */
     restartBrowser: () => void;
 }
+interface ReloadContentScriptPayload {
+    registration?: BaseContentScriptEntrypointOptions['registration'];
+    contentScript: Omit<Scripting.RegisteredContentScript, 'id'>;
+}
 type TargetBrowser = string;
 type TargetManifestVersion = 2 | 3;
 type UserConfig = Omit<InlineConfig, 'configFile'>;
@@ -1042,4 +1046,4 @@ type WxtResolvedUnimportOptions = Partial<UnimportOptions> & {
     eslintrc: ResolvedEslintrc;
 };
 
-export type { Eslintrc as $, UserManifestFn as A, BuildOutput as B, ContentScriptEntrypoint as C, ConfigEnv as D, ExtensionRunnerConfig as E, WxtBuilder as F, GenericEntrypoint as G, WxtBuilderServer as H, InlineConfig as I, ServerInfo as J, HookResult as K, Logger as L, MainWorldContentScriptEntrypointOptions as M, WxtHooks as N, OutputFile as O, PopupEntrypointOptions as P, Wxt as Q, ResolvedPerBrowserOptions as R, SidepanelEntrypointOptions as S, TargetBrowser as T, UserConfig as U, ResolvedConfig as V, WxtDevServer as W, FsCache as X, ExtensionRunner as Y, VirtualEntrypointType as Z, EslintGlobalsPropValue as _, WxtViteConfig as a, ResolvedEslintrc as a0, WxtUnimportOptions as a1, WxtResolvedUnimportOptions as a2, OutputChunk as b, OutputAsset as c, BuildStepOutput as d, TargetManifestVersion as e, BaseEntrypointOptions as f, BackgroundEntrypointOptions as g, BaseContentScriptEntrypointOptions as h, IsolatedWorldContentScriptEntrypointOptions as i, OptionsEntrypointOptions as j, BaseEntrypoint as k, BackgroundEntrypoint as l, PopupEntrypoint as m, OptionsEntrypoint as n, SidepanelEntrypoint as o, Entrypoint as p, EntrypointGroup as q, OnContentScriptStopped as r, IsolatedWorldContentScriptDefinition as s, MainWorldContentScriptDefinition as t, ContentScriptDefinition as u, BackgroundDefinition as v, UnlistedScriptDefinition as w, PerBrowserOption as x, PerBrowserMap as y, UserManifest as z };
+export type { EslintGlobalsPropValue as $, UserManifest as A, BuildOutput as B, ContentScriptEntrypoint as C, UserManifestFn as D, ExtensionRunnerConfig as E, ConfigEnv as F, GenericEntrypoint as G, WxtBuilder as H, InlineConfig as I, WxtBuilderServer as J, ServerInfo as K, Logger as L, MainWorldContentScriptEntrypointOptions as M, HookResult as N, OutputFile as O, PopupEntrypointOptions as P, WxtHooks as Q, ReloadContentScriptPayload as R, SidepanelEntrypointOptions as S, TargetBrowser as T, UserConfig as U, Wxt as V, WxtDevServer as W, ResolvedConfig as X, FsCache as Y, ExtensionRunner as Z, VirtualEntrypointType as _, WxtViteConfig as a, Eslintrc as a0, ResolvedEslintrc as a1, WxtUnimportOptions as a2, WxtResolvedUnimportOptions as a3, OutputChunk as b, OutputAsset as c, BuildStepOutput as d, TargetManifestVersion as e, BaseEntrypointOptions as f, BackgroundEntrypointOptions as g, BaseContentScriptEntrypointOptions as h, IsolatedWorldContentScriptEntrypointOptions as i, OptionsEntrypointOptions as j, BaseEntrypoint as k, BackgroundEntrypoint as l, PopupEntrypoint as m, OptionsEntrypoint as n, SidepanelEntrypoint as o, Entrypoint as p, EntrypointGroup as q, OnContentScriptStopped as r, IsolatedWorldContentScriptDefinition as s, MainWorldContentScriptDefinition as t, ContentScriptDefinition as u, BackgroundDefinition as v, UnlistedScriptDefinition as w, PerBrowserOption as x, PerBrowserMap as y, ResolvedPerBrowserOptions as z };

package/dist/{index-h54vKikt.d.ts → index-Du5Xv5e8.d.ts}

@@ -471,14 +471,18 @@ interface WxtDevServer extends Omit<WxtBuilderServer, 'listen' | 'close'>, Serve
     /**
      * Tell the extension to restart a content script.
      *
-     * @param contentScript The manifest definition for a content script
+     * @param payload Information about the content script to reload.
      */
-    reloadContentScript: (contentScript: Omit<Scripting.RegisteredContentScript, 'id'>) => void;
+    reloadContentScript: (payload: ReloadContentScriptPayload) => void;
     /**
      * Grab the latest runner config and restart the browser.
      */
     restartBrowser: () => void;
 }
+interface ReloadContentScriptPayload {
+    registration?: BaseContentScriptEntrypointOptions['registration'];
+    contentScript: Omit<Scripting.RegisteredContentScript, 'id'>;
+}
 type TargetBrowser = string;
 type TargetManifestVersion = 2 | 3;
 type UserConfig = Omit<InlineConfig, 'configFile'>;
@@ -1042,4 +1046,4 @@ type WxtResolvedUnimportOptions = Partial<UnimportOptions> & {
     eslintrc: ResolvedEslintrc;
 };
 
-export type { Eslintrc as $, UserManifestFn as A, BuildOutput as B, ContentScriptEntrypoint as C, ConfigEnv as D, ExtensionRunnerConfig as E, WxtBuilder as F, GenericEntrypoint as G, WxtBuilderServer as H, InlineConfig as I, ServerInfo as J, HookResult as K, Logger as L, MainWorldContentScriptEntrypointOptions as M, WxtHooks as N, OutputFile as O, PopupEntrypointOptions as P, Wxt as Q, ResolvedPerBrowserOptions as R, SidepanelEntrypointOptions as S, TargetBrowser as T, UserConfig as U, ResolvedConfig as V, WxtDevServer as W, FsCache as X, ExtensionRunner as Y, VirtualEntrypointType as Z, EslintGlobalsPropValue as _, WxtViteConfig as a, ResolvedEslintrc as a0, WxtUnimportOptions as a1, WxtResolvedUnimportOptions as a2, OutputChunk as b, OutputAsset as c, BuildStepOutput as d, TargetManifestVersion as e, BaseEntrypointOptions as f, BackgroundEntrypointOptions as g, BaseContentScriptEntrypointOptions as h, IsolatedWorldContentScriptEntrypointOptions as i, OptionsEntrypointOptions as j, BaseEntrypoint as k, BackgroundEntrypoint as l, PopupEntrypoint as m, OptionsEntrypoint as n, SidepanelEntrypoint as o, Entrypoint as p, EntrypointGroup as q, OnContentScriptStopped as r, IsolatedWorldContentScriptDefinition as s, MainWorldContentScriptDefinition as t, ContentScriptDefinition as u, BackgroundDefinition as v, UnlistedScriptDefinition as w, PerBrowserOption as x, PerBrowserMap as y, UserManifest as z };
+export type { EslintGlobalsPropValue as $, UserManifest as A, BuildOutput as B, ContentScriptEntrypoint as C, UserManifestFn as D, ExtensionRunnerConfig as E, ConfigEnv as F, GenericEntrypoint as G, WxtBuilder as H, InlineConfig as I, WxtBuilderServer as J, ServerInfo as K, Logger as L, MainWorldContentScriptEntrypointOptions as M, HookResult as N, OutputFile as O, PopupEntrypointOptions as P, WxtHooks as Q, ReloadContentScriptPayload as R, SidepanelEntrypointOptions as S, TargetBrowser as T, UserConfig as U, Wxt as V, WxtDevServer as W, ResolvedConfig as X, FsCache as Y, ExtensionRunner as Z, VirtualEntrypointType as _, WxtViteConfig as a, Eslintrc as a0, ResolvedEslintrc as a1, WxtUnimportOptions as a2, WxtResolvedUnimportOptions as a3, OutputChunk as b, OutputAsset as c, BuildStepOutput as d, TargetManifestVersion as e, BaseEntrypointOptions as f, BackgroundEntrypointOptions as g, BaseContentScriptEntrypointOptions as h, IsolatedWorldContentScriptEntrypointOptions as i, OptionsEntrypointOptions as j, BaseEntrypoint as k, BackgroundEntrypoint as l, PopupEntrypoint as m, OptionsEntrypoint as n, SidepanelEntrypoint as o, Entrypoint as p, EntrypointGroup as q, OnContentScriptStopped as r, IsolatedWorldContentScriptDefinition as s, MainWorldContentScriptDefinition as t, ContentScriptDefinition as u, BackgroundDefinition as v, UnlistedScriptDefinition as w, PerBrowserOption as x, PerBrowserMap as y, ResolvedPerBrowserOptions as z };

package/dist/index.cjs

@@ -4608,7 +4608,7 @@ function getChunkSortWeight(filename) {
 var import_picocolors4 = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "0.16.11";
+var version = "0.17.0";
 
 // src/core/utils/log/printHeader.ts
 var import_consola2 = require("consola");
@@ -5637,8 +5637,8 @@ async function createServer(inlineConfig) {
     transformHtml(url2, html, originalUrl) {
       return builderServer.transformHtml(url2, html, originalUrl);
     },
-    reloadContentScript(contentScript) {
-      server.ws.send("wxt:reload-content-script", contentScript);
+    reloadContentScript(payload) {
+      server.ws.send("wxt:reload-content-script", payload);
     },
     reloadPage(path11) {
       server.ws.send("wxt:reload-page", path11);
@@ -5739,9 +5739,14 @@ function reloadContentScripts(steps, server) {
       const js = [getEntrypointBundlePath(entry, wxt.config.outDir, ".js")];
       const cssMap = getContentScriptsCssMap(server.currentOutput, [entry]);
       const css = getContentScriptCssFiles([entry], cssMap);
-      server.reloadContentScript(
-        mapWxtOptionsToRegisteredContentScript(entry.options, js, css)
-      );
+      server.reloadContentScript({
+        registration: entry.options.registration,
+        contentScript: mapWxtOptionsToRegisteredContentScript(
+          entry.options,
+          js,
+          css
+        )
+      });
     });
   } else {
     server.reloadExtension();

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { I as InlineConfig, B as BuildOutput, U as UserConfig, E as ExtensionRunnerConfig, W as WxtDevServer } from './index-h54vKikt.cjs';
-export { v as BackgroundDefinition, l as BackgroundEntrypoint, g as BackgroundEntrypointOptions, h as BaseContentScriptEntrypointOptions, k as BaseEntrypoint, f as BaseEntrypointOptions, d as BuildStepOutput, D as ConfigEnv, u as ContentScriptDefinition, C as ContentScriptEntrypoint, p as Entrypoint, q as EntrypointGroup, _ as EslintGlobalsPropValue, $ as Eslintrc, Y as ExtensionRunner, X as FsCache, G as GenericEntrypoint, K as HookResult, s as IsolatedWorldContentScriptDefinition, i as IsolatedWorldContentScriptEntrypointOptions, L as Logger, t as MainWorldContentScriptDefinition, M as MainWorldContentScriptEntrypointOptions, r as OnContentScriptStopped, n as OptionsEntrypoint, j as OptionsEntrypointOptions, c as OutputAsset, b as OutputChunk, O as OutputFile, y as PerBrowserMap, x as PerBrowserOption, m as PopupEntrypoint, P as PopupEntrypointOptions, V as ResolvedConfig, a0 as ResolvedEslintrc, R as ResolvedPerBrowserOptions, J as ServerInfo, o as SidepanelEntrypoint, S as SidepanelEntrypointOptions, T as TargetBrowser, e as TargetManifestVersion, w as UnlistedScriptDefinition, z as UserManifest, A as UserManifestFn, Z as VirtualEntrypointType, Q as Wxt, F as WxtBuilder, H as WxtBuilderServer, N as WxtHooks, a2 as WxtResolvedUnimportOptions, a1 as WxtUnimportOptions, a as WxtViteConfig } from './index-h54vKikt.cjs';
+import { I as InlineConfig, B as BuildOutput, U as UserConfig, E as ExtensionRunnerConfig, W as WxtDevServer } from './index-Du5Xv5e8.cjs';
+export { v as BackgroundDefinition, l as BackgroundEntrypoint, g as BackgroundEntrypointOptions, h as BaseContentScriptEntrypointOptions, k as BaseEntrypoint, f as BaseEntrypointOptions, d as BuildStepOutput, F as ConfigEnv, u as ContentScriptDefinition, C as ContentScriptEntrypoint, p as Entrypoint, q as EntrypointGroup, $ as EslintGlobalsPropValue, a0 as Eslintrc, Z as ExtensionRunner, Y as FsCache, G as GenericEntrypoint, N as HookResult, s as IsolatedWorldContentScriptDefinition, i as IsolatedWorldContentScriptEntrypointOptions, L as Logger, t as MainWorldContentScriptDefinition, M as MainWorldContentScriptEntrypointOptions, r as OnContentScriptStopped, n as OptionsEntrypoint, j as OptionsEntrypointOptions, c as OutputAsset, b as OutputChunk, O as OutputFile, y as PerBrowserMap, x as PerBrowserOption, m as PopupEntrypoint, P as PopupEntrypointOptions, R as ReloadContentScriptPayload, X as ResolvedConfig, a1 as ResolvedEslintrc, z as ResolvedPerBrowserOptions, K as ServerInfo, o as SidepanelEntrypoint, S as SidepanelEntrypointOptions, T as TargetBrowser, e as TargetManifestVersion, w as UnlistedScriptDefinition, A as UserManifest, D as UserManifestFn, _ as VirtualEntrypointType, V as Wxt, H as WxtBuilder, J as WxtBuilderServer, Q as WxtHooks, a3 as WxtResolvedUnimportOptions, a2 as WxtUnimportOptions, a as WxtViteConfig } from './index-Du5Xv5e8.cjs';
 import 'vite';
 import 'webextension-polyfill';
 import 'unimport';
@@ -64,6 +64,6 @@ declare function prepare(config: InlineConfig): Promise<void>;
  */
 declare function zip(config?: InlineConfig): Promise<string[]>;
 
-var version = "0.16.11";
+var version = "0.17.0";
 
 export { BuildOutput, ExtensionRunnerConfig, InlineConfig, UserConfig, WxtDevServer, build, clean, createServer, defineConfig, defineRunnerConfig, initialize, prepare, version, zip };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { I as InlineConfig, B as BuildOutput, U as UserConfig, E as ExtensionRunnerConfig, W as WxtDevServer } from './index-h54vKikt.js';
-export { v as BackgroundDefinition, l as BackgroundEntrypoint, g as BackgroundEntrypointOptions, h as BaseContentScriptEntrypointOptions, k as BaseEntrypoint, f as BaseEntrypointOptions, d as BuildStepOutput, D as ConfigEnv, u as ContentScriptDefinition, C as ContentScriptEntrypoint, p as Entrypoint, q as EntrypointGroup, _ as EslintGlobalsPropValue, $ as Eslintrc, Y as ExtensionRunner, X as FsCache, G as GenericEntrypoint, K as HookResult, s as IsolatedWorldContentScriptDefinition, i as IsolatedWorldContentScriptEntrypointOptions, L as Logger, t as MainWorldContentScriptDefinition, M as MainWorldContentScriptEntrypointOptions, r as OnContentScriptStopped, n as OptionsEntrypoint, j as OptionsEntrypointOptions, c as OutputAsset, b as OutputChunk, O as OutputFile, y as PerBrowserMap, x as PerBrowserOption, m as PopupEntrypoint, P as PopupEntrypointOptions, V as ResolvedConfig, a0 as ResolvedEslintrc, R as ResolvedPerBrowserOptions, J as ServerInfo, o as SidepanelEntrypoint, S as SidepanelEntrypointOptions, T as TargetBrowser, e as TargetManifestVersion, w as UnlistedScriptDefinition, z as UserManifest, A as UserManifestFn, Z as VirtualEntrypointType, Q as Wxt, F as WxtBuilder, H as WxtBuilderServer, N as WxtHooks, a2 as WxtResolvedUnimportOptions, a1 as WxtUnimportOptions, a as WxtViteConfig } from './index-h54vKikt.js';
+import { I as InlineConfig, B as BuildOutput, U as UserConfig, E as ExtensionRunnerConfig, W as WxtDevServer } from './index-Du5Xv5e8.js';
+export { v as BackgroundDefinition, l as BackgroundEntrypoint, g as BackgroundEntrypointOptions, h as BaseContentScriptEntrypointOptions, k as BaseEntrypoint, f as BaseEntrypointOptions, d as BuildStepOutput, F as ConfigEnv, u as ContentScriptDefinition, C as ContentScriptEntrypoint, p as Entrypoint, q as EntrypointGroup, $ as EslintGlobalsPropValue, a0 as Eslintrc, Z as ExtensionRunner, Y as FsCache, G as GenericEntrypoint, N as HookResult, s as IsolatedWorldContentScriptDefinition, i as IsolatedWorldContentScriptEntrypointOptions, L as Logger, t as MainWorldContentScriptDefinition, M as MainWorldContentScriptEntrypointOptions, r as OnContentScriptStopped, n as OptionsEntrypoint, j as OptionsEntrypointOptions, c as OutputAsset, b as OutputChunk, O as OutputFile, y as PerBrowserMap, x as PerBrowserOption, m as PopupEntrypoint, P as PopupEntrypointOptions, R as ReloadContentScriptPayload, X as ResolvedConfig, a1 as ResolvedEslintrc, z as ResolvedPerBrowserOptions, K as ServerInfo, o as SidepanelEntrypoint, S as SidepanelEntrypointOptions, T as TargetBrowser, e as TargetManifestVersion, w as UnlistedScriptDefinition, A as UserManifest, D as UserManifestFn, _ as VirtualEntrypointType, V as Wxt, H as WxtBuilder, J as WxtBuilderServer, Q as WxtHooks, a3 as WxtResolvedUnimportOptions, a2 as WxtUnimportOptions, a as WxtViteConfig } from './index-Du5Xv5e8.js';
 import 'vite';
 import 'webextension-polyfill';
 import 'unimport';
@@ -64,6 +64,6 @@ declare function prepare(config: InlineConfig): Promise<void>;
  */
 declare function zip(config?: InlineConfig): Promise<string[]>;
 
-var version = "0.16.11";
+var version = "0.17.0";
 
 export { BuildOutput, ExtensionRunnerConfig, InlineConfig, UserConfig, WxtDevServer, build, clean, createServer, defineConfig, defineRunnerConfig, initialize, prepare, version, zip };

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   unnormalizePath,
   version,
   wxt
-} from "./chunk-YH7RSTGT.js";
+} from "./chunk-FD7GO6WM.js";
 import "./chunk-VBXJIVYU.js";
 
 // src/core/build.ts
@@ -268,8 +268,8 @@ async function createServer(inlineConfig) {
     transformHtml(url, html, originalUrl) {
       return builderServer.transformHtml(url, html, originalUrl);
     },
-    reloadContentScript(contentScript) {
-      server.ws.send("wxt:reload-content-script", contentScript);
+    reloadContentScript(payload) {
+      server.ws.send("wxt:reload-content-script", payload);
     },
     reloadPage(path3) {
       server.ws.send("wxt:reload-page", path3);
@@ -370,9 +370,14 @@ function reloadContentScripts(steps, server) {
       const js = [getEntrypointBundlePath(entry, wxt.config.outDir, ".js")];
       const cssMap = getContentScriptsCssMap(server.currentOutput, [entry]);
       const css = getContentScriptCssFiles([entry], cssMap);
-      server.reloadContentScript(
-        mapWxtOptionsToRegisteredContentScript(entry.options, js, css)
-      );
+      server.reloadContentScript({
+        registration: entry.options.registration,
+        contentScript: mapWxtOptionsToRegisteredContentScript(
+          entry.options,
+          js,
+          css
+        )
+      });
     });
   } else {
     server.reloadExtension();

package/dist/storage.cjs

@@ -40,6 +40,27 @@ var browser = import_webextension_polyfill.default;
 
 // src/storage.ts
 var import_lite = require("dequal/lite");
+
+// src/sandbox/utils/logger.ts
+var import_meta = {};
+function print(method, ...args) {
+  if (import_meta.env.MODE === "production")
+    return;
+  if (typeof args[0] === "string") {
+    const message = args.shift();
+    method(`[wxt] ${message}`, ...args);
+  } else {
+    method("[wxt]", ...args);
+  }
+}
+var logger = {
+  debug: (...args) => print(console.debug, ...args),
+  log: (...args) => print(console.log, ...args),
+  warn: (...args) => print(console.warn, ...args),
+  error: (...args) => print(console.error, ...args)
+};
+
+// src/storage.ts
 var storage = createStorage();
 function createStorage() {
   const drivers = {
@@ -250,7 +271,7 @@ function createStorage() {
           "Storage item version cannot be less than 1. Initial versions should be set to 1, not 0."
         );
       }
-      const runMigrations = async () => {
+      const migrate = async () => {
         const [value, meta] = await Promise.all([
           // TODO: Optimize with getItems
           getItem(driver, driverKey, void 0),
@@ -261,9 +282,12 @@ function createStorage() {
         const currentVersion = meta.v ?? 1;
         if (currentVersion > targetVersion) {
           throw Error(
-            `[wxt/storage] Migration ignored for "${key}", version downgrade detected (${currentVersion} -> ${targetVersion})`
+            `Version downgrade detected (v${currentVersion} -> v${targetVersion}) for "${key}"`
           );
         }
+        logger.debug(
+          `Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`
+        );
         const migrationsToRun = Array.from(
           { length: targetVersion - currentVersion },
           (_, i) => currentVersion + i + 1
@@ -277,17 +301,37 @@ function createStorage() {
           setItem(driver, driverKey, migratedValue),
           setMeta(driver, driverKey, { v: targetVersion })
         ]);
+        logger.debug(
+          `Storage migration completed for ${key} v${targetVersion}`,
+          { migratedValue }
+        );
       };
-      let _migrationsCompleted = runMigrations();
+      browser.runtime.onInstalled.addListener(async ({ reason }) => {
+        if (reason !== "update")
+          return;
+        try {
+          await migrate();
+        } catch (err) {
+          logger.error(`Migration failed for ${key}`, err);
+        }
+      });
+      const getDefaultValue = () => opts?.defaultValue ?? null;
       return {
-        _migrationsCompleted,
+        get defaultValue() {
+          return getDefaultValue();
+        },
         getValue: () => getItem(driver, driverKey, opts),
         getMeta: () => getMeta(driver, driverKey),
         setValue: (value) => setItem(driver, driverKey, value),
         setMeta: (properties) => setMeta(driver, driverKey, properties),
         removeValue: (opts2) => removeItem(driver, driverKey, opts2),
         removeMeta: (properties) => removeMeta(driver, driverKey, properties),
-        watch: (cb) => watch(driver, driverKey, cb)
+        watch: (cb) => watch(
+          driver,
+          driverKey,
+          (newValue, oldValue) => cb(newValue ?? getDefaultValue(), oldValue ?? getDefaultValue())
+        ),
+        migrate
       };
     }
   };

package/dist/storage.d.cts

@@ -94,20 +94,21 @@ interface WxtStorage {
     /**
      * Watch for changes to a specific key in storage.
      */
-    watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+    watch<T>(key: string, cb: WatchCallback<T | null>): Unwatch;
     /**
      * Remove all watch listeners.
      */
     unwatch(): void;
     /**
-     * Define a constant with utilities for reading/writing to a single value in storage.
+     * Define a storage item with a default value, type, or versioning.
      *
-     * @example
-     * export const installDate = storage.defineItem<number>("local:installDate");
+     * Read full docs: https://wxt.dev/guide/storage.html#defining-storage-items
      */
-    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options?: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string): WxtStorageItem<TValue | null, TMetadata>;
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
 }
 interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+    defaultValue: TValue;
     /**
      * Get the latest value from storage.
      */
@@ -119,7 +120,7 @@ interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
     /**
      * Set the value in storage.
      */
-    setValue(value: TValue | null): Promise<void>;
+    setValue(value: TValue): Promise<void>;
     /**
      * Set metadata properties.
      */
@@ -136,6 +137,13 @@ interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
      * Listen for changes to the value in storage.
      */
     watch(cb: WatchCallback<TValue>): Unwatch;
+    /**
+     * If there are migrations defined on the storage item, migrate to the latest version.
+     *
+     * **This function is ran automatically whenever the extension updates**, so you don't have to call it
+     * manually.
+     */
+    migrate(): Promise<void>;
 }
 interface GetItemOptions<T> {
     /**
@@ -158,7 +166,8 @@ interface SnapshotOptions {
      */
     excludeKeys?: string[];
 }
-interface WxtStorageItemOptions<T> extends GetItemOptions<T> {
+interface WxtStorageItemOptions<T> {
+    defaultValue: T;
     /**
      * Provide a version number for the storage item to enable migrations. When changing the version
      * in the future, migration functions will be ran on application startup.
@@ -179,7 +188,7 @@ type NullablePartial<T> = {
 /**
  * Callback called when a value in storage is changed.
  */
-type WatchCallback<T> = (newValue: T | null, oldValue: T | null) => void;
+type WatchCallback<T> = (newValue: T, oldValue: T) => void;
 /**
  * Call to remove a watch listener
  */

package/dist/storage.d.ts

@@ -94,20 +94,21 @@ interface WxtStorage {
     /**
      * Watch for changes to a specific key in storage.
      */
-    watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+    watch<T>(key: string, cb: WatchCallback<T | null>): Unwatch;
     /**
      * Remove all watch listeners.
      */
     unwatch(): void;
     /**
-     * Define a constant with utilities for reading/writing to a single value in storage.
+     * Define a storage item with a default value, type, or versioning.
      *
-     * @example
-     * export const installDate = storage.defineItem<number>("local:installDate");
+     * Read full docs: https://wxt.dev/guide/storage.html#defining-storage-items
      */
-    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options?: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string): WxtStorageItem<TValue | null, TMetadata>;
+    defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: string, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
 }
 interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+    defaultValue: TValue;
     /**
      * Get the latest value from storage.
      */
@@ -119,7 +120,7 @@ interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
     /**
      * Set the value in storage.
      */
-    setValue(value: TValue | null): Promise<void>;
+    setValue(value: TValue): Promise<void>;
     /**
      * Set metadata properties.
      */
@@ -136,6 +137,13 @@ interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
      * Listen for changes to the value in storage.
      */
     watch(cb: WatchCallback<TValue>): Unwatch;
+    /**
+     * If there are migrations defined on the storage item, migrate to the latest version.
+     *
+     * **This function is ran automatically whenever the extension updates**, so you don't have to call it
+     * manually.
+     */
+    migrate(): Promise<void>;
 }
 interface GetItemOptions<T> {
     /**
@@ -158,7 +166,8 @@ interface SnapshotOptions {
      */
     excludeKeys?: string[];
 }
-interface WxtStorageItemOptions<T> extends GetItemOptions<T> {
+interface WxtStorageItemOptions<T> {
+    defaultValue: T;
     /**
      * Provide a version number for the storage item to enable migrations. When changing the version
      * in the future, migration functions will be ran on application startup.
@@ -179,7 +188,7 @@ type NullablePartial<T> = {
 /**
  * Callback called when a value in storage is changed.
  */
-type WatchCallback<T> = (newValue: T | null, oldValue: T | null) => void;
+type WatchCallback<T> = (newValue: T, oldValue: T) => void;
 /**
  * Call to remove a watch listener
  */

package/dist/storage.js

@@ -6,6 +6,26 @@ var browser = originalBrowser;
 
 // src/storage.ts
 import { dequal } from "dequal/lite";
+
+// src/sandbox/utils/logger.ts
+function print(method, ...args) {
+  if (import.meta.env.MODE === "production")
+    return;
+  if (typeof args[0] === "string") {
+    const message = args.shift();
+    method(`[wxt] ${message}`, ...args);
+  } else {
+    method("[wxt]", ...args);
+  }
+}
+var logger = {
+  debug: (...args) => print(console.debug, ...args),
+  log: (...args) => print(console.log, ...args),
+  warn: (...args) => print(console.warn, ...args),
+  error: (...args) => print(console.error, ...args)
+};
+
+// src/storage.ts
 var storage = createStorage();
 function createStorage() {
   const drivers = {
@@ -216,7 +236,7 @@ function createStorage() {
           "Storage item version cannot be less than 1. Initial versions should be set to 1, not 0."
         );
       }
-      const runMigrations = async () => {
+      const migrate = async () => {
         const [value, meta] = await Promise.all([
           // TODO: Optimize with getItems
           getItem(driver, driverKey, void 0),
@@ -227,9 +247,12 @@ function createStorage() {
         const currentVersion = meta.v ?? 1;
         if (currentVersion > targetVersion) {
           throw Error(
-            `[wxt/storage] Migration ignored for "${key}", version downgrade detected (${currentVersion} -> ${targetVersion})`
+            `Version downgrade detected (v${currentVersion} -> v${targetVersion}) for "${key}"`
           );
         }
+        logger.debug(
+          `Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`
+        );
         const migrationsToRun = Array.from(
           { length: targetVersion - currentVersion },
           (_, i) => currentVersion + i + 1
@@ -243,17 +266,37 @@ function createStorage() {
           setItem(driver, driverKey, migratedValue),
           setMeta(driver, driverKey, { v: targetVersion })
         ]);
+        logger.debug(
+          `Storage migration completed for ${key} v${targetVersion}`,
+          { migratedValue }
+        );
       };
-      let _migrationsCompleted = runMigrations();
+      browser.runtime.onInstalled.addListener(async ({ reason }) => {
+        if (reason !== "update")
+          return;
+        try {
+          await migrate();
+        } catch (err) {
+          logger.error(`Migration failed for ${key}`, err);
+        }
+      });
+      const getDefaultValue = () => opts?.defaultValue ?? null;
       return {
-        _migrationsCompleted,
+        get defaultValue() {
+          return getDefaultValue();
+        },
         getValue: () => getItem(driver, driverKey, opts),
         getMeta: () => getMeta(driver, driverKey),
         setValue: (value) => setItem(driver, driverKey, value),
         setMeta: (properties) => setMeta(driver, driverKey, properties),
         removeValue: (opts2) => removeItem(driver, driverKey, opts2),
         removeMeta: (properties) => removeMeta(driver, driverKey, properties),
-        watch: (cb) => watch(driver, driverKey, cb)
+        watch: (cb) => watch(
+          driver,
+          driverKey,
+          (newValue, oldValue) => cb(newValue ?? getDefaultValue(), oldValue ?? getDefaultValue())
+        ),
+        migrate
       };
     }
   };

package/dist/testing.d.cts

@@ -1,6 +1,6 @@
 export { FakeBrowser, fakeBrowser } from '@webext-core/fake-browser';
 import * as vite from 'vite';
-import { I as InlineConfig } from './index-h54vKikt.cjs';
+import { I as InlineConfig } from './index-Du5Xv5e8.cjs';
 import 'webextension-polyfill';
 import 'unimport';
 import 'consola';

package/dist/testing.d.ts

@@ -1,6 +1,6 @@
 export { FakeBrowser, fakeBrowser } from '@webext-core/fake-browser';
 import * as vite from 'vite';
-import { I as InlineConfig } from './index-h54vKikt.js';
+import { I as InlineConfig } from './index-Du5Xv5e8.js';
 import 'webextension-polyfill';
 import 'unimport';
 import 'consola';

package/dist/testing.js

@@ -5,7 +5,7 @@ import {
   tsconfigPaths,
   unimport,
   webextensionPolyfillMock
-} from "./chunk-YH7RSTGT.js";
+} from "./chunk-FD7GO6WM.js";
 import "./chunk-VBXJIVYU.js";
 
 // src/testing/fake-browser.ts

package/dist/virtual/background-entrypoint.js

@@ -60,27 +60,44 @@ function keepServiceWorkerAlive() {
 // src/virtual/utils/reload-content-scripts.ts
 import { browser as browser2 } from "wxt/browser";
 import { MatchPattern } from "wxt/sandbox";
-function reloadContentScript(contentScript) {
+function reloadContentScript(payload) {
   const manifest = browser2.runtime.getManifest();
   if (manifest.manifest_version == 2) {
-    void reloadContentScriptMv2(contentScript);
+    void reloadContentScriptMv2(payload);
   } else {
-    void reloadContentScriptMv3(contentScript);
+    void reloadContentScriptMv3(payload);
   }
 }
-async function reloadContentScriptMv3(contentScript) {
-  const id = `wxt:${contentScript.js[0]}`;
+async function reloadContentScriptMv3({
+  registration,
+  contentScript
+}) {
+  if (registration === "runtime") {
+    await reloadRuntimeContentScriptMv3(contentScript);
+  } else {
+    await reloadRuntimeContentScriptMv3(contentScript);
+  }
+}
+async function reloadRuntimeContentScriptMv3(contentScript) {
   logger.log("Reloading content script:", contentScript);
   const registered = await browser2.scripting.getRegisteredContentScripts();
   logger.debug("Existing scripts:", registered);
-  const existing = registered.find((cs) => cs.id === id);
-  if (existing) {
-    logger.debug("Updating content script", existing);
-    await browser2.scripting.updateContentScripts([{ ...contentScript, id }]);
-  } else {
-    logger.debug("Registering new content script...");
-    await browser2.scripting.registerContentScripts([{ ...contentScript, id }]);
+  const matches = registered.filter((cs) => {
+    const hasJs = contentScript.js?.find((js) => cs.js?.includes(js));
+    const hasCss = contentScript.css?.find((css) => cs.css?.includes(css));
+    return hasJs || hasCss;
+  });
+  if (matches.length === 0) {
+    logger.log(
+      "Content script is not registered yet, nothing to reload",
+      contentScript
+    );
+    return;
   }
+  await browser2.scripting.updateContentScripts(matches);
+  await reloadTabsForContentScript(contentScript);
+}
+async function reloadTabsForContentScript(contentScript) {
   const allTabs = await browser2.tabs.query({});
   const matchPatterns = contentScript.matches.map(
     (match) => new MatchPattern(match)
@@ -93,7 +110,7 @@ async function reloadContentScriptMv3(contentScript) {
   });
   await Promise.all(matchingTabs.map((tab) => browser2.tabs.reload(tab.id)));
 }
-async function reloadContentScriptMv2(contentScript) {
+async function reloadContentScriptMv2(_payload) {
   throw Error("TODO: reloadContentScriptMv2");
 }
 
@@ -126,7 +143,7 @@ try {
   const res = definition.main();
   if (res instanceof Promise) {
     console.warn(
-      "The background's main() function return a promise, but it must be synchonous"
+      "The background's main() function return a promise, but it must be synchronous"
     );
   }
 } catch (err) {

package/package.json

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