# Build a browser extension that makes flashcards In this tutorial you build a browser extension that sends the text you select on any page to Anki. Select a sentence and a small export button appears beside it; one click and the card is in your collection with a link back to the page. The toolbar popup does the same with an editable card and a deck list. It uses [WXT](https://wxt.dev) for the extension, [Base UI](https://base-ui.com) for the interface, and the [TypeScript SDK](https://ankinize.com/docs/sdk) for the Ankinize API, so it works with Anki closed and syncs to every device. ## What you will build Three parts. A **selection widget** is a round export button that appears beside any text you select; clicking it adds a card to your starting deck. A **background script** sends the card to Ankinize. The **popup** opens from the toolbar, reads the selection of the current tab, and shows a form with the front, an optional back, a link switch and a deck list. The **options page** stores your server, your API key and a starting deck. The cards are **Basic** notes, so `fields` has two keys, `front` and `back`. The finished project, with every file and a `README`, is in the [ankinize-examples](https://github.com/0x0501/ankinize-examples/tree/main/browser-extension) repository. Each step below shows a file from it, unchanged. - **Bun** and a Chromium browser (or Firefox). - An Ankinize account with an API key that has the `write` scope, from *API Keys & Devices*. Make a key for this extension alone. - At least one deck in your collection. ## Build it 1. Create the project WXT scaffolds the extension. Choose the React template, then add the SDK and Base UI. Base UI ships components with behaviour and accessibility but no styles, which suits an extension: you write the few rules you need and nothing else is bundled. `web-ext` is what lets `bun run dev` open the browser for you; without it WXT only prints where the build is. Terminal ``` bunx wxt@latest init ankinize-clip --template react cd ankinize-clip bun add @ankinize/sdk @base-ui/react bun add -d web-ext ``` This tutorial keeps the code under `src/` (the `srcDir` option in the config, step 2). A WXT project finds its pages in `src/entrypoints`: a folder with an `index.html` named `popup` becomes the toolbar popup, and one named `options` the settings page. WXT writes the manifest from them, so you only declare what they cannot say. 2. Declare the permissions `activeTab` with `scripting` lets the popup read the selection of the tab you are on when you open the popup, and only that tab. The widget is a content script, which the manifest lists from its `matches` in the next steps; it needs no permission of its own. `host_permissions` names the Ankinize server, which lets the popup call it without CORS. The optional permission is for self-hosters: the options page asks for your own server's origin when you save. wxt.config.ts ``` import { defineConfig } from "wxt"; export default defineConfig({ srcDir: "src", modules: ["@wxt-dev/module-react"], manifest: { name: "Ankinize: selection to flashcard", description: "Select text on any page and add it to your Anki as a Basic card through Ankinize.", // activeTab + scripting read the selection when you open the popup, so the // extension needs no access to every page. permissions: ["activeTab", "scripting", "storage"], host_permissions: ["https://ankinize.com/*"], // The options page asks for your own server's origin when you self-host. optional_host_permissions: ["https://*/*", "http://*/*"], }, }); ``` 3. Store the settings WXT's `storage` wraps the extension storage with types and a fallback. Using the `local:` area keeps the key on this device and out of Chrome sync. src/lib/settings.ts ``` import { storage } from "wxt/utils/storage"; export interface Settings { /** Where Ankinize runs: https://ankinize.com, or your own server. */ baseUrl: string; /** An API key with the `write` scope. */ apiKey: string; /** The deck the popup starts on. */ deck: string; } export const DEFAULT_BASE_URL = "https://ankinize.com"; const settings = storage.defineItem("local:settings", { fallback: { baseUrl: DEFAULT_BASE_URL, apiKey: "", deck: "Default" }, }); export const getSettings = () => settings.getValue(); export const saveSettings = (value: Settings) => settings.setValue(value); ``` 4. Read the selection When the popup opens, run a one-line function in the active tab and return `window.getSelection()`. A page's own scripts never see the API key, because the key only ever lives in the popup. Pages that cannot be scripted (the browser's own settings pages, the web store) throw, so the popup falls back to an empty selection and you can type the card by hand. src/lib/selection.ts ``` import { browser } from "wxt/browser"; export interface PageSelection { text: string; title: string; url: string; } /** * Reads what is selected in the active tab. Opening the popup grants * `activeTab` for that tab, which is what lets `executeScript` run there. */ export async function readSelection(): Promise { const [tab] = await browser.tabs.query({ active: true, currentWindow: true }); const page = { title: tab?.title ?? "", url: tab?.url ?? "" }; if (tab?.id === undefined) return { text: "", ...page }; try { const [result] = await browser.scripting.executeScript({ target: { tabId: tab.id }, func: () => window.getSelection()?.toString() ?? "", }); return { text: String(result?.result ?? "").trim(), ...page }; } catch { // Pages such as chrome:// and the web store cannot be scripted. return { text: "", ...page }; } } ``` 5. Turn text into card fields A note's `fields` are an object keyed by each field's name in camelCase, so Basic's `Front` and `Back` are `front` and `back`. Card fields hold **HTML**, and a selection or a page title can contain markup, so everything is escaped before it goes in, and only `http(s)` addresses become links. Keeping this in its own module makes it easy to test. src/lib/card.ts ``` export interface CardInput { front: string; back: string; /** Add a link to the page the text came from, under the back. */ source?: { title: string; url: string }; } /** Card fields hold HTML, and a selection or a page title can contain markup. */ export const escapeHtml = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`); /** Plain text to field HTML: escaped, with line breaks kept. */ export const toHtml = (text: string) => escapeHtml(text.trim()).replace(/\r?\n/g, "
"); /** Only web links become links; javascript: and the like stay plain text. */ function sourceLink({ title, url }: { title: string; url: string }) { const label = escapeHtml(title || url); return /^https?:/i.test(url) ? `${label}` : label; } /** The `fields` of a Basic note: its keys are the field names in camelCase. */ export function basicFields({ front, back, source }: CardInput) { const parts = [toHtml(back)]; if (source) parts.push(sourceLink(source)); return { front: toHtml(front), back: parts.filter(Boolean).join("

