DEV Community: Dennis kinuthia

Setting up vector search for github starred repos

Dennis kinuthia — Wed, 30 Sep 2026 17:37:38 +0000

Ask the starred-repo corpus questions in natural language: embed the query on-device, rank the stored vectors, and show the matching repos in the TanStack Start UI.

This is where the earlier chapters pay off. Auth (chapter 2) got us a GitHub token, the worker (chapter 3) turned stars into vectors, the bus (chapter 4) kept the UI honest while it ran, and now a search box turns a sentence into a ranked list.

One query, end to end

 "graph databases in Rust"
        |
        |  600 ms debounce, ?q= in the URL
        v
 useQuery -> Eden: GET /api/elysia/enrich/starred/search?q=...
        |
        v
 Elysia route (TypeBox: 1..2000 chars)
        |
        v
 embedQuery(text)  -- EmbeddingGemma 300M, query prompt
        |             ONNX Runtime (onnxruntime-node, CPU), Q4 weights
        v
 Float32Array(768)
        |
        v
 PGlite + pgvector:  ORDER BY embedding <=> $query  LIMIT 50
        |
        v
 rows (no vector blob) -> list of repo links

Everything below the Elysia route runs inside the desktop app's Deno process. No request leaves the machine.

The model: EmbeddingGemma

EmbeddingGemma is Google's 308M-parameter embedding model built on Gemma 3, designed for phones and laptops. The properties that matter here:

768-dimensional vectors. The size can be cut down to 512, 256, or 128 through Matryoshka representation learning. We keep 768.
2K-token context, which is roomy for a repo's metadata plus the top of its README (chapter 3).
100+ languages, so non-English READMEs and queries still land.
Small when quantized. Google quotes under 200 MB of RAM with quantization.
Fully offline once the weights are on disk.

We run the onnx-community/embeddinggemma-300m-ONNX export through @kessler/gemma-embedding, a small wrapper over Transformers.js that uses native onnxruntime-node in Node-compatible runtimes. Our own package, packages/gemma-embedding, adds a shared instance, quantization switching, download progress, and cache inspection on top.

Documents and queries are embedded differently

EmbeddingGemma is asymmetric: the text is wrapped in a different prompt depending on whether it's something to find or something to search with. From the wrapper's source:

const prefixed =
  mode === "query"
    ? `task: search result | query: ${text}`
    : `title: none | text: ${text}`;

So the worker embeds repos with embedDocument() and search embeds the user's sentence with embedQuery(). Mixing the two up still returns results, just noticeably worse ones. That's why both are exported as separate named functions rather than a mode flag callers could forget (instance.ts):

export async function embedDocument(text: string) {
  const embedding = await getServerGemmaEmbedding();
  return embedding.embed(text, "document");
}

export async function embedQuery(text: string) {
  const embedding = await getServerGemmaEmbedding();
  return embedding.embed(text, "query");
}

One shared model instance

Loading the model takes a few seconds and a few hundred MB, so there's exactly one instance per process. It's created on first use, and concurrent callers await the same load promise:

export async function getServerGemmaEmbedding(options?: GemmaEmbeddingOptions) {
  if (options?.dtype && options.dtype !== getActiveGemmaDtype()) {
    await disposeInstance(); // switching quantization: drop the old one
    setActiveDtypeInternal(options.dtype);
  }

  let instance = getEmbeddingInstance();
  if (instance?.isLoaded()) return instance;

  if (!instance) {
    const { GemmaEmbedding } = await import("@kessler/gemma-embedding");
    instance = new GemmaEmbedding(resolveServerGemmaOptions({ ...options, dtype: getActiveGemmaDtype() }));
    setEmbeddingInstance(instance);
  }

  if (!getEmbeddingLoadPromise()) setEmbeddingLoadPromise(instance.load() /* + progress + error handling */);
  await getEmbeddingLoadPromise();
  return getEmbeddingInstance()!;
}

The worker and the search route share this instance, so indexing and searching at the same time don't load the model twice.

Quantization

The ONNX export ships several weight files. Settings lets the user pick one (catalog.ts):

Variant	Download	Notes
`q4`	~197 MB	Default. Smallest, and fine for repo search
`q8`	~309 MB	Balanced
`fp16`	~618 MB	Higher quality
`fp32`	~1.2 GB	Full precision

All variants run on the CPU (device: "cpu"). GEMMA_DTYPE and GEMMA_MODEL_PATH override the choice from the environment, which is handy for pointing at a pre-downloaded model.

ONNX Runtime inside a Deno Desktop binary

onnxruntime-node is a native addon, a .node binary per OS and architecture. Bundling every platform's copy into the desktop binary would bloat it for no benefit, so the packaging step excludes it:

"desktop:build": "... deno desktop ... --exclude-unused-npm --exclude ./.output/server/node_modules/onnxruntime-node --compress ..."

At runtime, ort-runtime.ts resolves ORT in two steps. In dev, the normal node_modules copy just works. In a packaged build, it uses a copy downloaded on first run into the config dir:

export async function ensureOrtReady(): Promise<void> {
  if (await canImportOrt()) return; // bundled / dev node_modules
  if (!downloadedOrtReady()) return; // nothing downloaded yet
  ensureOrtModulePath(); // prepend ~/.config/tangerine-desktop/native/node_modules to NODE_PATH
}

The download pulls the pinned onnxruntime-node tarball (the version must match what Transformers.js expects) straight from the npm registry. It extracts the tarball, deletes the binaries for other operating systems, and adds onnxruntime-common next to it:

const tarballUrl = `https://registry.npmjs.org/onnxruntime-node/-/onnxruntime-node-${ORT_NPM_VERSION}.tgz`;
// fetch with progress -> tar -xzf -> keep bin/napi-v6/<this OS>/ -> fetch onnxruntime-common

Every embed call goes through ensureOrtReady() before importing the model package, which is why that line appears in both embedRepo() and the search helper.

First run: the bootstrap

A fresh install has neither ORT nor model weights. The first time the app opens, it fetches both in the background with a progress toast. It's modelled on an IDE's first-run downloads and is cancellable from the toast.

The server side (embedding-bootstrap.ts) runs the two downloads in order:

void (async () => {
  await ensureOrtReady();
  await beginOrtRuntimeDownload(); // ~40 MB, skipped if ORT already imports
  await awaitOrtRuntimeDownload();

  const q4 = inspectGemmaCache().variants.find((v) => v.id === "q4");
  if (q4?.ready) return;
  beginServerGemmaDtypeSwitch("q4"); // ~197 MB of weights, then load
})();

Progress is streamed with the chapter 4 SSE pattern. This source is a status snapshot rather than an event bus, so the generator polls once a second, only sends when something changed, and closes itself when the downloads finish (models/bootstrap.ts):

.get("/events", async function* ({ request }) {
  let previous: string | null = null;
  while (!request.signal.aborted) {
    const status = await getEmbeddingBootstrapStatus();
    const serialized = JSON.stringify(status);
    if (serialized !== previous) {
      previous = serialized;
      yield sse({ data: status });
    }
    if (!isLive(status)) break;
    await sleep(1000, request.signal);
  }
})

On the client, EmbeddingBootstrapHost is mounted once. It calls POST /embedding/bootstrap/start when the server says shouldAutoStart, and renders the toast with a progress bar and a Cancel button.

Storage: pgvector in PGlite

Vectors live next to the repo rows in embedded Postgres (PGlite with the pgvector extension). The column width comes from the same constant the model package exports, so the two can't drift apart (project-enrichment-outputs.ts):

// packages/gemma-embedding/src/constants.ts
export const EMBEDDING_MODEL_ID = "embeddinggemma-300m";
export const EMBEDDING_DIMENSIONS = 768;

export const projectEnrichmentOutputs = pgTable("project_enrichment_outputs", {
  id: text("id").primaryKey().default(sql`gen_random_uuid()`),
  owner: text("owner").notNull(),
  name: text("name").notNull(),
  type: text("type").$type<"starred" | "repos" | "other">(),
  description: text("description"),
  summary: text("summary"),
  payload: jsonb("payload").notNull(), // { text } = the exact document that was embedded
  modelId: text("model_id"), // which model produced `embedding`
  embedding: vector("embedding", { dimensions: EMBEDDING_DIMENSIONS }),
  embeddedAt: timestamp("embedded_at", { withTimezone: true }),
  // ...
});

Storing payload.text and modelId makes the index easy to reason about later. You can see exactly what was embedded, and if the model ever changes you know which rows to re-embed.

Search

The whole retrieval step is one function (search.ts): embed the query, then let Postgres sort by cosine distance using Drizzle's cosineDistance (pgvector's <=> operator):

export async function searchStarredByQuery(q: string): Promise<StarredSearchHit[]> {
  const text = q.trim().slice(0, EMBED_TEXT_MAX_CHARS);
  if (!text) return [];

  await ensureOrtReady();
  const { embedQuery, getServerGemmaEmbedding } = await import("@repo/gemma-embedding/node");
  await getServerGemmaEmbedding({ dtype: readGemmaPrefs().dtype });
  const vector = Array.from(await embedQuery(text));

  const distance = sql<number>`${cosineDistance(projectEnrichmentOutputs.embedding, vector)}`;

  return db
    .select({ id: projectEnrichmentOutputs.id, owner: projectEnrichmentOutputs.owner, name: projectEnrichmentOutputs.name, description: projectEnrichmentOutputs.description, /* … */ distance })
    .from(projectEnrichmentOutputs)
    .where(and(eq(projectEnrichmentOutputs.type, "starred"), isNotNull(projectEnrichmentOutputs.embedding)))
    .orderBy(distance)
    .limit(50);
}

The select lists columns explicitly and leaves out embedding, so 768 floats per row never cross into the UI.

Right now this is an exact scan: Postgres computes the distance to every starred row. For a personal star list (hundreds to a few thousand rows) that's a small amount of work and always returns the true nearest neighbours. If the corpus grows much larger, an approximate HNSW index is one custom migration. drizzle-kit can't generate USING hnsw, so it would be hand-written:

CREATE INDEX project_enrichment_outputs_embedding_hnsw
  ON project_enrichment_outputs USING hnsw (embedding vector_cosine_ops);

The route exposes the search with validation and OpenAPI docs (enrich/starred/index.ts):

.get("/search", ({ query }) => searchStarredByQuery(query.q), {
  query: t.Object({
    q: t.String({ minLength: 1, maxLength: 2000, description: "Natural-language query; embedded then ranked by cosine distance." }),
  }),
})

The UI

The starred page (EnrichedStarred.tsx) reuses the app's normal list scaffold. The search box writes ?q= to the URL after a 600 ms debounce, and a query hook calls the typed Eden client:

const q = (routeApi.useSearch().q ?? "").trim();

const semantic = useQuery({
  queryKey: ["enriched-starred-search", q],
  enabled: q.length > 0,
  placeholderData: (previous) => previous, // keep old hits on screen while the next query embeds
  queryFn: async () => {
    const { data, error } = await getElysiaTreaty().enrich.starred.search.get({ query: { q } });
    if (error) throw new Error(treatyErrorMessage(error));
    return data ?? [];
  },
});

const rows = q ? (semantic.data ?? []) : allRows;

A few small choices make it feel local rather than remote:

The placeholder hints at meaning, not keywords: "Try natural language — e.g. graph databases in Rust…".
The loading state says "Embedding query…" instead of a generic spinner, which also explains the short wait on the very first search while the model loads.
placeholderData keeps the previous results visible while you refine the query, so the list doesn't flash empty on every keystroke.
No query means the full corpus. An empty q shows every embedded star, paginated, and that list keeps growing live during indexing (chapter 4).
Each hit is a link to the in-app repo page (/$user/repos/$repo).

What we built, and what's next

The finished loop: sign in once, click Embed starred, watch repos stream into the list, and search them by meaning. It all runs on your machine with a ~200 MB model.

It's deliberately "retrieval only": the answer is a ranked list of your own repos, not generated text. That keeps it fast, obviously correct (every result is a real star), and free of a second, much larger model.

Natural next steps, roughly in order of payoff:

Filters on language, topic, or owner, as a WHERE next to the vector sort.
Hybrid ranking: blend in Postgres full-text search, so exact names ("tokio") always rank first.
Chunked READMEs for deep-content matches (see the note in chapter 3).
An HNSW index once the corpus outgrows an exact scan.
Optional local generation: pass the top hits to a small local LLM for a one-paragraph answer that cites them.

With all that said

I tried hard to keep the shipped binary small:

Nothing heavy in the bundle. ONNX Runtime and the EmbeddingGemma weights are fetched at runtime (the first-run bootstrap above), not packaged.
Lazy imports. The model package is only imported the first time something embeds.
No CEF. backend: "webview" uses the OS webview instead of bundling Chromium, which saves roughly 100 MB (chapter 1).

Even so, the Deno runtime alone is about 70 MB, and that's a floor this approach can't go below. For a tool whose job is "search my stars", that feels like a lot.

I suspect a Go shell with Wails (a single Go binary using the OS webview) could come in well under that. So I've started learning Go, and I'm looking forward to rebuilding a slice of this and writing up what I find.

Live activity bus (Elysia SSE + pub/sub powered by nodejs event emitter)

Dennis kinuthia — Wed, 30 Sep 2026 17:31:38 +0000

Why

The workers we use run for minutes. The UI should show "embedding facebook/react", "42 done, 1 failed", and new rows appearing in the list as they land, without polling.

The shape is plain pub/sub: something publishes an event, and every open browser connection listens over Server-Sent Events. A small in-process bus sits in the middle.

 POST /chat  ----+
                 |  publish(topic, event)
 worker    ------+----------------------> [ pubSub (EventEmitter) ]
                                                 |
                                                 |  listen(topic)  one per open connection
                                                 v
                                      GET /chat/sse  (async generator)
                                                 |
                                                 v  yield sse({ data })
                                          EventSource in React
                                                 |
                                                 v
                                        TanStack Query cache -> UI

The bus

src/lib/pub-sub/client.ts wraps a Node EventEmitter. The useful part is listen(): Node's events.on() turns an emitter into an async iterable, and passing an AbortSignal ends the loop and removes the listener.

export class PubSub {
  readonly #emitter = new EventEmitter().setMaxListeners(100);

  publish(topic: PubSubTopic, message: unknown): void {
    this.#emitter.emit(topic, message);
  }

  async *listen<T = unknown>(topic: PubSubTopic, options?: { signal?: AbortSignal }) {
    for await (const [message] of on(this.#emitter, topic, options)) {
      yield message as T;
    }
  }
}

It's a process-wide singleton pinned on globalThis, so Vite HMR re-evaluating the module can't split routes and workers onto two different emitters:

export const pubSub: PubSub = (() => {
  const g = globalThis as GlobalWithPubSub;
  g[GLOBAL_KEY] ??= new PubSub();
  return g[GLOBAL_KEY];
})();

Topics are a const map, so a typo is a type error (topics.ts):

export const PUB_SUB_TOPICS = {
  HELLO_MESSAGE: "hello-message",
  CHAT_MESSAGE: "chat-message",
  REPO_EMBED_PROGRESS: "repo-embed-progress",
  USER_REPO_EMBED_PROGRESS: "user-repo-embed-progress",
} as const;

Worked example: chat

The scratchpad chat is the smallest complete version of the pattern: a list you can add to and delete from, synced live across every open window.

1. The event type

One discriminated union describes everything the stream can send (src/data-access-layer/chat/chat.ts). The row type is inferred from the route through Eden, so it can't drift:

export type ChatRow = AwaitedData<ReturnType<ElysiaTreaty["chat"]["get"]>>[number];

export type ChatSseEvent =
  | { type: "created"; row: ChatRow }
  | { type: "deleted"; id: number };

2. The route: write, then publish

src/elysia/routes/chat/index.ts. Mutations write to PGlite first and publish only what actually happened:

export const chatRoute = new Elysia({ prefix: "/chat" })
  .get("/", () => db.query.chat.findMany({ orderBy: (row, { desc }) => [desc(row.createdAt)] }))
  .post(
    "/",
    async ({ body }) => {
      const [row] = await db.insert(chat).values({ message: body.message }).returning();
      if (row) pubSub.publish(PUB_SUB_TOPICS.CHAT_MESSAGE, { type: "created", row } satisfies ChatSseEvent);
      return row;
    },
    { body: t.Object({ message: t.String({ minLength: 1 }) }) },
  )
  .delete(
    "/:id",
    async ({ params }) => {
      await db.delete(chat).where(eq(chat.id, params.id));
      pubSub.publish(PUB_SUB_TOPICS.CHAT_MESSAGE, { type: "deleted", id: params.id } satisfies ChatSseEvent);
      return { data: { message: "Chat deleted" }, error: null };
    },
    { params: t.Object({ id: t.Numeric() }) },
  )

3. The stream: an async generator

With Elysia, an SSE endpoint is a generator that yields sse(...) frames. Elysia sets the text/event-stream headers and stops the generator when the client disconnects. Passing request.signal to listen() also removes the emitter listener at that moment.

