DEV Community: Dennis kinuthia

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.

Revisiting GraphQL in 2025: A Type-Safe Stack with Pothos and Relay

Dennis kinuthia — Tue, 15 Apr 2025 08:30:40 +0000

This article explores building a GraphQL server in 2025 using a modern, type-safe stack. We'll cover the tooling choices, backend setup with Pothos and Prisma, and frontend integration using Relay, highlighting the benefits for developer experience and application robustness.

If you prefer GFM markdown , read it on github

code reposotory

Section 1: Setting the Stage - Choosing the Right Tools for Type Safety

This section outlines the project requirements, the specific technology stack chosen, and the critical decision-making process for selecting libraries that ensure end-to-end type safety, ultimately leading to Pothos and Relay.

When tasked with building a new GraphQL server in 2025, the core requirements mandated the use of:

Node.js
Express
GraphQL
Prisma
PostgreSQL
TypeScript

The primary challenge was identifying tools that integrate seamlessly and provide strong end-to-end type safety guarantees. In an ideal scenario, the GraphQL types would be directly derived from the database schema managed by Prisma, minimizing type drift and manual synchronization efforts.

After evaluating several options, the choice narrowed down to two main contenders for building the GraphQL schema layer on top of Prisma:

Nexus: While a popular choice in the past, it appeared to lack support for the latest versions of Prisma at the time of evaluation, making it less suitable.
TypeGraphQL: Having used TypeGraphQL previously with TypeORM, I knew it worked well in that ecosystem. However, Prisma's schema-first approach differs significantly from TypeORM's entity-based model. I was uncertain how well Prisma's schema definition would align with the decorator-heavy, class-based approach central to TypeGraphQL.
Pothos: This library stood out due to its dedicated Prisma plugin (prisma-pothos-types), specifically designed to generate GraphQL types directly from the Prisma schema. This seemed like a natural fit for the project's goals.

Further investigation into Pothos revealed excellent support for Relay, including helpers for connections and node interfaces. This was a significant advantage, as the decision between using Relay or Apollo on the client-side was still pending. The strong type-safety features Relay offers, particularly for handling pagination and filtering, ultimately tipped the scales in its favor. Consequently, Pothos became the clear choice for the schema builder.

Section 2: Backend Implementation - Pothos, Prisma, and Express Integration

Here, we delve into the practical backend setup. This includes defining the database models with Prisma, configuring the Pothos schema builder, integrating it into an Express application using GraphQL Yoga, and creating GraphQL types, including derived fields.

The project itself was envisioned as a simple social network. For brevity and focus, we'll concentrate on the GraphQL-specific aspects, particularly around the Post model, omitting the general Express and TypeScript boilerplate. (The complete setup can be found here).

Let's examine the core Prisma schema, focusing on the User and Post models:

