wxt 0.18.15 → 0.19.0

package/dist/core/zip.mjs

@@ -0,0 +1,137 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { kebabCaseAlphanumeric } from "./utils/strings.mjs";
+import { getPackageJson } from "./utils/package.mjs";
+import { minimatch } from "minimatch";
+import { formatDuration } from "./utils/time.mjs";
+import { printFileList } from "./utils/log/printFileList.mjs";
+import { internalBuild } from "./utils/building/index.mjs";
+import { registerWxt, wxt } from "./wxt.mjs";
+import JSZip from "jszip";
+import glob from "fast-glob";
+import { normalizePath } from "./utils/paths.mjs";
+export async function zip(config) {
+  await registerWxt("build", config);
+  const output = await internalBuild();
+  const start = Date.now();
+  wxt.logger.info("Zipping extension...");
+  const zipFiles = [];
+  const projectName = wxt.config.zip.name ?? kebabCaseAlphanumeric(
+    (await getPackageJson())?.name || path.dirname(process.cwd())
+  );
+  const applyTemplate = (template) => template.replaceAll("{{name}}", projectName).replaceAll("{{browser}}", wxt.config.browser).replaceAll(
+    "{{version}}",
+    output.manifest.version_name ?? output.manifest.version
+  ).replaceAll("{{mode}}", wxt.config.mode).replaceAll("{{manifestVersion}}", `mv${wxt.config.manifestVersion}`);
+  await fs.ensureDir(wxt.config.outBaseDir);
+  const outZipFilename = applyTemplate(wxt.config.zip.artifactTemplate);
+  const outZipPath = path.resolve(wxt.config.outBaseDir, outZipFilename);
+  await zipDir(wxt.config.outDir, outZipPath);
+  zipFiles.push(outZipPath);
+  if (wxt.config.browser === "firefox") {
+    const { overrides, files: downloadedPackages } = await downloadPrivatePackages();
+    const sourcesZipFilename = applyTemplate(wxt.config.zip.sourcesTemplate);
+    const sourcesZipPath = path.resolve(
+      wxt.config.outBaseDir,
+      sourcesZipFilename
+    );
+    await zipDir(wxt.config.zip.sourcesRoot, sourcesZipPath, {
+      include: wxt.config.zip.includeSources,
+      exclude: wxt.config.zip.excludeSources,
+      transform(absolutePath, zipPath, content) {
+        if (zipPath.endsWith("package.json")) {
+          return addOverridesToPackageJson(absolutePath, content, overrides);
+        }
+      },
+      additionalFiles: downloadedPackages
+    });
+    zipFiles.push(sourcesZipPath);
+  }
+  await printFileList(
+    wxt.logger.success,
+    `Zipped extension in ${formatDuration(Date.now() - start)}`,
+    wxt.config.outBaseDir,
+    zipFiles
+  );
+  return zipFiles;
+}
+async function zipDir(directory, outputPath, options) {
+  const archive = new JSZip();
+  const files = (await glob("**/*", {
+    cwd: directory,
+    // Ignore node_modules, otherwise this glob step takes forever
+    ignore: ["**/node_modules"],
+    onlyFiles: true
+    // TODO: Fix #738
+    // dot: true,
+  })).filter((relativePath) => {
+    return options?.include?.some((pattern) => minimatch(relativePath, pattern)) || !options?.exclude?.some((pattern) => minimatch(relativePath, pattern));
+  });
+  const filesToZip = [
+    ...files,
+    ...(options?.additionalFiles ?? []).map(
+      (file) => path.relative(directory, file)
+    )
+  ];
+  for (const file of filesToZip) {
+    const absolutePath = path.resolve(directory, file);
+    if (file.endsWith(".json")) {
+      const content = await fs.readFile(absolutePath, "utf-8");
+      archive.file(
+        file,
+        await options?.transform?.(absolutePath, file, content) || content
+      );
+    } else {
+      const content = await fs.readFile(absolutePath);
+      archive.file(file, content);
+    }
+  }
+  await options?.additionalWork?.(archive);
+  await new Promise(
+    (resolve, reject) => archive.generateNodeStream({
+      type: "nodebuffer",
+      ...wxt.config.zip.compressionLevel === 0 ? { compression: "STORE" } : {
+        compression: "DEFLATE",
+        compressionOptions: { level: wxt.config.zip.compressionLevel }
+      }
+    }).pipe(fs.createWriteStream(outputPath)).on("error", reject).on("close", resolve)
+  );
+}
+async function downloadPrivatePackages() {
+  const overrides = {};
+  const files = [];
+  if (wxt.config.zip.downloadPackages.length > 0) {
+    const _downloadPackages = new Set(wxt.config.zip.downloadPackages);
+    const allPackages = await wxt.pm.listDependencies({
+      all: true,
+      cwd: wxt.config.root
+    });
+    const downloadPackages = allPackages.filter(
+      (pkg) => _downloadPackages.has(pkg.name)
+    );
+    for (const pkg of downloadPackages) {
+      wxt.logger.info(`Downloading package: ${pkg.name}@${pkg.version}`);
+      const id = `${pkg.name}@${pkg.version}`;
+      const tgzPath = await wxt.pm.downloadDependency(
+        id,
+        wxt.config.zip.downloadedPackagesDir
+      );
+      files.push(tgzPath);
+      overrides[id] = tgzPath;
+    }
+  }
+  return { overrides, files };
+}
+function addOverridesToPackageJson(absolutePackageJsonPath, content, overrides) {
+  if (Object.keys(overrides).length === 0) return content;
+  const packageJsonDir = path.dirname(absolutePackageJsonPath);
+  const oldPackage = JSON.parse(content);
+  const newPackage = {
+    ...oldPackage,
+    [wxt.pm.overridesKey]: { ...oldPackage[wxt.pm.overridesKey] }
+  };
+  Object.entries(overrides).forEach(([key, absolutePath]) => {
+    newPackage[wxt.pm.overridesKey][key] = "file://./" + normalizePath(path.relative(packageJsonDir, absolutePath));
+  });
+  return JSON.stringify(newPackage, null, 2);
+}