  .get("/sse", async function* ({ request }) {
    for await (const event of pubSub.listen<ChatSseEvent>(PUB_SUB_TOPICS.CHAT_MESSAGE, {
      signal: request.signal,
    })) {
      yield sse({ data: event });
    }
  });

That's the entire server side of live updates: no socket bookkeeping and no subscriber list.

4. The client: EventSource → query cache

A tiny generic helper parses JSON frames and returns an unsubscribe function (use-embedding-sse.ts):

export function subscribeSseJson<T>(url: string, handlers: { onMessage: (data: T) => void }): () => void {
  const source = new EventSource(url);
  source.onmessage = (event) => handlers.onMessage(JSON.parse(event.data));
  source.onerror = () => {
    if (source.readyState !== EventSource.CONNECTING) source.close();
  };
  return () => source.close();
}

The chat hook (use-chat-sse.ts) applies each event straight to the TanStack Query cache, so the list re-renders without a refetch. The route path comes from Eden (~path), not a hardcoded string.

function applyChatSseEvent(event: ChatSseEvent) {
  getQueryClient().setQueryData<ChatRow[]>(chatQueryKey, (prev = []) => {
    if (event.type === "created") {
      return prev.some((row) => row.id === event.row.id) ? prev : [event.row, ...prev];
    }
    return prev.filter((row) => row.id !== event.id);
  });
}

export function useChatSse() {
  useEffect(() => {
    const path = getElysiaTreaty().chat.sse["~path"];
    return subscribeSseJson<ChatSseEvent>(path, { onMessage: applyChatSseEvent });
  }, []);
}

The some(...) check matters: the window that sent the message also receives its own created event, and this stops it from showing the row twice.

5. The component

The initial list comes from a normal query, and live changes come from the hook (Scratchpad.tsx):

export function Scratchpad() {
  useChatSse();
  const { data, isLoading, error } = useQuery({ queryKey: chatQueryKey, queryFn: listChats });
  // ...render ChatInput + ChatList
}

The input's mutation just calls createChat(message). It doesn't touch the cache, because the SSE event does that for every window, including this one.

The same pattern for embedding progress

The chapter 3 worker publishes { status, row } on REPO_EMBED_PROGRESS from patchEmbedActivity(). The stream route adds one thing: it sends the current snapshot first, so a window that opens mid-run starts from the real state instead of waiting for the next event (enrich/starred/index.ts):

.get("/activity/events", async function* ({ request }) {
  yield sse({ data: { status: getEmbedActivityStatus(), row: null } });

  for await (const payload of pubSub.listen<EmbedActivitySsePayload>(
    PUB_SUB_TOPICS.REPO_EMBED_PROGRESS,
    { signal: request.signal },
  )) {****
    yield sse({ data: payload });
  }****
})

On the client (use-embed-activity-sse.ts), each frame updates the status pill, and any row gets upserted into the enriched-repos collection, so newly embedded repos appear in the list while the run continues:

useEffect(() => {
  return subscribeSseJson<EmbedActivitySsePayload>("/api/elysia/enrich/starred/activity/events", {
    onMessage: (payload) => {
      setStatus(payload.status);
      if (payload.row) upsertEnrichedRepo(payload.row);
    },
  });
}, []);****

As a safety net, while a run is live the hook also polls GET /activity every 2 s. That way a frame lost during HMR can't leave the spinner stuck.

Limitations

This isn't RabbitMQ or Redis pub/sub. It's an EventEmitter in one Deno process, and for a desktop app with one embedded server and a few windows, that's all it needs to be.

Single process only. Publishers and listeners must live in the same process. That's always true here.
No replay. A client that connects late misses earlier events. The initial fetch, plus the snapshot-first frame on the activity stream, covers that.
Not durable. Events are for live UI only. The real state lives in PGlite and the job queue, so a restart loses progress messages, not data.
No backpressure. Each connection queues events until its generator pulls them, which is fine at the rate a paced worker publishes.

If it ever needed to span processes, only PubSub would change: Postgres LISTEN/NOTIFY or Redis could sit behind the same publish/listen pair.

Queues and workflows with conveyor

Dennis kinuthia — Wed, 30 Sep 2026 17:26:16 +0000

Why a worker

Embedding a few hundred starred repos means a few hundred README fetches and a few hundred model runs. That takes minutes, can hit GitHub's rate limit halfway through, and shouldn't die if the user navigates away or quits the app. So the HTTP request only kicks things off, and a background worker does the rest:

POST /enrich/starred/run
   |
   +--> worker.start()
   |
   +--> enqueueAllStarredRepos()      GitHub GraphQL, one page of stars at a time
            |
            v
     +------------------+
     | queue (SQLite)   |   one job per repo, deduped by repo id
     +------------------+
            |
            v  batches of 10
     Worker: fetch README -> build text -> EmbeddingGemma -> upsert into PGlite
            |
            +--> patchEmbedActivity()  --> pub/sub --> SSE (chapter 4)

The engine: Conveyor + SQLite

We use Conveyor, a job queue with a BullMQ-style API (Queue, Worker, retries with backoff, deduplication, pause/resume, batch processing) and pluggable stores. We use the SQLite store (@conveyor/store-sqlite-node), so the queue is just a file under ~/.config/tangerine-desktop/queues/.

That fits the app: one Deno process on one machine. There's no Redis to run, jobs survive restarts because they're on disk, and the whole engine lives in the same process as the UI server and the model.

Each queue gets its own SQLite file (src/lib/worker/store.ts):

export function createWorkerStore(options: { name: string }) {
  const filename = resolveLocalPath(
    process.env.QUEUE_DATABASE_PATH ?? process.env.QUEUE_DATABASE_URL,
    `queues/${options.name}.db`,
  );
  mkdirSync(dirname(filename), { recursive: true });
  return new SqliteStore({ filename });
}

// src/elysia/routes/enrich/starred/helpers/store.ts
export const starredRepoEmbedStore = createWorkerStore({ name: "starred-repo-embed" });
await starredRepoEmbedStore.connect();

Stage 1: the queue and its jobs

One job per repo. The payload is just what we already got from the stars list, so the worker doesn't need to re-fetch metadata (queue.ts):

export interface EmbedRepoShape {
  id: string;
  owner: string;
  name: string;
  description: string | null;
  languages: string[];
  tags: string[];
}

export const starredRepoEmbedQueue = new Queue<StarredRepoEmbedJob>("repo-embed", {
  store: starredRepoEmbedStore,
});

export const enqueueStarredRepoEmbedJobs = async (jobs: StarredRepoEmbedJob[]) => {
  const created = await starredRepoEmbedQueue.addBulk(
    jobs.map((job) => ({
      name: "embed-repo",
      data: job,
      opts: {
        deduplication: { key: `repo-embed:${job.id}` },
        attempts: 5,
        backoff: { type: "exponential", delay: 60_000 },
      },
    })),
  );
  return { enqueued: created.length, jobIds: created.map((job) => job.id) };
};

The dedup key is the GitHub node id, so re-running the crawl doesn't queue the same repo twice.
attempts + exponential backoff is how rate-limited jobs come back later on their own (stage 4).

Stage 2: page through the stars

enqueue.ts fetches one GraphQL page (up to 100 stars), hands it to the queue, and moves on to the next cursor. It never holds the whole star list in memory, because the queue owns the payload from here on:

const page = await client.getUserStarredReposMinimal({ login, first: pageSize, after });
if (!page) return { data: "crawl-done", error: null };

await enqueueStarredRepoEmbedJobs(
  page.edges.map(({ node }) => ({
    id: node.id,
    owner: node.owner.login,
    name: node.name,
    description: node.description,
    tags: node.tags,
    languages: node.tags,
  })),
);

const { hasNextPage, endCursor } = page.pageInfo;
if (!hasNextPage || !endCursor) return { data: "crawl-done", error: null };
if (pagesLeft !== undefined && pagesLeft <= 1) return { data: { nextCursor: endCursor }, error: null };

return enqueueAllStarredRepos({ ...input, after: endCursor, pages: pagesLeft && pagesLeft - 1 });

Two knobs make it easy to try on a small slice first:

pages caps how many pages this run fetches. The result hands back nextCursor so a later run can resume from there.
after starts from a saved cursor.

If GitHub rate-limits the list call itself, the same page is retried with exponential backoff (1 min, 2 min, 4 min, capped at 15) up to five times:

} catch (caught) {
  if (!isGithubRateLimited(caught)) throw caught;
  if (retriesLeft <= 0) return { data: null, error: "429" };

  const attempt = MAX_RATE_LIMIT_RETRIES - retriesLeft;
  await sleep(Math.min(60_000 * 2 ** attempt, 15 * 60_000));
  return enqueueAllStarredRepos({ ...input, retriesLeft: retriesLeft - 1 });
}

Stage 3: build the document and embed it

For each repo, src/lib/embedding-gemmma/embed-repo.ts fetches the README, keeps the first 20 lines, and builds one short text document:

export function buildRepoEmbedDocument(repo: EmbedRepoShape, readmeSummary: string | null): string {
  const parts = [
    `Repository: ${repo.name}`,
    `Full name: ${repo.owner}/${repo.name}`,
    repo.description ? `Description: ${repo.description}` : null,
    repo.languages.length > 0 ? `Languages: ${repo.languages.join(", ")}` : null,
    repo.tags.length > 0 ? `Tags: ${repo.tags.join(", ")}` : null,
    readmeSummary ? `README:\n${readmeSummary}` : null,
  ];
  return parts.filter(Boolean).join("\n").slice(0, EMBED_TEXT_MAX_CHARS);
}

Then it embeds that document with EmbeddingGemma in document mode (chapter 5 covers the model and why the mode matters):

export async function embedRepo(repo: EmbedRepoShape): Promise<EmbedRepoResult> {
  const client = createGitHubClient(await getGithubToken());
  const readme = await client.getRepoReadme(repo.owner, repo.name);
  const summary = clipReadmeSummary(readme?.content); // first 20 lines
  const text = buildRepoEmbedDocument(repo, summary);

  await ensureOrtReady();
  const { embedDocument, getEmbeddingModelId, getServerGemmaEmbedding } =
    await import("@repo/gemma-embedding/node");
  await getServerGemmaEmbedding({ dtype: readGemmaPrefs().dtype });
  const vector = await embedDocument(text);

  return { ...repo, summary, text, modelId: getEmbeddingModelId(), embedding: Array.from(vector) };
}

One vector per repo, no chunking. Metadata plus the top of the README tells you what a repo is, which is what "find that starred repo about X" needs, and it fits comfortably in EmbeddingGemma's 2K-token context. The tradeoff is that something mentioned only deep in a README won't match. A chunk table is the natural next step if that ever matters.

A repo with no README still gets embedded from its name, description, and topics.

Stage 4: the worker

worker.ts pulls batches of 10 and handles each job on its own, so one bad repo doesn't fail the batch:

export const starredRepoEmbedWorker = new Worker<StarredRepoEmbedJob>(
  "repo-embed",
  async (jobs) => {
    const results: BatchResult[] = [];

    for (let i = 0; i < jobs.length; i++) {
      const { owner, name } = jobs[i]!.data;
      patchEmbedActivity({ phase: "embedding", embed: { current: { owner, name } } });

      try {
        const embedded = await embedRepo(jobs[i]!.data);
        const row = await upsertStarredEmbed(embedded); // PGlite, no vector in the returned row
        const completed = getEmbedActivityStatus().embed.completed + 1;
        patchEmbedActivity({ embed: { current: null, completed } }, row);
        results.push({ status: "completed", value: { owner, name } });
      } catch (caught) {
        if (isGithubRateLimited(caught)) {
          await pauseForRateLimit(asError(caught));
          for (let j = i; j < jobs.length; j++) results.push({ status: "failed", error: asError(caught) });
          return results;
        }
        results.push({ status: "failed", error: asError(caught) });
      }
    }
    return results;
  },
  { store: starredRepoEmbedStore, batch: { size: 10 }, autoStart: false },
);

The upsert is keyed on (owner, name), so re-embedding a repo replaces its row instead of duplicating it:

await db
  .insert(projectEnrichmentOutputs)
  .values({ owner, name, type: "starred", description, summary, payload: { text }, modelId, embedding, embeddedAt: new Date() })
  .onConflictDoUpdate({
    target: [projectEnrichmentOutputs.owner, projectEnrichmentOutputs.name],
    set: { description, summary, payload: { text }, modelId, embedding, embeddedAt: new Date() },
  });

autoStart: false means the worker only runs when asked. POST /enrich/starred/run starts it, and there are worker/start, worker/pause, and worker/resume endpoints for manual control.

Staying under the rate limit

When a README fetch comes back rate-limited, the worker pauses itself for a minute and fails the rest of the batch without touching GitHub again:

async function pauseForRateLimit(error: Error): Promise<void> {
  starredRepoEmbedWorker.pause();
  patchEmbedActivity({ phase: "waiting", list: { rateLimited: true }, message: "GitHub rate limited — pausing embed for 60s" });

  await sleep(60_000);

  starredRepoEmbedWorker.resume();
  patchEmbedActivity({ phase: "embedding", list: { rateLimited: false }, message: "Resumed embed after rate-limit pause" });
}

Those failed jobs aren't lost. Each has attempts: 5 with exponential backoff from 60 s, so Conveyor schedules them again later. Between the pause and the backoff, a large star list just finishes more slowly instead of hammering the API.

A GitHub token outside the request

Workers run after the HTTP request that started them has ended, so there are no request headers to read a session from. The kickoff route stores the token for the process (src/lib/github-token.server.ts):

let workerGithubToken: string | null = null;

export function rememberGithubTokenForWorkers(token: string): void {
  workerGithubToken = token.trim() || null;
}

export async function getGithubToken(): Promise<string> {
  // 1. OAuth token from the current request, if any
  // 2. token remembered by the kickoff route
  // 3. GH_PAT from the environment
}

On desktop, the UI passes the token from bindings.getGithubAccessToken() (chapter 2) in the kickoff body.

Progress, restarts, and "done"

Every step calls patchEmbedActivity(...). That updates one status object (phase, counters, current repo, last error) and publishes it, together with the freshly upserted row if there is one, on the pub/sub bus. Chapter 4 streams that to the UI.

export type EmbedActivityStatus = {
  phase: "idle" | "listing" | "embedding" | "waiting" | "done" | "error";
  login: string | null;
  list: { after: string | null; fetchedTotal: number; enqueuedTotal: number; totalCount: number | null; rateLimited: boolean };
  embed: { current: { owner: string; name: string } | null; completed: number; failed: number; lastError: string | null };
  message: string | null;
  updatedAt: string;
};

"Done" is derived rather than tracked: once the list crawl has settled and the queue has nothing waiting or delayed, maybeMarkEmbedDone() flips the phase. It's called after each batch, when the worker emits drained, and on GET /activity, so a missed event can't leave the UI stuck on "embedding".

What survives a restart:

State	Where	After restart
Pending / retrying jobs	Conveyor SQLite file	Picked up again when the worker starts
Embedded repos	PGlite	Still there, and searchable right away
Progress status	in memory (`globalThis`)	Resets to `idle`; the next run starts fresh counts

The status lives on globalThis for the same reason as the pub/sub bus: Vite HMR re-evaluates modules, and the worker and the SSE route must keep sharing one object.

Things to know

Embeddings run one at a time on a single shared model instance on the CPU. That's plenty for a personal star list, and it keeps memory predictable next to the UI.
The first embed can trigger a model download if the bootstrap (chapter 5) hasn't run yet, so the first repo takes noticeably longer.
README content past line 20 isn't indexed. That's deliberate for v1, as described in stage 3.

Deno desktop Better Auth intergration

Dennis kinuthia — Wed, 30 Sep 2026 17:19:49 +0000

Why Better Auth

Better Auth is one of the nicest things in TypeScript right now: framework-agnostic, plugin-based, and it owns the boring parts (OAuth state, sessions, account linking, CSRF). So whenever I try a new framework, the first thing I check is whether someone already has a Better Auth integration for it.

For desktop apps there are two places to look: the official Electron integration and the community Tauri plugins. Neither drops into Deno Desktop as-is, but both taught us what the moving parts are.

What already exists

Electron (official)

Better Auth ships @better-auth/electron. It has three pieces:

Piece	Runs in	Job
`electron()` server plugin	your Better Auth server	PKCE-checked `/electron/token` exchange, `transferUser`, redirect cookie
`electronProxyClient()`	your web sign-in page	preserves PKCE through `signIn.social`, then redirects to `com.example.app:/auth/callback?token=…`
`electronClient()` + `setupMain()`	Electron main process	generates PKCE, opens the system browser, handles the deep link, stores cookies

The client half is built around Electron's process model. There's a Node main process that owns windows and OS integration, sandboxed Chromium renderer processes (one per window), and preload scripts that bridge them with contextBridge + ipcRenderer. setupMain() registers the protocol handler for deep links, a user-image:// protocol, CSP, and ipcMain handlers. setupRenderer() then exposes window.requestAuth(), window.onAuthenticated() and friends through the preload. Tokens never reach the renderer.

Deno Desktop has none of that plumbing (comparison):

No electron module, so no ipcMain, contextBridge, protocol, or app.on("open-url").
No separate main process. The Deno runtime and the webview live in one process (CEF) or one coordinated process group (OS webview). They talk through bindings (win.bind / bindings.x()), which are in-process channels, not IPC.
Deep links are registered but not delivered. desktop.app.deepLinks registers com.tigawanna.tangerine at package time, but Deno does not hand open-url to JS yet (see Asking upstream below). The custom-scheme return that the Electron flow depends on never arrives.

The good news: the server plugin and the web proxy client are plain HTTP. They don't care what the desktop shell is. Only the Electron client half is Electron-specific, so that's the only part we rewrite.

Tauri (community)

There's no official Tauri package (issue #8409 was closed as "no official plan yet"), but two community plugins solve the same problem in different ways.

daveyplate/better-auth-tauri replays the OAuth callback inside the app. A server hook rewrites callbackURL onto the app's scheme. When the OS delivers the deep link (@tauri-apps/plugin-deep-link), the client strips the scheme and re-issues the same /api/auth/... request through authClient.$fetch, so the callback lands in the app's cookie jar instead of the browser's:

// src/client/handle-auth-deep-link.ts (trimmed)
const href = `/${url.replace(`${scheme}:/${basePath}`, "")}`;
const response = await authClient.$fetch(href);
if (response.error?.status !== 302 && response.error?.message) onError?.(response.error);
else onSuccess?.(new URL(url).searchParams.get("callbackURL"));

Sign-in calls signIn.social({ disableRedirect: true }) and opens the returned URL with @tauri-apps/plugin-opener, so the webview never navigates to GitHub. On macOS/Windows it swaps fetch for @tauri-apps/plugin-http so cookies stick.