generator client {
  provider = "prisma-client-js"
  output   = "./generated/client"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// Pothos generator to create types from Prisma models
generator pothos {
  provider = "prisma-pothos-types"
}

model User {
  id            String    @id
  name          String
  email         String    @unique
  emailVerified Boolean
  image         String?
  createdAt     DateTime  @default(now()) // Corrected: Added default
  updatedAt     DateTime  @updatedAt
  sessions      Session[]
  accounts      Account[]

  // Social aspects
  posts         Post[]
  likes         Like[]
  comments      Comment[]
  // Follow relationships
  followers     Follow[]  @relation("following")
  following     Follow[]  @relation("follower")
  role          String?
  banned        Boolean?
  banReason     String?
  banExpires    DateTime?

  apikeys       Apikey[]

  @@map("user")
}

model Post {
  id        String   @id @default(ulid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  content   String
  imageUrl  String?
  // Relations
  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)
  authorId  String
  likes     Like[]
  comments  Comment[]
}

model Like {
  id        String   @id @default(ulid())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  // Relations
  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  userId    String
  post      Post     @relation(fields: [postId], references: [id], onDelete: Cascade)
  postId    String

  // Ensure a user can only like a post once
  @@unique([userId, postId])
}

Next, we configure the Pothos schema builder, specifying the Prisma client and enabling plugins like Relay support:

// Define the generic types for the Pothos builder, including Prisma types and Context
export type PothosBuilderGenericType = { // Corrected Typo: PothosBuilderGenericTYpe -> PothosBuilderGenericType
  PrismaTypes: PrismaTypes;
  Context: {
    currentUser?: Pick<User, "id" | "email" | "name">; // Context includes optional current user
  };
};

// Instantiate the builder with necessary plugins and configurations
export const builder = new SchemaBuilder<PothosBuilderGenericType>({ // Corrected Typo: PothosBuilderGenericTYpe -> PothosBuilderGenericType
  plugins: [PrismaPlugin, RelayPlugin], // Enable Prisma and Relay plugins
  relay: {}, // Basic Relay configuration
  prisma: {
    client: prisma, // Provide the Prisma client instance
    // Expose Prisma schema /// comments as GraphQL descriptions
    exposeDescriptions: true,
    // Use Prisma's filtering capabilities for Relay connection total counts
    filterConnectionTotalCount: true,
    // Warn about unused query parameters during development
    onUnusedQuery: process.env.NODE_ENV === "production" ? null : "warn",
  },
});

This builder is then used to generate the executable GraphQL schema, which is passed to the GraphQL Yoga server integrated with Express:

// graphql/builder.ts
import { lexicographicSortSchema, printSchema } from "graphql";
// Generate the schema object from the Pothos builder
export const pothosSchema = builder.toSchema();

// Export the schema definition as a string (SDL)
export const pothosSchemaString = printSchema(lexicographicSortSchema(pothosSchema));


// index.ts - Server setup
import express from 'express'; // Added import for clarity
import { createYoga } from 'graphql-yoga'; // Added import for clarity
import { fromNodeHeaders } from '@whatwg-node/server'; // Added import for clarity
import { auth } from './auth'; // Assuming auth setup exists
import { prisma } from './prismaClient'; // Assuming prisma client export exists
import { PothosBuilderGenericType, builder, pothosSchema, pothosSchemaString } from './graphql/builder'; // Assuming builder exports exist
// import { PrismaClient, User } from '@prisma/client'; // Assuming Prisma types import

const app = express(); // Added instantiation
const port = process.env.PORT || 4000; // Added port definition

// Configure GraphQL Yoga server
const yoga = createYoga<{
  req: express.Request;
  res: express.Response;
}>({
  // Use Apollo Sandbox for the GraphiQL interface
  renderGraphiQL: () => {
    // HTML to embed Apollo Sandbox
    return `
        <!DOCTYPE html>
        <html lang="en">
          <body style="margin: 0; overflow-x: hidden; overflow-y: hidden">
          <div id="sandbox" style="height:100vh; width:100vw;"></div>
          <script src="https://embeddable-sandbox.cdn.apollographql.com/_latest/embeddable-sandbox.umd.production.min.js"></script>
          <script>
          new window.EmbeddedSandbox({
            target: "#sandbox",
            initialEndpoint: "http://localhost:${port}/graphql", // Dynamic port
          });
          </script>
          </body>
        </html>`;
  },
  schema: pothosSchema, // Pass the generated Pothos schema
  // Define the context function to inject data (like authenticated user) into resolvers
  context: async (ctx): Promise<PothosBuilderGenericType['Context']> => { // Typed context return
    try {
      const session = await auth.api.getSession({ // Assuming auth setup provides getSession
        headers: fromNodeHeaders(ctx.req.headers),
      });
      if (!session?.user) { // Check specifically for user object in session
        return {
          currentUser: undefined, // Explicitly undefined if no user
        };
      }
      // Provide relevant user details to the context
      return {
        currentUser: {
          id: session.user.id,
          email: session.user.email ?? undefined, // Handle potentially null email
          name: session.user.name ?? undefined,   // Handle potentially null name
        },
      };
    } catch (error) {
      console.error("Error resolving context:", error); // Add error logging
      return { currentUser: undefined };
    }
  },
  graphiql: true, // Enable GraphiQL interface
  logging: true, // Enable logging
  cors: true, // Enable CORS
});

// Bind GraphQL Yoga to the /graphql endpoint
// @ts-expect-error - Yoga types might mismatch slightly with Express middleware types
app.use(yoga.graphqlEndpoint, yoga);

// Define a simple root query required by GraphQL
builder.queryType({
  fields: (t) => ({
    hello: t.string({
      resolve: () => "Hello world!",
    }),
    // Other root queries will be added here...
  }),
});

// Placeholder for other express routes/middleware
// app.get('/', (req, res) => res.send('Server is running!'));

app.listen(port, () => {
  console.log(`🚀 Server ready at http://localhost:${port}/graphql`);
  console.log(`🚀 GraphQL Playground available at http://localhost:${port}/graphql`); // Adjusted log message
});

With the basic server running, we can define GraphQL types based on our Prisma models. Pothos makes this straightforward. We could create a direct 1-to-1 mapping:

// Example of a simple Post type mapping (Not the final version used)
/*
export const SimplePostType = builder.prismaNode("Post", {
  id: { field: "id" },
  fields: (t) => ({
    postId: t.exposeString("id", { nullable: false }), // Expose Prisma 'id' as 'postId'
    content: t.exposeString("content"),
    imageUrl: t.exposeString("imageUrl"),
    createdAt: t.exposeString("createdAt", { // Directly expose createdAt as string
      type: "String", // Define the GraphQL type
    }),
    updatedAt: t.exposeString("updatedAt", { // Directly expose updatedAt as string
      type: "String",
    }),
    // Example resolver for the author relation
    postedBy: t.relation("author", {
       type: UserType // Assuming UserType is defined elsewhere
    })
  }),
});
*/

However, for a feed, we often need derived data specific to the viewing user (e.g., "Have I liked this post?"). Pothos allows defining variants of Prisma types or adding custom fields easily. Here's the FeedPost type incorporating likeCount and likedByMe:

// Define the Fren (User) type first if not already defined
// Assuming a basic User type 'Fren' exists or is defined similarly
export const Fren = builder.prismaNode("User", { // Example Fren type definition
  id: { field: "id" },
  fields: (t) => ({
    frenId: t.exposeString("id"), // Expose 'id' as 'frenId'
    name: t.exposeString("name"),
    email: t.exposeString("email"),
    image: t.exposeString("image"),
    // Add other user fields as needed
  }),
});


// Define the enhanced FeedPost type using prismaNode and custom fields
export const FeedPost = builder.prismaNode("Post", {
  // Using a variant allows multiple GraphQL types based on the same Prisma model if needed
  // variant: "FeedPost", // Optional: Define a variant name
  id: { field: "id" }, // Map the 'id' field for Relay Node interface
  fields: (t) => ({
    postId: t.exposeString("id", { nullable: false }), // Expose DB 'id' as 'postId'
    content: t.exposeString("content"),
    imageUrl: t.exposeString("imageUrl", { nullable: true }), // Explicitly nullable
    // Custom resolver for ISO string date format
    createdAt: t.field({
      type: "String",
      resolve: (post) => post.createdAt.toISOString(),
    }),
    // Custom resolver for ISO string date format
    updatedAt: t.field({
      type: "String",
      resolve: (post) => post.updatedAt.toISOString(), // Corrected: use updatedAt
    }),
    // Field resolving the User who posted this
    postedBy: t.field({
      type: Fren, // Reference the 'Fren' (User) type
      nullable: false, // Author should always exist
      resolve: async (parent, args, context) => {
        // Fetch the author using the authorId from the parent Post
        const author = await prisma.user.findUnique({
          where: { id: parent.authorId },
        });
        if (!author) {
          // Handle case where author is somehow not found, though schema constraints should prevent this
          throw new Error(`Author not found for post ${parent.id}`);
        }
        return author;
      },
    }),
    // Custom field to calculate the number of likes
    likeCount: t.field({
      type: "Int",
      resolve: async (parent) => {
        // Count likes associated with the parent Post's id
        return prisma.like.count({
          where: { postId: parent.id },
        });
      },
    }),
    // Custom field to check if the current user liked this post
    likedByMe: t.field({
      type: "Boolean",
      resolve: async (parent, args, context) => {
        // If no user is logged in, they haven't liked it
        if (!context.currentUser?.id) return false;
        // Check if a Like record exists for this user and post
        const like = await prisma.like.findUnique({ // Use findUnique for efficiency
          where: {
            userId_postId: { // Use the @@unique constraint defined in Prisma
              userId: context.currentUser.id,
              postId: parent.id,
            }
          },
        });
        // Return true if a like exists, false otherwise
        return !!like;
      },
    }),
  }),
});

Finally, we add a query to fetch posts, utilizing Pothos's Relay connection helper (prismaConnection) for automatic pagination setup:

// Extend the root query type with a field to fetch feed posts
builder.queryType({
  fields: (t) => ({
    // ... existing fields like 'hello'
    hello: t.string({ // Keeping the hello query from before
      resolve: () => "Hello world!",
    }),
    // Define the feedPosts query using Relay connections
    feedPosts: t.prismaConnection({
      type: FeedPost, // The type of nodes in the connection
      cursor: "id", // Field used for cursor-based pagination
      resolve: (query, parent, args, context, info) => {
        // Resolve by fetching posts from Prisma, applying connection arguments (like 'first', 'after')
        return prisma.post.findMany({
          ...query, // Spreads Relay arguments (first, after, etc.) into Prisma query
          orderBy: {
            createdAt: "desc", // Order posts by creation date, newest first
          },
        });
      },
    }),
  }),
});

Section 3: Frontend Integration - Consuming the API with Relay Fragments

This section transitions to the frontend, demonstrating how to leverage Relay's fragment-driven architecture. We'll cover fetching the schema, defining GraphQL fragments co-located with React components, and using Relay hooks to fetch and display data.

Pothos's built-in support for Relay connections is crucial here. The t.prismaConnection helper automatically generates the necessary GraphQL types for Relay pagination (like QueryFeedPostsConnection and QueryFeedPostsConnectionEdge), saving significant boilerplate.

# Auto-generated GraphQL types by Pothos prismaConnection
type QueryFeedPostsConnection {
  edges: [QueryFeedPostsConnectionEdge] # List of edges (cursor + node)
  pageInfo: PageInfo!                  # Information about the current page
}

type QueryFeedPostsConnectionEdge {
  cursor: String!                       # Opaque cursor for pagination
  node: FeedPost                        # The actual Post data
}

# Standard Relay PageInfo type
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Why is this structure important? Relay relies heavily on this standardized connection model for efficient pagination and data fetching.

To integrate with the frontend (assuming a React setup with Relay configured), a common first step is to fetch the latest GraphQL Schema Definition Language (SDL) generated by our backend API. This allows the Relay compiler to validate queries and generate types.

// Example API endpoint to serve the SDL
// (Add this within your Express setup in index.ts or a separate routes file)
app.get("/sdl", (req, res) => {
  res.type("application/graphql").send(pothosSchemaString); // Set content type
});

// Example script on the frontend (e.g., scripts/fetchSdl.ts)
import "dotenv/config"; // If using environment variables for API URL
import fs from "fs/promises";

export async function getSdl() {
  try {
    const apiUrl = process.env.VITE_API_URL || "http://localhost:4000"; // Default or from env
    console.log(`Workspaceing SDL from ${apiUrl}/sdl...`);
    const res = await fetch(`${apiUrl}/sdl`);
    if (!res.ok) {
      throw new Error(`Failed to fetch SDL: ${res.status} ${res.statusText}`);
    }
    const sdl = await res.text();
    await fs.writeFile("./schema.graphql", sdl); // Save to root or specified path
    console.log("✅ SDL fetched and saved to schema.graphql");
  } catch (error) {
    console.error("❌ Error fetching SDL: ", error); // Improved error logging
  }
}

// Run the script (e.g., via package.json script)
getSdl();

Relay encourages a "colocation" principle: data requirements (fragments) are defined alongside the components that use them. This differs from traditional REST approaches where a parent component might fetch all data and pass it down. In Relay, leaf components define their data needs via fragments, which are composed upwards into parent fragments and finally into a single page query.

Here's how fragments might look for our social feed:

# src/components/FeedCard.tsx (or similar) - Fragment defining data needed by a single post card
# Naming Convention: ComponentName_propName
export const FeedCardFragment = graphql`
  fragment FeedCard_post on FeedPost {
    id # Global Relay ID
    postId # Our application-specific ID
    content
    imageUrl
    createdAt
    likeCount
    likedByMe
    updatedAt
    postedBy {
      # We can include fragments from other components here too if needed
      # Or specify the fields directly:
      frenId # User's ID (exposed as frenId in our Fren type)
      name
      email
      image
      # Assuming 'amFollowing' fields were added to the 'Fren' type on the backend
      # amFollowing
    }
  }
`;

# src/components/MainFeed.tsx - Fragment defining the list of posts needed by the feed container
export const MainFeedFragment = graphql`
  # Fragment on the Query type, defining arguments for pagination
  fragment MainFeed_feedPosts on Query @argumentDefinitions(
    first: { type: "Int", defaultValue: 10 }, # How many items to fetch
    after: { type: "String" } # Cursor for pagination
  ) {
    # Use the feedPosts connection field defined in our backend query
    feedPosts(first: $first, after: $after) {
      edges {
        node {
          id # Needed for mapping and keys
          ...FeedCard_post # Include the data requirements from the child component
        }
      }
      pageInfo { # Needed for pagination logic
        hasNextPage
        endCursor
      }
    }
  }
`;


# src/pages/FeedPage.tsx (or container component) - The main query for the page
export const MainFeedQuery = graphql`
  # This query includes the MainFeed fragment, passing arguments down
  query MainFeedContainerQuery($first: Int!, $after: String) {
    ...MainFeed_feedPosts @arguments(first: $first, after: $after)
  }
`;

Note: The Relay compiler requires these graphql tagged literals to be in the same file as the component that uses the corresponding fragment or query. After defining these, run the Relay compiler (relay-compiler) to generate TypeScript types and runtime artifacts.

Here's how these fragments and queries are used in React components:

// src/pages/FeedPage.tsx - Root component for the feed view
import React from 'react';
import { useLazyLoadQuery } from 'react-relay';
import { MainFeedContainerQuery } from './__generated__/MainFeedContainerQuery.graphql'; // Import generated types
import { MainFeedQuery } from './MainFeed'; // Import the query definition
import { MainFeed } from '../components/MainFeed'; // Import the component using the fragment

export function FeedPage() { // Renamed component for clarity
  // Fetch the initial data for the page using the main query
  const queryData = useLazyLoadQuery<MainFeedContainerQuery>(MainFeedQuery, { first: 10 }); // Fetch initial 10 posts

  return (
    <div className="w-full py-4">
      {/* Pass the query data (specifically the part matching the fragment) to the MainFeed component */}
      <MainFeed queryRef={queryData} />
    </div>
  );
}


// src/components/MainFeed.tsx - Component rendering the list of posts
import React from 'react';
import { useFragment } from 'react-relay';
import { MainFeed_feedPosts$key } from './__generated__/MainFeed_feedPosts.graphql'; // Import fragment type
import { MainFeedFragment } from './MainFeed'; // Import fragment definition (assuming it's here or imported)
import { PostCard } from "./FeedCard"; // Import the child component

interface FeedProps {
  queryRef: MainFeed_feedPosts$key; // Prop type expects the fragment $key
}

export function MainFeed({ queryRef }: FeedProps) { // Renamed component
  // Use the useFragment hook to read data defined by the MainFeedFragment
  const data = useFragment(
    MainFeedFragment,
    queryRef
  );

  // Extract post nodes safely
  const posts = data?.feedPosts?.edges?.map(edge => edge?.node) ?? []; // Use optional chaining and nullish coalescing

  // Render the list of posts, passing each post's data (as a fragment ref) to PostCard
  return (
    <div className="w-full max-w-2xl mx-auto">
      {posts.map((post) => post && (
        // Pass the individual post fragment reference to the PostCard
        <PostCard key={post.id} postRef={post} />
      ))}
      {/* Pagination controls will be added later */}
    </div>
  );
}


// src/components/FeedCard.tsx - Component rendering a single post
import React from 'react';
import { useFragment } from 'react-relay';
import { FeedCard_post$key } from "./__generated__/FeedCard_post.graphql"; // Import fragment type
import { FeedCardFragment } from './FeedCard'; // Import fragment definition (assuming it's here or imported)
// Assuming Card components are imported from a UI library like ShadCN/UI
import { Card, CardContent /* ... other Card parts */ } from '@/components/ui/card';


interface PostCardProps {
  postRef: FeedCard_post$key; // Prop type expects the fragment $key for a single post
  // viewer?: BetterAuthViewer; // Example of passing other props if needed
}

export function PostCard({ postRef }: PostCardProps) { // Removed viewer prop for simplicity
  // Use useFragment to read the data defined by FeedCardFragment
  const postData = useFragment<FeedCard_post$key>(FeedCardFragment, postRef);

  // Early return if postData is somehow null/undefined (though Relay usually prevents this if ref is valid)
  if (!postData) {
    return null;
  }

  // Example: Using derived data or formatting
  // const postIdFirstChars = postData?.id.substring(0, 2).toUpperCase();

  return (
    <Card className="w-full mb-4 border-none bg-base-300">
      <CardContent className="pt-6">
        {/* Display post content, author info, like button, etc. using postData */}
        <p>{postData.content}</p>
        {/* ... other card elements ... */}
        <span>Likes: {postData.likeCount}</span>
        <span>{postData.likedByMe ? 'You liked this' : 'Like'}</span>
      </CardContent>
    </Card>
  )
}

Section 4: Advanced Relay - Effortless Pagination and Mutation Handling

This final section covers more advanced Relay capabilities facilitated by Pothos and Relay's design. We'll implement infinite scrolling/pagination using usePaginationFragment and demonstrate how Relay handles data mutations (updates, creates, deletes) with automatic and manual cache management.

While the initial setup fetches posts, real-world feeds require pagination (e.g., infinite scroll or "Load More"). Relay excels here, especially when combined with Pothos's connection fields.

First, we modify the MainFeedFragment to make it suitable for pagination using the @refetchable and @connection directives:

# src/components/MainFeed.tsx - Updated fragment for pagination
export const MainFeedFragment = graphql`
  fragment MainFeed_feedPosts on Query
  # Define arguments for pagination, Relay needs these defined here
  @argumentDefinitions(
    first: { type: "Int", defaultValue: 10 }, # Default items per page
    after: { type: "String" } # Cursor to fetch items after
  )
  # Make this fragment refetchable, generating a MainFeedPaginationQuery
  @refetchable(queryName: "MainFeedPaginationQuery") {
    # Specify the connection field
    feedPosts(first: $first, after: $after)
    # Identify this specific connection in the Relay store
    @connection(key: "MainFeed_feedPosts", filters: []) {
      edges {
        cursor # Needed for pagination
        node {
          id
          ...FeedCard_post # Include child fragment
        }
      }
      pageInfo {
        endCursor
        hasNextPage # Crucial for knowing if more data is available
        # Optional:
        # hasPreviousPage
        # startCursor
      }
    }
  }
`;

Now, the MainFeed component can use the usePaginationFragment hook provided by Relay:

// src/components/MainFeed.tsx - Updated component using usePaginationFragment
import React from 'react';
// Import the specific pagination query type generated by @refetchable
import { MainFeedPaginationQuery } from "./__generated__/MainFeedPaginationQuery.graphql";
import { MainFeed_feedPosts$key } from './__generated__/MainFeed_feedPosts.graphql';
import { usePaginationFragment } from 'react-relay';
import { PostCard } from "./FeedCard";
import { MainFeedFragment } from './MainFeed'; // Import fragment definition
// Assuming Button and Loader components are imported
import { Button } from '@/components/ui/button';
import { Loader2 } from 'lucide-react';

interface FeedProps {
  queryRef: MainFeed_feedPosts$key;
}

export function MainFeed({ queryRef }: FeedProps) {
  // Use usePaginationFragment hook
  const {
    data,       // The accumulated data for the connection
    loadNext,   // Function to load the next page
    hasNext,    // Boolean indicating if more pages exist
    isLoadingNext // Boolean indicating if the next page is currently loading
  } = usePaginationFragment<MainFeedPaginationQuery, MainFeed_feedPosts$key>(
    MainFeedFragment, // The fragment definition
    queryRef         // The fragment reference passed from the parent
  );

  // Function to trigger loading more posts
  const loadMorePosts = () => {
    // Prevent multiple requests or loading if no more data
    if (isLoadingNext || !hasNext) return;
    loadNext(5); // Load the next 5 items (or adjust count as needed)
  };

  // Extract post nodes from the accumulated data
  const posts = data?.feedPosts?.edges?.map(edge => edge?.node) ?? [];

  return (
    <div className="w-full max-w-2xl mx-auto">
      {posts.map((post) => post && (
        <PostCard key={post.id} postRef={post} />
      ))}

      {/* Display a "Load More" button if there's a next page */}
      {hasNext && (
        <div className="flex justify-center my-4">
          <Button onClick={loadMorePosts} variant="outline" disabled={isLoadingNext}>
            {isLoadingNext ? (
              <>
                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
                Loading more posts...
              </>
            ) : (
              "Load More Posts"
            )}
          </Button>
        </div>
      )}
    </div>
  );
}

This setup provides smooth pagination with minimal manual effort. If you've wrestled with pagination logic using libraries like Apollo Client, the simplicity here is particularly noteworthy.

Finally, let's look at mutations (creating, updating, deleting data). A great feature of Relay is that if a mutation returns the same fragment that was mutated (identified by the global id), Relay often updates the local store automatically.

For example, an edit mutation:

# src/components/PostDialogs.tsx (or similar) - Edit Mutation
const editPostMutation = graphql`
  mutation PostDialogsEditMutation($id: ID!, $content: String, $imageUrl: String) { # Use global ID!
    # Assume backend mutation 'updatePost' takes global ID
    updatePost(input: {id: $id, content: $content, imageUrl: $imageUrl}) { # Example input object
      # Return the fragment for the updated post
      updatedPostEdge { # Assuming mutation returns an edge or node
         node {
           ...FeedCard_post # Spreading the fragment triggers automatic update if ID matches
         }
      }
    }
  }
`;

However, for creating new items or deleting existing ones, the cache doesn't automatically know where the new item should go in a list (connection) or that an item should be removed. We need to provide an updater function.

Creating a Post:

# src/components/PostDialogs.tsx - Create Mutation
const createPostMutation = graphql`
  mutation PostDialogsCreateMutation($content: String!, $imageUrl: String) {
    # Assume backend mutation 'createPost' takes content/imageUrl
    createPost(input: { content: $content, imageUrl: $imageUrl }) {
      # Return the fragment for the newly created post, wrapped in an edge
      newPostEdge { # Standard Relay practice to return the new edge
         cursor
         node {
            ...FeedCard_post # Include the fragment data
         }
      }
    }
  }
`;

// src/components/PostDialogs.tsx - Usage of create mutation
import { useMutation, ConnectionHandler } from 'react-relay';
import { PostDialogsCreateMutation } from './__generated__/PostDialogsCreateMutation.graphql'; // Generated type

// Inside your component...
const [commitCreateMutation, isCreating] = useMutation<PostDialogsCreateMutation>(createPostMutation);
// Assuming 'setError' state hook exists
const setError = (e: Error | null) => { /* ... */ };
// Assuming PostFormData type exists
type PostFormData = { content: string; imageUrl?: string };

const handleCreateSubmit = (data: PostFormData) => {
  setError(null);
  commitCreateMutation({
    variables: {
      content: data.content,
      imageUrl: data.imageUrl || undefined, // Use undefined if optional
    },
    // Updater function to manually insert the new post into the connection
    updater: (store) => {
      // Get the newly created post edge from the mutation response payload
      const payload = store.getRootField("createPost"); // Matches mutation name
      const newEdge = payload?.getLinkedRecord("newPostEdge"); // Matches field in mutation response

      if (!newEdge) {
        console.error("Failed to get new edge from createPost mutation payload");
        return;
      }

      // Get the connection record from the store
      const root = store.getRoot();
      // Use the connection key defined in the @connection directive
      const connection = ConnectionHandler.getConnection(
        root,
        "MainFeed_feedPosts" // Must match the key in MainFeedFragment @connection
      );

      if (!connection) {
         console.error("Failed to find connection MainFeed_feedPosts in store");
        return;
      }

      // Insert the new edge at the beginning of the connection
      ConnectionHandler.insertEdgeBefore(connection, newEdge);
    },
    onError: (error) => {
       setError(error);
       console.error("Create post failed:", error);
    }
  });
};

Deleting a Post:

# src/components/PostDialogs.tsx - Delete Mutation
const deletePostMutation = graphql`
  mutation PostDialogsDeleteMutation($id: ID!) { # Use global ID!
    deletePost(input: { id: $id }) {
      deletedPostId # Return the ID of the deleted post
    }
  }
`;

// src/components/PostDialogs.tsx - Usage of delete mutation
import { useMutation, ConnectionHandler } from 'react-relay';
import { PostDialogsDeleteMutation } from './__generated__/PostDialogsDeleteMutation.graphql';

// Inside your component, assuming 'post' object with 'id' (global Relay ID) exists
// const post: { id: string, postId: string /* ... other fields */ };
const [commitDeleteMutation, isDeleting] =
  useMutation<PostDialogsDeleteMutation>(deletePostMutation);
const setError = (e: Error | null) => { /* ... */ };

const handleDeletePost = () => {
  setError(null);

  commitDeleteMutation({
    variables: {
      id: post.id, // Pass the global Relay ID
    },
    // Updater function to remove the node from the connection
    updater: (store) => {
      // Get the ID of the deleted post from the payload
      const payload = store.getRootField("deletePost");
      const deletedId = payload?.getValue("deletedPostId"); // Matches field in mutation

      if (typeof deletedId !== 'string') {
         console.error("Could not get deletedPostId from payload");
         return;
      }

      // Get the connection
      const root = store.getRoot();
      const connection = ConnectionHandler.getConnection(root, "MainFeed_feedPosts");

      if (!connection) {
         console.error("Failed to find connection MainFeed_feedPosts in store");
        return;
      }

      // Remove the node using its ID
      ConnectionHandler.deleteNode(connection, deletedId);
    },
    // Optimistic updater removes the item from the UI immediately
    optimisticUpdater: (store) => {
        const root = store.getRoot();
        const connection = ConnectionHandler.getConnection(root, "MainFeed_feedPosts");
        if (connection) {
          // Remove the node optimistically using its known ID
          ConnectionHandler.deleteNode(connection, post.id);
        }
    },
    onError: (error) => {
       setError(error);
       console.error("Delete post failed:", error);
    }
  });
};

By combining Pothos on the backend for easy schema generation and Relay integration with Relay on the frontend for its powerful data fetching, fragmentation, and cache management capabilities, we achieved a highly type-safe and efficient GraphQL setup for this 2025 project. The synergy between these tools significantly improves the developer experience when dealing with complex data interactions.

If you prefer GFM markdown , read it on github

code reposotory

How to get the Oauth providre access tokens from next auth/authjs

Dennis kinuthia — Thu, 20 Feb 2025 20:02:25 +0000

Modify your nextauth client and add a callbacks section that will

get the access token from the oauth provider
get the user profile from the oauth provider
store the access token and user profile in the session
store the access token and user profile in the token
modify the jwt payload to include the access token and user profile

import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const githubScopes = ["user", "repo", "delete_repo"] as const;

export const { handlers, signIn, signOut, auth } = NextAuth({
  pages: {
    signIn: "/auth",
  },
  providers: [
    GitHub({
      authorization: {
        params: {
          scope: githubScopes.slice(0, -2).join(" "),
        },
      },
      //  @ts-expect-error
      async profile(profile) {
      return { ...profile } // get the user oauth profile
    },
    }),
  ],
  debug: true,
  callbacks: {
    jwt: async ({ token, user,account }) => {
      if (account) {
        token.accessToken = account.access_token;
      }
      if (user) {
        token.user = user; // Include the full user profile in the token
      }
      return token;

    },
    session: async ({ session, token }) => {
      // @ts-expect-error
      session.accessToken = token.accessToken; // Include the access token in the session
      // @ts-expect-error
      session.user = token.user;
      return session;

    },
    authorized: async ({ auth }) => {
      // Logged in users are authenticated, otherwise redirect to login page
      return !!auth;
    },
      async redirect({ url, baseUrl }) {
        // redirect to the dashboard if the user is signed in
      return `${baseUrl}/dashboard`;
    },
  },
});

to fix the types create a next-auth.d.ts file

// next-auth.d.ts
import "next-auth";
import { DefaultSession } from "next-auth";

declare module "next-auth" {
  /**
   * Extends the `Session` interface to include custom fields.
   * This is merged with the default `Session` type from NextAuth.js.
   */
  interface Session {
      accessToken?: string;
    user: GithubUser & DefaultSession["user"]; // Merge with default user fields
  }
}

export type GithubUser={
  login: string
  id: string
  node_id: string
  avatar_url: string
  gravatar_id: string
  url: string
  html_url: string
  followers_url: string
    ....other fie;lds
}

How to select oauth scopes in next-auth / authjs

Dennis kinuthia — Thu, 20 Feb 2025 16:38:43 +0000

You can select the scopes you want to request from GitHub/your oauthprovider in the login page, and then the scopes will be passed to the OAuth provider.

firstly look up th eoauth scopes allowed for example the github ones are oauth scopes documentation

then we can do it in 2 ways

globally in your nextauth client

import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";

export const githubScopes = ["user", "repo", "delete_repo"] as const;

export const { handlers, signIn, signOut, auth } = NextAuth({
  pages: {
    signIn: "/auth",
  },
  providers: [
    GitHub({
      authorization: {
        params: {
          scope: githubScopes.join(" "),
        },
      },
    }),
  ],
  debug: true,
  callbacks: {
    authorized: async ({ auth }) => {
      // Logged in users are authenticated, otherwise redirect to login page
      return !!auth;
    },
  },
});

in the login page > useful when you want to conditionally select the scopes >[!NOTE] > use the signin for client side login , and make sure the component has a "use client" directive

"use client";
import { signIn } from "next-auth/react";
import { useState } from "react";
import { FaGithub } from "react-icons/fa";

interface OauthButtonProps {}

export function OauthButton({}: OauthButtonProps) {
  const [selectedScopes, setSelectedScopes] = useState<string[]>([]);

  const scopeOptions = [
    {
      id: "user",
      label: "User Profile",
      description: "Read/Write access to profile info",
    },
    {
      id: "repo",
      label: "Repository Access",
      description: "Full control of public and private repositories",
    },
    {
      id: "delete_repo",
      label: "Delete Repositories",
      description: "Ability to delete repositories",
    },
  ];

  const handleScopeToggle = (scope: string) => {
    setSelectedScopes((prev) =>
      prev.includes(scope) ? prev.filter((s) => s !== scope) : [...prev, scope]
    );
  };

  return (
    <div className="w-full flex flex-col justify-center items-center gap-5">
      <div className=" flex flex-col justify-center items-center gap-2">
        {selectedScopes.length === 0 && (
          <div role="alert" className="alert alert-info alert-outline">
            <span className="text-xs text-center">
              if no scopes are selected, 
              the default read-only access to public information will be used
            </span>
          </div>
        )}
        {scopeOptions.map((scope) => (
          <label
            key={scope.id}
            className="flex w-full bg-primary/10 items-start space-x-3 p-3 rounded-lg hover:bg-base-300 transition-colors">
            <input
              type="checkbox"
              className="checkbox checkbox-accent mt-1 border border-accent"
              checked={selectedScopes.includes(scope.id)}
              onChange={() => handleScopeToggle(scope.id)}
            />
            <div className="flex flex-col">
              <span className="font-medium">{scope.label}</span>
              <span className="text-sm text-base-content/70">{scope.description}</span>
            </div>
          </label>
        ))}
      </div>
      <button
        className="btn btn-wide btn-accent w-full"
        onClick={() =>
          signIn(
            "github",
            {},
            {
              scope: selectedScopes.join(" ") || undefined,
            }
          )
        }>
        <FaGithub className="h-5 w-5" />
        Sign in with GitHub
      </button>
    </div>
  );
}

[!NOTE]
The scopes should be a space separated string , eg "repo user delete_repo"

React devs KE 🇰🇪 Meetup February 2025 | Crafting Reusable Code with React & TypeScript: From Design to NPM

Dennis kinuthia — Sun, 02 Feb 2025 13:49:19 +0000

slides used in the presentation

building the generic component

In this example we'll use a tale to demostrate how to build a generic component that adapts to any type of data

to go from a fully
hardcoded componenst to a
more dynamic one

we first put
the tables rows into an array and then pass that array to the component which we
loop over to get the table rows

And the same can also be done to
the columns

and now our table mponent can take in the data and the columns and then render
the table rows and columns

type Player = {
  id: number;
  name: string;
  age: number;
  rank: number;
}

type TableColumn = {
  label: string;
  accessor: keyof Player;
};
interface DynamicPlayerstableProps {
  columns: Array<TableColumn>;
  data: Array<Player>;
}

export function DynamicPlayerstable({data,columns}: DynamicPlayerstableProps) {
    return ....
}

Our players table component

is now decoupled from the data but we can take this further by decouping it from
the shape of data. In it's current form it requires us to pass in data like this

const columns: Array<TableColumn> = [
  { label: "ID", accessor: "id" },
  { accessor: "name", label: "Name" },
  { accessor: "age", label: "Age" },
  { accessor: "rank", label: "Rank" },
];

const data: Array<Player> = [
  { id: 1, name: "Player1", age: 25, rank: "Silver" },
  { id: 2, name: "Player2", age: 30, rank: "Gold" },
  { id: 3, name: "Player3", age: 22, rank: "Bronze" },
  { id: 4, name: "Player4", age: 28, rank: "Platinum" },
  { id: 5, name: "Player5", age: 24, rank: "Diamond" },
  { id: 6, name: "Player6", age: 27, rank: "Silver" },
  { id: 7, name: "Player7", age: 29, rank: "Gold" },
];
return <DynamicPlayerstable columns={columns} data={data} />;

The table structure is dynamic enough to accomodate any array of objects we pass
in with the only required field being od id because we use it as the key to
every row

<tbody>
  {data.map((player) => (
    <tr key={player.id}>
      {columns.map((column) => (
        <td key={column.accessor}>{player[column.accessor]}</td>
      ))}
    </tr>
  ))}
</tbody>

To accomplish this we'll need to use a generic type usuaally maerked as T which is a way to pass in variables to out types and interfaces

firdt we pass it into the component

export function DynamicPlayerstable<T>({ data, columns }: DynamicPlayerstableProps);

then we pass it into our parameter interface

interface DynamicPlayerstableProps<T> {
  columns: Array<TableColumn>;
  data: Array<Player>;
}

export function DynamicPlayerstable<T>({ data, columns }: DynamicPlayerstableProps<T>);

this type T should be the type of the object that we pass in to the array so we can now replace type Player with T

interface DynamicPlayerstableProps<T> {
  columns: Array<TableColumn>;
  data: Array<T>;
}

our TbaleColumn type was also relying on the type Player so the type is also going to change to TableColumn<T> so we can now replace type Player with T

At this point typescipt will be able to give us auto complete for the coluns field based on what type T is based on the array we pass into the data field

with player rows array

with teams row array

Out component is working fine from the outside but typescript is having a hader time understanding the types inside the component sine generice type T could be any type and it's keys could be numver|string|symbol , symbols aren't allowed as react keys so we can narrow that type by using an intersection & to inform typescrpt that the keys of T must be a string like we had in type Player

type TableColumn<T> = {
  label: string;
  accessor: keyof T & string;
};
interface DynamicPlayerstableProps<T> {
  columns: Array<TableColumn<T>>;
  data: Array<T>;
}

That resolves that issue but introduces another one where typescipt doesn't know what type T is and what type T[keyof T] is going to resolve to

Because in it's current shape bothe

type Player = {
  id: number;
  name: string;
  age: number;
  rank: string;
};
//  and

type playeyWithArrays = {
  id: Array<number>;
  name: Array<string>;
  age: Array<number>;
  rank: Date;
  ratio: {
    numerator: number;
    denominator: number;
  };
};

[!TIP]
any type can be passed into the component as type T , react and our table doesn't expect that and will throw an error if we try to render an array or Date object in a td or any react node . so to further specify what inputs we expect we can use the extends operator

[!NOTE]
in typescript it's either used to inherit behaviour from a class or to mark a generic type as a subtype of another more specific type

T extends string // can only accept strings
T extends {} // can only accept objects
T extends {id:number} // can only accept objects with a key `id` that is a number
T extends Record<string, string | number> // can only accept objects with string or number keys

We'll use this to specify that only objects with string or number keys can be passed into the table

[!NOTE]
Record<TKey, TValue> can be used to specify objects

type TableColumn<T extends Record<string, string|number >> = {
  label: string;
  accessor: keyof T & string;
};
interface GenericTableProps<T extends Record<string, string|number >> {
  columns: Array<TableColumn<T>>;
  data: Array<T>;
}

export function GenericTable<T extends Record<string, string|number >>

now with this we can only pass in objects that have string or number keys

const data = [
  {
    id: 1,
    name: "John Doe",
    age: 30,
    rank: "Gold",
  },
];
const baddata = [
  {
    id: 1,
    name: "John Doe",
    age: [30],
    rank: new Date(),
  },
];

before restrictions

after restrictions

one last thing is rqeire type T to include a key id because it's going to be used as the key for the table rows

type GenericItem = Record<string, string | number> & { id: string }; // field of id:string required in passed in objects
type TableColumn<T extends GenericItem> = {
  label: string;
  accessor: keyof T & string;
};
interface GenericTableProps<T extends GenericItem> {
  columns: Array<TableColumn<T>>;
  data: Array<T>;
}

export function GenericPlayerstable<T extends GenericItem>({ data, columns }: GenericTableProps<T>);

[!TIP]
Bonus tip : handling nested objects

const data = [
  {
    id: "1",
    name: "John Doe",
    age: 30,
    rank: "Gold",
    ratio: {
      numerator: 1,
      denominator: 2,
    },
  },
];

This type will cause issues because field ratio is an object and we can't render it directly in the table because react can't render objects as its children

First the Record type should also intersect with an object type

// now lets the value of the record to be an object
type GenericItem = Record<string, string | number | object> & { id: string };
type TableColumn<T extends GenericItem> = {
  label: string;
  accessor: PossibleNestedUnions<T, 10> & string;
};

interface GenericTableProps<T extends GenericItem> {
  title:string;
  description?:string;
  columns: Array<TableColumn<T>>;
  data: Array<T>;
}

Then we add checks to handle object types

          <tbody>
            {data.map((row) => (
              <tr key={row.id}>
                {columns.map((column) => {
                  const value = row[column.accessor];
                  // this line grabs the nested object and maps it to a <td>
                  if (column.accessor.includes(".")) {
                    return <td key={column.accessor}>{getNestedProperty(row, column.accessor)}</td>;
                  }
                  //  we've already checked if the accessor is a nested object but typescript is not yet aware and 
                  // still thinks value is type string | number | objct at this point 
                  //  this part is only here to narrow the type or catch objects types that fell through
                  //  so that the value type on the section below is of type string | number
                  if (typeof value === "object") {
                    const nestedValue = getNestedProperty(row, column.accessor)
                    if(typeof nestedValue !== "string" || typeof nestedValue !== "number") {
                      // to avoid accidentally trying to renedr objects as react children
                      return <td key={column.accessor}>{JSON.stringify(nestedValue)}</td>;
                    }
                    return <td key={column.accessor}>{getNestedProperty(row, column.accessor)}</td>;
                  }
                  // value type is string| number , safe to render ina react td 
                  return <td key={column.accessor}>{value}</td>;
                })}
              </tr>
            ))}
          </tbody>

getNestedProperty is a utility function to retrieve a nested property value from an object based on a dot-separated path

example

const obj = { a: { b: { c: 42 } } };
console.log(getNestedProperty(obj, "a"));   // Outputs: { b: { c: 42 } }
console.log(getNestedProperty(obj, "a.b.c")); // Outputs: 42
console.log(getNestedProperty(obj, "a.b.x")); // Outputs: undefined

so how do we get the types to the dot separated values? this one is non trivial and one of the examples of the ugly typescript people hate.
PossibleNestedUnions uses recursion to extract the dot separated keys to inputs of type nested object

example

type ExampleType = {
  a: string;
  b: {
    c: number;
    d: {
      e: boolean;
      f: {
        g: string;
      };
    };
  };
  h: Date;
};

type NestedKeys1 = PossibleNestedUnions<ExampleType, 1>;  // "a" | "b" | "h"
type NestedKeys2 = PossibleNestedUnions<ExampleType, 2>;  // "a" | "b" | "b.c" | "b.d" | "h"
type NestedKeys3 = PossibleNestedUnions<ExampleType, 3>;  // "a" | "b" | "b.c" | "b.d" | "b.d.e" | "b.d.f" | "h"
type NestedKeysAll = PossibleNestedUnions<ExampleType>;   // includes all nested paths

and now our new type will be

import { PossibleNestedUnions } from "../types/nested_objects_union";
import { getNestedProperty } from "../utils/object";

type GenericItem = Record<string, string | number | object>&{id:string}
type TableColumn<T extends GenericItem> = {
  label: string;
  accessor: PossibleNestedUnions<T> & string;
};
interface GenericTableProps<T extends GenericItem> {
  columns: Array<TableColumn<T>>;
  data: Array<T>;
}

with the array

   const gooddata = [
     {
       id: "1",
       name: "John Doe",
       age: 30,
       rank: "Gold",
       stats:{
        running:20,
        jumping:10,
        swimming:30,
        weapons:{
          stars:10,
          katana:5
        }
       }
     },
     {
       id: "2",
       name: "Pedro",
       age: 30,
       rank: "Gold",
       stats:{
        running:20,
        jumping:10,
        swimming:30,
        weapons:{
          stars:1,
          katana:4,
          blades:{
            short:10,
            long:5
          }
        }
       }
     },
   ];

we'll get auto complete for all the possibly nested types

Finally we can make the title and description of the table dynamic too because we can render more than just players with this component

      <GenericTableWithNestedFields
      title="Players Table"
        description="list of players without their stats"
        data={gooddata}
        columns={[
          { accessor: "id", label: "age" },
          { accessor: "name", label: "name" },
          { accessor: "age", label: "age" },
          { accessor: "rank", label: "rank" },
        ]}
      />
      <GenericTableWithNestedFields
      title="Players Table with stats"
        description="list of players with their stats"
        data={gooddata}
        columns={[
          { accessor: "id", label: "age" },
          { accessor: "name", label: "name" },
          { accessor: "age", label: "age" },
          { accessor: "rank", label: "rank" },
          { accessor: "stats.running", label: "running" },
          { accessor: "stats.jumping", label: "jumping" },
          { accessor: "stats.swimming", label: "swimming" },
          { accessor: "stats.weapons.blades.short", label: "katana" },
        ]}
      />

publishing to npm

Publishing to npm requires 3 things

a nodejs project
a package.json file . an npm account

in our case we also need

tsconfig for typescript
tsup for transpiling (we could use tsc for this too)

create a node project

npm init -y
npm install typescript --save-dev
tsc --init

we'll change the tsconfig to look like this source + explanation

{
  "compilerOptions": {
    /* Base Options: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,

    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,

    /* If transpiling with TypeScript: */
    // "module": "NodeNext",
    "outDir": "dist",
    // "sourceMap": true,

    /* AND if you're building for a library: */
    "declaration": true,

    /* AND if you're building for a library in a monorepo: */
    // "composite": true,
    // "declarationMap": true,

    /* If NOT transpiling with TypeScript: */
    "module": "preserve",
    "noEmit": true,
    /* If your code doesn't run in the DOM: */
    // "lib": ["es2022"]
    /* If your code runs in the DOM: */
    "lib": ["es2022", "dom", "dom.iterable"],
    // if you want to use JSX (react)
    "jsx":"react-jsx",

    "paths": {
      "@/*": ["./src/*"]
    },

  },
  // only files under `src` will be transpiled
  "include": ["src"],
  // exclude files under `dist` and `node_modules`
  "exclude": ["dist", "node_modules"]
}

Our file will be in the src directory with an index.ts file as the main entrypoint

[!NOTE]
Entrypoint is the file that is executed when the package is imported

example

// my-table-package is the name of the package which is the default entrypoint
import { GenericTable } from "my-table-package";

entry points are defined in the package.json file

{
  "name": "my-table-package",
  "version": "1.0.0",
  "type": "module",
  // our transipiled file will be in the `dist` directory
  "files": [
    "dist"
  ],
  // our entrypoint is the `index.ts` file
  "main": "dist/index.js",
  // the exports field is a newer syntax for node 16+ that allows for multiple entrypoints
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    // we can also define exports for specific files
    "/styles":"./dist/index.css"
  },
  // peer dependencies are dependencies that we expect the user of the package to already have installed , if we're unsure that thy'll have it we put it i the dependencies field (it might lead to bigger final size)
    "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0",
    "tailwindcss": "^3.0.0 || ^4.0.0",
    "daisyui": " ^4.0.0 || ^5.0.0-beta"
  },
  // devDependencies are dependencies that are only used for development and don't get included in the final package
  // if uo have peer dependencies u can put them in dev dependencies
  "devDependencies": {
    "@arethetypeswrong/cli": "^0.17.3",
    "@changesets/cli": "^2.27.12",
    "@eslint/js": "^9.19.0",
    "@types/node": "^22.12.0",
    "@types/react": "^19.0.8",
    "daisyui": "5.0.0-beta.6",
    "eslint": "^9.19.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "tailwindcss": "^4.0.1",
    "tsup": "^8.3.6",
    "typescript": "^5.7.3"
  }
}