package/dist/index.d.ts

@@ -1,81 +1,6 @@
-import { I as InlineConfig, B as BuildOutput, U as UserConfig, E as ExtensionRunnerConfig, W as WxtDevServer } from './index-nWRfwAJi.js';
-export { x as BackgroundDefinition, n as BackgroundEntrypoint, i as BackgroundEntrypointOptions, j as BaseContentScriptEntrypointOptions, m as BaseEntrypoint, h as BaseEntrypointOptions, e as BuildStepOutput, J as ConfigEnv, w as ContentScriptDefinition, C as ContentScriptEntrypoint, ac as CopiedPublicFile, a5 as Dependency, r as Entrypoint, s as EntrypointGroup, $ as EslintGlobalsPropValue, a0 as Eslintrc, _ as ExtensionRunner, Z as FsCache, ad as GeneratedPublicFile, G as GenericEntrypoint, X as HookResult, u as IsolatedWorldContentScriptDefinition, k as IsolatedWorldContentScriptEntrypointOptions, L as Logger, v as MainWorldContentScriptDefinition, M as MainWorldContentScriptEntrypointOptions, t as OnContentScriptStopped, p as OptionsEntrypoint, l as OptionsEntrypointOptions, d as OutputAsset, c as OutputChunk, O as OutputFile, A as PerBrowserMap, z as PerBrowserOption, o as PopupEntrypoint, P as PopupEntrypointOptions, f as ReloadContentScriptPayload, ab as ResolvedBasePublicFile, R as ResolvedConfig, a1 as ResolvedEslintrc, D as ResolvedPerBrowserOptions, aa as ResolvedPublicFile, V as ServerInfo, q as SidepanelEntrypoint, S as SidepanelEntrypointOptions, T as TargetBrowser, g as TargetManifestVersion, y as UnlistedScriptDefinition, F as UserManifest, H as UserManifestFn, Y as Wxt, N as WxtBuilder, Q as WxtBuilderServer, K as WxtCommand, af as WxtDirEntry, ah as WxtDirFileEntry, ag as WxtDirTypeReferenceEntry, b as WxtHooks, a8 as WxtModule, a6 as WxtModuleOptions, a7 as WxtModuleSetup, a9 as WxtModuleWithMetadata, a4 as WxtPackageManager, ae as WxtPlugin, a3 as WxtResolvedUnimportOptions, a2 as WxtUnimportOptions, a as WxtViteConfig } from './index-nWRfwAJi.js';
-import 'vite';
-import 'webextension-polyfill';
-import 'unimport';
-import 'consola';
-import '@aklinker1/rollup-plugin-visualizer';
-import 'chokidar';
-import 'c12';
-import 'hookable';
-import 'nypm';
-
 /**
- * Bundles the extension for production. Returns a promise of the build result. Discovers the `wxt.config.ts` file in
- * the root directory, and merges that config with what is passed in.
- *
- * @example
- * // Use config from `wxt.config.ts`
- * const res = await build()
- *
- * // or override config `from wxt.config.ts`
- * const res = await build({
- *   // Override config...
- * })
+ * @module wxt
  */