DreamsHive/better-auth-tauri copies the official Expo plugin. The server appends the session cookie to the scheme redirect (yourapp://?cookie=…), and the client stores it and sends it back on every request. Webviews can't set Cookie (it's a forbidden header), so the client uses an x-tauri-cookie header and the server plugin rewrites it back to Cookie:

export const auth = betterAuth({
  trustedOrigins: ["yourapp://"],
  plugins: [tauri()], // tauri-origin → origin, x-tauri-cookie → Cookie, ?cookie= on scheme redirects
});

It also leaves storage to you, and its README recommends the OS keychain over localStorage.

Asking upstream

Before building anything, I asked on the Deno repo how Better Auth OAuth should work in Deno Desktop: Deno desktop better auth (discussion #36796). The accepted answer, from @ryux1, settled most of the design:

However, current Deno main only writes the OS registration metadata. The implementation explicitly says that delivering the opened URL to the running app, single-instance forwarding, and the JavaScript open-url event are tracked separately […]

For now I would keep Better Auth on a normal web backend and use a system-browser authorization flow with PKCE and state. The return path needs to be either: a loopback listener bound to 127.0.0.1 on a temporary port; or a manual short-lived authorization-code handoff similar to Better Auth's documented Electron fallback.

What that meant for us:

The Electron client can't be reused, but the server side can. The Electron package's client pieces depend on Electron APIs. The Better Auth server, the electron() plugin, and the web proxy flow are plain HTTP, so only the desktop half needs writing: browser launch, PKCE state, code exchange, and token storage.
Registering the scheme doesn't make deep links work. The source the answer points to (cli/tools/desktop.rs) confirms the app never receives the URL. A custom-scheme OAuth callback can't complete today.
Two return paths: a 127.0.0.1 loopback, plus a paste-the-code fallback modelled on Better Auth's Electron manual token exchange.
The GitHub client secret stays on the API. Nothing secret ships in the binary.
The loopback is temporary. Once Deno delivers open-url both at launch and to an already-running app, the custom scheme can replace it.

We ended up building both return paths: the loopback is the main one, and the paste box is the fallback.

What we took from all of this

OAuth belongs in the system browser. Real address bar, existing GitHub session, and providers that block embedded webviews still work.
The return path is the hard part. Electron and Tauri both use a custom-scheme deep link, which Deno can't deliver yet. Per the discussion, use a 127.0.0.1 loopback plus a paste-the-code fallback.
Keep the session out of the webview. Electron keeps it in main, and Tauri fights the webview's cookie rules. With Deno we can keep it in the Deno runtime and only expose bindings.getSession().
Storage is your problem. Electron uses conf in userData, and Tauri asks for a keychain adapter. Deno Desktop has no native secure-storage API yet, so we use a JSON file under the config dir.
Reuse the official server plugin. electron() already implements the PKCE exchange, so we don't reinvent it.
Secrets stay on the server. The GitHub client secret lives only on apps/api. The desktop binary only ever sees a PKCE verifier and, after the exchange, a session token.

Our flow

Same shape as Electron: electron() on the API, electronProxyClient() on the web page, and our own client in the Deno preload. The deep link is swapped for a loopback HTTP server on 127.0.0.1.

 +-------------+   bindings.requestAuth()   +----------------+
 | Desktop UI  | -------------------------> | Deno preload   |
 | (webview)   |                            | PKCE + loopback|
 +-------------+                            +----------------+
        ^                                          |
        |                                          | open system browser
        |                                          v
        |                                 +-------------------+     GitHub OAuth     +-----------+
        |                                 | apps/web  /auth   | <------------------> | apps/api  |
        |                                 | (system browser)  |                      | electron()|
        |                                 +-------------------+                      +-----------+
        |                                          |                                       ^
        |                                          | fetch 127.0.0.1:17832/callback?token= |
        |                                          v                                       |
        |   tangerine:authenticated        +----------------+   POST /electron/token       |
        +--------------------------------- | Deno preload   | -----------------------------+
            + navigate("/viewer")          | save session   |   { token, state, verifier }
                                           +----------------+

Three apps take part: apps/api (:5000) owns Better Auth and the GitHub secret, apps/web (:3064) hosts the sign-in page the system browser opens, and apps/desktop (:3070) is the native shell. No GitHub secret ever ships in the desktop binary.

Step by step

1. Server: `electron()` + `bearer()` on the API

apps/api/src/lib/auth.ts is the only Better Auth instance. The desktop-relevant bits are the two plugins and the trusted origin:

betterAuth({
  baseURL: envVariables.BETTER_AUTH_URL, // public web origin, not the API host
  basePath: "/api/auth",
  trustedOrigins: [...AUTHORIZED_ORIGINS, ELECTRON_TRUSTED_ORIGIN], // "com.tigawanna.tangerine:/"
  socialProviders: {
    github: {
      clientId: envVariables.GITHUB_CLIENT_ID,
      clientSecret: envVariables.GITHUB_CLIENT_SECRET,
      scope: [...DEFAULT_GITHUB_SCOPES],
      mapProfileToUser: (profile: GithubProfile) => ({ githubUsername: profile.login /* … */ }),
    },
  },
  plugins: [electron(), bearer() /* openAPI, apiKey, admin … */],
});

electron() gives us /electron/token (PKCE exchange) and transferUser for free.
bearer() lets the preload authenticate with Authorization: Bearer <token> instead of rebuilding a signed cookie jar (see lesson 4 below).
ELECTRON_TRUSTED_ORIGIN comes from packages/auth/src/electron.ts, so the API, web, and desktop all agree on the scheme.

2. UI: ask the preload to start

The desktop sign-in button (src/routes/auth/-components/GitHubSignIn.tsx) doesn't touch OAuth. It calls a binding and waits:

const desktopSignIn = useMutation({
  mutationFn: async () => {
    if (!globalThis.bindings) throw new Error("Desktop bindings unavailable");
    setAwaitingBrowser(true);
    await globalThis.bindings.requestAuth();
  },
});

3. Preload: PKCE, loopback, open the browser

deno/auth/request-auth.ts does what electronClient().requestAuth() would do in Electron main:

export async function requestAuth() {
  const cfg = readConfig();
  const state = randomString(16);
  const codeVerifier = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
  const codeChallenge = await generateCodeChallenge(codeVerifier); // SHA-256, base64url
  await rememberPkce(state, codeVerifier); // memory + ~/.config/tangerine-desktop/pkce.json

  const loopback = await startLoopbackServer(); // http://127.0.0.1:<real port>/callback

  const url = new URL(cfg.signInURL); // apps/web /auth
  url.searchParams.set("client_id", CLIENT_ID); // "electron"
  url.searchParams.set("state", state);
  url.searchParams.set("code_challenge", codeChallenge);
  url.searchParams.set("loopback", loopback);

  await openExternal(url.toString()); // xdg-open / open / start
  return { loopback, state };
}

The query params are exactly what electronProxyClient expects. loopback is our one addition.

4. Preload: the loopback server

deno/auth/loopback.ts is a tiny Deno.serve on 127.0.0.1 that stands in for the deep link. It starts at app boot (from deno/window.ts), not on click, so the port is ready before the browser needs it:

const server = Deno.serve(
  {
    hostname: "127.0.0.1",
    port: preferredPort, // DESKTOP_AUTH_LOOPBACK_PORT or 17832
    onListen: (addr) => {
      boundPort = addr.port; // Deno Desktop may remap — always advertise this one
    },
  },
  async (req) => {
    const url = new URL(req.url);
    if (url.pathname === "/health") return Response.json({ ok: true }, { headers: corsHeaders });
    if (url.pathname !== "/callback") return new Response("Not found", { status: 404 });

    const token = url.searchParams.get("token");
    if (!token) return Response.json({ ok: false, error: "missing_token" }, { status: 400 });
    await authenticate({ token }); // step 6
    return Response.json({ ok: true }, { headers: corsHeaders });
  },
);

The handle lives on globalThis under a Symbol.for(...) key and gets probed via /health before reuse, so HMR or a second requestAuth() doesn't orphan a dead listener.

The discussion suggested a temporary port. We start with a fixed preferred port instead, because random ports kept breaking after HMR and re-sign-in: the browser tab still held the old URL. Deno Desktop can remap it anyway, so the advertised URL always uses the real port from onListen.

This whole step is the part that goes away once Deno delivers open-url. At that point the web page can redirect to com.tigawanna.tangerine:/auth/callback?token=… like the stock Electron flow, and the preload handles it with the same authenticate() call.

5. Web: sign in, then hand the code to the loopback

The browser half (apps/web/src/routes/auth/-components/GitHubSignIn.tsx) uses the official proxy client (apps/web/src/lib/auth-client.ts):

export const authClient = createAuthClient({
  baseURL: clientEnv.VITE_APP_URL,
  basePath: "/api/auth",
  fetchOptions: { credentials: "include" },
  plugins: [electronProxyClient({ protocol: { scheme: ELECTRON_PROTOCOL_SCHEME } })],
});

On click it forwards the PKCE params into signIn.social and sets the callback back to /auth, so the page can finish the handoff after GitHub returns:

await authClient.signIn.social({
  provider: "github",
  callbackURL: `${window.location.origin}/auth${window.location.search}`,
  scopes: buildGithubOAuthScopes([...selected]),
  fetchOptions: { query: electronQuery }, // client_id, state, code_challenge
});

Back on /auth, instead of ensureElectronRedirect() (which would redirect to the custom scheme), it asks the API for an authorization code and fetches the loopback with it:

const transferred = await authClient.electron.transferUser({
  fetchOptions: { query: electronQuery },
});
const identifier = transferred.data?.electron_authorization_code;
// token = base64url(JSON.stringify({ identifier, state }))
const target = new URL(loopback);
target.searchParams.set("token", encodeRedirectToken(identifier, electronQuery.state));
const res = await fetch(target, { headers: { accept: "application/json" } });
if (res.ok) window.location.replace("/auth/desktop-done"); // "you can close this tab"

It uses fetch rather than navigating to the loopback URL, so if the listener is down the page stays put and shows the token for the paste fallback.

6. Preload: exchange the code for a session

deno/auth/authenticate.ts decodes the token, finds the matching PKCE verifier by state, and calls the electron() plugin's exchange endpoint:

const { identifier, state } = decodeRedirectToken(input.token);
const codeVerifier = await peekPkce(state); // read, don't consume yet

const res = await fetch(`${authBase(cfg)}/electron/token`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ token: identifier, state, code_verifier: codeVerifier }),
});
if (!res.ok) throw new Error(await res.text());

await clearPkce(state); // only after success, so retries still work
const data = (await res.json()) as { token: string; user: DesktopAuthUser };
await saveStored({ cookies, user: data.user, token: data.token }); // session.json
getAuthListeners().onAuthenticated?.(data.user);

The same function backs the paste fallback: bindings.authenticate({ token }) from the UI ends up here too.

7. Session storage and authenticated calls

The session is a JSON file in the Deno runtime, never in the webview:

~/.config/tangerine-desktop/
├── session.json   # { user, token, cookies }, written after a good exchange
└── pkce.json      # in-flight state → verifier (last 20), survives restarts/HMR

Every call from the preload to the API goes through one helper (deno/auth/cookies.ts):

export function apiHeaders(stored: StoredSession, extra?: HeadersInit): Headers {
  const headers = new Headers(extra);
  headers.set("origin", `${PROTOCOL_SCHEME}:/`); // Better Auth CSRF check
  const cookie = cookieHeader(stored.cookies);
  if (cookie) headers.set("cookie", cookie);
  if (stored.token) headers.set("authorization", `Bearer ${stored.token}`);
  if (!headers.has("content-type")) headers.set("content-type", "application/json");
  return headers;
}

Deno's fetch runs outside the webview, so it can set Cookie and Origin freely. That's the problem DreamsHive works around with x-tauri-cookie, and here it simply doesn't exist.

Plain JSON is a tradeoff: Deno Desktop doesn't have a secure-storage API yet. When it lands, session-store.ts is the only file that needs to change.

8. Tell the UI, and guard routes with bindings

After onAuthenticated, the preload (deno/window.ts) pushes an event into the webview and navigates, because executeJs events can get dropped:

setAuthListeners({
  onAuthenticated: (user) => {
    notifyRenderer("tangerine:authenticated", user); // window CustomEvent
    win.navigate(`${appOrigin()}/viewer`);
  },
  onAuthError: (message) => notifyRenderer("tangerine:auth-error", { message }),
});

Route guards ask the preload, not cookies (src/routes/_dashboard/layout.tsx). The same code still works in a plain browser tab via the normal Better Auth session:

if (hasDesktopBindings() && globalThis.bindings) {
  const desktopSession = await globalThis.bindings.getSession();
  if (!desktopSession) throw redirect({ to: "/auth", search: { returnTo: location.pathname } });
  sessionUser = desktopSession.user;
} else {
  const session = await getSession();
  if (!session) throw redirect({ to: "/auth", search: { returnTo: location.pathname } });
  sessionUser = session.user;
}

9. The payoff: a GitHub token for the RAG corpus

The whole point is a real user token for GitHub. It lets us list starred repos and pull READMEs and metadata at the authenticated rate limit instead of the anonymous one. deno/auth/session.ts exposes it as bindings.getGithubAccessToken():

// Better Auth wants the account *row* id, not GitHub's user id
const accountId = await resolveGithubAccountRowId(stored); // GET /list-accounts → providerId === "github"
const res = await fetch(`${authBase(cfg)}/get-access-token`, {
  method: "POST",
  headers: apiHeaders(stored),
  body: JSON.stringify({ accountId }),
});

Better Auth keeps the GitHub OAuth token on the API side, and the desktop fetches it on demand. Chapter 3's worker uses it to crawl stars.

Lessons learned

Most of these cost an evening each. The full list with debugging tips is in docs/auth.md.

Deno Desktop can remap your loopback port. Ask for 17832, but always advertise the port from onListen. Start the loopback at boot and keep a strong reference to the server, or the browser ends up posting to a dead port.

   // ✗ advertises the port you asked for
   Deno.serve({ port: 17832 }, handler);
   loopback = "http://127.0.0.1:17832/callback";

   // ✓ advertises the port you actually got
   Deno.serve({ port: 17832, onListen: ({ port }) => (boundPort = port) }, handler);
   loopback = `http://127.0.0.1:${boundPort}/callback`;

Use a query string, not a fragment. #token= never reaches an HTTP server. Use ?token=.
Persist PKCE and peek, don't pop. HMR and React Strict Mode remounts will lose an in-memory verifier. Keep it on disk and clear it only after a successful exchange. If it's gone but session.json is valid, treat that as already signed in.

   const verifier = await peekPkce(state); // read only; a retry can reuse it
   if (!verifier) return (await getSession()) ?? fail("start sign-in again");

   const res = await exchange(identifier, state, verifier);
   if (res.ok) await clearPkce(state); // consume only after success

The raw session token is not the cookie. /electron/token returns the DB session token, while the better-auth.session_token cookie is signed. Putting the raw token in Cookie makes get-session come back empty. Use Authorization: Bearer (hence bearer() on the API).
Send Origin on every cookie-bearing request. Better Auth's CSRF check rejects requests with a missing or null Origin (MISSING_OR_NULL_ORIGIN). Electron sets it for you. In Deno, send com.tigawanna.tangerine:/ yourself.

   // ✗ empty session, then 403 on the first POST
   headers.set("cookie", `better-auth.session_token=${rawToken}`);

   // ✓ what apiHeaders() sends
   headers.set("authorization", `Bearer ${rawToken}`);
   headers.set("origin", "com.tigawanna.tangerine:/");