"), }; } ``` 6. Make the form controls with Base UI `Field` connects a label, a hint and an error message to its control, and `Field.Control` renders a textarea when you pass one to `render`. `Select` gives a keyboard-driven list with a trigger, a popup and items, and you style them through the class names and `data-*` attributes it sets, such as `data-highlighted`. The stylesheet is in the [repository](https://github.com/0x0501/ankinize-examples/tree/main/browser-extension/src/ui/styles.css). src/ui/Field.tsx ``` import { Field } from "@base-ui/react/field"; import type { ReactNode } from "react"; interface TextFieldProps { label: string; hint?: ReactNode; /** Render a textarea instead of a single-line input. */ multiline?: boolean; name: string; value: string; onValueChange: (value: string) => void; type?: "text" | "password" | "url"; required?: boolean; placeholder?: string; } /** * A labelled text control. Base UI's Field wires the label, the hint and the * validation message to the control, so we only style it. */ export function TextField({ label, hint, multiline, onValueChange, ...control }: TextFieldProps) { return ( {label} : undefined} onValueChange={onValueChange} {...control} /> {hint ? ( {hint} ) : null} This is required. ); } ``` src/ui/DeckSelect.tsx ``` import { Field } from "@base-ui/react/field"; import { Select } from "@base-ui/react/select"; interface DeckSelectProps { decks: string[]; value: string; onValueChange: (deck: string) => void; } export function DeckSelect({ decks, value, onValueChange }: DeckSelectProps) { return ( ({ label: deck, value: deck }))} value={value} onValueChange={(deck) => deck && onValueChange(deck)} > Deck ▾ {decks.map((deck) => ( ✓ {deck} ))} ); } ``` 7. Write the options page A form with three fields. When the server is not `ankinize.com`, saving first asks the browser for access to that origin. The request has to start from the click, so it comes before anything else in the handler. Base UI's `Form` checks the required fields before it calls you. src/entrypoints/options/App.tsx ``` import { Button } from "@base-ui/react/button"; import { Form } from "@base-ui/react/form"; import { useEffect, useState } from "react"; import { browser } from "wxt/browser"; import { DEFAULT_BASE_URL, getSettings, saveSettings } from "@/lib/settings"; import { TextField } from "@/ui/Field"; export function App() { const [baseUrl, setBaseUrl] = useState(DEFAULT_BASE_URL); const [apiKey, setApiKey] = useState(""); const [deck, setDeck] = useState(""); const [message, setMessage] = useState(""); useEffect(() => { getSettings().then((saved) => { setBaseUrl(saved.baseUrl); setApiKey(saved.apiKey); setDeck(saved.deck); }); }, []); async function save() { const origin = new URL(baseUrl).origin; // A server of your own needs its origin granted once; ankinize.com already // is. This must run straight from the click, so it comes first. if (origin !== DEFAULT_BASE_URL) { const granted = await browser.permissions.request({ origins: [`${origin}/*`], }); if (!granted) return setMessage("Access to that server was not granted."); } await saveSettings({ baseUrl: origin, apiKey: apiKey.trim(), deck }); setMessage("Saved."); } return (