-declare function build(config?: InlineConfig): Promise<BuildOutput>;
-
-/**
- * Remove generated/temp files from the directory.
- *
- * @param config Optional config that will override your `<root>/wxt.config.ts`.
- *
- * @example
- * await clean();
- */
-declare function clean(config?: InlineConfig): Promise<void>;
-/**
- * Remove generated/temp files from the directory.
- *
- * @deprecated
- *
- * @param root The directory to look for generated/temp files in. Defaults to `process.cwd()`. Can be relative to `process.cwd()` or absolute.
- *
- * @example
- * await clean();
- */
-declare function clean(root?: string): Promise<void>;
-
-declare function defineConfig(config: UserConfig): UserConfig;
-
-declare function defineRunnerConfig(config: ExtensionRunnerConfig): ExtensionRunnerConfig;
-
-/**
- * Creates a dev server and pre-builds all the files that need to exist before loading the extension.
- *
- * @example
- * const server = await wxt.createServer({
- *   // Enter config...
- * });
- * await server.start();
- */
-declare function createServer(inlineConfig?: InlineConfig): Promise<WxtDevServer>;
-
-declare function initialize(options: {
-    directory: string;
-    template: string;
-    packageManager: string;
-}): Promise<void>;
-
-declare function prepare(config: InlineConfig): Promise<void>;
-
-/**
- * Build and zip the extension for distribution.
- * @param config Optional config that will override your `<root>/wxt.config.ts`.
- * @returns A list of all files included in the ZIP.
- */
-declare function zip(config?: InlineConfig): Promise<string[]>;
-
-var version = "0.18.14";
-
-export { BuildOutput, ExtensionRunnerConfig, InlineConfig, UserConfig, WxtDevServer, build, clean, createServer, defineConfig, defineRunnerConfig, initialize, prepare, version, zip };
+export * from './core';
+export * from './types';
+export * from './version';

package/dist/index.mjs

@@ -0,0 +1,3 @@
+export * from "./core/index.mjs";
+export * from "./types.mjs";
+export * from "./version.mjs";

package/dist/modules.d.ts

@@ -1,21 +1,13 @@
-import { a6 as WxtModuleOptions, a8 as WxtModule, a7 as WxtModuleSetup, Y as Wxt, r as Entrypoint } from './index-nWRfwAJi.js';
-import * as vite from 'vite';
-import { UnimportOptions } from 'unimport';
-import 'webextension-polyfill';
-import 'consola';
-import '@aklinker1/rollup-plugin-visualizer';
-import 'chokidar';
-import 'c12';
-import 'hookable';
-import 'nypm';
-
 /**
  * Utilities for creating reusable, build-time modules for WXT.
  *
  * @module wxt/modules
  */