Don't wipe the session on soft failures. Only clear session.json when the API says the session is gone (user: null) or on sign-out. Never do it on a network error or a bad cookie.
Guard with bindings, not cookies. Server functions reading Start request cookies always look logged-out inside the native shell. The session lives in the preload.
Tell the UI more than once. executeJs CustomEvents can be dropped. We send the event, call win.navigate("/viewer"), and poll bindings.getSession() while the UI shows "Waiting for browser…".
Gate the web handoff on the click. Don't poll transferUser while the user is still picking scopes. If a web session already exists, run only the handoff and not signIn.social as well, or GitHub bounces you back to /auth looking stuck.
/get-access-token wants { accountId }, the account row id from list-accounts, not GitHub's numeric id.
Keep the env split straight.
- Desktop VITE_API_URL points at the API (:5000) for the token exchange.
- VITE_APP_URL is the desktop UI (:3070).
- VITE_SIGN_IN_URL is the web /auth page (:3064).
- On the API, BETTER_AUTH_URL is the web origin, so OAuth cookies stay first-party.
The preload does not hot-reload. Changes to deno/* and .env only apply after you fully quit and restart the app. Vite HMR only refreshes the UI.

Wishlist for Deno Desktop

Most of the code in deno/auth/ works around something the runtime doesn't do yet. These are the features that would shrink it, roughly in order of impact:

Deliver open-url to JS. A Deno.BrowserWindow or app-level open-url event that fires both when the scheme launches the app and when it's already running. This alone would delete the loopback server (loopback.ts, about 200 lines), the port-remap handling, and the web-side fetch handoff. The web page could just use the stock ensureElectronRedirect().

   // hypothetical API: replaces loopback.ts
   Deno.desktop.addEventListener("open-url", async ({ url }) => {
     const token = new URL(url).searchParams.get("token");
     if (token) await authenticate({ token });
   });

Single-instance lock with argument forwarding. Opening com.tigawanna.tangerine:/… while the app runs should focus the existing window and pass the URL along, not start a second copy. Electron has requestSingleInstanceLock() and Tauri has tauri-plugin-single-instance. Deep links are only half useful without it.
A native auth-session API. Something like macOS's ASWebAuthenticationSession or Windows' WebAuthenticationBroker: await Deno.desktop.authenticate({ url, callbackScheme }) opens the system browser and resolves with the callback URL. That would replace deep links, the loopback, and the paste fallback in one call.

   // hypothetical API: the whole return path in one await
   const callback = await Deno.desktop.authenticate({
     url: signInUrlWithPkce,
     callbackScheme: "com.tigawanna.tangerine",
   });
   await authenticate({ token: new URL(callback).searchParams.get("token")! });

Secure storage. Keychain / Credential Manager / Secret Service behind one API. The session is plain JSON in ~/.config/tangerine-desktop/session.json today because there's nothing else; Deno lists this under "doesn't have yet".
Open a URL in the default browser. A built-in openExternal(url). We shell out to xdg-open / open / cmd /c start in open-external.ts, which is fiddly on Windows and needs --allow-run.
Reliable Deno → webview events. Bindings only go from the webview to Deno. To push "signed in" back, we executeJs a CustomEvent, which can get dropped, so we also navigate and poll bindings.getSession(). A typed win.emit(channel, payload) paired with a webview-side bindings.on(channel, fn) would remove all three workarounds.

   // today: string-built JS that may never arrive
   win.executeJs(`window.dispatchEvent(new CustomEvent("tangerine:authenticated", …))`);

   // hypothetical: typed push from Deno, subscription in the webview
   win.emit("auth:changed", user);
   bindings.on("auth:changed", (user) => navigate({ to: "/viewer" }));

Hot reload for the preload. --preload and --env-file are read once at startup, so every auth change means fully quitting the app. HMR for deno/* (or at least a "reload preload" command) would make iterating on this flow far less painful.
Predictable Deno.serve ports. A way to opt out of port remapping when an explicit port is requested, or a documented rule for when it happens. Half of lesson 1 exists because the port you ask for isn't always the port you get.
Typed bindings. A shared type between win.bind(...) and bindings.*. Today we keep src/lib/desktop-bindings.ts in sync with deno/window.ts by hand, and the docs suggest the same.

Deno Desktop the basics

Dennis kinuthia — Wed, 30 Sep 2026 16:42:14 +0000

What's the deal with Deno desktop

Deno Desktop (deno desktop, Deno ≥ 2.9) packages a web app together with the Deno runtime and a rendering engine into one binary per platform.

Point it at a project directory and it auto-detects the framework: Next.js, Astro, Nuxt, SvelteKit, SolidStart, TanStack Start, and several more. It embeds the build output and runs the framework's own production server (or its dev server under --hmr), with the webview pointed at it:

deno desktop --hmr .             # dev: framework dev server + native window
deno desktop -o ./dist/myapp .   # package: one binary for this platform

Server code just runs, no IPC

A sweet feature is how server-side code runs in the Deno runtime automatically, with no IPC. In Electron you split code into "main" and "renderer" and wire channels between them:

// Electron: main process
ipcMain.handle("read-notes", () => fs.readFile(notesPath, "utf8"));

// Electron: preload, to expose it safely
contextBridge.exposeInMainWorld("api", { readNotes: () => ipcRenderer.invoke("read-notes") });

// Electron: renderer
const notes = await window.api.readNotes();

With deno desktop, the framework server is the backend. A TanStack Start server function (or a Next.js server action) does the same job in one place:

// Deno Desktop + TanStack Start: runs in the Deno runtime, called from React like a function
export const readNotes = createServerFn().handler(() => fs.readFile(notesPath, "utf8"));

const notes = await readNotes();

Server routes work the same way. With full Node compat, node:fs, node:child_process, native npm modules like onnxruntime-node, and embedded Postgres (PGlite) all run right next to your UI code.

For a local RAG tool that matters a lot. Fetching from GitHub, running an ONNX embedding model, and writing to a vector index are all "server" work, and we want it in plain TypeScript next to the routes that trigger it.

Bindings for the truly native bits

For the handful of things that really are native (window, menus, the OS browser for OAuth), Deno Desktop has bindings. A function bound on the Deno side shows up on a global bindings object in the webview, through in-process channels rather than socket IPC:

// Deno side (preload)
win.bind("openExternal", (url: string) => openInSystemBrowser(url));

// webview side
await bindings.openExternal("https://github.com/login");

The real versions are in the preload section below.

Why TanStack Start fits

TanStack Start builds with Nitro into .output/server/index.*, which is exactly the entry deno desktop looks for:

vp build
  └── .output/
      ├── public/          static assets
      └── server/index.mjs  <- deno desktop finds and runs this

Everything else is a normal TanStack Start app, so the same code also runs in a browser tab (pnpm dev:vite) for fast UI iteration.

Monorepo layout

apps/desktop sits in the pnpm + Turbo monorepo next to apps/api (Better Auth + Turso) and apps/web (the browser dashboard and the OAuth /auth page). Shared code lives in packages/*.

apps/desktop/
├── deno.json              # desktop.app identity, icons, backend, output paths
├── package.json           # dev / build / package scripts
├── vite.config.ts         # TanStack Start + Nitro + React Compiler + Relay
├── nitro.config.ts        # Nitro server (evlog drain)
├── deno/                  # Deno-side preload (NOT bundled by Vite)
│   ├── window.ts          # BrowserWindow + bindings exposed to the webview
│   ├── menu.ts            # native application menu
│   └── auth/              # PKCE, loopback server, session jar (chapter 2)
├── src/                   # TanStack Start app
│   ├── routes/            # file-based routes (UI + server routes)
│   │   └── api/elysia/$.ts  # Elysia mounted as a catch-all server route
│   ├── elysia/            # embedded Elysia API + Eden treaty client
│   ├── pglite/            # local Postgres + pgvector (Drizzle)
│   ├── lib/pub-sub/       # in-process pub/sub that feeds SSE
│   └── hooks/use-*-sse.ts # React hooks that consume SSE streams
├── .output/               # `vp build` output, embedded into the binary
└── dist-desktop/          # packaged app (never committed)

Shared packages used here:

Package	Role
`@repo/auth`	GitHub-only Better Auth pieces (wired up in chapter 2)
`@repo/github`	GitHub REST/GraphQL client for repos and stars
`@repo/gemma-embedding`	EmbeddingGemma ONNX pipeline (chapter 3)

The local data lives in the user's config directory, not in the repo: PGlite data at ~/.config/tangerine-desktop/pgdata (or DATABASE_URL), plus session JSON and the job-queue SQLite files.

`deno.json`: identity, backend, output

The desktop block in deno.json holds all the desktop-specific config (docs):

{
  "nodeModulesDir": "manual",
  "unstable": ["sloppy-imports"],
  "imports": {
    "@/": "./src/",
    "@api/": "../api/src/"
  },
  "tasks": {
    "dev": "pnpm run dev:vite",
    "build": "pnpm run build"
  },
  "desktop": {
    "app": {
      "name": "Tangerine",
      "identifier": "com.tigawanna.tangerine",
      "deepLinks": ["com.tigawanna.tangerine"],
      "icons": {
        "linux": "./public/icon.png",
        "macos": "./public/icon.png",
        "windows": "./public/favicon.ico"
      }
    },
    "backend": "webview", // we save like 100 extra mbs by not using the CEF which embeds a chromiu
    "output": {
      "linux": "./dist-desktop/tangerine",
      "macos": "./dist-desktop/Tangerine.app",
      "windows": "./dist-desktop/Tangerine"
    }
  }
}

A few things are not obvious:

nodeModulesDir: "manual": pnpm owns node_modules. Deno reads it and never installs into it.
imports mirrors the Vite @/ alias so the same imports resolve under both Deno and Vite.
tasks.dev must point at Vite, not at deno desktop. Under --hmr, Deno Desktop runs the framework dev server by calling deno task dev. If that task started deno desktop again, it would recurse.
backend: "webview" uses the OS webview (WebKitGTK / WebKit / WebView2) for small binaries. Switch to cef (bundled Chromium) with --backend=cef when you need identical rendering or DevTools. See Backends.
deepLinks registers the custom scheme when the app is packaged, but Deno does not yet deliver open-url to JS, so OAuth returns through a loopback server instead (chapter 2).

Dev loop: HMR, ports, env

The scripts in package.json:

{
  "dev": "NODE_OPTIONS='--dns-result-order=ipv4first --no-network-family-autoselection' DENO_DESKTOP_DEVTOOLS=1 deno desktop --hmr --preload ./deno/window.ts --env-file=.env -A .",
  "dev:vite": "vp dev --port 3070 --host",
  "desktop:build": "pnpm run build && deno desktop --preload ./deno/window.ts --env-file=.env --no-check --node-modules-dir=none --exclude-unused-npm --exclude ./.output/server/node_modules/onnxruntime-node --compress -A -o ./dist-desktop/tangerine ."
}

Command	What it does
`pnpm dev` (repo root)	Turbo: `apps/api` + this app's native `deno desktop --hmr`
`pnpm dev` (this package)	Native window, Vite dev server with HMR on :3070
`pnpm dev:vite`	Same app in a normal browser tab on :3070, no native shell
`pnpm desktop:build`	`vp build` → `.output/`, then package into `dist-desktop/`
`pnpm desktop:run`	Run the native shell against an existing `.output/`

What the flags do:

--hmr: runs the framework's own dev server, so React fast refresh works inside the native window just like in a browser (HMR docs). The Deno runtime and webview stay alive across edits.
--preload ./deno/window.ts: runs our Deno-side code before the UI loads (next section). Preload is not hot-reloaded. Restart after editing deno/*.
--env-file=.env: env is read once at startup, so restart after changing .env too.
-A: all permissions. Bindings and server code inherit the runtime's permissions, and desktop apps usually ship with broad ones baked in.
NODE_OPTIONS=...ipv4first: avoids localhost resolving to ::1 while the API listens on IPv4.
DENO_DESKTOP_DEVTOOLS=1: the preload opens DevTools when this is set.
Packaging flags (--exclude-unused-npm, --exclude …onnxruntime-node, --compress) keep the binary small. deno desktop does not run your framework build, which is why desktop:build runs pnpm run build first.

Env basics (see .env.example):

VITE_APP_URL=http://localhost:3070          # the desktop UI itself
VITE_API_URL=http://localhost:5000          # apps/api (auth + token exchange)
VITE_SIGN_IN_URL=http://localhost:3064/auth # apps/web sign-in page, opened in the system browser
DATABASE_URL=./pgdata                       # PGlite dir, relative to ~/.config/tangerine-desktop/

No GitHub client secrets ever go in this file. They stay on apps/api.

The preload: native window + bindings

deno/window.ts is the only "main process"-style code we write. It takes over the startup window, installs the menu, and exposes a small set of functions to the webview:

/// <reference lib="deno.ns" />
/// <reference lib="deno.desktop" />

const win = new Deno.BrowserWindow({
  title: "Tangerine",
  width: 1280,
  height: 840,
  resizable: true,
});

installApplicationMenu(win);

win.bind("openExternal", async (url: string) => {
  if (typeof url !== "string" || url.length === 0) {
    throw new TypeError("openExternal(url) requires a non-empty string");
  }
  await openExternal(url);
});

win.bind("getSession", async () => {
  return await getSession();
});

if (Deno.env.get("DENO_DESKTOP_DEVTOOLS") === "1") {
  win.openDevtools();
}

On the React side, src/lib/desktop-bindings.ts types the bindings proxy. Deno gives you no type bridge between the two realms, so we declare one ourselves. We also feature-detect it so the same UI still works in a plain browser tab:

declare global {
  // Deno Desktop injects this proxy into the renderer.
  var bindings: DesktopBindings | undefined;
}

/** True when running inside a `deno desktop` webview with bindings available. */
export function hasDesktopBindings(): boolean {
  return typeof globalThis.bindings?.requestAuth === "function";
}

Rule of thumb: bindings are for things only the native shell can do (window, menus, OS browser, the auth session). Everything else (GitHub fetches, embeddings, database, SSE) goes through normal TanStack Start server code, which already runs in Deno.

Related docs: Windows · Menus · Bindings.

Server functions just work

Because the Nitro server runs inside the Deno runtime, a TanStack Start server function can use Node APIs, the local database, or the GitHub token directly. From src/data-access-layer/github/repos.ts:

export const getPinnedRepos = createServerFn({ method: "GET" }).handler(async () => {
  try {
    const nodes = await createGitHubClient(await getGithubToken()).getPinnedRepos();
    return {
      data: {
        viewer: {
          pinnedItems: { nodes },
          repositories: { nodes: [] },
        },
      },
    } satisfies PinnedViewerReposResponse;
  } catch {
    return null;
  }
});

There's no preload channel and no IPC: the client calls getPinnedRepos() and TanStack Start handles the RPC over the local HTTP server that the webview is already talking to.

Pairing TanStack Start with Elysia (for SSE)

Server functions work well for request/response calls. A RAG indexer, though, needs long-lived streams: "fetched repo X", "embedded chunk 40/200", "upserted into the vector index". Those should be pushed to the UI as they happen, not polled.

TanStack Start server routes can return a raw Response, so you can stream SSE by hand. But then you build the ReadableStream, encode data: frames, set text/event-stream / no-cache / X-Accel-Buffering headers, and wire up abort handling yourself. src/lib/sse.ts shows what that looks like. Doing it per endpoint gets old fast.

So this project mounts Elysia inside TanStack Start, following the official TanStack Start integration. Elysia gives us:

SSE as async generators: yield sse({ data }) inside async function*, with request.signal for disconnects (Elysia SSE docs).
Validation: TypeBox t.Object(...) schemas on body/query/params.
End-to-end types: Eden Treaty gives a typed client (tRPC-style) derived from the route tree.
One composable API tree: feature routes (/system, /models, /enrich, /worker, /chat, …) are separate Elysia instances combined with .use().

It all runs in the same Nitro process as the UI, on the same port, and inside the same deno desktop binary. There's no second server to start.

1. Mount Elysia as a catch-all server route

src/routes/api/elysia/$.ts forwards every method under /api/elysia/* to Elysia's fetch:

import { elysiaApp } from "@/elysia/app";
import { createFileRoute } from "@tanstack/react-router";

/**
 * Mount Elysia under `/api/elysia/*` inside TanStack Start.
 * @see https://elysiajs.com/integrations/tanstack-start
 */
const handle = ({ request }: { request: Request }) => elysiaApp.fetch(request);

export const Route = createFileRoute("/api/elysia/$")({
  server: {
    handlers: {
      GET: handle,
      POST: handle,
      PUT: handle,
      PATCH: handle,
      DELETE: handle,
    },
  },
});

With pnpm, add Elysia's peer deps explicitly (pnpm add @sinclair/typebox openapi-types). pnpm does not auto-install them.

2. Compose the app

src/elysia/app.ts owns the prefix and composes the feature routes. The /tick route is the smallest possible SSE stream: one event per second until the client disconnects.

import { sleep } from "@/lib/sse";
import { Elysia, sse } from "elysia";

export const elysiaApp = new Elysia({ prefix: "/api/elysia" })
  .get("/tick", async function* ({ request }) {
    let n = 0;
    while (!request.signal.aborted) {
      n += 1;
      yield sse({
        event: "tick",
        data: { n, at: new Date().toISOString() },
      });
      try {
        await sleep(1000, request.signal);
      } catch (caught) {
        if (caught instanceof DOMException && caught.name === "AbortError") break;
        throw caught;
      }
    }
  })
  .use(consoleRoute)
  .use(systemRoute)
  .use(embeddingsRoute)
  .use(workerRoute)
  .use(enrichRoute)
  .use(helloRoute)
  .use(chatRoute);

export type ElysiaApp = typeof elysiaApp;

3. A publish/subscribe example: `/hello`

src/elysia/routes/hello/index.ts is the toy version of the live activity bus from chapter 4. POST /hello publishes a message, and every open GET /hello/sse connection receives it:

import { pubSub } from "@/lib/pub-sub/client";
import { PUB_SUB_TOPICS } from "@/lib/pub-sub/topics";
import { Elysia, sse, t } from "elysia";

export const helloRoute = new Elysia({ prefix: "/hello" })
  .get("/", () => [{ id: "1", message: "Hello, world!" }])
  .get("/sse", async function* ({ request }) {
    // `{ signal }` ends the loop (and removes listeners) when the client disconnects.
    for await (const message of pubSub.listen<string>(PUB_SUB_TOPICS.HELLO_MESSAGE, {
      signal: request.signal,
    })) {
      yield sse({ data: message });
    }
  })
  .post(
    "/",
    ({ body }) => {
      pubSub.publish(PUB_SUB_TOPICS.HELLO_MESSAGE, body.message);
      return { message: `Emitted ${body.message}` };
    },
    { body: t.Object({ message: t.String() }) },
  );

The bus in src/lib/pub-sub/client.ts is a process-wide EventEmitter. It's pinned on globalThis so Vite HMR re-evaluating the module doesn't give routes and workers two different emitters:

export const pubSub: PubSub = (() => {
  const g = globalThis as GlobalWithPubSub;
  g[GLOBAL_KEY] ??= new PubSub();
  return g[GLOBAL_KEY];
})();

4. A typed Eden client on both sides

src/elysia/treaty.ts uses TanStack Start's createIsomorphicFn. On the server (SSR, loaders, server functions) Eden calls the Elysia app in-process with no HTTP. In the browser it makes HTTP calls to the same origin:

export const getElysiaTreaty = createIsomorphicFn()
  .server(() => getServerElysiaTreaty())
  .client(() => {
    const origin = globalThis.location?.origin ?? clientEnv.VITE_APP_URL;
    return (treaty(origin) as unknown as ElysiaTreatyRoot).api.elysia;
  });

Two project-specific tweaks on top of the Elysia docs:

The server half lives in treaty.server.ts, so the client bundle never imports app.ts (and with it every route, worker, and Node-only module). This also avoids a circular import with the route tree.
Types come from ElysiaApp["~Routes"], not treaty<typeof app>(). Deno and Vite can resolve two copies of the elysia types, and typeof app then fails to line up. Pulling out the route map sidesteps that.

5. Call it from React

A plain mutation, fully typed from the route's TypeBox schema (PingMessage.tsx):

const { mutate, isPending } = useMutation({
  mutationFn: async (input: { message: string }) => {
    const { data, error } = await getElysiaTreaty().hello.post({
      message: input.message,
    });
    if (error) throw new Error(treatyErrorMessage(error));
    return data;
  },
});

And the SSE side (src/hooks/use-hello-sse.ts). Eden's ~path gives us the URL without hardcoding it, and a native EventSource handles reconnects:

const connect = () => {
  const path = getElysiaTreaty().hello.sse["~path"];
  source = new EventSource(path);
  source.onmessage = (event) => appendHelloMessage(event.data);
  source.onerror = () => {
    if (source && source.readyState !== EventSource.CONNECTING) {
      source.close();
    }
  };
};

appendHelloMessage writes into a TanStack DB collection (hello-collection.ts). The collection is seeded from GET /hello, and live SSE rows are appended on top. Chapters 3–4 use the same pattern for embedding progress.

Product objectives

This is the product the rest of the series builds toward:

Natural-language search over starred repos. Ask "that Rust crate for terminal UIs with a flexbox layout" and get the right starred repo back, even if you starred it three years ago and forgot the name.
Local RAG pipeline: fetch → embed → store → retrieve.
- Fetch: README and metadata for each starred repo via the user's GitHub token, paced under API rate limits.
- Embed: EmbeddingGemma via ONNX Runtime (onnxruntime-node), on-device.
- Store: vectors in PGlite with pgvector, ranked by cosine distance (src/pglite/client.ts).
- Retrieve: vector similarity search, with the matching repos shown in the UI.
Stay on-device. Your stars, READMEs, and vectors never leave the machine. There's no hosted RAG SaaS or vector DB in the loop. The only network calls are to GitHub (the source of truth) and to apps/api for sign-in.
Visible progress. Indexing takes minutes on purpose, so the UI shows live activity over SSE instead of a spinner.

How later chapters fit

Chapter 2: Better Auth: sign in with GitHub through the system browser, PKCE, and a loopback server in the preload, so the app gets a user token without shipping secrets.
Chapter 3: Worker engine: a durable job queue that crawls stars, stays under rate limits, and embeds repos in batches.
Chapter 4: Live activity bus: the /hello pub/sub pattern above, reused as typed progress events from the worker to the UI.
Chapter 5: Query path: embed the question, run a pgvector search, and render results.

Tanstack DB in action

Dennis kinuthia — Sun, 16 Aug 2026 12:00:29 +0000

The team at TanStack, makers of TanStack Query (aka react-query), partnered with the ElectricSQL team to give us something truly awesome.

This library excites me for two reasons:

Why it excites me

Joining data from multiple sources

Anything you can express as a collection can be joined to another collection with SQL-like semantics, and the library automatically handles mitigating against N+1 queries.

// Left join - all users, even without posts
const allUsers = createLiveQueryCollection((q) =>
  q
    .from({ user: usersCollection })
    .leftJoin({ post: postsCollection }, ({ user, post }) => eq(user.id, post.userId)),
);

Basic local-first functionality

The library shipped persistence in its latest version, backed by SQLite with Web and React Native adapters, enabling true local-first approaches—all while remaining provider- and backend-agnostic.

In my usage of the library, I have discovered a few cool approaches that make life with this library better.

The Basics

TanStack DB comes with adapters for many local-first providers, but in our case, we'll be using the TanStack Query adapter since it lets us progressively enhance.

From `useQuery` to a collection

Let's take the example of a movie app:

import { useQuery } from "@tanstack/react-query";

export function MovieListWithUseQuery() {
  // TODO: add filters from url search params
  const filters = {
    page: 1,
    perPage: 10,
    q: "",
    sortBy: "vote_average",
    sortDirection: "desc",
    includeTotal: true,
  } as const;
  const { data, isLoading } = useQuery({
    queryKey: ["movies-with-use-query"],
    queryFn: () =>
      getPaginatedFakeMoviesFn({
        data: filters,
      }),
  });

  return (
    <div className="w-full flex flex-col">
      <h1 className="text-2xl font-bold">Movies</h1>
      {isLoading ? (
        <div>Loading...</div>
      ) : (
        <div>
          {data?.items.map((movie) => (
            <div key={movie.id}>{movie.title}</div>
          ))}
        </div>
      )}
    </div>
  );
}

This is a nice starting point for us to port. We start by creating the collection definition:

export const moviesCollection = createCollection(
  queryCollectionOptions({
    queryKey: [PAGINATED_MOVIES_COLLECTION_QUERY_KEY],
    queryFn: async (ctx) => {
      const filters = {
        page: 1,
        perPage: 10,
        q: "",
        sortBy: "vote_average",
        sortDirection: "desc",
        includeTotal: true,
      } as const;
      const response = await getPaginatedFakeMoviesFn({
        data: filters,
      });
      return response;
    },
    select: (data) => data.items,
    queryClient: getQueryClient(),
    getKey: (item) => item.id,
    autoIndex: "eager",
    defaultIndexType: BasicIndex,
    staleTime: 1000 * 60 * 60,
  }),
);

Querying with `useLiveQuery`

And we can query our collection via a useLiveQuery hook:

import { useLiveQuery } from "@tanstack/react-db";
import { queryDrivenMoviesCollection } from "../query-driven-collection";

export function MovieList() {
  const { data, isLoading } = useLiveQuery((qb) =>
    qb.from({ movies: moviesCollection }).orderBy(({ movies }) => movies.vote_average, "desc"),
  );

  return (
    <div className="w-full flex flex-col">
      <h1 className="text-2xl font-bold">Movies</h1>
      {isLoading ? (
        <div>Loading...</div>
      ) : (
        <div>
          {data?.map((movie) => (
            <div key={movie.id}>{movie.title}</div>
          ))}
        </div>
      )}
    </div>
  );
}

For now, this might seem like a downgrade compared to the previous setup as it requires more boilerplate, and if you've noticed, we're not passing the filters to get a new paginated subset.

While TanStack DB can handle up to 50,000 rows with no problem, our backend team or third-party APIs would never allow us to fetch that many records at once. We'll explore solutions to that later, but for now, let's do something that useQuery can't.

//  watchlist collection
export const watchlistCollection = createCollection(
  queryCollectionOptions({
    queryKey: [WATCHLIST_COLLECTION_QUERY_KEY],
    queryFn: async () => getFakeWatchlistFn(),
    queryClient: getQueryClient(),
    schema: fakeWatchlistSchema,
    getKey: (item) => item.id,
    autoIndex: "eager",
    defaultIndexType: BasicIndex,
    staleTime: 1000 * 60 * 60,
    onInsert: async ({ transaction }) => {
      await Promise.all(
        transaction.mutations.map((mutation) =>
          addFakeWatchlistFn({
            data: {
              id: mutation.modified.id,
              movieId: mutation.modified.movieId,
              createdAt: mutation.modified.createdAt,
            } satisfies FakeWatchlistItem,
          }),
        ),
      );
    },
    onDelete: async ({ transaction }) => {
      await Promise.all(
        transaction.mutations.map((mutation) =>
          removeFakeWatchlistFn({ data: { id: String(mutation.key) } }),
        ),
      );
    },
  }),
);

Joining with another collection

import { eq, isUndefined, not, useLiveQuery } from "@tanstack/react-db";
import { moviesCollection, watchlistCollection } from "../query-driven-collection";

export function MovieList() {
  const { data, isLoading } = useLiveQuery((qb) =>
    qb
      .from({ movies: queryDrivenMoviesCollection })
      .join({ watchlist: watchlistCollection }, ({ movies, watchlist }) =>
        eq(movies.id, watchlist.movieId),
      )
      .orderBy(({ movies }) => movies.vote_average, "desc")
      .select(({ movies, watchlist }) => ({
        id: movies.id,
        title: movies.title,
        overview: movies.overview,
        poster_path: movies.poster_path,
        vote_average: movies.vote_average,
        release_date: movies.release_date,
        watchlistId: watchlist.id,
        onWatchlist: not(isUndefined(watchlist)),
      })),
  );

  return (
    <div className="w-full flex flex-col">
      <h1 className="text-2xl font-bold">Movies</h1>
      {isLoading ? (
        <div>Loading...</div>
      ) : (
        <div>
          {data?.map((movie) => (
            <div key={movie.id}>{movie.title}</div>
          ))}
        </div>
      )}
    </div>
  );
}

This is not impossible to accomplish in useQuery land, but it is not as incrementally computed and certainly not as clean. Comparisons can take a back seat for now as we examine how to do partial data responses and handle non-array responses.

Handling non-array responses

As you might notice:

      const response = await getPaginatedFakeMoviesFn({
        data:filters
      });
      return response; // this response is an object and checking the query devtools will show the whole payload, but TanStack DB only allows you to return an array, so we use the select method below similar to the TanStack Query equivalent
    },
    select: (data) => data.items, // only return the items array from the collection

Reading pagination metadata from the query store

This means we can grab the rest of the metadata from the query store. I made a handy helper for this:

import { useQueryClient } from "@tanstack/react-query";

export type MetaObject<T = unknown> = {
  items: T[];
  page?: number | undefined;
  perPage?: number | undefined;
  q?: string | undefined;
  totalItems?: number | undefined;
  totalPages?: number | undefined;
};

export type DBQueryMetaObject<T> = {
  queryKey: readonly unknown[] | undefined;
  meta: MetaObject<T> | undefined;
};

export type TSDBQueryMetaMatch = {
  page?: number;
  q?: string;
};

export function useTSDBQueryMeta(queryKey: string, match?: TSDBQueryMetaMatch) {
  const qc = useQueryClient();
  const queriesData = qc.getQueriesData({ queryKey: [queryKey] });

  const metaObject = parseAndFindMetaObject(queriesData, queryKey, match);
  return metaObject;
}

export function parseAndFindMetaObject<T>(
  queryData: [readonly unknown[], unknown][],
  queryKey: string,
  match?: TSDBQueryMetaMatch,
) {
  const candidates = queryData.filter(([, data]) => isMetaObject(data));

  const keyed = candidates.filter(([key]) =>
    key.some((part) => typeof part === "string" && part.includes(queryKey)),
  );

  const pool = keyed.length > 0 ? keyed : candidates;

  const matched = match
    ? pool.find(([, data]) => metaMatches(data as MetaObject, match))
    : undefined;

  const metaObject = matched ?? pool.at(-1);

  if (!metaObject) {
    return {
      queryKey: undefined,
      meta: undefined,
    };
  }

  return {
    queryKey: metaObject[0],
    meta: metaObject[1] as MetaObject<T>,
  } satisfies DBQueryMetaObject<T>;
}

function isMetaObject(data: unknown): data is MetaObject {
  return (
    !!data &&
    typeof data === "object" &&
    "items" in data &&
    Array.isArray((data as MetaObject).items)
  );
}

function metaMatches(data: MetaObject, match: TSDBQueryMetaMatch) {
  if (match.page != null && data.page != null && data.page !== match.page) {
    return false;
  }

  const wantedQ = (match.q ?? "").trim();
  const cachedQ = (data.q ?? "").trim();
  if (wantedQ !== cachedQ) {
    return false;
  }

  return true;
}

// usage
const { meta } = useTSDBQueryMeta(PAGINATED_MOVIES_COLLECTION_QUERY_KEY, {
  page,
  q,
});
// meta.page
// meta.totalItems
// meta.totalPages...

Pagination

Client-side infinite query

If your server does return a massive payload, you can leverage the useLiveInfiniteQuery hook to perform cursor-based pagination on the dataset that has already been fetched:

import { useLiveInfiniteQuery } from "@tanstack/react-db";
import { useState } from "react";
import ResponsivePagination from "react-responsive-pagination";

export function ListMoviesInfinite() {
  const { isLoading, fetchNextPage, pages, pageParams, hasNextPage, state } = useLiveInfiniteQuery(
    (q) =>
      q.from({ movies: moviesCollection }).orderBy(({ movies }) => movies.vote_average, "desc"),
    {
      initialPageParam: 0,
      pageSize: 200,
      getNextPageParam: (lastPage, allPages) =>
        lastPage.length === 200 ? allPages.length : undefined,
    },
  );

  const latestPage = pageParams.at(-1);
  const [currentPage, setCurrentPage] = useState(latestPage ?? 0);
  const currentPageData = pages[currentPage];

  async function handleLoadMore() {
    setCurrentPage((prev) => (latestPage ?? prev) + 1);
    fetchNextPage();
  }

  return (
    <div className="w-full h-full flex flex-col gap-4">
      <div className="w-full h-full flex justify-end items-center gap-4">
        <div className="max-w-[90%] w-full ">
          <ResponsivePagination
            current={currentPage}
            total={latestPage ?? 1}
            onPageChange={(page) => setCurrentPage(page)}
          />
        </div>
        <Button onClick={handleLoadMore} disabled={!hasNextPage}>
          Load more
        </Button>
      </div>
      <div className="w-full h-full flex flex-col gap-4">
        <MoviesTable data={currentPageData} isLoading={isLoading} />
      </div>
    </div>
  );
}

Query-driven sync

This works, but it doesn't give us ultimate control, which is unlocked via a feature released in 0.5 called query-driven-sync.

To achieve this, we set the collection sync option to on-demand:

[!NOTE]
This will opt us out of the ability to preload a collection in the loaders more info

import { parseWhereWithHandlers } from "@/lib/tanstack/db/utils";
import { BasicIndex, createCollection, parseLoadSubsetOptions } from "@tanstack/db";
import { queryCollectionOptions } from "@tanstack/query-db-collection";

export const PAGINATED_MOVIES_COLLECTION_QUERY_KEY = "query-driven-movies";
export const WATCHLIST_COLLECTION_QUERY_KEY = "query-driven-watchlist";

const MOVIE_SORT_KEYS = [
  "title",
  "overview",
  "vote_average",
  "release_date",
  "popularity",
] as const;

type MoviesWhereClause = {
  page?: { _eq: number };
  q?: { _eq?: string; _ilike?: string };
};

function parseSearchQ(where: MoviesWhereClause | null | undefined) {
  const raw = where?.q?._eq ?? where?.q?._ilike;
  if (!raw) return undefined;
  const stripped = raw.replace(/^%|%$/g, "").trim();
  return stripped || undefined;
}

export const queryDrivenMoviesCollection = createCollection(
  queryCollectionOptions({
    queryKey: [PAGINATED_MOVIES_COLLECTION_QUERY_KEY],
    queryFn: async (ctx) => {
      const where = parseWhereWithHandlers<MoviesWhereClause>(ctx.meta?.loadSubsetOptions?.where); //this will now be available
      const { sorts } = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions);
      const page = where?.page?._eq ?? 1;
      const q = parseSearchQ(where);
      const primarySort = sorts[0];
      const { sortBy, sortOrder: sortDirection } = resolveSortOrder({
        sortBy: primarySort ? String(primarySort.field.at(-1)) : undefined,
        sortOrder: primarySort?.direction,
        allowedKeys: MOVIE_SORT_KEYS,
        defaultSortBy: "vote_average",
        defaultSortOrder: "desc",
      });
      const response = await getPaginatedFakeMoviesFn({
        data: { page, perPage: 10, q, sortBy, sortDirection, includeTotal: true },
      });
      return response;
    },
    select: (data) => data.items,
    queryClient: getQueryClient(),
    getKey: (item) => item.id,
    autoIndex: "eager",
    defaultIndexType: BasicIndex,
    syncMode: "on-demand",
    staleTime: 1000 * 60 * 60,
  }),
);

The query parsing helpers are here

And just like that, we can now compose our queries, and the filters will be used to determine the next subset that gets loaded.

Persistence

TanStack Query has some persistence options, but they're backed by IndexedDB and LocalStorage and have somewhat unreliable mutation persistence.

With version 0.6, TanStack DB introduced persistence via SQLite. This closes the gap in making better offline-first applications with powerful and persisted optimistic mutations:

import { BasicIndex, createCollection, parseLoadSubsetOptions } from "@tanstack/db";
import { queryCollectionOptions } from "@tanstack/query-db-collection";

import {
  createBrowserWASQLitePersistence,
  openBrowserWASQLiteOPFSDatabase,
  persistedCollectionOptions,
} from "@tanstack/browser-db-sqlite-persistence";


const database = await openBrowserWASQLiteOPFSDatabase({
  databaseName: "my-app.sqlite",
});

const persistence = createBrowserWASQLitePersistence({
  database,
});

const watchlistQueryOptions = queryCollectionOptions({
  queryKey: [WATCHLIST_COLLECTION_QUERY_KEY],
  queryFn: async () => getFakeWatchlistFn(),
  queryClient: getQueryClient(),
  schema: fakeWatchlistSchema,
  getKey: (item) => item.id,
  autoIndex: "eager",
  defaultIndexType: BasicIndex,
  staleTime: 1000 * 60 * 60,
  onInsert: async ({ transaction }) => {
    await Promise.all(
      transaction.mutations.map((mutation) =>
        addFakeWatchlistFn({
          data: {
            id: mutation.modified.id,
            movieId: mutation.modified.movieId,
            createdAt: mutation.modified.createdAt,
            title: mutation.modified.title,
            poster_path: mutation.modified.poster_path,
            overview: mutation.modified.overview,
            vote_average: mutation.modified.vote_average,
            release_date: mutation.modified.release_date,
          } satisfies FakeWatchlistItem,
        }),
      ),
    );
  },
  onDelete: async ({ transaction }) => {
    await Promise.all(
      transaction.mutations.map((mutation) =>
        removeFakeWatchlistFn({ data: { id: String(mutation.key) } }),
      ),
    );
  },
});

export const queryDrivenWatchlistCollection = createCollection({
  ...persistedCollectionOptions({
    persistence,
    schemaVersion: 2,
    ...watchlistQueryOptions,
  }),
  schema: fakeWatchlistSchema,
});

Conclusions

While good, this isn't a perfect system, and I would absolutely like a few features that would make this library even more awesome.

Wishlist

A meta object from `useLiveQuery` into the collection

I'll take the example of our API that returns paged data. We currently map all the subsets with a page so that we can filter on that page, despite every subset that we load ever being the same page for every row in a subset.

const current_page = // whatever was in the filters
// take a sample subset
const result = [{id: 1, name: "hello"}, {id: 2, name: "hello 2"}, {id: 3, name: "hello 3"}]
// we have to map in the page item
const pagedResult = results.map((item) => ({...item, page: current_page}))