We'll build this package using tsup . we can use tsc (the typescript compiler) to build the package but that would require some changes

//tsconfig.json
{
   /* If transpiling with TypeScript: */
    "module": "NodeNext",
    "sourceMap": true,
}

which requires that all our import should end with the file extension name

import { GenericTable } from "./src/components/GenericTable";
// to be 
import { GenericTable } from "./src/components/GenericTable.js";

which can be a bit much if we already have the code we want to publish
to use tsup we just add a config

//tsup.config.ts
import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts","src/components/RedSquare.tsx"],
  splitting: false,
  format: ["cjs", "esm"],
  dts: true,
  clean: true,
  minify: false,
  platform: "browser", 
});

and with our build script

{
  "scripts": {
    "dev": "tsup --watch",
    "build": "tsup",
    "format": "prettier --write .",
    "typecheck": "tsc",
    "lint": "eslint --quiet .",
    "ci:version": "changeset version",
    "ci:release": "changeset publish",
    "release": "changeset publish --no-git-checks",
    "check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm --profile node16"
  }
}

npm run build

the outputs should be in the dist directory
and tio test if our component works (am using pnpm)
we check the working directory using pwd then head to the project we want to install the package in and run

 pnpm install <file-path-to-package>

which adds a linked package like this

  "dependencies": {
    "@tailwindcss/vite": "^4.0.1",
    //locally linked package
    "my-table-package": "link:/home/dennis/Desktop/packaging/my-table-package",
    "pp": "^1.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "tailwindcss": "^4.0.1"
  }