-
-declare function defineWxtModule<TOptions extends WxtModuleOptions>(module: WxtModule<TOptions> | WxtModuleSetup<TOptions>): WxtModule<TOptions>;
+import type { Entrypoint, Wxt, WxtModule, WxtModuleOptions, WxtModuleSetup } from './types';
+import * as vite from 'vite';
+import type { UnimportOptions } from 'unimport';
+export { WxtModule };
+export declare function defineWxtModule<TOptions extends WxtModuleOptions>(module: WxtModule<TOptions> | WxtModuleSetup<TOptions>): WxtModule<TOptions>;
 /**
  * Adds a TS/JS file as an entrypoint to the project. This file will be bundled
  * along with the other entrypoints.
@@ -39,7 +31,7 @@ declare function defineWxtModule<TOptions extends WxtModuleOptions>(module: WxtM
  *   });
  * });
  */
-declare function addEntrypoint(wxt: Wxt, entrypoint: Entrypoint): void;
+export declare function addEntrypoint(wxt: Wxt, entrypoint: Entrypoint): void;
 /**
  * Copy files inside a directory (as if it were the public directory) into the
  * extension's output directory. The directory itself is not copied, just the
@@ -53,7 +45,7 @@ declare function addEntrypoint(wxt: Wxt, entrypoint: Entrypoint): void;
  *   addPublicAssets(wxt, "./dist/prebundled");
  * });
  */
-declare function addPublicAssets(wxt: Wxt, dir: string): void;
+export declare function addPublicAssets(wxt: Wxt, dir: string): void;
 /**
  * Merge additional vite config for one or more entrypoint "groups" that make
  * up individual builds. Config in the project's `wxt.config.ts` file takes
@@ -72,7 +64,7 @@ declare function addPublicAssets(wxt: Wxt, dir: string): void;
  *   });
  * });
  */
-declare function addViteConfig(wxt: Wxt, viteConfig: (env: vite.ConfigEnv) => vite.UserConfig | undefined): void;
+export declare function addViteConfig(wxt: Wxt, viteConfig: (env: vite.ConfigEnv) => vite.UserConfig | undefined): void;
 /**
  * Add a runtime plugin to the project. In each entrypoint, before executing
  * the `main` function, plugins are executed.
@@ -86,7 +78,7 @@ declare function addViteConfig(wxt: Wxt, viteConfig: (env: vite.ConfigEnv) => vi
  *   addWxtPlugin(wxt, "wxt-module-analytics/client-plugin");
  * });
  */
-declare function addWxtPlugin(wxt: Wxt, plugin: string): void;
+export declare function addWxtPlugin(wxt: Wxt, plugin: string): void;
 /**
  * Add an Unimport preset ([built-in](https://github.com/unjs/unimport?tab=readme-ov-file#built-in-presets),
  * [custom](https://github.com/unjs/unimport?tab=readme-ov-file#custom-presets),
@@ -114,6 +106,4 @@ declare function addWxtPlugin(wxt: Wxt, plugin: string): void;
  *   addImportPreset(wxt, { package: "vue" });
  * });
  */
-declare function addImportPreset(wxt: Wxt, preset: UnimportOptions['presets'][0]): void;
-
-export { WxtModule, addEntrypoint, addImportPreset, addPublicAssets, addViteConfig, addWxtPlugin, defineWxtModule };
+export declare function addImportPreset(wxt: Wxt, preset: UnimportOptions['presets'][0]): void;

package/dist/{chunk-6XSIWUWF.js → modules.mjs}

@@ -1,17 +1,17 @@
-// src/modules.ts
 import * as vite from "vite";
 import glob from "fast-glob";
 import { resolve } from "node:path";
