TypeScript Configuration

When you run wxt prepare, WXT generates a base TSConfig file for your project at <rootDir>/.wxt/tsconfig.json.

At a minimum, you need to create a TSConfig in your root directory that looks like this:

// <rootDir>/tsconfig.json
{
  "extends": ".wxt/tsconfig.json",
}

Or if you're in a monorepo, you may not want to extend the config. If you don't extend it, you need to add .wxt/wxt.d.ts to the TypeScript project:

/// <reference path="./.wxt/wxt.d.ts" />

TSConfig Paths

WXT provides a default set of path aliases.

Alias	To	Example
~~	<rootDir>/*	import "~~/package.json"
@@	<rootDir>/*	import "@@/package.json"
~	<srcDir>/*	import { toLowerCase } from "~/utils/strings"
@	<srcDir>/*	import { toLowerCase } from "@/utils/strings"

To add your own, DO NOT add them to your tsconfig.json! Instead, use the alias option in wxt.config.ts.

This will add your custom aliases to <rootDir>/.wxt/tsconfig.json next time you run wxt prepare. It also adds your alias to the bundler so it can resolve imports.

import { resolve } from 'node:path';

export default defineConfig({
  alias: {
    // Directory:
    testing: resolve('utils/testing'),
    // File:
    strings: resolve('utils/strings.ts'),
  },
});

import { fakeTab } from 'testing/fake-objects';
import { toLowerCase } from 'strings';

Custom Options

To specify custom compiler or top-level options, you have two options:

1. Override WXT's value completely by setting it in your root tsconfig.json:

   // <rootDir>/tsconfig.json
   {
     "extends": ".wxt/tsconfig.json",
     "compilerOptions": {
       "jsx": "preserve",
     },
   }

2. Merge custom values into values generated by WXT via the prepare:tsconfig hook:

   // wxt.config.ts
   export default defineConfig({
     hooks: {
       'prepare:tsconfig': (wxt, { tsconfig }) => {
         tsconfig.compilerOptions.lib.push('WebWorker');
       },
     },
   });

Overriding is great for simple boolean values, but not for complex options like paths or libs, where you can't just "add" a value to the object from your tsconfig.json file. So WXT provides the hook that let's you add or merge or delete or do whatever you want to the config file before it's written to the .wxt/ directory.