[!NOTE]
if u're not using pnpm u can use npm link instead of pnpm install

[!WARNING]
This will only work if you build yoour project locally where the package project also is , if you ad this to a projecct that get's build in CI or any other machnie it will not work

to make it usable by everyone we publish it to npm using

npm publish

[!NOTE]
once at least one project installs your library it will be
undeletable from the npm registry

Extras

check exports with are the types correct to chek if everything is being exported correctly

{
  "scripts": {
    "dev": "tsup --watch",
    "build": "tsup",
    "format": "prettier --write .",
    "typecheck": "tsc",
    "lint": "eslint --quiet .",
    "ci:version": "changeset version",
    "ci:release": "changeset publish",
    "release": "changeset publish --no-git-checks",
    "check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm --profile node16"
  }
}

npm run check-exports

create a changelog
write unit tests
use other entrypoint , useful for
- optimize and minimize the bundle size by allowing tree-shaking
- separate and organize code into logical modules for better maintainability
- enable independent development and testing of different components
- facilitate conditional loading of features based on environment or user preferences
- improve application startup time by loading only necessary code
- enhance code reuse across different parts of the application or projects

example

// /src/inde: main entrypoint contents

import { GenericTable } from "./components/GenericTable";
import { GenericTableWithNestedFields } from "./components/GenericTableWithNestedFields";
import { HardCodedTable } from "./components/HardCodedTable";