-function defineWxtModule(module) {
+export {};
+export function defineWxtModule(module) {
   if (typeof module === "function") return { setup: module };
   return module;
 }
-function addEntrypoint(wxt, entrypoint) {
+export function addEntrypoint(wxt, entrypoint) {
   wxt.hooks.hook("entrypoints:resolved", (wxt2, entrypoints) => {
     entrypoints.push(entrypoint);
   });
 }
-function addPublicAssets(wxt, dir) {
+export function addPublicAssets(wxt, dir) {
   wxt.hooks.hook("build:publicAssets", async (wxt2, files) => {
     const moreFiles = await glob("**/*", { cwd: dir });
     if (moreFiles.length === 0) {
@@ -23,7 +23,7 @@ function addPublicAssets(wxt, dir) {
     });
   });
 }
-function addViteConfig(wxt, viteConfig) {
+export function addViteConfig(wxt, viteConfig) {
   wxt.hooks.hook("ready", (wxt2) => {
     const userVite = wxt2.config.vite;
     wxt2.config.vite = async (env) => {
@@ -33,12 +33,12 @@ function addViteConfig(wxt, viteConfig) {
     };
   });
 }
-function addWxtPlugin(wxt, plugin) {
+export function addWxtPlugin(wxt, plugin) {
   wxt.hooks.hook("ready", (wxt2) => {
     wxt2.config.plugins.push(plugin);
   });
 }
-function addImportPreset(wxt, preset) {
+export function addImportPreset(wxt, preset) {
   wxt.hooks.hook("ready", (wxt2) => {
     if (!wxt2.config.imports) return;
     wxt2.config.imports.presets ??= [];
@@ -46,12 +46,3 @@ function addImportPreset(wxt, preset) {
     wxt2.config.imports.presets.push(preset);
   });
 }
-
-export {
-  defineWxtModule,
-  addEntrypoint,
-  addPublicAssets,
-  addViteConfig,
-  addWxtPlugin,
-  addImportPreset
-};

package/dist/sandbox/define-app-config.d.ts

@@ -0,0 +1,19 @@
+export interface WxtAppConfig {
+}
+/**
+ * Runtime app config defined in `<srcDir>/app.config.ts`.
+ *
+ * You can add fields to this interface via ["Module Augmentation"](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation):
+ *
+ * ```ts
+ * // app.config.ts
+ * import 'wxt/sandbox';
+ *
+ * declare module "wxt/sandbox" {
+ *   export interface WxtAppConfig {
+ *     analytics: AnalyticsConfig
+ *   }
+ * }
+ * ```
+ */
+export declare function defineAppConfig(config: WxtAppConfig): WxtAppConfig;

package/dist/sandbox/define-app-config.mjs

@@ -0,0 +1,3 @@
+export function defineAppConfig(config) {
+  return config;
+}

package/dist/sandbox/define-background.d.ts

@@ -0,0 +1,3 @@
+import type { BackgroundDefinition } from '../types';
+export declare function defineBackground(main: () => void): BackgroundDefinition;
+export declare function defineBackground(definition: BackgroundDefinition): BackgroundDefinition;

package/dist/sandbox/define-background.mjs

@@ -0,0 +1,4 @@
+export function defineBackground(arg) {
+  if (typeof arg === "function") return { main: arg };
+  return arg;
+}

package/dist/sandbox/define-content-script.d.ts

@@ -0,0 +1,2 @@
+import type { ContentScriptDefinition } from '../types';
+export declare function defineContentScript(definition: ContentScriptDefinition): ContentScriptDefinition;

package/dist/sandbox/define-content-script.mjs

@@ -0,0 +1,3 @@
+export function defineContentScript(definition) {
+  return definition;
+}

package/dist/sandbox/define-unlisted-script.d.ts

@@ -0,0 +1,3 @@
+import type { UnlistedScriptDefinition } from '../types';
+export declare function defineUnlistedScript(main: () => void): UnlistedScriptDefinition;
+export declare function defineUnlistedScript(definition: UnlistedScriptDefinition): UnlistedScriptDefinition;

package/dist/sandbox/define-unlisted-script.mjs

@@ -0,0 +1,4 @@
+export function defineUnlistedScript(arg) {
+  if (typeof arg === "function") return { main: arg };
+  return arg;
+}

package/dist/sandbox/define-wxt-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { WxtPlugin } from '../types';
+export declare function defineWxtPlugin(plugin: WxtPlugin): WxtPlugin;

package/dist/sandbox/define-wxt-plugin.mjs

@@ -0,0 +1,3 @@
+export function defineWxtPlugin(plugin) {
+  return plugin;
+}

package/dist/sandbox/dev-server-websocket.d.ts

@@ -0,0 +1,21 @@
+export interface WxtWebSocket extends WebSocket {
+    addWxtEventListener(type: 'wxt:reload-extension', callback: (event: CustomEvent<undefined>) => void, options?: AddEventListenerOptions | boolean): void;
+    addWxtEventListener(type: 'wxt:reload-content-script', callback?: (event: CustomEvent<ReloadContentScriptPayload>) => void, options?: AddEventListenerOptions | boolean): void;
+    addWxtEventListener(type: 'wxt:reload-page', callback?: (event: CustomEvent<string>) => void, options?: AddEventListenerOptions | boolean): void;
+    sendCustom(event: string, payload?: any): void;
+}
+/**
+ * Connect to the websocket and listen for messages.
+ *
+ * @param onMessage Optional callback that is called when a message is recieved and we've verified
+ *                  it's structure is what we expect.
+ */
+export declare function getDevServerWebSocket(): WxtWebSocket;
+export interface ReloadContentScriptPayload {
+    registration?: 'manifest' | 'runtime';
+    contentScript: {
+        matches: string[];
+        js?: string[];
+        css?: string[];
+    };
+}

package/dist/sandbox/dev-server-websocket.mjs

@@ -0,0 +1,37 @@
+import { logger } from "./utils/logger.mjs";
+let ws;
+export function getDevServerWebSocket() {
+  if (import.meta.env.COMMAND !== "serve")
+    throw Error(
+      "Must be running WXT dev command to connect to call getDevServerWebSocket()"
+    );
+  if (ws == null) {
+    const serverUrl = `${__DEV_SERVER_PROTOCOL__}//${__DEV_SERVER_HOSTNAME__}:${__DEV_SERVER_PORT__}`;
+    logger.debug("Connecting to dev server @", serverUrl);
+    ws = new WebSocket(serverUrl, "vite-hmr");
+    ws.addWxtEventListener = ws.addEventListener.bind(ws);
+    ws.sendCustom = (event, payload) => ws?.send(JSON.stringify({ type: "custom", event, payload }));
+    ws.addEventListener("open", () => {
+      logger.debug("Connected to dev server");
+    });
+    ws.addEventListener("close", () => {
+      logger.debug("Disconnected from dev server");
+    });
+    ws.addEventListener("error", (event) => {
+      logger.error("Failed to connect to dev server", event);
+    });
+    ws.addEventListener("message", (e) => {
+      try {
+        const message = JSON.parse(e.data);
+        if (message.type === "custom") {
+          ws?.dispatchEvent(
+            new CustomEvent(message.event, { detail: message.data })
+          );
+        }
+      } catch (err) {
+        logger.error("Failed to handle message", err);
+      }
+    });
+  }
+  return ws;
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Any runtime APIs that don't use the web extension APIs.
+ *
+ * @module wxt/sandbox
+ */
+export * from './define-unlisted-script';
+export * from './define-background';
+export * from './define-content-script';
+export * from './define-wxt-plugin';
+export * from './define-app-config';
+export * from '@webext-core/match-patterns';

package/dist/sandbox/index.mjs

@@ -0,0 +1,6 @@
+export * from "./define-unlisted-script.mjs";
+export * from "./define-background.mjs";
+export * from "./define-content-script.mjs";
+export * from "./define-wxt-plugin.mjs";
+export * from "./define-app-config.mjs";
+export * from "@webext-core/match-patterns";

package/dist/sandbox/utils/logger.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Wrapper around `console` with a "[wxt]" prefix
+ */
+export declare const logger: {
+    debug: (...args: any[]) => void;
+    log: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};

package/dist/sandbox/utils/logger.mjs

@@ -0,0 +1,15 @@
+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);
+  }
+}
+export const 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)
+};

package/dist/storage.d.ts

@@ -1,5 +1,5 @@
-declare const storage: WxtStorage;
-interface WxtStorage {
+export declare const storage: WxtStorage;
+export interface WxtStorage {
     /**
      * Get an item from storage, or return `null` if it doesn't exist.
      *
@@ -108,8 +108,15 @@ interface WxtStorage {
     defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey): WxtStorageItem<TValue | null, TMetadata>;
     defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(key: StorageItemKey, options: WxtStorageItemOptions<TValue>): WxtStorageItem<TValue, TMetadata>;
 }
-interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+export interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
+    /**
+     * @deprecated Renamed to `fallback`, use it instead.
+     */
     defaultValue: TValue;
+    /**
+     * The value provided by the `fallback` option.
+     */
+    fallback: TValue;
     /**
      * Get the latest value from storage.
      */
@@ -146,15 +153,19 @@ interface WxtStorageItem<TValue, TMetadata extends Record<string, unknown>> {
      */
     migrate(): Promise<void>;
 }
-type StorageArea = 'local' | 'session' | 'sync' | 'managed';
-type StorageItemKey = `${StorageArea}:${string}`;
-interface GetItemOptions<T> {
+export type StorageArea = 'local' | 'session' | 'sync' | 'managed';
+export type StorageItemKey = `${StorageArea}:${string}`;
+export interface GetItemOptions<T> {
     /**
-     * Value returned from `getValue` when it would otherwise return null.
+     * @deprecated Renamed to `fallback`, use it instead.
      */
     defaultValue?: T;
+    /**
+     * Default value returned when `getItem` would otherwise return `null`.
+     */
+    fallback?: T;
 }
-interface RemoveItemOptions {
+export interface RemoveItemOptions {
     /**
      * Optionally remove metadata when deleting a key.
      *
@@ -162,15 +173,29 @@ interface RemoveItemOptions {
      */
     removeMeta?: boolean;
 }
-interface SnapshotOptions {
+export interface SnapshotOptions {
     /**
      * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
      * specific storage area already.
      */
     excludeKeys?: string[];
 }
-interface WxtStorageItemOptions<T> {
-    defaultValue: T;
+export interface WxtStorageItemOptions<T> {
+    /**
+     * @deprecated Renamed to `fallback`, use it instead.
+     */
+    defaultValue?: T;
+    /**
+     * Default value returned when `getValue` would otherwise return `null`.
+     */
+    fallback?: T;
+    /**
+     * If passed, a value in storage will be initialized immediately after
+     * defining the storage item. This function returns the value that will be
+     * saved to storage during the initialization process if a value doesn't
+     * already exist.
+     */
+    init?: () => T | Promise<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.
@@ -185,16 +210,14 @@ interface WxtStorageItemOptions<T> {
  * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
  * nullable.
  */
-type NullablePartial<T> = {
+export type NullablePartial<T> = {
     [key in keyof T]+?: T[key] | undefined | null;
 };
 /**
  * Callback called when a value in storage is changed.
  */
-type WatchCallback<T> = (newValue: T, oldValue: T) => void;
+export type WatchCallback<T> = (newValue: T, oldValue: T) => void;
 /**
  * Call to remove a watch listener
  */
-type Unwatch = () => void;
-
-export { type GetItemOptions, type NullablePartial, type RemoveItemOptions, type SnapshotOptions, type StorageArea, type StorageItemKey, type Unwatch, type WatchCallback, type WxtStorage, type WxtStorageItem, type WxtStorageItemOptions, storage };
+export type Unwatch = () => void;