Ankinize settings

void save()} >

{message}

); } ``` 8. Send the card to Ankinize One function adds a Basic card, and the popup and the widget both use it. The `idempotencyKey` makes a double click or a retry safe: the second request returns the first answer instead of adding another card. Errors from the API arrive as an `AnkinizeError` with a readable message, such as a deck that does not exist or a key without the write scope. src/lib/export.ts ``` import { AnkinizeError, createNote } from "@ankinize/sdk"; import { useServer } from "./api"; import { basicFields, type CardInput } from "./card"; import type { Settings } from "./settings"; /** Adds one Basic card to `deck`. Throws an `AnkinizeError` the API refuses. */ export async function addCard( settings: Settings, { deck, ...card }: CardInput & { deck: string }, ) { useServer(settings); await createNote({ notetypeName: "Basic", deckName: deck, fields: basicFields(card), tags: ["from-browser"], // A retry of this same click must not add the card twice. idempotencyKey: crypto.randomUUID(), }); } /** A message a person can read, for whatever went wrong. */ export function describeError(error: unknown) { if (error instanceof AnkinizeError) return error.message; return error instanceof Error ? error.message : "The card was not added."; } ``` 9. Add the background script A page's scripts must never see your API key, and a content script's requests are subject to the page's CORS rules, so the widget cannot call the API itself. It sends the selection to the extension's service worker, which holds the key and has the host permission, and answers with the result. Returning `true` from the listener keeps the channel open for that later answer. src/entrypoints/background.ts ``` import { browser } from "wxt/browser"; import { defineBackground } from "wxt/utils/define-background"; import { addCard, describeError } from "@/lib/export"; import { type ExportRequest, type ExportResponse, isExportRequest, } from "@/lib/messages"; import { getSettings } from "@/lib/settings"; /** * The page widget cannot call the API itself: a content script's requests are * subject to the page's CORS rules, and the key must stay out of pages. So it * asks this service worker, which holds the key and has the host permission. */ async function exportSelection( request: ExportRequest, ): Promise { const settings = await getSettings(); if (!settings.apiKey) { await browser.runtime.openOptionsPage(); return { ok: false, message: "Add your API key in the settings first." }; } try { await addCard(settings, { front: request.text, back: "", deck: settings.deck, source: { title: request.title, url: request.url }, }); return { ok: true, deck: settings.deck }; } catch (error) { return { ok: false, message: describeError(error) }; } } export default defineBackground(() => { browser.runtime.onMessage.addListener((message, _sender, sendResponse) => { if (!isExportRequest(message)) return; exportSelection(message).then(sendResponse); return true; // the answer comes later }); }); ``` The message types are the small `src/lib/messages.ts` in the repository. 10. Add the selection widget A content script runs inside pages. `createShadowRootUi` mounts our React tree in a shadow root, and `cssInjectionMode: "ui"` puts the stylesheet inside it, so the page cannot restyle the button and the button cannot leak styles into the page. Matching `` means the script is loaded on every page, so it only watches for a selection and reads nothing else. src/entrypoints/selection-widget.content/index.tsx ``` import { createRoot } from "react-dom/client"; import { defineContentScript } from "wxt/utils/define-content-script"; import { createShadowRootUi } from "wxt/utils/content-script-ui/shadow-root"; import "./style.css"; import { SelectionWidget } from "./SelectionWidget"; export default defineContentScript({ matches: [""], // Put the stylesheet inside the shadow root, so the page cannot restyle the // widget and the widget cannot leak styles into the page. cssInjectionMode: "ui", async main(ctx) { const ui = await createShadowRootUi(ctx, { name: "ankinize-selection-widget", position: "inline", anchor: "body", onMount(container) { const root = createRoot(container); root.render(); return root; }, onRemove(root) { root?.unmount(); }, }); ui.mount(); }, }); ``` The widget shows the button after you finish a selection (on mouse up or a key up), puts it under the end of the selection, and hides it when the selection clears. Pressing the button does not clear the selection, because the container cancels `mousedown`. The button is Base UI's `Button`, a plain ` {current && current.state !== "busy" ? current.message : ""} ); } function Icon({ state }: { state: Result["state"] | undefined }) { const path = state === "done" ? "M5 12.5l4.5 4.5L19 7.5" // check : state === "error" ? "M6 6l12 12M18 6L6 18" // cross : "M12 4v11m0 0l-4-4m4 4l4-4M5 19h14"; // arrow into a tray return ( ); } ``` 11. Write the popup On open it loads the settings and the selection together, then lists your decks with `listDecks`. Pressing *Add card* calls `addCard` with the front and back you edited and the deck you chose. Use the popup when you want to reword the card or pick another deck; use the widget when the selection is already the card. src/entrypoints/popup/App.tsx ``` import { listDecks } from "@ankinize/sdk"; import { Button } from "@base-ui/react/button"; import { Checkbox } from "@base-ui/react/checkbox"; import { useEffect, useState } from "react"; import { browser } from "wxt/browser"; import { useServer } from "@/lib/api"; import { addCard, describeError } from "@/lib/export"; import { type PageSelection, readSelection } from "@/lib/selection"; import { getSettings, type Settings } from "@/lib/settings"; import { DeckSelect } from "@/ui/DeckSelect"; import { TextField } from "@/ui/Field"; type Status = | { tone: "idle" } | { tone: "busy" } | { tone: "done"; deck: string } | { tone: "error"; message: string }; export function App() { const [settings, setSettings] = useState(); const [page, setPage] = useState(); const [decks, setDecks] = useState([]); const [front, setFront] = useState(""); const [back, setBack] = useState(""); const [deck, setDeck] = useState(""); const [withLink, setWithLink] = useState(true); const [status, setStatus] = useState({ tone: "idle" }); useEffect(() => { (async () => { const [saved, selection] = await Promise.all([ getSettings(), readSelection(), ]); setSettings(saved); setPage(selection); setFront(selection.text); setDeck(saved.deck); if (!saved.apiKey) return; useServer(saved); try { const { decks } = await listDecks(); const names = decks.map((d) => d.name).sort(); setDecks(names); // Keep the saved deck if it still exists, else start on the first. setDeck((current) => names.includes(current) ? current : (names[0] ?? ""), ); } catch (error) { setStatus({ tone: "error", message: describeError(error) }); } })(); }, []); if (!settings || !page) return
; if (!settings.apiKey) { return (

Connect Ankinize

Add your API key to start making cards.

); } async function add() { if (!page || !settings) return; setStatus({ tone: "busy" }); try { await addCard(settings, { front, back, deck, source: withLink ? page : undefined, }); setStatus({ tone: "done", deck }); } catch (error) { setStatus({ tone: "error", message: describeError(error) }); } } const done = status.tone === "done"; return (

Add to Anki

{ event.preventDefault(); void add(); }} >
✓

{status.tone === "done" && `Added to ${status.deck}. It syncs to your devices.`} {status.tone === "error" && status.message}

); } ``` The popup's `main.tsx`, the two `index.html` files and `src/lib/api.ts` (which points the SDK at the saved server) are a few lines each; copy them from the repository. 12. Run it `bun run dev` opens a browser with the extension loaded and reloads it as you edit. Open the settings from the extension's menu, enter your key, select some text on a page and click the export button beside it (reload tabs that were open before you installed the extension). The card appears in your collection at once, and on your other devices at their next sync. The toolbar popup works too. Terminal ``` bun run dev # Chrome, with live reload bun run dev:firefox # the same in Firefox bun run build # .output/chrome-mv3, for "Load unpacked" bun run zip # a package for the store ``` > Use a key made for the extension > > A key in an extension can write to your whole collection. Make a separate key with the `write` scope so you can revoke it alone, and never publish an extension with a key built in: each user enters their own in the options page. ## Make it your own - **Other note types.** Use `getNoteType` to list a type's field keys, then change `notetypeName` and `fields` to match. - **A right-click menu.** Add the `contextMenus` permission and a background script that calls `createNote` straight from the selection. - **Check for duplicates.** Before adding, search with `listNotes` and a `q` built with `q.field` to see whether the front already exists. ## Next Let an agent do the choosing: [AI agents and Ankinize](https://ankinize.com/docs/agents). Every endpoint is in the [API reference](https://ankinize.com/docs/api).