export {
  GenericTable,
  GenericTableWithNestedFields,
  HardCodedTable
};

import { defineConfig } from "tsup";

export default defineConfig({
  // our entrypoint is the `index.ts` file
  // RedSquare.tsx component will be build with it's own entrypoint
  entry: ["src/index.ts","src/components/RedSquare.tsx"],
  splitting: false,
  format: ["cjs", "esm"],
  dts: true,
  clean: true,
  minify: false,
  platform: "browser",

});

{
      "exports": {
      // default entrypoint  
      ".": {
        "import": "./dist/index.js",
        "require": "./dist/index.cjs"
      },
      //  /redbox entrypoint
      "./redbox": "./dist/components/RedSquare.js"
    },
}

// import the default entrypoint
import { GenericTable } from "my-table-package";
// import the redbox entrypoint
import { RedBox} from "my-table-package/redbox";

The end

Cookies auto clearing after browser refresh issue , CORS related express cookies issue

Dennis kinuthia — Sun, 12 Jan 2025 09:56:19 +0000

This error is a combination of CORS issues and incorrect cookie settings.
To resolve you need to set your server to allow cookies and set the same origin policy to allow the frontend to make requests to your backend server.

cors

// cors-utils.ts
import type { Request, Response, NextFunction } from "express";

export function corsHeaders(req: Request, res: Response, next: NextFunction) {
  if (!req.headers.origin) return next();
  if (allowedOrigins.includes(req.headers.origin)) {
    res.setHeader("Access-Control-Allow-Credentials", "true");
    res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE");
    next();
  }
}
export const allowedOrigins = [
  "http://localhost:3000",
  process.env.FRONTEND_URL ?? "",
];