// we can now do this in our live query
.where(({ movies }) => and(eq(movies.page, page), eq(movies.q, q)))
// and access it in our collection
    queryFn: async (ctx) => {
      const where = parseWhereWithHandlers<MoviesWhereClause>(ctx.meta?.loadSubsetOptions?.where);
      const { sorts } = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions);
      const page = where?.page?._eq ?? 1; // we can finally extract this to pass into our new query for the subset

`placeholderData` and `isRefetching`

An option like placeholderData: keepPreviousData from TanStack Query in the collection and an isRefetching property to be returned from the query hooks.

This would be especially helpful for TanStack Router/Start since they can't use useTransition to stop every filter change from transitioning the page into isLoading and instead show the last data the user was looking at when using query-driven sync.

I really love this library and have even built more abstractions (event-sourced-collection) over it to take local-first development even further.

References

Example TanStack Start app with TanStack DB
event-sourced-collection — event-sourcing based local-first layer on TanStack DB
TanStack DB skills
TanStack DB official blogs

Reasons to Still Use Next.js from a TanStack Start Enjoyer

Dennis kinuthia — Tue, 28 Jul 2026 14:07:50 +0000

Why You Might Still Pick Next.js Over TanStack Start

From a TanStack Start fanboy

TanStack Start is exciting. File-based routing, type-safe search params, and a stack that feels modern and, most importantly, lets you keep your SPA goodies and cool libraries like TanStack Query to maximize UX for your users and DX for yourself. We all know how heavy-handed mutations can be in Next.js, but with TanStack it all feels like a breeze. Lately, with server components quietly encroaching on Next.js territory, and a rising number of job postings asking for TanStack skills, the ecosystem is clearly growing.

That said, Next.js still wins in a few places that matter in production. This isn't a dunk on TanStack. It's a short list of reasons you might still choose Next.js, especially for mostly-static content sites.

1. Static Server State, Prebuild, and ISR

To be clear: this is not about TanStack Query client caching. This is about static server state: how Server Components and page output get stored, served, and regenerated on the server (Next's Full Route Cache / Data Cache style setup). Off Vercel that usually means wiring a KV (or similar) so the framework can actually persist that page-level server state. On Vercel, a lot of that plumbing is already there.

Next.js makes this easy. You declare revalidation once and the framework owns the rest:

// Next.js -- page-level ISR / static server state
export const revalidate = 3600 // regenerate at most once per hour

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  return <Article post={post} />
}

TanStack Start does have prebuild capabilities, but you still end up manually setting cache headers (or whatever your platform expects) to get proper edge/CDN behavior. Cloudflare made this friendlier with Workers Cache and solid stale-while-revalidate support (so the pieces exist), but Next's declarative revalidate, revalidatePath, and revalidateTag story is cleaner when SEO and freshness matter at scale. Less platform glue, more "set a number and ship."

2. Suspense-Aware Routing (and the Query-Param Flicker)

Next's data fetching and router integrate more cleanly with Suspense. TanStack Router leans on an external store for a lot of its state, and that store doesn't register with Suspense the way you'd hope.

A common pain point: a list driven by search params (filters, page, sort). Change a param, TanStack tracks it, your useSuspenseQuery re-suspends, and the Suspense boundary flickers.

In Next.js you'd wrap the update in useTransition so React keeps showing the old UI until the new data is ready. Same trick on TanStack Router / Start? Mostly a no-op: the navigate still lands, the query still suspends, and you still get the fallback flash.

Workarounds (neither ideal):

Swap useSuspenseQuery for useQuery + keepPreviousData so you never hit a Suspense boundary on param changes. Old rows stay on screen; dim them with isFetching / isPlaceholderData.
If you're on a fully suspenseful library (e.g. Relay), you're mostly stuck. Compose so controls (search, pagination) live outside the suspending region and only the data pane suspends. Filters stay mounted, but you still get flicker in the list where startTransition would have held previous data.

Same patterns as the demos above, side by side:

// Pain: useSuspenseQuery + startTransition (no-op dampening)
function ProductsPage() {
  const { page, q } = Route.useSearch()
  const navigate = Route.useNavigate()
  const [isPending, startTransition] = useTransition()

  // Looks like the Next pattern. Does not hold previous UI here.
  // Router search updates aren't coordinated with Suspense the way
  // React state + use() are.
  function goToPage(nextPage: number) {
    startTransition(() => {
      navigate({ search: (prev) => ({ ...prev, page: nextPage }) })
    })
  }

  return (
    <>
      <Filters onPageChange={goToPage} />
      <div className={isPending ? "opacity-60" : ""}>
        <Suspense fallback={<ListSkeleton />}>
          <ProductResults page={page} q={q} />
        </Suspense>
      </div>
    </>
  )
}

function ProductResults({ page, q }: { page: number; q: string }) {
  // Changing page / q re-suspends → fallback flash
  // (even when navigate was wrapped in startTransition)
  const { data } = useSuspenseQuery(productsQueryOptions({ page, q }))
  return <ProductList products={data} />
}

// Workaround: useQuery + keepPreviousData (no Suspense flicker)
function ProductsPageKeepPrevious() {
  const { page, q } = Route.useSearch()
  const { data, isFetching, isPlaceholderData } = useQuery({
    ...productsQueryOptions({ page, q }),
    placeholderData: keepPreviousData,
  })

  return (
    <>
      <Filters />
      {/* dim via isFetching / isPlaceholderData */}
      <ProductList products={data} />
    </>
  )
}

// Next contrast: startTransition *does* hold the previous list
const [isPending, startTransition] = useTransition()

function selectColor(next: string) {
  startTransition(() => setColor(next)) // keeps old UI while Results suspends
}

3. Image and Font Optimization

For mostly-static sites chasing Lighthouse / Core Web Vitals, Next's next/image and next/font are still a real advantage. TanStack is working on this space, but today the built-in story isn't as strong. If those scores are a hard requirement, Next is the safer bet.

import Image from 'next/image'
import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'], display: 'swap' })

export default function Hero() {
  return (
    <div className={inter.className}>
      <Image src={hero} alt="" width={1200} height={630} priority sizes="100vw" />
    </div>
  )
}

next/image handles responsive sizes, lazy loading, and WebP/AVIF conversion out of the box. next/font subsets and self-hosts fonts to reduce CLS. In TanStack Start, you'd reach for Vite plugins like vite-imagetools or manual preload links. Both work, but require more configuration and ongoing maintenance.

4. React Canary Features (View Transitions) Built In

Another Next.js W: App Router ships on React canary, so features like the <ViewTransition> component are available without bolting on a separate experimental React install. Navigations already run inside React's startTransition, so the React-aware View Transition path can participate in the render lifecycle.

TanStack Start does support view transitions, but I've hit flashes of white before the animation starts. Part of that is the transition firing outside React's startTransition / Suspense coordination: blank paint, then the morph. It's also because the current TanStack implementation is the standard web View Transitions API: no React integration. Next gives you React's canary <ViewTransition> component, which actually participates in React's render lifecycle. Same feature name, very different depth of integration, and the React-aware path feels smoother out of the box.

Tanstack version has white flashes that do not appear in the nextjs one with the same style of css
To remedy this I found that addinga display none to the old view helped

Before (flash / underlay linger)

[data-style="wipe"]::view-transition-old(root) {
  animation: none; /* old page stays under the wipe */
}

[data-style="wipe"]::view-transition-new(root) {
  animation-name: reveal-dark;
}

The incoming page animates, but the outgoing snapshot stays painted underneath — so you see a blank/flash before the wipe finishes.

After (no flash)

[data-style="wipe"]::view-transition-old(root) {
  display: none; /* drop old snapshot immediately */
}

[data-style="wipe"]::view-transition-new(root) {
  animation-name: reveal-dark;
}

Only the new view participates. Same pattern on Next with React’s class target — swap root for .canvas-vt.

5. Ecosystem Fit

This one's more personal (it might not move the needle for everyone), but it matters a lot if you live in that stack.

Payload CMS is a strong pick when you're already on Next.js. It ties into the App Router cleanly, gives you a highly customizable backend without building half of it yourself, and leans on Server Components to get a lot done. That's a plus TanStack Start simply doesn't have today.

Big caveat: the Payload team has said they're working on TanStack support. After Start gained Server Components, they've been taking it more seriously. They've talked about a TanStack integration landing before the next major Payload release. Until that ships, if you want Payload in your React app today, Next.js is the option.

Closing: When I'd Still Bite the Complexity and Pick TanStack Start

Most of these gaps will shrink as Start matures (including a real Payload integration). For static, crawlable content where ISR, Suspense-friendly nav, image/font SEO, canary React features, or Next-native CMS matter, Next still has the edge.

But I'm a Start fanboy for a reason. Classic fit: a light landing page attached to a heavy, auth-gated dashboard. No bot crawls it. First paint of 80ms vs 800ms barely matters when the user is about to wrestle charts and filters. Paying Next's full server-render + static-server-state tax for that UI is wasted compute and DX.

What you gain instead:

Full useQuery power: fine-grained fetches, optimistic updates, cache as source of truth, without the App Router's mutation → revalidate → stream-diff loop.
Typed search params in the router. Share a URL; coworkers land on the same filters. In Next you'd bolt on nuqs; in TanStack Router it's first-class.
Rendering escape hatches: data-only (hydrate from server-fetched data) or SSR off. Dump heavy charting into the browser instead of keeping server compute warm for dashboards no bot will score.

Doing that shape in Next is hard. Wiring Query into the App Router fights you toward server actions that invalidate and re-render the whole page. For a per-user, constantly moving dashboard, that's a quiet inefficiency: throw the page away, re-render on the server, ship a diff, for data the next person won't even share. Why run dynamic server caching if nothing is shared?

Adam Rackis breaks down how TanStack's RSC model differs: explicit, opt-in, not your primary data path (React Server Components in TanStack). Loaders + Query own data; RSCs keep expensive non-interactive trees off the client. In Next, RSC is the center of gravity. That gap is why auth-gated dashboards feel native in Start and upstream in Next.

So: static / SEO / CMS → Next. Thin public shell + thick private dashboard → Start, any day. Even after listing all those rough edges.

🎨 TanStack Start SSR-Friendly Theme Provider

Dennis kinuthia — Fri, 25 Jul 2025 17:45:17 +0000

A complete theme management system for React applications with SSR support! ✨

🌟 Overview

This implementation provides a robust theme provider that handles:

🌙 Dark/Light mode switching
🖥️ System preference detection
💾 Persistent storage with localStorage
🚀 SSR-friendly initialization
⚡ Real-time theme updates
✅ No flash of unstyled content (FOUC)

🎭 The Provider: `ThemeProvider.tsx`

Key Features:

🔧 Manages theme state ('dark' | 'light' | 'system')
🗄️ Handles localStorage persistence
👂 Listens to system preference changes
⚡ Updates DOM classes dynamically

import { createContext, use, useEffect, useMemo, useState } from 'react'
import { FunctionOnce } from './lib/function-once'

export type ResolvedTheme = 'dark' | 'light'
export type Theme = ResolvedTheme | 'system'

interface ThemeProviderProps {
  children: React.ReactNode
  defaultTheme?: Theme
  storageKey?: string
}

interface ThemeProviderState {
  theme: Theme
  resolvedTheme: ResolvedTheme
  setTheme: (theme: Theme) => void
}

const initialState: ThemeProviderState = {
  theme: 'system',
  resolvedTheme: 'light',
  setTheme: () => null,
}

const ThemeProviderContext = createContext<ThemeProviderState>(initialState)

const isBrowser = typeof window !== 'undefined'

export function ThemeProvider({
  children,
  defaultTheme = 'system',
  storageKey = 'conar.theme',
}: ThemeProviderProps) {
  const [theme, setTheme] = useState<Theme>(
    () => (isBrowser ? (localStorage.getItem(storageKey) as Theme) : defaultTheme) || defaultTheme,
  )
  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>('light')

  useEffect(() => {
    const root = window.document.documentElement
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')

    function updateTheme() {
      root.classList.remove('light', 'dark')

      if (theme === 'system') {
        const systemTheme = mediaQuery.matches ? 'dark' : 'light'
        setResolvedTheme(systemTheme)
        root.classList.add(systemTheme)
        return
      }

      setResolvedTheme(theme as ResolvedTheme)
      root.classList.add(theme)
    }

    mediaQuery.addEventListener('change', updateTheme)
    updateTheme()

    return () => mediaQuery.removeEventListener('change', updateTheme)
  }, [theme])

  const value = useMemo(() => ({
    theme,
    resolvedTheme,
    setTheme: (theme: Theme) => {
      localStorage.setItem(storageKey, theme)
      setTheme(theme)
    },
  }), [theme, resolvedTheme, storageKey])

  return (
    <ThemeProviderContext value={value}>
      <FunctionOnce param={storageKey}>
        {(storageKey) => {
          const theme: string | null = localStorage.getItem(storageKey)

          if (
            theme === 'dark'
            || (
              (theme === null || theme === 'system')
              && window.matchMedia('(prefers-color-scheme: dark)').matches
            )
          ) {
            document.documentElement.classList.add('dark')
          }
        }}
      </FunctionOnce>
      {children}
    </ThemeProviderContext>
  )
}

// eslint-disable-next-line react-refresh/only-export-components
export function useTheme() {
  const context = use(ThemeProviderContext)

  if (context === undefined)
    throw new Error('useTheme must be used within a ThemeProvider')

  return context
}

🛠️ FunctionOnce Utility: `/lib/function-once.ts`

📜 Purpose: Executes JavaScript code once during SSR hydration

✅ Uses ScriptOnce from TanStack Router
🔄 Prevents hydration mismatches
🎨 Ensures theme is applied before first paint

import { ScriptOnce } from '@tanstack/react-router'

export function FunctionOnce<T = unknown>({ children, param }: { children: (param: T) => unknown, param?: T }) {
  return (
    <ScriptOnce>
      {`(${children.toString()})(${JSON.stringify(param)})`}
    </ScriptOnce>
  )
}

🏗️ Implementation Flow

🚀 Initial Load: Checks localStorage or defaults to system preference
👂 Event Listening: Monitors system theme changes via matchMedia
🎨 DOM Updates: Adds/removes CSS classes on documentElement
💾 Persistence: Saves theme choice to localStorage
🔄 Hydration: Uses FunctionOnce to prevent SSR/client mismatches

🎯 Example Usage: `/src/routes/__root.tsx`

Integration highlights:

🏠 App-wide theme provider wrapping
🔧 Integration with TanStack Router
🎨 Global CSS and styling setup
🛠️ Development tools integration

