[FEEDBACK] Why I didn't migrate to wxt

[BingeCode]

I want to share why I didn't make the switch from a vanilla js chrome extension workflow to wxt in the hopes of giving some insights to you, the contributors, from me, a newbie in browser extension development.

I was looking at wxt, because I wanted to use

• Svelte Components, Layouts and a simple hash router with multiple pages
• hot reloading to improve DX
• and it seemed more modern and flexible than Plasmo

I got wxt working with Svelte and even hash routing and was quite proud and excited to continue migrating my large background.js, content.js and popup.js

But there my excitement stopped. The way that wxt/storage is implemented meant too much work for me to make the switch because not only do I need to refactor the code, I also need to learn how wxt/storage is implemented.

Furthermore the documentation was quite lacking. Many places where I was hoping for an answer were still under construction.

Also, the DX wasn't as good as I expected it to be. On new compiles a fresh Chrome instance was opened every time and I was forced to pick a default search engine (even though I did it before already) before I could use the extension. The popup didn't stay open while the dev server was running if I saved the background.ts or content.ts and it didn't seem possible to explicitly set "optional_host_permissions" in the wxt config manifest.

I was hoping I would be able to instantly open the extension in my current default browser, open dev tools for my popup instance and have hot module reloading work regardless of file type (popup.js or background.ts etc.).

In the end I decided to set up Svelte + svelte-hash-router with vite configured such that it builds to dist on every save. This way I only have to manually reload the application in chrome://extensions on every change. But that I could live with. This was less migration work for me to deal with.

Hope this feedback helps!

[aklinker1]

Thank you for taking the time to try out WXT and for writing up your feedback! It's very valuable, and I will be making some changes based on this.

To address some of your comments for anyone else that comes across this:

The way that wxt/storage is implemented meant too much work for me to make the switch because not only do I need to refactor the code, I also need to learn how wxt/storage is implemented.

You don't have to use any of the utils WXT provides, like wxt/storage. They're there if you want to use them. I'll update the docs to make that clear.

If you were using chrome.storage or browser.storage or an NPM package like @webext-core/storage, you can keep doing so. No reason to change working code!

The only change you absolutely have to make is to wrap your entrypoints in a main function.

On new compiles a fresh Chrome instance was opened every time and I was forced to pick a default search engine (even though I did it before already) before I could use the extension.

Yeah, it doesn't persist any data by default, but you can configure it to do so.

Personally, I prefer a fresh profile during development, but this is a very common question, so maybe the majority of devs would prefer I change the default... I'll run a poll in discord and we'll see.

The popup didn't stay open while the dev server was running if I saved the background.ts or content.ts

Yeah, chrome removed the ability to reload the background individually. See #53.

As for changing content scripts... That should keep your popup open. Just checked, and it does for me. So not sure why this was happening to you.

it didn't seem possible to explicitly set "optional_host_permissions" in the wxt config manifest.

It's possible, here's an example showing how to do it:

https://github.com/wxt-dev/examples/blob/main/examples%2Fdynamic-content-scripts%2Fwxt.config.ts#L11

Furthermore the documentation was quite lacking. Many places where I was hoping for an answer were still under construction.

Haha yeah... I just need to buckle down and type all that up. There was another contributor who wanted to help improve the docs, but I haven't heard anything from them in a month...

The fact you couldn't find solutions to some of these issues in the docs tells me they're not good enough, that's for sure.

[aklinker1]

How is the hot module reload implemented, btw? Did it take a lot of work?

Oof, yeah, but mostly because there are lots of edge cases for generic support. You could try and re-implement it with your setup and ignore most those edge cases because they won't be relevant to you.

Basically, unlike normal vite projects, you need to render all the entrypoints to files in your output directory so the extension is "valid" and browsers will load it. With normal vite projects, you load the HTML file over localhost, not directly from the file system.

To do so, you'll need to spin up a dev server and call server.transformIndexHtml on each of your HTML files. You'll also need to add a plugin to transform the URLs of scripts and stylesheets. By default, vite thinks you're loading the HTML files over localhost, so it just lists the paths of these assets ,eg "/chunks/index-af8e741.js", but since you're actually loading the HTML file from "chrome-extension://id/path/to/page.html", you'll get errors like chrome-extension://id/chunks/index-af8e741.js" doesn't exist. So you need a vite plugin that parses the HTML files and adds localhost:5173 to all those URLs.