//  app.ts
app.use(corsHeaders);
app.use(
  cors({
    origin: (origin, callback) => {
      if ((origin && allowedOrigins.indexOf(origin) !== -1) || !origin) {
        callback(null, true);
      } else {
        callback(new Error("Not allowed by CORS"));
      }
    },
    optionsSuccessStatus: 200,
  }),
);

and create the cookies using the options

import jwt from "jsonwebtoken";
const { sign, verify } = jwt;

const accessTokencookieOptions = {
      httpOnly: true,
      secure:true,
      sameSite: "none",
      path: "/",
      maxAge: 12 * 60 * 1000, // expires in 12 minutes
}

const accessTokebCookieKey = "rfsh-token";
  const fiftenMinutesInSeconds = Math.floor(Date.now() / 1000) + 60 * 15; // 15 minutes
  const accessToken = await sign(
    { ...sanitizedPayload, exp:  : fiftenMinutesInSeconds },
    ACCESS_TOKEN_SECRET,
  );
  res.clearCookie(accessTokebCookieKey, accessTokencookieOptions);
  res.cookie(accessTokebCookieKey, accessToken, accessTokencookieOptions);

DEV Community: Dennis kinuthia

Tanstack DB in action

Why it excites me

Joining data from multiple sources

Basic local-first functionality