import type { QueryClient } from '@tanstack/react-query'
import { Toaster } from '@conar/ui/components/sonner'
import appCss from '@conar/ui/globals.css?url'
import { useMountedEffect } from '@conar/ui/hookas/use-mounted-effect'
import { ThemeProvider } from '@conar/ui/theme-provider'
import { QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import { createRootRouteWithContext, HeadContent, Outlet, Scripts, useRouterState } from '@tanstack/react-router'
import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
import { ErrorPage } from '~/error-page'
import { getLatestReleaseOptions, getRepoOptions, getUsersCountOptions } from '~/queries'
import { seo } from '~/utils/seo'

if (import.meta.env.DEV) {
  import('react-scan').then(({ scan }) => {
    scan()
  })
}

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient
}>()({
  beforeLoad: async ({ context }) => {
    if (typeof window !== 'undefined') {
      context.queryClient.prefetchQuery(getRepoOptions)
      context.queryClient.prefetchQuery(getLatestReleaseOptions)
      context.queryClient.prefetchQuery(getUsersCountOptions)
    }
  },
  head: () => ({
    meta: [
      {
        charSet: 'utf-8',
      },
      {
        name: 'viewport',
        content: 'width=device-width, initial-scale=1',
      },
      ...seo({
        title: 'Conar.app - AI-powered connections management tool',
        description: 'AI-powered tool that makes database operations easier. Built for PostgreSQL. Modern alternative to traditional database management tools.',
        image: '/og-image.png',
      }),
      { name: 'apple-mobile-web-app-title', content: 'Conar' },
    ],
    links: [
      { rel: 'stylesheet', href: appCss },
      { rel: 'icon', type: 'image/png', href: '/favicon-96x96.png', sizes: '96x96' },
      { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' },
      { rel: 'shortcut icon', href: '/favicon.ico' },
      { rel: 'apple-touch-icon', href: '/apple-touch-icon.png', sizes: '180x180' },
      { rel: 'manifest', href: '/site.webmanifest' },
    ],
    scripts: [
      {
        defer: true,
        src: 'https://assets.onedollarstats.com/stonks.js',
        ...(import.meta.env.DEV ? { 'data-debug': 'conar.app' } : {}),
      },
    ],
  }),
  component: RootComponent,
  errorComponent: props => <ErrorPage {...props} />,
})

function RootComponent() {
  const { queryClient } = Route.useRouteContext()
  const pathname = useRouterState({ select: state => state.location.pathname })

  useMountedEffect(() => {
    window.scrollTo({
      top: 0,
    })
  }, [pathname])

  return (
    <html suppressHydrationWarning>
      <head>
        <HeadContent />
      </head>
      <body className="bg-gray-100 dark:bg-neutral-950">
        <QueryClientProvider client={queryClient}>
          <ThemeProvider>
            <Outlet />
            <ReactQueryDevtools buttonPosition="bottom-left" />
          </ThemeProvider>
        </QueryClientProvider>
        <Toaster />
        <TanStackRouterDevtools position="bottom-right" />
        <Scripts />
      </body>
    </html>
  )
}

🌈 Benefits & Features

✅ Production-Ready Advantages

No FOUC (Flash of Unstyled Content) - Theme applied before first paint
Smooth SSR Hydration - No client/server mismatches
Automatic System Detection - Respects user's OS preference
Persistent Preferences - Remembers user's choice across sessions
TypeScript Support - Full type safety throughout
Performance Optimized - Minimal re-renders with useMemo

🎯 Usage Tips

Customization: Change storageKey prop to match your app's naming
Styling: Use CSS classes .dark and .light for theme-specific styles
Integration: Works seamlessly with Tailwind's dark: modifier
Testing: The suppressHydrationWarning prevents dev warnings during SSR

🚀 Quick Setup

Install dependencies: @tanstack/react-router
Copy the ThemeProvider.tsx and FunctionOnce.ts files
Wrap your app with <ThemeProvider>
Use useTheme() hook in components
Add CSS classes for .dark and .light themes

📚 References

This theme provider is battle-tested in production and handles all the tricky edge cases of SSR theme management! 🚀✨

Building Android Widgets in Expo with Custom Native Modules

Dennis kinuthia — Tue, 15 Jul 2025 13:17:13 +0000

A guide to creating Android home screen widgets using Expo modules, complete with state management, auto-updates, and best practices.

Overview
High-Level Process
Native Modules vs Native Views
Development Client Setup
Quick Start (TL;DR)
Prerequisites
Project Structure
Step-by-Step Implementation
Advanced Features
Best Practices
Troubleshooting
Examples
References

Overview

This guide demonstrates how to create Android home screen widgets in Expo applications using custom native modules. Unlike traditional widgets that exist independently, this approach allows seamless integration between your React Native app and Android widgets with shared state management.

What You'll Learn

Create custom Expo modules for Android widgets
Implement widget logic in Kotlin with Jetpack Compose Glance
Set up state management between app and widget
Configure auto-updating widgets with WorkManager
Use config plugins for build-time configurations

High-Level Process

Before diving into the specifics, here's the overall workflow for creating Android widgets in Expo:

1. Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     Expo React Native App                      │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐    ┌─────────────────┐                   │
│  │  Native Module  │◄──►│  Android Widget │                   │
│  │  (Bridge Layer) │    │  (Glance UI)    │                   │
│  └─────────────────┘    └─────────────────┘                   │
├─────────────────────────────────────────────────────────────────┤
│                   Android System Layer                         │
│  ┌─────────────────┐    ┌─────────────────┐                   │
│  │ App Manifest    │◄──►│ Widget Manifest │                   │
│  │ (Main Entry)    │    │ (Widget Entry)  │                   │
│  └─────────────────┘    └─────────────────┘                   │
└─────────────────────────────────────────────────────────────────┘

2. Build Process Flow

Development: Write widget code in Kotlin using Jetpack Compose Glance
Native Module: Create bridge between React Native and Android widget
Config Plugins: Configure build-time settings and manifest merging
Prebuild: expo prebuild merges widget manifest into main app manifest
Build: Standard Android build process includes widget in APK
Runtime: Widget appears in launcher, communicates with app via native module

3. Key Components

Jetpack Compose Glance: Modern UI framework for widgets
Expo Module: Bridge between React Native and native Android code
Config Plugins: Build-time configuration and manifest manipulation
WorkManager: Background tasks for widget updates
DataStore: Persistent state management for widgets

Native Modules vs Native Views

Understanding the distinction between native modules and native views is crucial for widget development:

Native Views

Purpose: Custom UI components rendered within the React Native app
Lifecycle: Managed by React Native's UI thread
Entry Point: React Native component tree
Examples: Custom buttons, charts, camera views
Manifest: No direct manifest entries needed

Native Modules (Our Choice)

Purpose: Bridge between JavaScript and native platform APIs
Lifecycle: Independent of React Native UI lifecycle
Entry Point: Native Android system (AndroidManifest.xml)
Examples: File system access, device sensors, widgets
Manifest: Requires explicit manifest declarations

Why We Use Native Modules for Widgets

// Widget exists independently of the React Native app
// Entry point is the Android system, not React Native
<receiver android:name="expo.modules.widget.widgets.MyWidgetReceiver">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
</receiver>

Key Reasons:

System Integration: Widgets are launched by the Android system, not React Native
Independent Lifecycle: Widgets must function even when the main app is closed
Manifest Entry Point: Widget receiver must be declared in AndroidManifest.xml
Background Operation: Widgets can update independently of the main app
System Services: Direct access to Android system services and broadcasts

Important: The widget's AndroidManifest.xml declarations (in the native module) get merged into the main app's manifest during expo prebuild, making the widget discoverable by the Android system.

Development Client Setup

Prerequisites

Before starting, ensure you have:

Expo CLI: npm install -g @expo/cli
Android Studio: Properly configured for React Native development (see Android Studio with react native Setup Guide)
Node.js: Version 18 or higher
Basic Knowledge: React Native, Kotlin, and Android development concepts

Using Expo Dev Client

For widget development, you'll need to use Expo Dev Client instead of Expo Go, as widgets require custom native code:

1. Install Development Build Dependencies

# Install expo-dev-client
npx expo install expo-dev-client

2. Configure Development Build

Add to your app.config.ts:

export default {
  expo: {
    name: "your-app-name",
    plugins: [
      "expo-dev-client",
      // Your widget config plugins
      "./modules/expo-widget-module/plugins/withWidgetConfig",
    ],
    ios: {
      bundleIdentifier: "com.yourcompany.yourapp",
    },
    android: {
      package: "com.yourcompany.yourapp",
    },
  },
};

3. Create Development Build

# For local development
npx expo run:android

# Or create a development build
eas build --profile development --platform android

4. Widget Testing Workflow

# 1. Make changes to widget code
# 2. Rebuild native code (required for native changes)
npx expo run:android

# 3. Test widget functionality
# 4. For JS-only changes, use fast refresh as normal

Note: Unlike pure JavaScript changes, widget modifications require a full native rebuild since they involve Kotlin code and manifest changes.

Quick Start (TL;DR)

Create Expo Module: Generate a new Expo module for your widget
Implement Widget Logic: Write Kotlin/Java code using Jetpack Compose Glance
Declare Widget: Add widget configuration to AndroidManifest.xml
Auto-Integration: Widget automatically includes when running expo prebuild
State Management: Create native module methods to update widget state
Auto-Updates: Use WorkManager with config plugins for background updates
Build Configuration: Use config plugins for project-level dependencies

Project Structure

your-expo-app/
├── modules/
│   └── expo-widget-module/
│       ├── android/
│       │   ├── src/main/java/expo/modules/widget/
│       │   │   ├── ExpoWidgetModule.kt
│       │   │   ├── widgets/
│       │   │   │   ├── MyWidget.kt
│       │   │   │   └── MyWidgetReceiver.kt
│       │   │   └── utils/
│       │   │       └── WidgetConstants.kt
│       │   └── build.gradle
│       ├── src/
│       │   ├── index.ts
│       │   └── ExpoWidgetModule.types.ts
│       ├── plugins/
│       │   └── withWidgetConfig.ts
│       └── expo-module.config.json
├── app.config.ts
└── package.json

Step-by-Step Implementation

Step 1: Create the Expo Module

# Create a new Expo module
npx create-expo-module expo-widget-module --local

# Navigate to the module directory
cd modules/expo-widget-module

Step 2: Configure Module Dependencies

Edit android/build.gradle:

dependencies {
  implementation project(':expo-modules-core')

  // Jetpack Compose Glance for widgets
  implementation "androidx.glance:glance-appwidget:1.0.0"
  implementation "androidx.glance:glance-material3:1.0.0"

  // WorkManager for background updates
  implementation "androidx.work:work-runtime-ktx:2.8.1"

  // DataStore for widget state
  implementation "androidx.datastore:datastore-preferences:1.0.0"

  // Coroutines
  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4"
}

Step 3: Implement the Widget

Create android/src/main/java/expo/modules/widget/widgets/MyWidget.kt:

package expo.modules.widget.widgets

import androidx.compose.runtime.Composable
import androidx.compose.ui.unit.dp
import androidx.compose.ui.unit.sp
import androidx.glance.GlanceId
import androidx.glance.GlanceModifier
import androidx.glance.appwidget.GlanceAppWidget
import androidx.glance.appwidget.provideContent
import androidx.glance.layout.Alignment
import androidx.glance.layout.Column
import androidx.glance.layout.fillMaxSize
import androidx.glance.layout.padding
import androidx.glance.text.FontWeight
import androidx.glance.text.Text
import androidx.glance.text.TextStyle
import androidx.glance.currentState
import androidx.glance.state.GlanceStateDefinition
import androidx.glance.state.PreferencesGlanceStateDefinition
import android.content.Context

class MyWidget : GlanceAppWidget() {

    override val stateDefinition: GlanceStateDefinition<*> = PreferencesGlanceStateDefinition

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        provideContent {
            WidgetContent()
        }
    }

    @Composable
    private fun WidgetContent() {
        val prefs = currentState<androidx.datastore.preferences.core.Preferences>()
        val title = prefs[stringPreferencesKey("widget_title")] ?: "Default Title"
        val subtitle = prefs[stringPreferencesKey("widget_subtitle")] ?: "Default Subtitle"

        Column(
            modifier = GlanceModifier
                .fillMaxSize()
                .padding(16.dp),
            verticalAlignment = Alignment.CenterVertically,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(
                text = title,
                style = TextStyle(
                    fontSize = 18.sp,
                    fontWeight = FontWeight.Bold
                )
            )

            Text(
                text = subtitle,
                style = TextStyle(
                    fontSize = 14.sp
                )
            )
        }
    }
}

Step 4: Create Widget Receiver

Create android/src/main/java/expo/modules/widget/widgets/MyWidgetReceiver.kt:

package expo.modules.widget.widgets

import androidx.glance.appwidget.GlanceAppWidget
import androidx.glance.appwidget.GlanceAppWidgetReceiver

class MyWidgetReceiver : GlanceAppWidgetReceiver() {
    override val glanceAppWidget: GlanceAppWidget = MyWidget()
}

Step 5: Implement the Native Module

Create android/src/main/java/expo/modules/widget/ExpoWidgetModule.kt:

package expo.modules.widget

import android.content.Context
import androidx.glance.appwidget.GlanceAppWidgetManager
import androidx.glance.appwidget.state.updateAppWidgetState
import androidx.glance.appwidget.updateAll
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
import expo.modules.kotlin.records.Field
import expo.modules.kotlin.records.Record
import expo.modules.widget.widgets.MyWidget
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import androidx.datastore.preferences.core.stringPreferencesKey

data class WidgetData(
    @Field val title: String,
    @Field val subtitle: String
) : Record

class ExpoWidgetModule : Module() {
    private val context: Context
        get() = requireNotNull(appContext.reactContext)

    override fun definition() = ModuleDefinition {
        Name("ExpoWidgetModule")

        AsyncFunction("updateWidget") { data: WidgetData ->
            CoroutineScope(Dispatchers.IO).launch {
                try {
                    val glanceIds = GlanceAppWidgetManager(context)
                        .getGlanceIds(MyWidget::class.java)

                    glanceIds.forEach { glanceId ->
                        updateAppWidgetState(context, glanceId) { prefs ->
                            prefs[stringPreferencesKey("widget_title")] = data.title
                            prefs[stringPreferencesKey("widget_subtitle")] = data.subtitle
                        }
                    }

                    MyWidget().updateAll(context)
                } catch (e: Exception) {
                    e.printStackTrace()
                }
            }
        }

        AsyncFunction("refreshWidget") {
            CoroutineScope(Dispatchers.IO).launch {
                try {
                    MyWidget().updateAll(context)
                } catch (e: Exception) {
                    e.printStackTrace()
                }
            }
        }
    }
}

Step 6: TypeScript Interface

Create src/ExpoWidgetModule.types.ts:

export interface WidgetData {
  title: string;
  subtitle: string;
}

export interface ExpoWidgetModuleEvents {
  updateWidget: (data: WidgetData) => void;
  refreshWidget: () => void;
}

Create src/index.ts:

import ExpoWidgetModule from './ExpoWidgetModule';
import type { WidgetData } from './ExpoWidgetModule.types';

export async function updateWidget(data: WidgetData): Promise<void> {
  return ExpoWidgetModule.updateWidget(data);
}

export async function refreshWidget(): Promise<void> {
  return ExpoWidgetModule.refreshWidget();
}

export type { WidgetData };

Step 7: Android Manifest Configuration

The widget needs to be declared in AndroidManifest.xml. Create a config plugin at plugins/withWidgetConfig.ts:

import { ConfigPlugin, withAndroidManifest } from '@expo/config-plugins';

const withWidgetConfig: ConfigPlugin = (config) => {
  return withAndroidManifest(config, (config) => {
    const { manifest } = config.modResults;

    if (!manifest.application) {
      manifest.application = [];
    }

    const application = manifest.application[0];

    if (!application.receiver) {
      application.receiver = [];
    }

    // Add widget receiver
    application.receiver.push({
      $: {
        'android:name': 'expo.modules.widget.widgets.MyWidgetReceiver',
        'android:exported': 'false',
      },
      'intent-filter': [
        {
          action: [
            { $: { 'android:name': 'android.appwidget.action.APPWIDGET_UPDATE' } },
          ],
        },
      ],
      'meta-data': [
        {
          $: {
            'android:name': 'android.appwidget.provider',
            'android:resource': '@xml/my_widget_info',
          },
        },
      ],
    });

    return config;
  });
};

export default withWidgetConfig;

Step 8: Widget Info XML

Create android/src/main/res/xml/my_widget_info.xml:

<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="250dp"
    android:minHeight="110dp"
    android:updatePeriodMillis="0"
    android:previewImage="@mipmap/ic_launcher"
    android:initialLayout="@layout/widget_loading"
    android:configure="expo.modules.widget.widgets.MyWidgetReceiver"
    android:widgetCategory="home_screen" />

Advanced Features

Auto-Updating with WorkManager

For widgets that need regular updates, implement WorkManager:

// In your ExpoWidgetModule.kt
AsyncFunction("scheduleWidgetUpdates") { intervalMinutes: Int ->
    val workRequest = PeriodicWorkRequestBuilder<WidgetUpdateWorker>(
        intervalMinutes.toLong(), TimeUnit.MINUTES
    ).build()

    WorkManager.getInstance(context).enqueueUniquePeriodicWork(
        "widget_update_work",
        ExistingPeriodicWorkPolicy.REPLACE,
        workRequest
    )
}

Config Plugin for WorkManager Initialization

Create a config plugin to initialize WorkManager in MainActivity:

import { ConfigPlugin, withMainActivity } from '@expo/config-plugins';

const withWorkManagerInit: ConfigPlugin = (config) => {
  return withMainActivity(config, (config) => {
    const { modResults } = config;

    // Add WorkManager initialization
    const workManagerInit = `
    import androidx.work.Configuration
    import androidx.work.WorkManager

    // In onCreate method
    WorkManager.initialize(this, Configuration.Builder().build())
    `;

    // Insert the initialization code
    // (Implementation depends on your specific needs)

    return config;
  });
};

export default withWorkManagerInit;

Best Practices

1. State Management

Use DataStore: For persistent widget state
Minimize Updates: Only update when necessary to save battery
Error Handling: Always wrap widget operations in try-catch blocks

2. Performance Optimization

Lazy Loading: Load data only when widget is visible
Caching: Cache frequently accessed data
Background Processing: Use coroutines for heavy operations

3. User Experience

Loading States: Show loading indicators during updates
Error States: Provide meaningful error messages
Responsive Design: Support different widget sizes

4. Development Workflow

Config Plugins: Use for build-time configurations
Never Edit android/ Directly: Use Expo prebuild for native changes
Version Control: Include generated files in .gitignore

Troubleshooting

Common Issues

Widget Not Appearing
- Check AndroidManifest.xml configuration
- Verify widget receiver is properly declared
- Ensure widget info XML is correctly configured
State Not Updating
- Verify DataStore keys match between update and display
- Check if widget is properly refreshed after state changes
- Ensure coroutines are running on correct dispatcher
Build Errors
- Check Gradle dependencies are correctly added
- Verify Kotlin version compatibility
- Ensure proper plugin configuration

Debug Tips

// Add logging to debug widget updates
import android.util.Log

Log.d("WidgetDebug", "Updating widget with title: ${data.title}")

Examples

Basic Usage in React Native

import { updateWidget } from 'expo-widget-module';

const handleUpdateWidget = async () => {
  try {
    await updateWidget({
      title: "Hello World",
      subtitle: "Updated from React Native"
    });
  } catch (error) {
    console.error("Failed to update widget:", error);
  }
};

Integration with App State

import { useEffect } from 'react';
import { AppState } from 'react-native';
import { refreshWidget } from 'expo-widget-module';

export function useWidgetSync() {
  useEffect(() => {
    const handleAppStateChange = (nextAppState: string) => {
      if (nextAppState === 'active') {
        refreshWidget();
      }
    };

    const subscription = AppState.addEventListener('change', handleAppStateChange);
    return () => subscription?.remove();
  }, []);
}

Conclusion

This guide provides a complete foundation for creating Android widgets in Expo applications. The combination of Jetpack Compose Glance, Expo modules, and config plugins enables powerful widget functionality while maintaining the simplicity of Expo development.

Key Takeaways

Modular Design: Keep widget logic separate from main app
State Management: Use DataStore for persistent widget state
Config Plugins: Automate build-time configurations
Best Practices: Follow Android widget development guidelines
Performance: Optimize for battery and memory usage

For more advanced use cases, consider exploring WorkManager for background tasks, Room database for complex data storage, and Material3 theming for consistent design.

References

Official Documentation & Videos

Official Google I/O Introduction to Jetpack Glance - Comprehensive overview of Jetpack Glance for building app widgets
How to Build a Widget that Updates using Jetpack Glance and Expo - Practical tutorial on widget development with Expo

Example Implementation

Moggin - WakaTime Glance Widgets - Complete working example of an Expo widget module with:
- WakaTime API integration
- Auto-updating widget with WorkManager
- Config plugins for build automation
- State management with DataStore
- Real-world production implementation

Additional Resources

Expo Modules Documentation - Official Expo modules guide
Jetpack Compose Glance Documentation - Android's official Glance documentation
Android App Widgets Overview - Comprehensive Android widget development guide

