Example using Svelte 5 runes for state management (#21)

oliverturner · 42willow · web-flow · commit da6c72d440ed · 2025-06-04T07:33:47.000-05:00
Co-authored-by: willow &lt;42willow@pm.me&gt;
diff --git a/examples/svelte-state-rune/README.md b/examples/svelte-state-rune/README.md
@@ -0,0 +1,20 @@
+---
+name: Svelte State Rune
+description: A uses a state rune with WXT's storage to enable clean subscriptions in Svelte (and TS) as well as persisting state.
+---
+
+```sh
+npm install
+npm run dev
+```
+
+Demonstrates how the browser.storage API allows different parts of the extension share state and reflect activity on the current page.
+
+- The page fires a "counter:updated" event every second.
+- The Content Script handles these events by pushing the event payload into session storage.
+- The CounterState class watches the store and updates its reactive state property on change
+- App.svelte reflects the value of `counterState.state`
+
+Open dev tools or the extension service worker logs, click the extension's action icon and watch the events being fired by the active page update the counter.
+
+When closing and re-opening the Popup, the state is persisted.
diff --git a/examples/svelte-state-rune/index.html b/examples/svelte-state-rune/index.html
@@ -0,0 +1,24 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Document</title>
+  </head>
+  <body>
+    <h1>Emit events</h1>
+
+    <script>
+      let counter = 0;
+      setInterval(() => {
+        document.dispatchEvent(
+          new CustomEvent("counter:updated", {
+            detail: {
+              counter: counter++,
+            },
+          })
+        );
+      }, 1000);
+    </script>
+  </body>
+</html>
diff --git a/examples/svelte-state-rune/package.json b/examples/svelte-state-rune/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "svelte-state-rune",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "wxt",
+    "dev:firefox": "wxt -b firefox",
+    "build": "wxt build",
+    "build:firefox": "wxt build -b firefox",
+    "zip": "wxt zip",
+    "zip:firefox": "wxt zip -b firefox",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "postinstall": "wxt prepare"
+  },
+  "devDependencies": {
+    "@tsconfig/svelte": "^5.0.4",
+    "@wxt-dev/module-svelte": "^2.0.3",
+    "svelte": "^5.28.2",
+    "svelte-check": "^4.1.6",
+    "tslib": "^2.7.0",
+    "typescript": "^5.8.2",
+    "vite": "6.3.3",
+    "wxt": "^0.20.5"
+  }
+}
diff --git a/examples/svelte-state-rune/public/icon/128.png b/examples/svelte-state-rune/public/icon/128.png
diff --git a/examples/svelte-state-rune/public/icon/16.png b/examples/svelte-state-rune/public/icon/16.png
diff --git a/examples/svelte-state-rune/public/icon/32.png b/examples/svelte-state-rune/public/icon/32.png
diff --git a/examples/svelte-state-rune/public/icon/48.png b/examples/svelte-state-rune/public/icon/48.png
diff --git a/examples/svelte-state-rune/public/icon/96.png b/examples/svelte-state-rune/public/icon/96.png
diff --git a/examples/svelte-state-rune/public/wxt.svg b/examples/svelte-state-rune/public/wxt.svg
@@ -0,0 +1,15 @@
+<svg width="72" height="72" viewBox="0 0 72 72" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_305_516)">
+<g clip-path="url(#clip1_305_516)">
+<path d="M49.0229 69.1875C54.1272 69.1875 58.265 65.0497 58.265 59.9454V50.7033H59.9454C65.0497 50.7033 69.1875 46.5655 69.1875 41.4612C69.1875 36.357 65.0497 32.2191 59.9454 32.2191H58.265V22.9771C58.265 17.8728 54.1272 13.735 49.0229 13.735H39.7809V12.0546C39.7809 6.95032 35.643 2.8125 30.5388 2.8125C25.4345 2.8125 21.2967 6.95032 21.2967 12.0546V13.735H12.0546C6.95032 13.735 2.8125 17.8728 2.8125 22.9771V32.2191H4.49288C9.59714 32.2191 13.735 36.357 13.735 41.4612C13.735 46.5655 9.59714 50.7033 4.49288 50.7033H2.8125V69.1875H21.2967V67.5071C21.2967 62.4029 25.4345 58.265 30.5388 58.265C35.643 58.265 39.7809 62.4029 39.7809 67.5071V69.1875H49.0229Z" stroke="#67D55E" stroke-width="5.625"/>
+</g>
+</g>
+<defs>
+<clipPath id="clip0_305_516">
+<rect width="72" height="72" fill="white"/>
+</clipPath>
+<clipPath id="clip1_305_516">
+<rect width="72" height="72" fill="white"/>
+</clipPath>
+</defs>
+</svg>
diff --git a/examples/svelte-state-rune/src/assets/svelte.svg b/examples/svelte-state-rune/src/assets/svelte.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="26.6" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 308"><path fill="#FF3E00" d="M239.682 40.707C211.113-.182 154.69-12.301 113.895 13.69L42.247 59.356a82.198 82.198 0 0 0-37.135 55.056a86.566 86.566 0 0 0 8.536 55.576a82.425 82.425 0 0 0-12.296 30.719a87.596 87.596 0 0 0 14.964 66.244c28.574 40.893 84.997 53.007 125.787 27.016l71.648-45.664a82.182 82.182 0 0 0 37.135-55.057a86.601 86.601 0 0 0-8.53-55.577a82.409 82.409 0 0 0 12.29-30.718a87.573 87.573 0 0 0-14.963-66.244"></path><path fill="#FFF" d="M106.889 270.841c-23.102 6.007-47.497-3.036-61.103-22.648a52.685 52.685 0 0 1-9.003-39.85a49.978 49.978 0 0 1 1.713-6.693l1.35-4.115l3.671 2.697a92.447 92.447 0 0 0 28.036 14.007l2.663.808l-.245 2.659a16.067 16.067 0 0 0 2.89 10.656a17.143 17.143 0 0 0 18.397 6.828a15.786 15.786 0 0 0 4.403-1.935l71.67-45.672a14.922 14.922 0 0 0 6.734-9.977a15.923 15.923 0 0 0-2.713-12.011a17.156 17.156 0 0 0-18.404-6.832a15.78 15.78 0 0 0-4.396 1.933l-27.35 17.434a52.298 52.298 0 0 1-14.553 6.391c-23.101 6.007-47.497-3.036-61.101-22.649a52.681 52.681 0 0 1-9.004-39.849a49.428 49.428 0 0 1 22.34-33.114l71.664-45.677a52.218 52.218 0 0 1 14.563-6.398c23.101-6.007 47.497 3.036 61.101 22.648a52.685 52.685 0 0 1 9.004 39.85a50.559 50.559 0 0 1-1.713 6.692l-1.35 4.116l-3.67-2.693a92.373 92.373 0 0 0-28.037-14.013l-2.664-.809l.246-2.658a16.099 16.099 0 0 0-2.89-10.656a17.143 17.143 0 0 0-18.398-6.828a15.786 15.786 0 0 0-4.402 1.935l-71.67 45.674a14.898 14.898 0 0 0-6.73 9.975a15.9 15.9 0 0 0 2.709 12.012a17.156 17.156 0 0 0 18.404 6.832a15.841 15.841 0 0 0 4.402-1.935l27.345-17.427a52.147 52.147 0 0 1 14.552-6.397c23.101-6.006 47.497 3.037 61.102 22.65a52.681 52.681 0 0 1 9.003 39.848a49.453 49.453 0 0 1-22.34 33.12l-71.664 45.673a52.218 52.218 0 0 1-14.563 6.398"></path></svg>
diff --git a/examples/svelte-state-rune/src/entrypoints/background.ts b/examples/svelte-state-rune/src/entrypoints/background.ts
@@ -0,0 +1,7 @@
+export default defineBackground(() => {
+  // Set the access level so `browser.storage.session` is defined and availble
+  // in content scripts: https://developer.chrome.com/docs/extensions/reference/api/storage#storage_areas
+  void browser.storage.session.setAccessLevel?.({
+    accessLevel: "TRUSTED_AND_UNTRUSTED_CONTEXTS",
+  });
+});
diff --git a/examples/svelte-state-rune/src/entrypoints/content.ts b/examples/svelte-state-rune/src/entrypoints/content.ts
@@ -0,0 +1,11 @@
+import { counterStore } from "@/lib/counter-store";
+
+export default defineContentScript({
+  matches: ["http://localhost/*"],
+
+  main() {
+    document.addEventListener("counter:updated", (event) => {
+      void counterStore.setValue(event.detail);
+    });
+  },
+});
diff --git a/examples/svelte-state-rune/src/entrypoints/popup/App.svelte b/examples/svelte-state-rune/src/entrypoints/popup/App.svelte
@@ -0,0 +1,22 @@
+<script lang="ts">
+  import svelteLogo from "../../assets/svelte.svg";
+  import { counterState } from "@/lib/counter-state.svelte";
+</script>
+
+<main class="app">
+  <div>
+    <a href="https://wxt.dev" target="_blank" rel="noreferrer">
+      <img src="/wxt.svg" class="logo" alt="WXT Logo" />
+    </a>
+    <a href="https://svelte.dev" target="_blank" rel="noreferrer">
+      <img src={svelteLogo} class="logo svelte" alt="Svelte Logo" />
+    </a>
+  </div>
+  <h1>WXT + Svelte</h1>
+
+  <div class="card">
+    <p>{counterState.state.counter}</p>
+  </div>
+
+  <p class="read-the-docs">Click on the WXT and Svelte logos to learn more</p>
+</main>
diff --git a/examples/svelte-state-rune/src/entrypoints/popup/app.css b/examples/svelte-state-rune/src/entrypoints/popup/app.css
@@ -0,0 +1,53 @@
+:root {
+  font-family: Inter, system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+.app {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+
+  &:hover {
+    filter: drop-shadow(0 0 2em #54bc4ae0);
+  }
+
+  &.svelte:hover {
+    filter: drop-shadow(0 0 2em #ff3e00aa);
+  }
+}
+
+.read-the-docs {
+  color: #888;
+}
+
+.card {
+  font-size: 2rem;
+}
diff --git a/examples/svelte-state-rune/src/entrypoints/popup/index.html b/examples/svelte-state-rune/src/entrypoints/popup/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Default Popup Title</title>
+    <meta name="manifest.type" content="browser_action" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>
diff --git a/examples/svelte-state-rune/src/entrypoints/popup/main.ts b/examples/svelte-state-rune/src/entrypoints/popup/main.ts
@@ -0,0 +1,10 @@
+import { mount } from "svelte";
+
+import "./app.css";
+import App from "./App.svelte";
+
+const app = mount(App, {
+  target: document.getElementById("app")!,
+});
+
+export default app;
diff --git a/examples/svelte-state-rune/src/lib/counter-state.svelte.ts b/examples/svelte-state-rune/src/lib/counter-state.svelte.ts
@@ -0,0 +1,16 @@
+import { counterStore } from "./counter-store.ts";
+
+class CounterState {
+  state = $state(counterStore.fallback);
+
+  constructor() {
+    counterStore.getValue().then(this.updateCounter);
+    counterStore.watch(this.updateCounter);
+  }
+
+  updateCounter = (newState: { counter: number } | null) => {
+    this.state = newState ?? counterStore.fallback;
+  };
+}
+
+export const counterState = new CounterState();
diff --git a/examples/svelte-state-rune/src/lib/counter-store.ts b/examples/svelte-state-rune/src/lib/counter-store.ts
@@ -0,0 +1,6 @@
+export const counterStore = storage.defineItem<{ counter: number }>(
+  "session:counter",
+  {
+    fallback: { counter: 0 }
+  }
+);
diff --git a/examples/svelte-state-rune/src/typings/example.d.ts b/examples/svelte-state-rune/src/typings/example.d.ts
@@ -0,0 +1,3 @@
+export type CounterEvent = CustomEvent<{
+  counter: number;
+}>;
diff --git a/examples/svelte-state-rune/src/typings/globals.ts b/examples/svelte-state-rune/src/typings/globals.ts
@@ -0,0 +1,7 @@
+import type { CounterEvent } from "./example.d.ts";
+
+declare global {
+  interface DocumentEventMap {
+    "counter:updated": CounterEvent;
+  }
+}
diff --git a/examples/svelte-state-rune/tsconfig.json b/examples/svelte-state-rune/tsconfig.json
@@ -0,0 +1,7 @@
+{
+  "extends": "./.wxt/tsconfig.json",
+  "compilerOptions": {
+    "useDefineForClassFields": true,
+    "allowImportingTsExtensions": true
+  }
+}
diff --git a/examples/svelte-state-rune/wxt-env.d.ts b/examples/svelte-state-rune/wxt-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="svelte" />
diff --git a/examples/svelte-state-rune/wxt.config.ts b/examples/svelte-state-rune/wxt.config.ts
@@ -0,0 +1,13 @@
+import { defineConfig } from "wxt";
+
+// See https://wxt.dev/api/config.html
+export default defineConfig({
+  srcDir: "src",
+  modules: ["@wxt-dev/module-svelte"],
+  manifest: {
+    permissions: ["storage"],
+  },
+  webExt: {
+    startUrls: ["http://localhost:3000"],
+  },
+});
diff --git a/metadata.json b/metadata.json
@@ -297,6 +297,24 @@
         "storage"
       ]
     },
+    {
+      "name": "Svelte State Rune",
+      "description": "A uses a state rune with WXT's storage to enable clean subscriptions in Svelte (and TS) as well as persisting state.",
+      "searchText": "Svelte State Rune|A uses a state rune with WXT's storage to enable clean subscriptions in Svelte (and TS) as well as persisting state.|@wxt-dev/module-svelte|svelte|vite|storage|browser.storage.session.setAccessLevel|browser.storage.session",
+      "url": "https://github.com/wxt-dev/examples/tree/main/examples/svelte-state-rune",
+      "apis": [
+        "browser.storage.session.setAccessLevel",
+        "browser.storage.session"
+      ],
+      "packages": [
+        "@wxt-dev/module-svelte",
+        "svelte",
+        "vite"
+      ],
+      "permissions": [
+        "storage"
+      ]
+    },
     {
       "name": "TailwindCSS",
       "description": "Add TailwindCSS to your extension.",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