The Basics

From useQuery to a collection

Querying with useLiveQuery

Joining with another collection

Handling non-array responses

Reading pagination metadata from the query store

Pagination

Client-side infinite query

Query-driven sync

Persistence

Conclusions

Wishlist

A meta object from useLiveQuery into the collection

placeholderData and isRefetching

References

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

Why You Might Still Pick Next.js Over TanStack Start

1. Static Server State, Prebuild, and ISR

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

3. Image and Font Optimization

4. React Canary Features (View Transitions) Built In

5. Ecosystem Fit

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

🎨 TanStack Start SSR-Friendly Theme Provider

🌟 Overview

🎭 The Provider: ThemeProvider.tsx

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

🏗️ Implementation Flow

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

🌈 Benefits & Features

✅ Production-Ready Advantages

🎯 Usage Tips

🚀 Quick Setup

📚 References

Building Android Widgets in Expo with Custom Native Modules

Table of Contents

Overview

What You'll Learn

High-Level Process

1. Architecture Overview

2. Build Process Flow

3. Key Components

Native Modules vs Native Views

Native Views

Native Modules (Our Choice)

Why We Use Native Modules for Widgets

Development Client Setup

Prerequisites

Using Expo Dev Client

1. Install Development Build Dependencies

2. Configure Development Build

3. Create Development Build

4. Widget Testing Workflow

Quick Start (TL;DR)

Project Structure

Step-by-Step Implementation

Step 1: Create the Expo Module

Step 2: Configure Module Dependencies

Step 3: Implement the Widget

Step 4: Create Widget Receiver

Step 5: Implement the Native Module

Step 6: TypeScript Interface

Step 7: Android Manifest Configuration

Step 8: Widget Info XML

Advanced Features

Auto-Updating with WorkManager

Config Plugin for WorkManager Initialization

Best Practices

1. State Management

2. Performance Optimization

3. User Experience

4. Development Workflow

Troubleshooting

Common Issues

Debug Tips

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`