Repository Structure: This guide can be implemented as a complete example repository with working code samples, making it easy for developers to fork and customize for their specific needs.

Setting Up Android Studio on Linux for React Native (Expo) Development

Dennis kinuthia — Tue, 15 Jul 2025 12:44:43 +0000

This comprehensive guide will walk you through installing and configuring Android Studio on Linux specifically for React Native and Expo development. By the end of this guide, you'll have a fully functional development environment optimized for mobile app development.

Prerequisites
Installing Android Studio
Initial Android Studio Configuration
React Native/Expo Specific Setup
Environment Variables Configuration
Debugging and Development Tools
Common Issues and Solutions
Best Practices

Prerequisites

Before starting, ensure you have:

Ubuntu/Debian-based Linux distribution
At least 8GB of RAM (16GB recommended)
10GB+ of free disk space
Terminal access with sudo privileges
Basic knowledge of command line operations

Installing Android Studio

Step 1: Update Your System

First, update your package manager and system packages:

sudo apt update && sudo apt upgrade -y

Step 2: Install Android Studio

We'll use the official PPA repository for the most up-to-date version:

# Add the repository for Android Studio
sudo add-apt-repository ppa:maarten-fonville/android-studio -y

# Update package list
sudo apt update

# Install Android Studio
sudo apt install android-studio -y

Step 3: Verify Installation

Launch Android Studio to verify the installation:

android-studio

Initial Android Studio Configuration

Step 1: Complete the Setup Wizard

Welcome Screen: Click "Next" to start the setup wizard
Install Type: Choose "Standard" for typical development setup
UI Theme: Select your preferred theme (Darcula or Light)
SDK Components: The wizard will automatically download:
- Android SDK
- Android SDK Platform
- Android Virtual Device (AVD)
- Latest Android SDK build-tools

Step 2: Create a Test Project

To verify everything works correctly:

Create a new Kotlin project
Select "Empty Activity" template
Click "Finish" and wait for Gradle sync
Click the "Run" button (green play icon) to test compilation

React Native/Expo Specific Setup

Critical: Fix the Launch Script

This is essential for React Native/Expo projects to work properly with Android Studio.

Why this matters: The default launch script (studio.sh) doesn't load the Node.js environment properly, causing issues with Gradle configurations that use Node.js commands.

Method 1: Modify Desktop Entry

Edit the desktop application file:

sudo nano /usr/share/applications/android-studio.desktop

Change the Exec line from:

Exec=/opt/android-studio-2025.1.1/android-studio/bin/studio.sh

To:

Exec=/opt/android-studio-2025.1.1/android-studio/bin/studio

Method 2: Launch from Terminal

Alternatively, always launch Android Studio from the terminal:

/opt/android-studio-2025.1.1/android-studio/bin/studio

Note: Update the path according to your Android Studio version.

Understanding the Node.js Integration

React Native projects use Gradle configurations that execute Node.js commands:

def reactNativeAndroidDir = new File(
  providers.exec {
    workingDir(rootDir)
    commandLine("node", "--print", "require.resolve('react-native/package.json')")
  }.standardOutput.asText.get().trim(),
  "../android"
)

Without proper Node.js environment loading, these commands fail, causing build errors.

Environment Variables Configuration

Set Up JAVA_HOME and ANDROID_HOME

Add these environment variables to your ~/.bashrc or ~/.zshrc:

# Open your shell configuration file
nano ~/.bashrc

# Add these lines at the end:

# Set JAVA_HOME to the JDK bundled with Android Studio
export JAVA_HOME="/opt/android-studio-2025.1.1/android-studio/jbr"
export PATH="$JAVA_HOME/bin:$PATH"

# Android SDK paths
export ANDROID_HOME="$HOME/Android/Sdk"
export ANDROID_SDK_ROOT="$ANDROID_HOME"
export PATH="$ANDROID_HOME/platform-tools:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$PATH"

# React Native development
export PATH="$PATH:$ANDROID_HOME/emulator"
export PATH="$PATH:$ANDROID_HOME/platform-tools"

Apply the Changes

# Reload your shell configuration
source ~/.bashrc

# Verify the environment variables
echo $JAVA_HOME
echo $ANDROID_HOME

Verify SDK Installation

In Android Studio, go to:

File → Settings (or Android Studio → Preferences on some systems)
Appearance & Behavior → System Settings → Android SDK
Verify that the SDK path matches your ANDROID_HOME variable

Debugging and Development Tools

Android Studio's Built-in Tools

Android Studio provides excellent debugging tools for React Native/Expo development:

1. Logcat Tool Window

The Logcat window displays real-time logs from your device/emulator:

How to access:

View → Tool Windows → Logcat
Filter logs by app package name
Use different log levels (Verbose, Debug, Info, Warn, Error)

2. App Inspection Tool

For advanced debugging of background tasks, network requests, and databases:

How to access:

View → Tool Windows → App Inspection
Inspect network traffic
View database contents
Monitor background tasks

3. Device File Explorer

View and modify files on your device/emulator:

How to access:

View → Tool Windows → Device File Explorer
Navigate to /data/data/[your-app-package]/
Useful for debugging storage issues

Additional Development Tools

ADB (Android Debug Bridge):

   # List connected devices
   adb devices

   # Install APK
   adb install path/to/your/app.apk

   # View device logs
   adb logcat

Emulator Management:
- Tools → AVD Manager
- Create multiple device configurations
- Test different Android versions

Common Issues and Solutions

Issue 1: "Autolinking is not set up in settings.gradle"

This error occurs when Expo modules aren't properly configured in your Android project.

Solution:

First, try reopening Android Studio and reloading the project
Clean and reinstall dependencies:

   rm -rf node_modules
   npm install
   # or
   yarn install

Verify your android/settings.gradle file:

pluginManagement {
  def reactNativeGradlePlugin = new File(
    providers.exec {
      workingDir(rootDir)
      commandLine("node", "--print", "require.resolve('@react-native/gradle-plugin/package.json', { paths: [require.resolve('react-native/package.json')] })")
    }.standardOutput.asText.get().trim()
  ).getParentFile().absolutePath
  includeBuild(reactNativeGradlePlugin)

  def expoPluginsPath = new File(
    providers.exec {
      workingDir(rootDir)
      commandLine("node", "--print", "require.resolve('expo-modules-autolinking/package.json', { paths: [require.resolve('expo/package.json')] })")
    }.standardOutput.asText.get().trim(),
    "../android/expo-gradle-plugin"
  ).absolutePath
  includeBuild(expoPluginsPath)
}

plugins {
  id("com.facebook.react.settings")
  id("expo-autolinking-settings")
}

extensions.configure(com.facebook.react.ReactSettingsExtension) { ex ->
  if (System.getenv('EXPO_USE_COMMUNITY_AUTOLINKING') == '1') {
    ex.autolinkLibrariesFromCommand()
  } else {
    ex.autolinkLibrariesFromCommand(expoAutolinking.rnConfigCommand)
  }
}
expoAutolinking.useExpoModules()

rootProject.name = 'your-app-name'

expoAutolinking.useExpoVersionCatalog()

include ':app'
includeBuild(expoAutolinking.reactNativeGradlePlugin)

If the issue persists, regenerate native code:

   npx expo prebuild --clean

Issue 2: Gradle Sync Failures

Common causes and solutions:

Node.js not found: Ensure you're using the correct Android Studio launcher (not studio.sh)
JDK version mismatch: Use the bundled JDK in Android Studio
Network issues: Configure proxy settings if behind a corporate firewall

Issue 3: Emulator Performance Issues

Optimization tips:

Enable Hardware Acceleration:

   # Check if KVM is available
   grep -E "(vmx|svm)" /proc/cpuinfo

   # Install KVM if not present
   sudo apt install qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils

AVD Configuration:
- Allocate sufficient RAM (2GB minimum)
- Enable "Use Host GPU" in AVD settings
- Use x86_64 images for better performance

Best Practices

1. Project Structure

Never directly edit the android/ folder in Expo projects
Use Expo Config Plugins for native modifications
Keep custom native modules in separate directories

2. Autolinking Configuration

Only modify autolinking settings if you have specific requirements:

{
  "expo": {
    "name": "your-app-name",
    "autolinking": {
      "searchPaths": ["../../packages"],
      "nativeModulesDir": "../../packages"
    }
  }
}

3. Development Workflow

Use Expo CLI for project creation and management
Test on real devices when possible
Use Android Studio for:
- Native code debugging
- Performance profiling
- Advanced logging
- Build analysis

4. Version Management

Keep Android Studio updated
Use specific Android SDK versions for consistency
Document your environment setup in project README

Troubleshooting Checklist

Before asking for help, verify:

[ ] Android Studio launches with the correct script
[ ] Environment variables are set correctly
[ ] Node.js is accessible from Android Studio
[ ] Gradle can execute Node.js commands
[ ] Expo CLI is up to date
[ ] Project dependencies are installed

Conclusion

With Android Studio properly configured on Linux, you now have a powerful development environment for React Native and Expo projects. The key points to remember:

Use the correct launcher to ensure Node.js integration
Set up environment variables properly
Leverage Android Studio's debugging tools for efficient development
Follow Expo best practices for native code modifications

This setup will provide you with professional-grade tools for mobile app development, from initial coding to debugging and performance optimization.

vite-plugin-graphql-usage

Dennis kinuthia — Mon, 26 May 2025 09:36:00 +0000

🚀 Spent 5 hours automating a 5-minute task... and I regret nothing!

At work, I kept finding myself manually checking which GraphQL operations from our schema were actually implemented in our codebase. You know the drill - opening the schema file, scrolling through hundreds of queries/mutations, then grep-ing through the entire project to see what's actually being used.

repository

5 minutes per check × multiple times per week = death by a thousand paper cuts 📈

So naturally, I did what any self-respecting developer would do: I spent an entire weekend building a tool to automate it! 🛠️

Introducing vite-plugin-graphql-usage - a Vite plugin and CLI tool that:

✅ Introspects your GraphQL schema (endpoint or SDL file)

✅ Scans your codebase for operation usage

✅ Generates beautiful markdown reports with checkboxes

✅ Shows exactly where each operation is used (file + line number)

✅ Integrates seamlessly into your build process

The best part? It's completely non-intrusive - it analyzes your code without modifying anything.

// Just add to your vite.config.ts
viteGraphQLUsages({
  schemaSource: { 
    endpoint: 'https://api.example.com/graphql' 
  },
  printTable: true,
  saveReport: true
})

Now instead of manual detective work, I get automated reports like this:

📊 GraphQL Operations Report:
✅ Found: 47
❌ Not found: 23  
📊 Total operations: 70

The classic developer paradox: "I'll spend 5 hours automating something that takes 5 minutes... because those 5 minutes happen 100 times!" 😅

But honestly? This has already saved our team hours of manual work, helped us identify unused operations to clean up, and made onboarding new developers way smoother.

Sometimes the best solutions come from being just annoyed enough at repetitive tasks to do something about it! 🎯

Check it out: npm install vite-plugin-graphql-usage
repository

What's the most "unnecessary" automation you've built that turned out to be incredibly useful? Drop it in the comments! 👇

Understanding Discriminated Unions in TypeScript

Dennis kinuthia — Fri, 25 Apr 2025 09:01:47 +0000

Discriminated unions (also known as tagged unions) are a powerful TypeScript pattern that enables type-safe handling of values that could be of different types. They're especially useful when dealing with API responses, state management, or any scenario where you need to handle different outcomes.

What is a Discriminated Union?

A discriminated union is a data structure where:

Each possible type in the union contains a common property (the "discriminant")
This property has a different literal type for each variant
TypeScript uses this property to narrow down the type when checking conditions

The Problem with Regular Union Types

Consider our first example using regular union types:

type ErrorResponse = {
  message: string;
  statusCode: number;
  cause: string;
};

type SuccessResponse = {
  statusCode: number;
  data: Record<string, unknown>;
};

// Union type to represent the possible responses
type Result = ErrorResponse | SuccessResponse;

When working with this type, we need to use property checking to determine which type we're dealing with:

const fetchedData = await fetchData("https://example.com/api");

// Check for a property that only exists in one variant
if ("message" in fetchedData) {
  // TypeScript narrows fetchedData to ErrorResponse
  return { error: fetchedData.message };
}

// TypeScript narrows fetchedData to SuccessResponse
const response = fetchedData.data;

This approach has several issues:

It relies on the presence of specific properties
You need to know which properties are unique to each type
There's no guarantee that you've exhaustively handled all possibilities
Refactoring can easily break the type narrowing

The Solution: Discriminated Unions

A better approach is to use a discriminated union with an explicit tag:

type ErrorResponse = {
  message: string;
  statusCode: number;
  cause: string;
  response_type: "error";  // The discriminant
};

type SuccessResponse = {
  message: string;
  statusCode: number;
  data: Record<string, unknown>;
  response_type: "success";  // The discriminant
};

type Result = ErrorResponse | SuccessResponse;

With this pattern, type narrowing becomes explicit and reliable:

const fetchedData = await fetchData2("https://example.com/api");

if (fetchedData.response_type === "error") {
  // TypeScript knows fetchedData is ErrorResponse
  return { error: fetchedData.message };
}

// TypeScript knows fetchedData is SuccessResponse
const response = fetchedData.data;

Benefits of Discriminated Unions

Type Safety: TypeScript can verify that you've handled all possible cases.
Explicit Intent: The code clearly communicates the different possibilities.
Refactoring Resilience: Adding new variants forces you to update all the code that handles the union.
Self-Documenting: The discriminant property makes the code more readable.
IDE Support: Better autocomplete and error checking.

Real-World Example: API Response Handling

In our example application, we've implemented API response handling in two ways:

Without Discriminated Unions:

app.get("/create", async (c) => {
  const fetechedData = await fetchData("https://jsonplaceholder.typicode.com/posts");

  //  implicit ErrorResponse because of the error key
  if ("message" in fetechedData) {
    return c.json({ error: fetechedData.message }, 500);
  }

  // The type here is SuccessResponse & Record<"error", unknown>
  if ("error" in fetechedData) {
    return c.json({ error: fetechedData.error }, 500);
  }

  // implicit SuccessResponse because of the data key
  if ("data" in fetechedData) {
    return c.json({ message: fetechedData.data }, 500);
  }

  // We have to handle every possible case to avoid type errors
  const response = fetechedData.data;
  return c.json(response, 200);
});

With Discriminated Unions:

app.get("/create", async (c) => {
  const fetechedData = await fetchData2("https://jsonplaceholder.typicode.com/posts");

  // Using our discriminator we can easily narrow the type
  if (fetechedData.response_type === "error") {
    return c.json({ error: fetechedData.message }, 500);
  }

  // TypeScript knows fetechedData must be SuccessResponse2 here
  const response = fetechedData.data;
  return c.json(response, 200);
});

Best Practices

Use a Consistent Property Name: Common conventions are type, kind, or tag.
Use String Literals: They're more maintainable than numbers or booleans.
Make the Discriminant Required: Don't make it optional.
Keep the Union Simple: Don't overload with too many variants.
Use Exhaustiveness Checking: Ensure all variants are handled.

Conclusion

Discriminated unions provide a robust pattern for handling multiple related types in TypeScript. By adding a specific property with a unique value for each type variant, you gain compile-time safety and improved code clarity. This pattern is particularly valuable when dealing with operations that can produce different outcomes, like API responses or state transitions.

DEV Community: Dennis kinuthia

Setting up vector search for github starred repos

One query, end to end

The model: EmbeddingGemma

Documents and queries are embedded differently

One shared model instance

Quantization

ONNX Runtime inside a Deno Desktop binary

First run: the bootstrap

Storage: pgvector in PGlite

Search

The UI

What we built, and what's next

With all that said

Live activity bus (Elysia SSE + pub/sub powered by nodejs event emitter)

Why

The bus

Worked example: chat

1. The event type

2. The route: write, then publish

3. The stream: an async generator

4. The client: EventSource → query cache

5. The component

The same pattern for embedding progress

Limitations

Queues and workflows with conveyor

Why a worker

The engine: Conveyor + SQLite

Stage 1: the queue and its jobs

Stage 2: page through the stars

Stage 3: build the document and embed it

Stage 4: the worker

Staying under the rate limit

A GitHub token outside the request

Progress, restarts, and "done"

Things to know

Deno desktop Better Auth intergration

Why Better Auth

What already exists

Electron (official)

Tauri (community)

Asking upstream

What we took from all of this

Our flow

Step by step

1. Server: electron() + bearer() on the API

2. UI: ask the preload to start

3. Preload: PKCE, loopback, open the browser

4. Preload: the loopback server

5. Web: sign in, then hand the code to the loopback

6. Preload: exchange the code for a session

7. Session storage and authenticated calls

8. Tell the UI, and guard routes with bindings

9. The payoff: a GitHub token for the RAG corpus

Lessons learned

Wishlist for Deno Desktop

Deno Desktop the basics

What's the deal with Deno desktop

Server code just runs, no IPC

Bindings for the truly native bits

Why TanStack Start fits

Monorepo layout

deno.json: identity, backend, output

Dev loop: HMR, ports, env

The preload: native window + bindings

Server functions just work

Pairing TanStack Start with Elysia (for SSE)

1. Mount Elysia as a catch-all server route

2. Compose the app

3. A publish/subscribe example: /hello

4. A typed Eden client on both sides

5. Call it from React

Product objectives

How later chapters fit

Tanstack DB in action

Why it excites me

Joining data from multiple sources

Basic local-first functionality

The Basics

From useQuery to a collection

1. Server: `electron()` + `bearer()` on the API

`deno.json`: identity, backend, output

3. A publish/subscribe example: `/hello`

From `useQuery` to a collection

Querying with `useLiveQuery`

A meta object from `useLiveQuery` into the collection

`placeholderData` and `isRefetching`

🎭 The Provider: `ThemeProvider.tsx`

🛠️ FunctionOnce Utility: `/lib/function-once.ts`

🎯 Example Usage: `/src/routes/__root.tsx`