Here's the plugin WXT uses to do this: https://github.com/wxt-dev/wxt/blob/main/packages/wxt/src/core/builders/vite/plugins/devHtmlPrerender.ts

That's just the rough idea of how to get started...

[BingeCode]

Interesting, thanks for the explanation. I reckon, I could implement something simple for my Vite + Svelte setup. I already have some configs that correctly bundle and map everything to a chrome-compatible output directory. I am just curious as to how I can trigger the reload on the chrome extension to enable hot module reload without the popup closing. What mechanism are you using to tell chrome to reload the directory?

[aklinker1]

I am just curious as to how I can trigger the reload on the chrome extension to enable hot module reload without the popup closing. What mechanism are you using to tell chrome to reload the directory?

For HTML files, the only file that is output is the HTML file itself when HMR is setup - so when a JS file changes, there's no output to reload, because it was loaded from the dev server, not a local file. As long as you load JS, CSS, and other assets from the local dev server, you don't need to manually reload the extension after a JS/CSS change, vite will handle HMR for you. If you change the HTML file, you'll need to rerun it through transformIndexHtml, and just reload the HTML page with location.reload()

For all other entrypoints, WXT bundles the output to a single file (or a single file + single CSS file if there's CSS). So when a file changes, you need to do an analysis of the build output and determine which builds depend on the changed file, and rebuild them.

For content scripts, if you use the scripting APIs to register and load content scripts during development instead of listing them in the manifest, you don't have to reload the extension when a content script is changed, just need to re-register it. Realistically for your simple setup, you should not do this. Instead, keep listing content scripts in your manfiest and just reload the extension (closing the popup) when one is rebuilt. This would be one benefit WXT provides over a DIY solution.

For the background, once again, if a file is changed that the background depends on, it get's rebuilt, and you reload the entire extension (closing the popup).

The actual mechanism for reloading the extension is simple. Custom web socket messages from the dev server.

// Inside your background
if (import.meta.env.DEV) {
  const ws = // setup websocket connection with dev server
  ws.on("reload-extension", () => browser.runtime.reload());
}

// Note, you can't use `import.meta.hot.on` because the background isn't loaded from the server, so you have to setup the websocket connection yourself

Here's WXT's code:

wxt/packages/wxt/src/virtual/background-entrypoint.ts

Lines 9 to 37 in 763dbd5

	if (import.meta.env.COMMAND === 'serve') {
	try {
	const ws = getDevServerWebSocket();
	ws.addWxtEventListener('wxt:reload-extension', () => {
	browser.runtime.reload();
	});
	ws.addWxtEventListener('wxt:reload-content-script', (event) => {
	reloadContentScript(event.detail);
	});
	if (import.meta.env.MANIFEST_VERSION === 3) {
	// Tell the server the background script is loaded and ready to go
	ws.addEventListener('open', () =>
	ws.sendCustom('wxt:background-initialized'),
	);
	// Web Socket will disconnect if the service worker is killed
	keepServiceWorkerAlive();
	}
	} catch (err) {
	logger.error('Failed to setup web socket connection with dev server', err);
	}
	browser.commands.onCommand.addListener((command) => {
	if (command === 'wxt:reload-extension') {
	browser.runtime.reload();
	}
	});
	}

// Inside a vite plugin
server.ws.send("reload-extension")

Here's WXT's code:

wxt/packages/wxt/src/core/create-server.ts

Lines 77 to 85 in 763dbd5

	reloadContentScript(payload) {
	server.ws.send('wxt:reload-content-script', payload);
	},
	reloadPage(path) {
	server.ws.send('wxt:reload-page', path);
	},
	reloadExtension() {
	server.ws.send('wxt:reload-extension');
	},

[aklinker1]

If you're doing all this, it's good to understand how it works, but you're gonna save a lot of time and troubleshooting if you use WXT. Just use the build and dev setup, and ignore all the other features it comes with.

[BingeCode]

That's really interesting, thank you for this explanation!
This might be something you could perhaps include in the documentation under "How Hot Module reloading works in WXT" or something like that.
I will see if I can find the time to contribute later when I have finished my thesis. Seems like an awesome project.

[kdme-designed]

@BingeCode

You cant run your dev server on the actual chrome browser you are using. It does not actually launch a browser but an instance of a chrome webdriver.

To be able to persist your chrome profile when you restart the server, set this on your wxt.config

const { chromeProfilePath, userDataDir, userProfile } = ensureChromeProfile();

export default defineConfig({
  runner: {
    keepProfileChanges: true,
    chromiumProfile: chromeProfilePath,
    chromiumArgs: [
      `--user-data-dir=${userDataDir}`,
      `--user-profile=${userProfile}`,
    ],
  },
});

You need to set the chromeProfile, userDataDir, and userProfile
And the directory to it must exists

Here's a utility function i wrote that does this for me.

import { mkdirSync } from "node:fs";
import { join, resolve } from "node:path";
import { homedir } from "node:os";

interface ChromeVariables {
  userDataDir: string;
  userProfile: string;
  chromeProfilePath: string;
}

const DEFAULT_DATA_DIR = "~/chrome-data";
const DEFAULT_PROFILE = "default";

export function ensureChromeProfile(
  dataDir: string = DEFAULT_DATA_DIR,
  profile: string = DEFAULT_PROFILE,
): ChromeVariables {
  const userDataDir = dataDir.startsWith("~")
    ? join(homedir(), dataDir.slice(1))
    : resolve(dataDir);

  const chromeProfilePath = join(userDataDir, profile);

  try {
    mkdirSync(chromeProfilePath, { recursive: true });
  } catch (error) {
    if (error instanceof Error && "code" in error && error.code !== "EEXIST") {
      console.error(`Failed to create directory: ${chromeProfilePath}`);
      console.error(error);
      throw error;
    }
  }

  return {
    userDataDir,
    userProfile: profile,
    chromeProfilePath,
  };
}

btw i'm using bun so the node std lib are preface with 'node:'

[BingeCode]

@kdme-designed thank you for the code snippets.

I implemented them, but notice no difference. The browser instance does not remember that I pinned the extension in the toolbar for example. What is the use case for you?

[kdme-designed]

what exactly do you need to do on the chrome browser?

Pinning probably does not work because chrome. But it should persist logins and your data. If you want bookmarks you have to add another arg like --enable-features=Bookmarks. If you need another feature you should google the right flag to enable it.

Try this one. maybe you did something different

./wxt.config.ts

import { defineConfig } from "wxt";
import { getChromeProfile } from "./chromeProfile";

const chromeProfile = getChromeProfile();

// See https://wxt.dev/api/config.html
export default defineConfig({
  srcDir: "src",
  manifest: {
    host_permissions: ["<all_urls"],
  },
  runner: {
    startUrls: ["https://www.google.com/"],
    keepProfileChanges: true,
    chromiumProfile: chromeProfile,
    chromiumArgs: ["--start-maximized", "--enable-features=Bookmarks"],
  }
});

./chromeProfile.ts

import { mkdirSync } from "node:fs";
import { homedir } from "node:os";
import { join, resolve } from "node:path";

const DEFAULT_DATA_DIR = "~/chrome-data";
const DEFAULT_PROFILE = "default";

export function getChromeProfile(
  dataDir: string = DEFAULT_DATA_DIR,
  profile: string = DEFAULT_PROFILE,
): string {
  const userDataDir = dataDir.startsWith("~")
    ? join(homedir(), dataDir.slice(1))
    : resolve(dataDir);

  const chromeProfile = join(userDataDir, profile);

  try {
    mkdirSync(chromeProfile, { recursive: true });
  } catch (error) {
    if (error instanceof Error && "code" in error && error.code !== "EEXIST") {
      throw error;
    }
  }

  return chromeProfile;
}

[BingeCode]

I mostly need the browser to remember my login, because I am developing an extension that extends the webpage UI and logic and the webpage is behind a login. Also I am using Brave instead of Chrome.

I found the easiest solution to be to set
runner: { disabled: true, },

and manually load the extension in my browser. HMR and reloads still work and I can work in a familiar browser/environment.
Ideally the wxt init process would prompt for which configuration and set up the config based on that.

[kdme-designed]

There you go. Why are you using brave instead of chrome when your developing an extension? That is going to cause a lot of issues.

But if you are going to disable runner how managable is it? How did you ever got HMR and reloads to work? Do you have to manually load the extension again if you accidentally close the browser or something failed and you have to restart wxt?

[BingeCode]

Brave is based on Chromium just the same as Chrome. So far I have not encountered any differences in development - neither for browser extensions nor for websites/web applications. I just prefer to develop in the familiar environment that I am used to browsing in.

Disabling the runner has barely downsides. You only need to manually load the extension for the first time. Each subsequent update to the code base then automatically propagates to the extension. The only thing I had to manually reload the extension for were new entrypoints added to the code base - but I reckon this is not due to disabling the runner but rather the implementation of wxt.