DEV Community: Sarah

File-Based Routing: Your Folder Structure Is Your Navigation

Sarah — Tue, 13 Oct 2026 05:27:52 +0000

TL;DR

File-based routing = the file path is the route. No routes.js, no navigator registration.
Expo Router: every file in app/ is a route. Next.js App Router: only page.tsx makes a route; folders are the segments.
Six conventions cover ~everything: index, [param], [...catchAll], _layout, (group), +not-found.
Biggest trap: renaming a file changes its URL and silently breaks deep links. Treat it like an API change.
Auth guards still need code, usually a <Redirect /> in a layout.

I used to have a ~300-line AppNavigator.tsx in every project that nobody wanted to touch. Adding a screen meant: create the component → register it → type its params. Skip step 2, crash. Skip step 3, any everywhere.

File-based routing deletes that file. Here's how it works, mostly in code.

Files → routes

Expo Router: every file is a route:

app/index.tsx            →  /
app/about.tsx            →  /about
app/blog/[slug].tsx      →  /blog/any-post-name
app/settings/profile.tsx →  /settings/profile

Next.js App Router: folders are segments, page.tsx is the route:

app/page.tsx                  →  /
app/about/page.tsx            →  /about
app/blog/[slug]/page.tsx      →  /blog/any-post-name
app/settings/profile/page.tsx →  /settings/profile

Same idea, different rule for what counts as a route. Remember that, because it matters later.

The 6 conventions

1. Index routes

app/blog/index.tsx (Expo) or app/blog/page.tsx (Next) → /blog.

2. Dynamic segments

Expo, via a hook:

// app/user/[id].tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';

export default function User() {
  const { id } = useLocalSearchParams<{ id: string }>();
  return <Text>User {id}</Text>;
}

Next.js 15+, via props, where params is now a Promise:

// app/user/[id]/page.tsx
export default async function User({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return <h1>User {id}</h1>;
}

3. Catch-all

// app/docs/[...slug].tsx  →  /docs/a/b/c
const { slug } = useLocalSearchParams<{ slug: string[] }>();
// slug === ['a', 'b', 'c']

4. Layouts

A layout wraps every route in its folder and stays mounted. In React Native, this is where you pick the navigator:

// app/_layout.tsx
import { Stack } from 'expo-router';

export default function RootLayout() {
  return <Stack screenOptions={{ headerShown: false }} />;
}

// app/(tabs)/_layout.tsx
import { Tabs } from 'expo-router';
import Ionicons from '@expo/vector-icons/Ionicons';

export default function TabsLayout() {
  return (
    <Tabs>
      <Tabs.Screen
        name="index"
        options={{
          title: 'Home',
          tabBarIcon: ({ color }) => <Ionicons name="home" size={22} color={color} />,
        }}
      />
      <Tabs.Screen name="search" options={{ title: 'Search' }} />
      <Tabs.Screen name="profile" options={{ title: 'Profile' }} />
    </Tabs>
  );
}

Navigators are folders now. That's the whole mental shift.

5. Route groups

(parens) = organise files without adding a URL segment. app/(auth)/login.tsx → /login. Use groups to give screens different layouts (tabs vs. plain stack).

6. Not-found

+not-found.tsx (Expo) / not-found.tsx (Next). Add it on day one; a blank screen on a bad deep link looks like a crash.

A real structure

app/
├── _layout.tsx          # root Stack
├── (auth)/
│   ├── _layout.tsx      # plain Stack, no tabs
│   ├── login.tsx        # /login
│   └── signup.tsx       # /signup
├── (tabs)/
│   ├── _layout.tsx      # Tabs
│   ├── index.tsx        # /
│   ├── search.tsx       # /search
│   └── profile.tsx      # /profile
├── post/
│   └── [id].tsx         # /post/42, pushed over tabs
└── +not-found.tsx

You can read the entire app's navigation from ls -R app/. Try that with a hand-rolled navigator.

Navigating

import { Link, router } from 'expo-router';

<Link href="/post/42">Open post</Link>

// with params object
<Link href={{ pathname: '/post/[id]', params: { id: '42' } }}>Open post</Link>

router.push('/settings/profile');
router.replace('/login');   // no back entry
router.back();

Turn on typed routes and typos become compile errors:

// app.json
{
  "expo": {
    "experiments": { "typedRoutes": true }
  }
}

<Link href="/psot/42" />
//          ^^^^^^^^ Type error: not a valid route

Where it bites

Renaming = breaking change

git mv app/settings/profile.tsx app/account/profile.tsx changes the URL. Push notification payloads, emails, bookmarks and SEO all still point at the old path. Leave a redirect behind:

// app/settings/profile.tsx  (keep this file after the move)
import { Redirect } from 'expo-router';
export default function Moved() {
  return <Redirect href="/account/profile" />;
}

In Next.js, use redirects() in next.config.js instead.

Non-route files in `app/`

Expo Router: everything in app/ is a route. Drop Button.tsx in there and you've shipped a screen called /Button. Keep shared code in components/, lib/, hooks/.
Next.js: only page.tsx / route.ts etc. are routes, so colocating components is safe. Still, many teams keep them out for clarity.

Deep nesting

Three levels of groups, each with its own _layout.tsx, and nobody can tell which layout wraps which screen. If you need a diagram for your folder tree, flatten it.

Auth guards are still code

The folder tree can't express "signed-in users only." Do it in the layout:

// app/(tabs)/_layout.tsx
import { Redirect, Tabs } from 'expo-router';
import { useSession } from '@/lib/session';

export default function TabsLayout() {
  const { user, isLoading } = useSession();

  if (isLoading) return null;
  if (!user) return <Redirect href="/login" />;

  return <Tabs />;
}

Newer Expo Router versions also have Stack.Protected for declarative guards. In Next.js this usually goes in middleware.ts or a server-side check in layout.tsx.

Should you switch?

New project: yes. Both Expo and Next.js default to it; fighting the default costs more than it saves.
Existing React Navigation app: migrate one flow at a time (onboarding is easiest) and keep a redirect for every URL you move.

If you want to poke at a working tree before designing your own, RapidNative generates Expo apps with the app/ folder, layouts and groups already wired up, and you can read and edit them like normal code.

Wrap-up

Six conventions, keep non-route code out of app/, and treat every rename as a URL change. That's it.

How is your app/ folder organised? Drop your tree in the comments. I'm curious how people use route groups in production.

We deleted our docs framework. The replacement is 400 lines of Next.js + MDX.

Sarah — Mon, 12 Oct 2026 10:18:09 +0000

TL;DR

A small docs site needs 5 packages: next-mdx-remote, remark-gfm, rehype-pretty-code, shiki, gray-matter.
One route (app/docs/[[...slug]]/page.tsx) serves every page via generateStaticParams.
The filesystem is the CMS. No _meta.json, no sidebars.js, no manifest.
We killed Contentlayer, the right-side TOC, search, and an entire docs section that described a product we don't ship.
Don't copy this if you have 500+ pages, non-dev writers, i18n, or multiple shipping versions.

Hot take: most docs frameworks are installed to solve problems the team doesn't have yet.

We rebuilt our docs on raw Next.js 16 + MDX. The whole thing is about 400 lines of code we wrote ourselves. It started because we found a docs section describing features we never shipped. Once we deleted that, we started asking what else in the stack was there because a template said so.

Most of it was. Here's what survived, file by file.

The entire dependency list

{
  "next-mdx-remote": "^6.0.0",
  "remark-gfm": "^4.0.1",
  "rehype-pretty-code": "^0.14.3",
  "shiki": "^4.0.2",
  "gray-matter": "^4.0.3"
}

A docs framework plus its peer dependencies typically adds 20 to 40 packages. We have five.

The file tree

app/
  docs/
    [[...slug]]/
      page.tsx          # catch-all route + generateStaticParams
    layout.tsx          # sidebar + content column
content/
  docs/
    index.mdx
    getting-started/
      installation.mdx
      quick-start.mdx
    core-concepts/
      expo-integration.mdx
      supabase.mdx
components/
  docs/
    sidebar.tsx
    mdx-components.tsx
lib/
  docs.ts               # ~144 lines: filesystem → nav tree

If a .mdx file exists in content/docs/, it's a page. If it doesn't, it isn't. That's the whole content model.

1. One route for every page

// app/docs/[[...slug]]/page.tsx
import { notFound } from "next/navigation"
import { getAllDocPaths, getDocBySlug } from "@/lib/docs"

export async function generateStaticParams() {
  return getAllDocPaths().map((slug) => ({ slug }))
}

export default async function DocPage({
  params,
}: {
  params: Promise<{ slug?: string[] }>
}) {
  const { slug = [] } = await params
  const doc = getDocBySlug(slug)
  if (!doc) notFound()
  return <DocLayout doc={doc} />
}

[[...slug]] is an optional catch-all, so /docs matches with slug = [] and /docs/getting-started/installation matches with ["getting-started", "installation"]. Every page is pre-rendered at next build. There's no ISR or runtime parsing, and no stale cache to blame when something is wrong in prod.

2. The "content layer" is `fs` + `gray-matter`

This is the function that replaced Contentlayer:

// lib/docs.ts
export function getDocBySlug(slug: string[]): Doc | null {
  const file = resolveDocFile(slug)
  if (!file) return null
  const raw = fs.readFileSync(file, "utf8")
  const { data, content } = matter(raw)
  return { slug, frontmatter: data as DocFrontmatter, content }
}

The helpers around it are just as boring. Simplified version:

// lib/docs.ts (simplified)
const DOCS_DIR = path.join(process.cwd(), "content/docs")

function resolveDocFile(slug: string[]): string | null {
  const base = path.join(DOCS_DIR, ...slug)
  const candidates = [`${base}.mdx`, path.join(base, "index.mdx")]
  return candidates.find((f) => fs.existsSync(f)) ?? null
}

export function getAllDocPaths(dir = DOCS_DIR, prefix: string[] = []): string[][] {
  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
    if (entry.isDirectory()) {
      return getAllDocPaths(path.join(dir, entry.name), [...prefix, entry.name])
    }
    if (!entry.name.endsWith(".mdx")) return []
    const name = entry.name.replace(/\.mdx$/, "")
    return [name === "index" ? prefix : [...prefix, name]]
  })
}

The frontmatter contract is deliberately tiny:

---
title: Installation
description: Get the template running locally.
order: 1
---

It has no author, date, or category fields. Docs aren't blog posts, and metadata nobody updates starts lying within a month.

3. Rendering: MDX on the server, zero MDX runtime on the client

import { MDXRemote } from "next-mdx-remote/rsc"
import remarkGfm from "remark-gfm"
import rehypePrettyCode from "rehype-pretty-code"
import { mdxComponents } from "@/components/docs/mdx-components"

<MDXRemote
  source={doc.content}
  components={mdxComponents}
  options={{
    mdxOptions: {
      remarkPlugins: [remarkGfm],
      rehypePlugins: [[rehypePrettyCode, { theme: "github-dark-dimmed" }]],
    },
  }}
/>

shiki uses the same TextMate grammars as VS Code, so code in the docs looks exactly like code in the editor the reader just left. Line numbers are off and wrapping is on, because people read docs on phones and horizontal scroll on a phone is hostile.

One gotcha: rehype-pretty-code puts its own inline styles on inline <code> too, which fought our Tailwind styling. The fix is a one-line override (roughly):

// components/docs/mdx-components.tsx
export const mdxComponents = {
  code: ({ style, ...props }: React.ComponentProps<"code">) => (
    <code {...props} />  // drop the plugin's inline style, let Tailwind win
  ),
  // ...other overrides
}

4. The sidebar is not alphabetical. On purpose.

The right reading order for docs is almost never alphabetical. "Getting Started" comes before "Core Concepts" even though G > C.

const sectionConfig: Record<string, { title: string; order: number }> = {
  "": { title: "Overview", order: 0 },
  "getting-started": { title: "Getting Started", order: 1 },
  "core-concepts": { title: "Core Concepts", order: 2 },
}

const byOrder = (a?: number, b?: number) => (a ?? 99) - (b ?? 99)

sections.sort((a, b) => byOrder(sectionConfig[a.key]?.order, sectionConfig[b.key]?.order))
section.pages.sort((a, b) => byOrder(a.frontmatter.order, b.frontmatter.order))

If you add a new section without registering it in sectionConfig, it sinks to position 99. That's an intentionally ugly failure mode, because it forces whoever added the section to decide where it belongs.

The kill list

Contentlayer. It added 30 to 90 seconds per build, broke on Next.js upgrades, and gave us typed frontmatter we were already getting from 20 lines of gray-matter.

Right-side TOC. We built it, used it for a month, and deleted it. Our pages are short enough that scrolling beats scanning. On a 375px viewport, the only place a TOC fits is a dropdown nobody opens. We removed rehype-slug and rehype-autolink-headings along with it.

Search. We have no Algolia and no search bar. Most docs traffic arrives from Google, which is already a search engine, and the sidebar is faster than typing once you're on the page. Pagefind is on the shortlist for later.

A whole section about a product we don't ship. Our old docs had an "AI Integration" section describing a generic AI starter kit. That isn't what we sell. The docs now mirror the actual React Native templates in the catalog. The old file is still in the repo as ai-generation.mdx_old, a tombstone to remind us what aspirational docs cost.

Things we almost built and didn't:

Live code editor. It would need a sandboxed runtime, a React Native web shim, and an API proxy. Copy-paste snippets won.
Versioned docs. We have one shipping version, and versioning a one-version product is a drawer labeled drawer.
Separate docs dark-mode toggle. We prototyped it for a week. It meant two theme states to debug for one marginal benefit, so we binned it.

Framework vs hand-rolled, honestly

	Docs framework	Our setup
Deps added	20–40	5
Docs code you own	~0 (it's in `node_modules`)	~400 lines
New page	create `.mdx` + edit `_meta.json`	create `.mdx`
Layout bug	read framework source	open the file
Search / versioning / i18n	built in	none

The comparison cuts both ways. A framework gives you features you don't have, and it also makes you maintain features you don't want.

Don't do this if…

You have 500+ pages. Hand-ordering that sidebar is masochism.
You have non-developer writers. A CMS pays for itself the first time someone without a terminal needs to fix a typo.
You need multiple shipping versions. Docusaurus already solved that, so don't re-solve it.
You need i18n on day one. That's framework territory.

If none of those apply, hand-rolled MDX on Next.js is probably smaller than the framework you were about to npm install.

References

What's your docs stack right now: framework, hand-rolled, or "a README we keep meaning to fix"? Drop it in the comments. I'm especially curious whether anyone has made Pagefind work nicely with next-mdx-remote.

Expo Push Notifications in React Native: The Production Guide the Quickstart Skips

Sarah — Fri, 09 Oct 2026 08:34:48 +0000

TL;DR

A push ticket that says "ok" only means Expo accepted your message. Whether Apple or Google accepted it is in the receipt, which you have to fetch yourself ~15 minutes later.
Expo Go can't do remote push on Android since SDK 53. Use a development build.
On Android 13+, create a notification channel before requesting a token, or the permission prompt never appears.
Store tokens per device, not per user, and hand them over when someone else signs in on the same phone.
Send from your server with expo-server-sdk. Never from the app.
Taps that launch a killed app skip your listener. Read getLastNotificationResponse() on mount.

The quickstart gets a test push onto your phone in about twenty minutes. Then you ship, and things break quietly: half your Android users never see the permission prompt, tokens pile up for phones that uninstalled months ago, a notification tap opens the home screen instead of the order, and your server logs say every send was ok.

Nothing throws. That's the whole problem with push: the happy path is easy and every failure is silent.

Here's the setup I'd use in production. Stack: expo-notifications, Expo Push Service, Expo Router, and a Supabase/Postgres backend. All TypeScript.

The mental model (get this wrong and nothing else helps)

App ──(1) getExpoPushTokenAsync──▶ Expo ──▶ ExponentPushToken[...]
App ──(2) save token─────────────▶ Your backend

Your backend ──(3) POST /push/send───────▶ Expo ──▶ TICKET
Expo ──(4)──▶ FCM (Android) / APNs (iOS) ──▶ device
Your backend ──(5) POST /push/getReceipts──▶ RECEIPT

Ticket ok = Expo got it. That's all.
Receipt = what FCM/APNs said. DeviceNotRegistered, InvalidCredentials and friends live here.

If you only read tickets, you're blind to most failures.

Before you write any code

No Expo Go. Since SDK 53, remote push doesn't work in Expo Go on Android. Local notifications still do, which is why push seems to "half work." Use a development build.
Credentials. Android needs an FCM V1 service account key uploaded to EAS. iOS needs an APNs key; eas build offers to generate one on your first push-enabled build (or run eas credentials).
Test targets. Physical devices, Android emulators with Google Play services, or iOS simulators on Xcode 14+.

1. Install and configure

npx expo install expo-notifications expo-constants

{
  "expo": {
    "plugins": [
      [
        "expo-notifications",
        {
          "icon": "./assets/notification-icon.png",
          "color": "#4F46E5",
          "defaultChannel": "default"
        }
      ]
    ]
  }
}

icon and color are Android-only and build-time, so changing them needs a new build. The icon must be an all-white PNG on transparent (96×96). Use your full-colour app icon and you'll get a white square in the status bar.

2. Channels first, and by intent

Android 8+ users can mute channels individually. Put promos and chat in one channel and a user who's tired of promos mutes your chat too.

// lib/notifications/channels.ts
import * as Notifications from 'expo-notifications';
import { Platform } from 'react-native';

export const CHANNELS = {
  default: 'default',
  messages: 'messages',
  orders: 'orders',
  promotions: 'promotions',
} as const;

export async function ensureAndroidChannels() {
  if (Platform.OS !== 'android') return;

  await Notifications.setNotificationChannelAsync(CHANNELS.default, {
    name: 'General',
    importance: Notifications.AndroidImportance.DEFAULT,
  });
  await Notifications.setNotificationChannelAsync(CHANNELS.messages, {
    name: 'Messages',
    importance: Notifications.AndroidImportance.HIGH,
  });
  await Notifications.setNotificationChannelAsync(CHANNELS.orders, {
    name: 'Order updates',
    importance: Notifications.AndroidImportance.HIGH,
  });
  await Notifications.setNotificationChannelAsync(CHANNELS.promotions, {
    name: 'Offers & news',
    importance: Notifications.AndroidImportance.LOW,
  });
}

Three gotchas:

On Android 13+, the OS permission prompt won't show until at least one channel exists. Call this before requesting a token.
Send to a channelId the device hasn't created and the notification is silently dropped. Ship the channel in the app before your backend starts using it.
After creation, Android only lets you change a channel's name and description. Choose importance carefully.

3. Don't burn your one iOS prompt

If an iOS user taps "Don't Allow," you can't show the system prompt again. Asking on first launch, before they know why you'd notify them, wastes it.

Show your own soft prompt at a moment of value, and only trigger the real dialog on "yes":

// components/NotificationSoftPrompt.tsx
import { Linking, View, Text, Pressable } from 'react-native';
import * as Notifications from 'expo-notifications';
import { registerPushToken } from '@/lib/notifications/register';

export function NotificationSoftPrompt({ onDone }: { onDone: () => void }) {
  async function enable() {
    const { status, canAskAgain } = await Notifications.getPermissionsAsync();

    if (status !== 'granted' && !canAskAgain) {
      // System prompt is gone for good. Settings is the only way back.
      await Linking.openSettings();
      return onDone();
    }

    await registerPushToken(); // shows the system prompt if needed
    onDone();
  }

  return (
    <View>
      <Text>Know the moment your order ships</Text>
      <Text>Only order updates and replies to your messages.</Text>
      <Pressable onPress={enable}>
        <Text>Turn on notifications</Text>
      </Pressable>
      <Pressable onPress={onDone}>
        <Text>Not now</Text>
      </Pressable>
    </View>
  );
}

"Not now" is free; you can ask again later. A system "Don't Allow" is close to permanent.

On iOS, check ios.status on the permission response, not just the root status, especially if you use provisional authorization.

4. Get the token without crashing launch

getExpoPushTokenAsync hits Expo's servers, so it fails on bad networks. The docs example alerts and gives up. Retry with backoff instead, and return null rather than throwing:

// lib/notifications/register.ts
import * as Notifications from 'expo-notifications';
import Constants from 'expo-constants';
import { Platform } from 'react-native';
import { supabase } from '@/lib/supabase';
import { ensureAndroidChannels } from './channels';

let currentToken: string | null = null;

async function getExpoPushToken(): Promise<string | null> {
  await ensureAndroidChannels(); // must come first on Android 13+

  let { status, canAskAgain } = await Notifications.getPermissionsAsync();
  if (status !== 'granted' && canAskAgain) {
    ({ status, canAskAgain } = await Notifications.requestPermissionsAsync());
  }
  if (status !== 'granted') return null;

  const projectId =
    Constants.expoConfig?.extra?.eas?.projectId ?? Constants.easConfig?.projectId;
  if (!projectId) throw new Error('EAS projectId is missing from app config');

  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      const { data } = await Notifications.getExpoPushTokenAsync({ projectId });
      return data; // "ExponentPushToken[...]"
    } catch {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
    }
  }
  return null; // try again next launch
}

export async function registerPushToken() {
  const token = await getExpoPushToken();
  if (!token) return null;

  const { error } = await supabase.rpc('register_push_token', {
    p_token: token,
    p_platform: Platform.OS,
  });
  if (error) {
    console.warn('Push token registration failed:', error.message);
    return null;
  }

  currentToken = token;
  return token;
}

export async function unregisterPushToken() {
  if (!currentToken) return;
  try {
    await supabase.rpc('deactivate_push_token', { p_token: currentToken });
  } catch {
    // Offline? The next sign-in on this device moves the token anyway.
  }
  currentToken = null;
}

Call registerPushToken() on every launch once the user is signed in and has already granted permission. It's cheap and keeps last_seen_at honest.

Tokens can also rotate while the app is running:

useEffect(() => {
  const sub = Notifications.addPushTokenListener(() => {
    registerPushToken();
  });
  return () => sub.remove();
}, []);

5. A user is not a token

Hot take: a push_token column on users is a bug waiting to happen. Users have phones and tablets, they reinstall, and they share devices. One user has many tokens, and one token can change owners.

create table public.push_tokens (
  id            uuid primary key default gen_random_uuid(),
  user_id       uuid not null references auth.users (id) on delete cascade,
  token         text not null unique,
  platform      text not null check (platform in ('ios', 'android')),
  is_active     boolean not null default true,
  last_seen_at  timestamptz not null default now(),
  created_at    timestamptz not null default now()
);

create index on public.push_tokens (user_id) where is_active;

alter table public.push_tokens enable row level security;

create policy "Users can read their own tokens"
  on public.push_tokens for select
  using (auth.uid() = user_id);

No insert or update policy, on purpose. When user B signs in on user A's old phone, the token has to move, and a plain upsert fails under RLS because the row belongs to A. Two security definer functions handle it, both scoped to the caller:

create or replace function public.register_push_token(p_token text, p_platform text)
returns void
language plpgsql
security definer
set search_path = public
as $$
begin
  if auth.uid() is null then
    raise exception 'not authenticated';
  end if;

  insert into public.push_tokens (user_id, token, platform)
  values (auth.uid(), p_token, p_platform)
  on conflict (token) do update
    set user_id      = excluded.user_id,
        platform     = excluded.platform,
        is_active    = true,
        last_seen_at = now();
end;
$$;

create or replace function public.deactivate_push_token(p_token text)
returns void
language sql
security definer
set search_path = public
as $$
  update public.push_tokens
     set is_active = false
   where token = p_token
     and user_id = auth.uid();
$$;

Deactivate on sign-out while the session is still valid, since the RPC checks auth.uid():

export async function signOut() {
  await unregisterPushToken(); // before the session is gone
  await supabase.auth.signOut();
}

Skip this and user A keeps getting notifications on a phone user B is now using.

Side note: if you want to iterate on this schema, the RLS policy and both RPCs locally without running the full Supabase Docker stack, tinbase is an MIT-licensed, Supabase-compatible backend that runs as a single process with real Postgres and RLS, and supabase-js works against it unchanged. It's alpha, so keep it to local dev and push the same migrations to hosted Supabase for prod.

One more table, for the receipts job in step 7:

create table public.push_tickets (
  ticket_id   text primary key,
  token       text not null,
  created_at  timestamptz not null default now(),
  checked_at  timestamptz
);

6. Send from the server, never the app

The quickstart sends straight from the device with fetch. That's fine for a demo and wrong for production. Your server is where you batch, throttle, log and protect sends.

npm install expo-server-sdk

// server/push/send.ts
import { Expo, type ExpoPushMessage } from 'expo-server-sdk';
import { createClient } from '@supabase/supabase-js';

const expo = new Expo({ accessToken: process.env.EXPO_ACCESS_TOKEN });
const db = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY!);

type PushInput = {
  title: string;
  body: string;
  url?: string;       // in-app route to open on tap, e.g. "/orders/123"
  channelId?: string; // must already exist on the device
};

export async function sendToUser(userId: string, input: PushInput) {
  const { data: rows } = await db
    .from('push_tokens')
    .select('token')
    .eq('user_id', userId)
    .eq('is_active', true);

  const messages: ExpoPushMessage[] = (rows ?? [])
    .map((r) => r.token)
    .filter((token) => Expo.isExpoPushToken(token))
    .map((to) => ({
      to,
      title: input.title,
      body: input.body,
      data: input.url ? { url: input.url } : {},
      channelId: input.channelId ?? 'default',
      sound: 'default',
    }));

  // Max 100 messages per request; the SDK chunks for you.
  for (const chunk of expo.chunkPushNotifications(messages)) {
    const tickets = await expo.sendPushNotificationsAsync(chunk);

    await Promise.all(
      tickets.map(async (ticket, i) => {
        const token = chunk[i].to as string;

        if (ticket.status === 'ok') {
          await db.from('push_tickets').insert({ ticket_id: ticket.id, token });
        } else if (ticket.details?.error === 'DeviceNotRegistered') {
          await db.from('push_tokens').update({ is_active: false }).eq('token', token);
        } else {
          console.error('Push ticket error', ticket.message, ticket.details);
        }
      }),
    );
  }
}

What matters in there:

Small payloads. The total must be ≤ 4,096 bytes. Send an ID and a route, then fetch the details in the app.
Enhanced push security. By default, anyone with a user's Expo push token can send to it. Turn on enhanced security in the EAS dashboard and pass accessToken (SDK v3.6.0+). Requests without it then get UNAUTHORIZED.
Secrets stay server-side. The access token and the service role key never go in the app bundle.

7. Check receipts and prune dead tokens

This is the step most tutorials skip. Expo recommends checking receipts ~15 minutes after sending, and receipts are deleted after 24 hours. So run this every 15 minutes:

// server/push/receipts.ts (run every 15 minutes)
import { Expo } from 'expo-server-sdk';
import { createClient } from '@supabase/supabase-js';

const expo = new Expo({ accessToken: process.env.EXPO_ACCESS_TOKEN });
const db = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_ROLE_KEY!);

export async function processReceipts() {
  const fifteenMinutesAgo = new Date(Date.now() - 15 * 60 * 1000).toISOString();

  const { data: pending } = await db
    .from('push_tickets')
    .select('ticket_id, token')
    .is('checked_at', null)
    .lt('created_at', fifteenMinutesAgo)
    .limit(5000);

  if (!pending?.length) return;
  const tokenByTicket = new Map(pending.map((p) => [p.ticket_id, p.token]));

  // Max 1,000 receipt IDs per request; the SDK chunks for you.
  for (const ids of expo.chunkPushNotificationReceiptIds([...tokenByTicket.keys()])) {
    const receipts = await expo.getPushNotificationReceiptsAsync(ids);

    for (const [ticketId, receipt] of Object.entries(receipts)) {
      if (receipt.status !== 'error') continue;
      const error = receipt.details?.error;

      if (error === 'DeviceNotRegistered') {
        await db
          .from('push_tokens')
          .update({ is_active: false })
          .eq('token', tokenByTicket.get(ticketId)!);
      } else {
        console.error(`Receipt ${ticketId}: ${error}`, receipt.message);
      }
    }

    await db
      .from('push_tickets')
      .update({ checked_at: new Date().toISOString() })
      .in('ticket_id', ids);
  }
}

What each error means:

Error	Where	Meaning	Fix
`DeviceNotRegistered`	Ticket or receipt	App uninstalled or permission revoked	Deactivate the token
`MessageTooBig`	Receipt	Payload over 4,096 bytes	Send an ID, fetch in-app
`MessageRateExceeded`	Receipt	Too many pushes to one device	Exponential backoff for that device
`InvalidCredentials`	Receipt	FCM/APNs credentials revoked or wrong	Re-upload FCM V1 key / `eas credentials`
`MismatchSenderId`	Receipt	FCM key and `google-services.json` from different projects	Use the same Firebase project for both
`TOO_MANY_REQUESTS`	Whole request	Over 600 notifications/sec per project	Throttle (the Node SDK already does)

InvalidCredentials means every push on that platform is failing. Page someone; don't just log it.

Also: don't try to test DeviceNotRegistered by uninstalling and sending a minute later. Apple and Google decide a device is gone on their own schedule.

8. Foreground notifications and taps

Foreground: be selective

By default, a notification that arrives while the app is open is not shown. Your handler opts in, and it has 3 seconds to answer or the notification is discarded.

If the user is already on the screen the notification is about, a banner is noise. Track the active route:

// lib/navigation/active-route.ts
let activeRoute: string | null = null;

export const setActiveRoute = (route: string) => {
  activeRoute = route;
};
export const getActiveRoute = () => activeRoute;

Taps: cover the cold start

A tap can open the app from foreground, background, or fully killed. In the killed case your listener isn't registered yet when the tap happens, so read the last response on mount and subscribe:

// app/_layout.tsx
import { useEffect, useRef } from 'react';
import * as Notifications from 'expo-notifications';
import { Slot, router, usePathname, type Href } from 'expo-router';
import { getActiveRoute, setActiveRoute } from '@/lib/navigation/active-route';

Notifications.setNotificationHandler({
  handleNotification: async (notification) => {
    const url = notification.request.content.data?.url;
    const alreadyThere = typeof url === 'string' && url === getActiveRoute();

    return {
      shouldShowBanner: !alreadyThere,
      shouldShowList: true,
      shouldPlaySound: !alreadyThere,
      shouldSetBadge: false,
    };
  },
});

function useTrackActiveRoute() {
  const pathname = usePathname();
  useEffect(() => {
    setActiveRoute(pathname);
  }, [pathname]);
}

function useNotificationObserver() {
  const handledId = useRef<string | null>(null);

  useEffect(() => {
    function open(response: Notifications.NotificationResponse) {
      const id = response.notification.request.identifier;
      if (handledId.current === id) return; // no double navigation
      handledId.current = id;

      const url = response.notification.request.content.data?.url;
      // Internal routes only. Never navigate to an arbitrary URL from a payload.
      if (typeof url === 'string' && url.startsWith('/')) {
        router.push(url as Href);
      }
    }

    const last = Notifications.getLastNotificationResponse();
    if (last) open(last); // app was launched by a tap

    const sub = Notifications.addNotificationResponseReceivedListener(open);
    return () => sub.remove();
  }, []);
}

export default function RootLayout() {
  useTrackActiveRoute();
  useNotificationObserver();
  return <Slot />;
}

Notes:

shouldShowAlert is deprecated. Use shouldShowBanner and shouldShowList.
The startsWith('/') check is there because a payload is server data. A buggy or compromised sender shouldn't be able to send users to an external URL.
On Android debug builds, launching from a notification can glitch the splash screen. That's a known debug-only issue, so test cold-start taps with npx expo run:android --variant release.

Limits cheat sheet

Limit	Value
Messages per send request	100
Receipt IDs per receipts request	1,000
Send rate per project	600 / second
Total payload	4,096 bytes
Check receipts	~15 min after sending
Receipts kept for	24 hours
Foreground handler deadline	3 seconds
Default TTL	Provider default (~4 weeks)

priority defaults to normal on Android and high on iOS, and normal-priority messages can wait on a sleeping Android device. A very low ttl (like 0) can mean a notification never reaches an Android phone in Doze mode. Use high priority and a sensible TTL only when a message is genuinely time-sensitive.

Drop a comment with what you're building and the push bug that cost you the most time. I'm collecting the weird ones for a follow-up on background (headless) notifications.

This article was created with the help of AI. Code, limits and API names were checked against the Expo docs (SDK 57) and Apple's App Review Guidelines.

Your Supabase Auth Is Only as Good as Your RLS Policies. So Test Them.

Sarah — Wed, 07 Oct 2026 09:00:56 +0000

TL;DR

With Supabase, auth answers "who are you?" and RLS policies answer "what can you touch?" The second question is where real data leaks happen.
RLS failures are silent. A blocked select returns [], not an error, so manually clicking around the app won't catch a broken policy.
The fix: integration tests that sign up two real users and check that each one can't read, edit, or delete the other's rows.
You can run those tests against a local Supabase-compatible backend in seconds, including in CI.

The bug nobody notices

Here's a situation I've seen more than once. Sign-up works. Login works. The session persists. You ship.

Then someone opens DevTools, takes the anon key from your bundle (it's meant to be public), and runs:

await supabase.from('notes').select('*')

They get back every note from every user, because RLS was never enabled on that table.

The anon key is public by design. Your RLS policies are the only thing between that key and your entire database. Auth by itself only tells Postgres who the user is. Whether that user is allowed to touch a row is decided entirely by the policies you wrote, and if you didn't write them correctly, nothing else stops the request.

The schema we'll protect

A simple notes table where each user should see only their own rows:

-- supabase/migrations/20261007000000_notes.sql
create table public.notes (
  id         uuid primary key default gen_random_uuid(),
  user_id    uuid not null default auth.uid() references auth.users (id) on delete cascade,
  body       text not null,
  created_at timestamptz not null default now()
);

alter table public.notes enable row level security;

create policy "read own notes"
  on public.notes for select
  to authenticated
  using ((select auth.uid()) = user_id);

create policy "insert own notes"
  on public.notes for insert
  to authenticated
  with check ((select auth.uid()) = user_id);

create policy "update own notes"
  on public.notes for update
  to authenticated
  using ((select auth.uid()) = user_id)
  with check ((select auth.uid()) = user_id);

create policy "delete own notes"
  on public.notes for delete
  to authenticated
  using ((select auth.uid()) = user_id);

Two details worth pointing out:

(select auth.uid()) instead of a bare auth.uid() lets Postgres evaluate the function once per query instead of once per row. On large tables this makes a real performance difference.
default auth.uid() on user_id means clients don't need to send it at all. That also gives an attacker one less field to tamper with.

Four ways RLS quietly breaks

These are the mistakes your tests need to catch:

1. RLS never enabled. You created the policies but forgot enable row level security. The policies exist but aren't enforced, so the table is fully open.

2. An insert policy that checks the wrong thing.

-- ❌ any logged-in user can create rows owned by anyone
create policy "insert notes" on public.notes for insert
  to authenticated
  with check (true);

This lets user B insert rows with user_id set to user A's ID. That allows spoofed content and, depending on your app, possibly worse.

3. Policies that trust user_metadata. auth.jwt() -> 'user_metadata' can be edited by the user through supabase.auth.updateUser(). If a policy checks user_metadata ->> 'role' = 'admin', any user can make themselves an admin. Store roles in app_metadata or in your own table instead.

4. Views that skip RLS. By default, a view runs with its owner's permissions, which means the underlying table's RLS doesn't apply. On Postgres 15+, create views with with (security_invoker = true).

None of these mistakes produce an error. Your app keeps working normally while the data is exposed.

The tests

The approach is to create two real users with two separate clients, then check that each one is properly isolated from the other. I'm using Vitest, but any test runner works.

npm i -D vitest @supabase/supabase-js

// tests/rls.test.ts
import { createClient, type SupabaseClient } from '@supabase/supabase-js'
import { beforeAll, describe, expect, it } from 'vitest'

const URL = process.env.SUPABASE_URL ?? 'http://127.0.0.1:54321'
const ANON_KEY = process.env.SUPABASE_ANON_KEY!

// Each user gets an isolated client. No shared session storage.
function newClient() {
  return createClient(URL, ANON_KEY, {
    auth: { persistSession: false, autoRefreshToken: false },
  })
}

async function signUpUser() {
  const client = newClient()
  const email = `rls-${crypto.randomUUID()}@example.com`
  const { data, error } = await client.auth.signUp({
    email,
    password: 'correct-horse-battery-staple',
  })
  if (error) throw error
  if (!data.session) {
    throw new Error('No session returned. Disable email confirmation for local tests.')
  }
  return { client, id: data.user!.id }
}

describe('notes RLS', () => {
  let alice: { client: SupabaseClient; id: string }
  let bob: { client: SupabaseClient; id: string }
  let aliceNoteId: string
  let bobNoteId: string

  beforeAll(async () => {
    alice = await signUpUser()
    bob = await signUpUser()

    const a = await alice.client.from('notes').insert({ body: 'alice secret' }).select().single()
    if (a.error) throw a.error
    aliceNoteId = a.data.id

    const b = await bob.client.from('notes').insert({ body: 'bob note' }).select().single()
    if (b.error) throw b.error
    bobNoteId = b.data.id
  })

  it("bob can't read alice's notes", async () => {
    const { data, error } = await bob.client.from('notes').select('*').eq('id', aliceNoteId)
    expect(error).toBeNull() // RLS filters rows. It doesn't throw.
    expect(data).toEqual([])
  })

  it("bob can't update alice's notes", async () => {
    const { data } = await bob.client
      .from('notes')
      .update({ body: 'pwned' })
      .eq('id', aliceNoteId)
      .select()
    expect(data).toEqual([]) // zero rows matched

    const { data: check } = await alice.client
      .from('notes')
      .select('body')
      .eq('id', aliceNoteId)
      .single()
    expect(check!.body).toBe('alice secret')
  })

  it("bob can't delete alice's notes", async () => {
    await bob.client.from('notes').delete().eq('id', aliceNoteId)

    const { data } = await alice.client.from('notes').select('id').eq('id', aliceNoteId)
    expect(data).toHaveLength(1)
  })

  it("bob can't create rows owned by alice", async () => {
    const { error } = await bob.client
      .from('notes')
      .insert({ body: 'spoofed', user_id: alice.id })
    expect(error?.code).toBe('42501') // new row violates row-level security policy
  })

  it("bob can't hand his note over to alice", async () => {
    const { error } = await bob.client
      .from('notes')
      .update({ user_id: alice.id })
      .eq('id', bobNoteId)
    expect(error?.code).toBe('42501')
  })

  it('anonymous users see nothing', async () => {
    const { data } = await newClient().from('notes').select('*')
    expect(data).toEqual([])
  })

  it('alice can still read her own note', async () => {
    const { data } = await alice.client.from('notes').select('body').eq('id', aliceNoteId)
    expect(data).toEqual([{ body: 'alice secret' }])
  })
})

The last test matters more than it looks. A policy that blocks everyone will pass every "can't" test. Always include at least one positive check that the owner still has access.

Try this as an experiment: comment out enable row level security in the migration and run the tests again. Most of them should fail. That confirms the tests are actually checking something.

Running it locally (and in CI)

These tests need a real auth server and real Postgres. A mock won't work, because RLS runs inside Postgres itself.

The standard approach is supabase start, which runs the full local stack in Docker. It works, but it starts about a dozen containers, which is a lot for a test suite and noticeably slow in CI.

Lately I've been using tinbase for this. It's an open-source, Supabase-compatible backend that runs as a single process without Docker. It runs real Postgres with RLS and GoTrue-style auth, reads your existing supabase/migrations/*.sql, and the official supabase-js connects to it without changes. Since everything in this post is just migrations plus supabase-js, nothing in the test file needs to change.

npx tinbase start
# copy the anon key it prints, then:
SUPABASE_ANON_KEY=<key> npx vitest run

It's still alpha, so I use it for local development and CI, not production. But for answering "do my policies actually hold?" in a couple of seconds, it's a good fit.

A minimal GitHub Actions job:

# .github/workflows/rls.yml
name: RLS tests
on: [push, pull_request]

jobs:
  rls:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx tinbase start &
      - run: npx wait-on tcp:127.0.0.1:54321
      - run: npx vitest run
        env:
          SUPABASE_URL: http://127.0.0.1:54321
          SUPABASE_ANON_KEY: ${{ secrets.LOCAL_ANON_KEY }}

The rule I follow now

Every table with RLS gets two tests before it ships: one showing a stranger can't access the data, and one showing the owner can. It takes about ten minutes per table, and it catches exactly the bugs that manual testing misses.

What's the worst RLS mistake you've found in your own app, or in someone else's? Drop it in the comments. I'd like to collect the strange edge cases.

React Native Accessibility in 2026 — Mapping WCAG 2.2 AA to the Props You Actually Write

Sarah — Mon, 05 Oct 2026 08:46:53 +0000

TL;DR

The DOJ's ADA Title II rule (WCAG 2.1 AA for state/local gov web + mobile apps) got pushed back. The big-entity deadline is now April 26, 2027, smaller entities April 26, 2028. The EU's Accessibility Act has been live since June 2025 and points at WCAG 2.2 AA. Translation: the clock is still running.
React Native maps almost 1:1 onto iOS UIAccessibility and Android AccessibilityNodeInfo. The API is small. The hard part is knowing which prop satisfies which criterion.
WCAG 2.2 added four criteria that hit native apps directly: 2.4.11 Focus Not Obscured, 2.5.7 Dragging Movements, 2.5.8 Target Size, 3.3.8 Accessible Authentication.
Five bugs cause most failures: unlabeled Pressables, modals that don't trap focus, silent form errors, switches with no state, and text on gradients.
Test in four layers: lint in CI → screen reader walkthrough → Xcode Inspector / Android Scanner → Appium + axe for regression.

Let's get into it.

Why you should care (even though the deadline moved)

Quick recap of where things stand as of late 2026:

ADA Title II (US): The DOJ's 2024 rule was the first US regulation to name mobile apps explicitly and tie them to a WCAG version (2.1 AA). In April 2026, four days before it was supposed to bite, DOJ extended the dates by a year. Entities serving 50,000+ people now have until April 26, 2027. Everyone else gets until April 26, 2028. The underlying Title II nondiscrimination obligations didn't go anywhere.
HHS Section 504: If your app is built for anyone receiving HHS funding (hospitals, clinics, health programs), that rule kept its May 2026 date.
European Accessibility Act: In force since June 2025. Covers private-sector stuff like banking, e-commerce, and transport apps, and references EN 301 549, which lines up with WCAG 2.2 AA.
Procurement: B2G contracts routinely list WCAG 2.1 AA as a pass/fail checkbox, so even if a regulation doesn't technically cover you, your customer's contract might.
Private lawsuits: Title III web and app suits keep coming every year. "We'll fix it later" is not a strategy your legal team will enjoy.

So the practical move hasn't changed: run an accessibility audit on every store build, and be able to show the report when someone asks.

The whole toolbox in one component

WCAG has four principles (Perceivable, Operable, Understandable, Robust) and three conformance levels (A, AA, AAA). For Level AA on native mobile, you're working through the A + AA criteria that apply to apps. A handful of web-only ones (skip links, document heading outline, parsing) don't translate.

Everything else lands on this prop surface:

<Pressable
  accessible
  accessibilityLabel="Save changes"
  accessibilityHint="Saves your draft"
  accessibilityRole="button"
  accessibilityState={{ disabled: false, busy: isSaving }}
  accessibilityValue={{ min: 0, max: 100, now: 42 }}
  importantForAccessibility="yes"
  accessibilityLiveRegion="polite"
>
  <Text>Save</Text>
</Pressable>

That's basically it. (On RN 0.71+ you can also use the ARIA-style aliases like role, aria-label, and aria-busy. Same thing under the hood.)

Now the mapping.

Perceivable + Operable

1.1.1 Non-text Content (A)

Anything meaningful that isn't text needs a label. Anything decorative should disappear from the accessibility tree.

// Meaningful icon button
<Pressable accessibilityRole="button" accessibilityLabel="Delete message" onPress={onDelete}>
  <TrashIcon />
</Pressable>

// Decorative image: hide it on both platforms
<Image
  source={confetti}
  accessible={false}
  accessibilityElementsHidden            // iOS
  importantForAccessibility="no-hide-descendants" // Android
/>

1.3.1 Info and Relationships (A)

Visual structure must be exposed in code. A styled View with onPress is just a blob to a screen reader until you give it a role.

<Text accessibilityRole="header" style={styles.h1}>Account settings</Text>

<Pressable accessibilityRole="link" onPress={openTerms}>
  <Text>Terms of service</Text>
</Pressable>

1.4.3 Contrast (Minimum) (AA)

4.5:1 for body text, 3:1 for large text (18pt+, or 14pt+ bold). Don't eyeball it. Put it in a test so your design tokens can't regress:

// contrast.js
const toRgb = (hex) => {
  const n = parseInt(hex.replace('#', ''), 16);
  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
};

const luminance = (hex) => {
  const [r, g, b] = toRgb(hex).map((v) => {
    v /= 255;
    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
};

export const contrastRatio = (a, b) => {
  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
};

// tokens.test.js
import { contrastRatio } from './contrast';
import { colors } from './theme';

const pairs = [
  ['textPrimary', 'background'],
  ['textSecondary', 'background'],
  ['onPrimary', 'primary'],
];

test.each(pairs)('%s on %s meets AA (4.5:1)', (fg, bg) => {
  expect(contrastRatio(colors[fg], colors[bg])).toBeGreaterThanOrEqual(4.5);
});

Classic RN failure: text over a gradient hero. It passes against the top color and fails against the bottom one. Test against the worst stop, or put a semi-opaque scrim behind the text.

1.4.4 Resize Text + 1.4.10 Reflow (AA)

Text must scale to 200% without clipping. allowFontScaling is on by default, so Dynamic Type and Android font scale already work. What breaks is your layout:

// ❌ clips at large font sizes
<View style={{ height: 48 }}><Text>{title}</Text></View>

// ✅ grows with the text
<View style={{ minHeight: 48, paddingVertical: 12 }}><Text>{title}</Text></View>

If you must cap scaling for a tight UI element, use maxFontSizeMultiplier={1.5} instead of disabling scaling entirely.

2.1.1 Keyboard (A)

On mobile this means hardware keyboards: iPads, foldables, Android with Bluetooth. Every custom gesture needs a non-gesture path, which ties straight into 2.5.7 below.

2.4.3 Focus Order (A) + 2.4.11 Focus Not Obscured (AA, new)

Focus follows render/view-hierarchy order, which usually matches the visual order. It stops matching once you start using position: 'absolute' and zIndex. The usual offender is a custom bottom sheet built as an absolutely positioned View:

<>
  <View
    accessibilityElementsHidden={sheetOpen}                               // iOS
    importantForAccessibility={sheetOpen ? 'no-hide-descendants' : 'auto'} // Android
  >
    <MainScreen />
  </View>

  {sheetOpen && (
    <View accessibilityViewIsModal style={styles.sheet}>
      <SheetContent />
    </View>
  )}
</>

For 2.4.11, don't let the keyboard cover the focused input:

<KeyboardAvoidingView
  behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
  style={{ flex: 1 }}
>
  <ScrollView keyboardShouldPersistTaps="handled">{/* form */}</ScrollView>
</KeyboardAvoidingView>

2.5.8 Target Size (Minimum) (AA, new)

The floor is 24×24 CSS px. The platform guidelines want 44×44 (iOS) and 48×48 (Android), so aim for those. Icon-only buttons are the repeat offender. hitSlop fixes them without touching the visual design:

<Pressable
  accessibilityRole="button"
  accessibilityLabel="Close"
  hitSlop={{ top: 12, bottom: 12, left: 12, right: 12 }}
  onPress={onClose}
>
  <CloseIcon size={20} />
</Pressable>

2.5.7 Dragging Movements (AA, new)

Reorderable lists need a non-drag alternative. Drag libraries don't hand you this. For screen reader users, custom accessibility actions are the cleanest route:

<View
  accessible
  accessibilityLabel={`${item.title}, position ${index + 1} of ${items.length}`}
  accessibilityActions={[
    { name: 'moveUp', label: 'Move up' },
    { name: 'moveDown', label: 'Move down' },
  ]}
  onAccessibilityAction={({ nativeEvent }) => {
    if (nativeEvent.actionName === 'moveUp' && index > 0) move(index, index - 1);
    if (nativeEvent.actionName === 'moveDown' && index < items.length - 1) move(index, index + 1);
  }}
>
  <DraggableRow item={item} />
</View>

2.5.7 applies to everyone, not just screen reader users, so also ship a visible long-press menu or up/down buttons.

Understandable + Robust

This half of the audit is smaller, but the failures here block people from finishing a signup or a checkout. Those are the ones that end up in demand letters.

3.3.1 Error Identification (A) + 3.3.3 Error Suggestion (AA)

A red border is invisible to VoiceOver. Announce the error and attach it to the field:

const onSubmit = () => {
  if (!isValidEmail(email)) {
    const msg = 'Email is invalid. Use the format name@example.com';
    setEmailError(msg);
    AccessibilityInfo.announceForAccessibility(msg);
    return;
  }
  submit();
};

<TextInput
  value={email}
  onChangeText={setEmail}
  accessibilityLabel={emailError ? `Email, error: ${emailError}` : 'Email'}
/>
{emailError ? <Text style={styles.error}>{emailError}</Text> : null}

3.3.2 Labels or Instructions (A)

Placeholder-only inputs fail, because the placeholder vanishes on focus. Use a persistent visible label:

<Text nativeID="emailLabel">Email</Text>
<TextInput
  accessibilityLabel="Email"            // works on both platforms
  accessibilityLabelledBy="emailLabel"  // Android only
  placeholder="name@example.com"
/>

3.3.8 Accessible Authentication (Minimum) (AA, new)

Let password managers do their job, and never block paste:

<TextInput
  secureTextEntry
  textContentType="password"   // iOS autofill
  autoComplete="password"      // Android autofill
  accessibilityLabel="Password"
/>

Disabling paste "for security" fails 3.3.8 and pushes users toward weaker passwords. Biometric login via expo-local-authentication is a solid extra path.

4.1.2 Name, Role, Value (A)

Every custom control needs all three. Here's a custom toggle:

<Pressable
  onPress={() => setEnabled((v) => !v)}
  accessibilityRole="switch"
  accessibilityLabel="Dark mode"
  accessibilityState={{ checked: enabled }}
>
  <ToggleVisual on={enabled} />
</Pressable>

VoiceOver reads: "Dark mode, switch, on." Drop any one of the three props and you fail 4.1.2.

4.1.3 Status Messages (AA)

Toasts, "Saved!", and loading states should be announced without stealing focus. Android uses live regions. iOS needs an explicit announcement:

function useStatusAnnouncement(message) {
  useEffect(() => {
    if (message && Platform.OS === 'ios') {
      AccessibilityInfo.announceForAccessibility(message);
    }
  }, [message]);
}

function SaveStatus({ message }) {
  useStatusAnnouncement(message);
  return <Text accessibilityLiveRegion="polite">{message}</Text>;
}

The 5 bugs you'll find in almost every audit

#	Bug	Fix
1	Icon-only `Pressable`, no label	`accessibilityLabel` + `accessibilityRole="button"`
2	Custom modal/sheet doesn't trap focus	`accessibilityViewIsModal` (iOS) + hide background with `importantForAccessibility="no-hide-descendants"` (Android)
3	Form errors are visual-only	`AccessibilityInfo.announceForAccessibility()` on failure
4	Custom switch/checkbox reads as "button"	Correct role + `accessibilityState={{ checked }}`
5	Text on a gradient	Test against the worst stop, or add a scrim

The first four are pure "forgot the prop" bugs, and they're the easiest to prevent at the source. Some teams do it with a strict component library that makes the label a required prop. Others use codegen that writes them for you. RapidNative, for example, treats accessibilityLabel, accessibilityRole, and target-safe hitSlop as required on every generated interactive element. Contrast (#5) depends on your palette, so it's the one you'll still want the token test from earlier for.

If you're doing it by hand, a typed wrapper gets you most of the way:

type A11yPressableProps = PressableProps & {
  accessibilityLabel: string; // required, not optional
  accessibilityRole: AccessibilityRole;
};

export function A11yPressable(props: A11yPressableProps) {
  return <Pressable hitSlop={8} {...props} />;
}

Ban raw Pressable in feature code with a lint rule, and TypeScript enforces the rest.

Testing: the 4-layer workflow

Layer 1: Lint in CI.

npm i -D eslint-plugin-react-native-a11y

// .eslintrc.js
module.exports = {
  plugins: ['react-native-a11y'],
  extends: ['plugin:react-native-a11y/all'],
};

This catches missing labels, invalid roles, and unlabeled inputs. It can't see contrast or focus order. No linter can.

Layer 2: Screen reader walkthrough. Turn on VoiceOver (iOS) or TalkBack (Android) and go through each primary flow without looking at the screen. It's about 20 minutes per flow, and it finds more real problems than any other step.

Layer 3: Device audit tools. Xcode → Open Developer Tool → Accessibility Inspector runs an audit against the simulator: contrast, missing labels, hit targets. On Android, use Accessibility Scanner.

Layer 4: Automated regression. axe DevTools Mobile plugs into Appium and runs WCAG rulesets against built apps. It's paid, but it's how you prove compliance at CI speed on a big app.

Cadence that works:

every commit          → Layer 1
every PR touching UI  → Layer 2
every store build     → Layers 3 + 4

For a weekly release train, that's about a 2-hour accessibility pass. Retrofitting a 40-screen app that never had props usually takes weeks.

Where to start today

Don't start with a spreadsheet of 50+ criteria. Start with Layer 2. Turn on VoiceOver or TalkBack, open your app, and try to complete your main flow. Whatever you trip over first is your backlog's #1.

Reference specs if you want to go deeper: WCAG 2.2 and what's new in 2.2.

What's the worst accessibility bug you've found in your own React Native app? Or which WCAG criterion are you still stuck on? Drop it in the comments. I'm reading every one.

Build vs Buy a Boilerplate: What Your React Native Starter Actually Costs

Sarah — Wed, 30 Sep 2026 06:28:13 +0000

TL;DR

A "boilerplate" is not a folder structure. It's auth, env handling, an API client, navigation guards, and CI that someone has to maintain.
Building your own takes longer than you think, mostly because of the boring 20%: token refresh, env validation, upgrade churn.
Buying saves weeks but you inherit someone else's opinions and their upgrade schedule.
Build if the starter is your competitive edge or you ship many apps on one stack. Buy or generate if you need to validate an idea this month.
Whatever you choose, judge it by the four files below, not the feature list.

The boilerplate you think you're building

Every build-it-yourself plan starts like this:

npx create-expo-app@latest my-app
cd my-app
npx expo install expo-router expo-secure-store
npm i zod @tanstack/react-query

Ten minutes, done, right? That's the scaffold. The boilerplate is everything you write in the next three weeks.

The boilerplate you actually build

Here are four pieces nearly every production app needs. None of them are hard. All of them take longer than planned.

1. Env validation

Skip this and you'll ship a build pointing at undefined/api/users.

// src/env.ts
import { z } from 'zod';

const schema = z.object({
  EXPO_PUBLIC_API_URL: z.string().url(),
  EXPO_PUBLIC_ENV: z.enum(['development', 'staging', 'production']),
});

// Expo inlines these at build time, so reference them statically
export const env = schema.parse({
  EXPO_PUBLIC_API_URL: process.env.EXPO_PUBLIC_API_URL,
  EXPO_PUBLIC_ENV: process.env.EXPO_PUBLIC_ENV,
});

2. Session storage

// src/session.tsx
import * as SecureStore from 'expo-secure-store';
import { createContext, useContext, useEffect, useState } from 'react';

type Session = {
  token: string | null;
  loading: boolean;
  signIn: (token: string) => Promise<void>;
  signOut: () => Promise<void>;
};

const Ctx = createContext<Session | null>(null);
const KEY = 'session_token';

export function SessionProvider({ children }: { children: React.ReactNode }) {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    SecureStore.getItemAsync(KEY)
      .then(setToken)
      .finally(() => setLoading(false));
  }, []);

  const signIn = async (t: string) => {
    await SecureStore.setItemAsync(KEY, t);
    setToken(t);
  };

  const signOut = async () => {
    await SecureStore.deleteItemAsync(KEY);
    setToken(null);
  };

  return (
    <Ctx.Provider value={{ token, loading, signIn, signOut }}>
      {children}
    </Ctx.Provider>
  );
}

export const useSession = () => {
  const ctx = useContext(Ctx);
  if (!ctx) throw new Error('useSession must be used inside SessionProvider');
  return ctx;
};

3. Route guard

// app/(app)/_layout.tsx
import { Redirect, Stack } from 'expo-router';
import { useSession } from '@/src/session';

export default function AppLayout() {
  const { token, loading } = useSession();

  if (loading) return null; // keep the splash screen up
  if (!token) return <Redirect href="/sign-in" />;

  return <Stack />;
}

4. An API client that handles 401s

This is the one everybody underestimates.

// src/api.ts
import { env } from './env';

let refreshing: Promise<string | null> | null = null;

export function createApi(
  getToken: () => string | null,
  refresh: () => Promise<string | null>,
) {
  return async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
    const call = (token: string | null) =>
      fetch(`${env.EXPO_PUBLIC_API_URL}${path}`, {
        ...init,
        headers: {
          'Content-Type': 'application/json',
          ...(token ? { Authorization: `Bearer ${token}` } : {}),
          ...init.headers,
        },
      });

    let res = await call(getToken());

    if (res.status === 401) {
      // de-dupe: ten parallel requests should trigger one refresh
      refreshing ??= refresh().finally(() => (refreshing = null));
      const fresh = await refreshing;
      if (fresh) res = await call(fresh);
    }

    if (!res.ok) throw new Error(`${res.status} ${path}`);
    return res.json() as Promise<T>;
  };
}

That's four files. You still haven't touched push notifications, deep links, payments, analytics, error reporting, EAS build profiles, or CI.

Do the math honestly

Here's a tiny estimator. Plug in your own numbers; mine are illustrative, not data.

type Item = { name: string; days: number };

const build: Item[] = [
  { name: 'auth + session + guards', days: 3 },
  { name: 'api client + query setup', days: 2 },
  { name: 'env, build profiles, CI', days: 3 },
  { name: 'theming + base components', days: 4 },
  { name: 'push, deep links', days: 3 },
  { name: 'payments', days: 4 },
];

const dayRate = 400; // your cost, not your price
const buildDays = build.reduce((sum, i) => sum + i.days, 0);
const upkeepDaysPerYear = 8; // SDK upgrades, dependency churn

console.log({
  buildCost: buildDays * dayRate,           // 7600
  yearOneCost: (buildDays + upkeepDaysPerYear) * dayRate, // 10800
});

The line most people leave out is upkeepDaysPerYear. Expo ships new SDK versions regularly, and a boilerplate that isn't upgraded is a liability by next year.

What "buy" really means now

"Buy" used to mean one thing: pay for a starter kit repo. Now there are three flavors:

Option	You get	You give up
Free OSS template	A starting point, community fixes	Guarantees, consistency
Paid starter kit	Integrated auth, payments, support	Freedom from the author's stack choices
AI-generated starter	Screens and code shaped to your idea	Some cleanup and review time

The third is the interesting one. Instead of a generic starter you bend into shape, tools like RapidNative generate React Native + Expo code from a prompt, so the starting point already looks like your app rather than a todo-list demo. You still own and review the code, which matters, because generated code deserves the same scrutiny as a purchased kit.

The decision, in code

type Context = {
  appsPerYear: number;
  needsToShipInWeeks: number;
  stackIsUnusual: boolean;   // custom native modules, odd backend
  teamKnowsTheStack: boolean;
};

function decide(c: Context): 'build' | 'buy' {
  if (c.stackIsUnusual) return 'build';            // no kit will fit
  if (c.appsPerYear >= 3 && c.teamKnowsTheStack) return 'build'; // it amortizes
  if (c.needsToShipInWeeks <= 6) return 'buy';     // time is the constraint
  if (!c.teamKnowsTheStack) return 'buy';          // learn from working code
  return 'build';
}

Crude, but it captures the real trade: building pays off through reuse, buying pays off through speed.

How to audit anything you didn't write

Before you commit to a kit or a generated codebase, check:

# How stale is it?
npx expo-doctor
npm outdated

# How much is there to own?
npx cloc src app --exclude-dir=node_modules

# Does it even typecheck and build clean?
npx tsc --noEmit

Then open the four files from earlier: env, session, route guard, API client. If those are clean, the rest usually is. If token refresh is missing or the env is read ad hoc all over the app, walk away.

My take

Build your own boilerplate once, on purpose, so you know what's in one. After that, stop. Your users don't care who wrote your auth provider, and the second time you hand-roll a 401 retry you're just procrastinating on the product.

What's in your starter that you'd never give up? Drop a comment with what you're building and whether you built or bought the base.

Docker Alternatives in 2026: What to Use Instead (and When You Don't Need a Container at All)

Sarah — Mon, 28 Sep 2026 05:55:33 +0000

TL;DR

"Docker" is four things: a desktop app, an engine, a build tool, and the OCI standard. Most alternatives replace one layer, not all of them.
Podman if you need free at any company size and want rootless, daemonless containers.
OrbStack if you're on a Mac and want speed (paid for commercial use).
Colima if you want the lightest free Mac setup with no GUI.
Rancher Desktop if you deploy to Kubernetes. Finch/nerdctl if you want containerd everywhere.
Buildah/Kaniko for building images in CI without a privileged daemon.
And sometimes the fix is a single binary instead of a container stack. Local Supabase is the textbook case.

Why everyone's shopping for alternatives

Let's be honest about the actual pain, because each tool below fixes a different one:

Licensing. Docker Desktop is paid for commercial use above ~250 employees or $10M revenue. The engine is free; the desktop app isn't.
RAM and startup on macOS/Windows. It's a Linux VM. 1–2 GB idle and a slow cold start is the norm.
Root daemon. dockerd runs as root on every dev machine. That's a big surface.
Heavy local stacks. Some projects need a dozen containers just to run a backend locally.

Figure out which of these is your problem before picking a replacement.

The stack, layer by layer

Every "Docker alternative" swaps out one row here:

Layer	Docker	Alternatives
Desktop app (VM + GUI)	Docker Desktop	OrbStack, Colima, Rancher Desktop, Lima, Finch
Engine / CLI	`dockerd` + `docker`	Podman, `nerdctl` + containerd
Image builder	`docker build` / BuildKit	Buildah, Kaniko, `nerdctl build`
Orchestration	Compose, Swarm	Podman Compose, k3s, kind
The workload	A container	A single binary

Your Dockerfiles and images work everywhere because it's all OCI. Only the tooling changes.

Podman: alias it and move on

Daemonless, rootless, OCI-compatible. The closest thing to a drop-in engine replacement.

# macOS
brew install podman
podman machine init && podman machine start

# Fedora / RHEL
sudo dnf install podman

# Ubuntu / Debian
sudo apt install podman

# Existing scripts keep working
alias docker=podman

Same commands you already know:

podman pull nginx:alpine
podman run -d -p 8080:80 --name web nginx:alpine
podman ps
podman logs web
podman stop web && podman rm web

No daemon means each container is a child process owned by you. A container escape lands in your user account, not root.

Podman also has native pods and can spit out Kubernetes YAML from a running one:

podman pod create --name app -p 3000:3000
podman run -d --pod app --name api node:20 node server.js
podman run -d --pod app --name cache redis:7
podman generate kube app > app.yaml

podman compose handles most docker-compose.yml files. Expect the occasional edge case with exotic Compose features.

OrbStack: the fast Mac option

macOS-only. Own VM layer, Docker-compatible engine, so docker and docker compose work as-is.

brew install orbstack
docker run -it --rm alpine sh   # that's it

You get ~1s startup, much lower idle memory, zero-config file sharing and port forwarding, lightweight Linux VMs (orb create ubuntu), and optional Kubernetes.

Catch: free for personal use, paid for commercial. Cheaper than Docker Business, but not open source.

Colima / Lima: no GUI, no license, no drama

Lima runs Linux VMs on macOS with file sharing and port forwarding handled. Colima wraps it and gives you a container runtime in one command.

brew install colima docker

colima start                          # dockerd in a Lima VM
colima start --runtime containerd     # or containerd + nerdctl
colima start --cpu 4 --memory 8 --disk 60
colima start --kubernetes

After that, the plain docker CLI just points at Colima's socket. Want more control? Use Lima directly and write your own VM template — it's also what Rancher Desktop and Finch sit on.

Rancher Desktop: containers + local k8s

From SUSE. Container runtime, GUI, and a k3s cluster in one install. Switch runtime between containerd and dockerd in settings.

brew install --cask rancher

nerdctl run -d -p 8080:80 nginx   # containerd mode
docker run -d -p 8080:80 nginx    # dockerd mode
kubectl get nodes                 # already there

Heavier than Colima or OrbStack because Kubernetes always ships with it. Worth it if prod is k8s and you want local parity for free.

Finch / nerdctl: go containerd-native

containerd is what's under Docker, Kubernetes, and basically every cloud. nerdctl is a Docker-compatible CLI that talks to it directly. Finch (from AWS) bundles Lima + containerd + nerdctl + BuildKit.

brew install --cask finch
finch vm init && finch vm start

finch run -d -p 8080:80 nginx
finch compose up

No Docker engine in the picture at all — just the runtime everything already standardizes on.

Buildah / Kaniko: your CI doesn't need a daemon

If the pain is in CI rather than on laptops, skip the engine entirely.

Buildah builds OCI images from a Dockerfile with no daemon:

buildah bud -t myapp:latest .
buildah push myapp:latest docker://registry.example.com/myapp:latest

Kaniko builds inside a Kubernetes pod or CI job with no privileged access:

- name: Build with Kaniko
  image: gcr.io/kaniko-project/executor:latest
  args:
    - --dockerfile=Dockerfile
    - --context=.
    - --destination=registry.example.com/myapp:${CI_COMMIT_SHA}

Both let you delete Docker-in-Docker from your pipeline.

Apple's native `container`

Since macOS 15.4, Apple ships a native container framework — one lightweight VM per container. Ecosystem is thin right now, but if you're on Apple Silicon it's worth a look.

container system start
container run -it alpine sh

Experimental today. Might be the macOS default in a couple of years.

The alternative nobody lists: no container

Everything above assumes the thing you're running should be a container. For plenty of local dev, that's true. But some workloads are only containerized out of convenience, and the container stack is the overhead.

Local Supabase is the clearest example. supabase start pulls a 12-container stack (Postgres, PostgREST, GoTrue, Storage, Realtime, ...) at 2+ GB of images, just so your app can hit a database on localhost. On a constrained laptop, a locked-down corporate machine, or inside a browser, that's somewhere between painful and impossible.

Tinbase flips it: the Supabase wire protocols (PostgREST, GoTrue, Storage, Realtime) reimplemented in a single process, backed by embedded Postgres 17. No Docker, no VM:

npx tinbase start

Your supabase-js code doesn't change because the API surface is identical:

import { createClient } from '@supabase/supabase-js'

// Tinbase locally, hosted Supabase in prod — same code
const supabase = createClient(
  process.env.SUPABASE_URL,   // e.g. http://localhost:54321
  process.env.SUPABASE_ANON_KEY
)

const { data, error } = await supabase
  .from('todos')
  .select('*')
  .order('created_at', { ascending: false })

It reads the same supabase/migrations/*.sql files as the Supabase CLI, so when you're ready to ship you push the same migrations to hosted Supabase. RLS, auth.uid(), triggers, FKs — all real Postgres behavior, because it's real Postgres.

Caveats, because they matter: it's MIT-licensed and open source, it's alpha (local dev, prototypes, embedded — not prod), and it also has WASM and in-memory engines that run the whole backend in a browser tab.

The bigger takeaway: before you swap one VM manager for another, ask whether the workload needs a container at all. Embedded databases (SQLite, PGlite, embedded Postgres), single-binary services, and in-process runtimes often delete the problem instead of moving it.

Pick one

Situation	Use
Over the Docker Desktop license line, need free at any size	Podman (+ Podman Desktop for GUI)
Solo Mac dev, want speed	OrbStack
Lightest free Mac setup, no GUI	Colima
Deploy to Kubernetes	Rancher Desktop
containerd everywhere	Finch / nerdctl
Image builds in CI without privileged Docker	Buildah or Kaniko
Local Supabase and the stack is the problem	Tinbase

Things that will bite you when switching

Socket path. Testcontainers, VS Code Dev Containers, and some CLIs assume /var/run/docker.sock. Set DOCKER_HOST to the new socket (Colima and Podman print it on start).
Volume mount perf is different. If a mounted node_modules suddenly crawls, exclude it or use a named volume.
Compose edge cases. Test depends_on conditions and healthcheck blocks before assuming parity on Podman/nerdctl.
One tool per team. Five engineers on five setups costs more than any of these tools save. Agree on a default and write it down.

Wrapping up

The ecosystem is better because Docker stopped being the only option. Podman covers licensing and security, OrbStack and Colima cover Mac performance, Rancher Desktop and Finch cover k8s and containerd, Buildah and Kaniko cover CI, and for workloads that were only ever containerized out of habit, a single npx command can replace the whole stack.

What did you switch to — or what did you realize never needed a container in the first place? Drop it in the comments.

Single Binary Deploy: Ship Your Whole App as One File

Sarah — Fri, 25 Sep 2026 13:29:09 +0000

TL;DR

Compile your entire app — server, templates, static files, migrations, SQLite — into one static binary
Go's embed and Rust's rust-embed make this a few lines of code
Deploy = scp + atomic mv + systemctl restart. Rollback = the reverse
Great for monoliths and small service counts. Not great for multi-node writes or 200 MB frontend bundles
Full copy-paste deploy.sh at the bottom

Most deployment pain is a headcount problem. A runtime, a dependency tree, a static folder, a config dir, a container image wrapping all of it — every piece is one more thing that can drift between your laptop and prod.

A single-binary deploy collapses all of it into one executable with zero runtime dependencies. If it runs on staging, it runs on prod, because there's nothing else to install.

Here's the full setup in Go, the Rust equivalent, and where it falls apart.

What goes in the binary

Traditional deploy	Single-binary deploy
Runtime (Node, Python, JVM)	Compiled in
`node_modules` / `site-packages`	Compiled in
`/static`, `/templates`	Embedded
SQL migrations	Embedded
Config files	Flags + env vars, defaults compiled in
Database server	SQLite embedded (optional)
Dockerfile + image	Gone

The Go version

Layout

myapp/
├── main.go
├── migrations/001_init.sql
├── static/app.css
└── templates/index.html

Embed everything

package main

import (
    "database/sql"
    "embed"
    "html/template"
    "io/fs"
    "log"
    "net/http"

    _ "modernc.org/sqlite" // pure Go, no CGO
)

//go:embed static/*
var staticFS embed.FS

//go:embed templates/*.html
var templateFS embed.FS

//go:embed migrations/*.sql
var migrationFS embed.FS

func main() {
    db, err := sql.Open("sqlite", "app.db")
    if err != nil {
        log.Fatal(err)
    }
    if err := runMigrations(db); err != nil {
        log.Fatal(err)
    }

    tmpl := template.Must(template.ParseFS(templateFS, "templates/*.html"))
    staticSub, _ := fs.Sub(staticFS, "static")
    http.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.FS(staticSub))))

    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        tmpl.ExecuteTemplate(w, "index.html", nil)
    })

    log.Fatal(http.ListenAndServe(":8080", nil))
}

Run migrations from the embedded FS

func runMigrations(db *sql.DB) error {
    entries, err := migrationFS.ReadDir("migrations")
    if err != nil {
        return err
    }
    for _, e := range entries {
        b, err := migrationFS.ReadFile("migrations/" + e.Name())
        if err != nil {
            return err
        }
        if _, err := db.Exec(string(b)); err != nil {
            return err
        }
    }
    return nil
}

(For real projects, golang-migrate has an iofs driver that reads from embed.FS and tracks versions. Use that.)

Build it

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags="-s -w -X main.version=$(git describe --tags --always)" -o myapp .

CGO_ENABLED=0 → fully static, no libc
GOOS/GOARCH → cross-compile from anywhere
-s -w → strip symbols, ~35% smaller
-X main.version=... → bake the git tag in so /healthz tells you what's live

One file, ~15 MB, whole app.

The Rust version

use rust_embed::RustEmbed;
use axum::{Router, routing::get, response::Html};

#[derive(RustEmbed)]
#[folder = "static/"]
struct Assets;

async fn index() -> Html<&'static str> {
    Html(include_str!("../templates/index.html"))
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(index));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

Deploying it

scp ./myapp deploy@server:/opt/myapp/myapp.new
ssh deploy@server '
  cd /opt/myapp &&
  mv myapp myapp.prev &&
  mv myapp.new myapp &&
  sudo systemctl restart myapp
'

mv on the same filesystem is atomic — no half-written binary ever gets executed. Rollback:

ssh deploy@server 'cd /opt/myapp && mv myapp.prev myapp && sudo systemctl restart myapp'

systemd unit:

[Unit]
Description=myapp
After=network.target

[Service]
User=deploy
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/myapp
Restart=always
RestartSec=2
Environment=PORT=8080
Environment=DATABASE_PATH=/opt/myapp/data/app.db

[Install]
WantedBy=multi-user.target

Don't want to manage the box at all? Hosted options like RapidNative Deploy take the compiled artifact and handle the hosting layer, so the copy-and-restart step becomes a push.

Config without config files

port := flag.String("port", envOr("PORT", "8080"), "listen port")
dbPath := flag.String("db", envOr("DATABASE_PATH", "app.db"), "sqlite path")
flag.Parse()

func envOr(key, fallback string) string {
    if v := os.Getenv(key); v != "" {
        return v
    }
    return fallback
}

Precedence: flag → env → compiled default. Runs with zero setup, overridable in the unit file.

Where it breaks

Constraint	Reality
Multi-node writes	SQLite is single-writer. Litestream/LiteFS help; otherwise Postgres
Huge frontend bundles	Embedding 200 MB inflates every deploy — CDN those
Python / Node	Works via PyInstaller or `bun build --compile`, but it's a bolt-on
15+ services	An orchestrator still earns its keep at that scale
Zero-downtime restarts	You still need `http.Server.Shutdown` for graceful drain

Sweet spot: a monolith or a handful of services on one or a few boxes. Which is most projects.

The whole deploy script

#!/usr/bin/env bash
set -euo pipefail

APP=myapp
HOST=deploy@your-server
DIR=/opt/$APP
VERSION=$(git describe --tags --always)

echo "Building $APP@$VERSION..."
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags="-s -w -X main.version=$VERSION" -o "$APP" .

echo "Uploading..."
scp "$APP" "$HOST:$DIR/$APP.new"

echo "Swapping and restarting..."
ssh "$HOST" "cd $DIR && mv $APP $APP.prev && mv $APP.new $APP && sudo systemctl restart $APP"

echo "Verifying..."
sleep 2
ssh "$HOST" "curl -sf localhost:8080/healthz"
echo
echo "Deployed $VERSION"

Twenty lines. No Docker, no YAML, rollback is one mv away.

If you've been reaching for Docker by default, try shipping your next small service as a single binary. Drop a comment with what you're running this way — or what stopped you from trying it.

Stripe, Merchant of Record, or In-App Purchases? Picking a Payments Stack Without Regretting It

Sarah — Wed, 23 Sep 2026 05:51:24 +0000

TL;DR

There are three real options: a payment processor (Stripe), a Merchant of Record (Paddle, Lemon Squeezy), or app store billing (Apple/Google, usually via RevenueCat).
The decision is about who is legally the seller — that determines who owns tax, disputes, and refunds. Fees are secondary.
Native mobile app selling digital features? IAP isn't a choice, it's a constraint. Plan a cheaper web checkout alongside it.
Whatever you pick, you'll write a unified entitlement layer fed by webhooks. Build it before your second payment channel, not after.
Code for the webhook handler, entitlement table, and cross-platform access check is below.

The moment every app hits

Product works. A few people want to pay. Suddenly you're reading about VAT nexus, webhook idempotency, and why Apple wants 30%.

Payments look like a checkout button. Underneath it's a question of who is on the receipt, and that question decides most of your operational load for the next two years.

The three options

1. Payment processor (Stripe, Adyen, regional gateways)

You are the seller. Stripe moves money; everything else is yours.

Lowest fees, around 3%.
Full control over checkout and pricing logic.
Tax is your problem. Stripe Tax calculates it; registering and filing is still you.
Chargebacks and dispute evidence are yours.
Your entitlement logic lives entirely in how well you handle webhooks.

Here's the minimum viable Stripe webhook handler. The important parts are signature verification and idempotency — Stripe will retry events, and you will get duplicates.

// app/api/stripe/webhook/route.ts
import Stripe from "stripe";
import { db } from "@/lib/db";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const body = await req.text();
  const sig = req.headers.get("stripe-signature")!;

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response("Bad signature", { status: 400 });
  }

  // Idempotency: bail if we've already processed this event id
  const seen = await db.processedEvents.findUnique({ where: { id: event.id } });
  if (seen) return new Response("ok");

  switch (event.type) {
    case "checkout.session.completed":
    case "invoice.paid": {
      const sub = await stripe.subscriptions.retrieve(
        (event.data.object as any).subscription as string
      );
      await grantEntitlement({
        userId: sub.metadata.userId,
        plan: sub.items.data[0].price.lookup_key ?? "pro",
        source: "stripe",
        expiresAt: new Date(sub.current_period_end * 1000),
      });
      break;
    }
    case "customer.subscription.deleted": {
      const sub = event.data.object as Stripe.Subscription;
      await revokeEntitlement({ userId: sub.metadata.userId, source: "stripe" });
      break;
    }
  }

  await db.processedEvents.create({ data: { id: event.id } });
  return new Response("ok");
}

That's the skeleton. Proration, trials, dunning, and upgrade-mid-cycle all add branches to that switch statement.

Best for: web SaaS with a team that can own billing, marketplaces, custom pricing, or businesses selling into one or two tax jurisdictions.

2. Merchant of Record (Paddle, Lemon Squeezy, FastSpring)

They are the seller. Their name is on the receipt. They calculate, collect, and remit tax everywhere, eat the chargebacks, and send you a payout.

Higher take, roughly 5% plus a fixed fee.
Global tax just disappears as a problem. Sell to the EU, UK, India, Australia on day one with zero registrations.
Less control: you live inside their checkout and subscription model.
Slower payouts, typically bi-weekly or monthly.

The webhook handler looks almost identical to the Stripe one — different event names, same shape. Which is the point: your entitlement layer shouldn't care which provider fired the event.

// Paddle-style events map onto the same grant/revoke calls
switch (event.event_type) {
  case "subscription.activated":
  case "subscription.updated":
    await grantEntitlement({ userId, plan, source: "paddle", expiresAt });
    break;
  case "subscription.canceled":
    await revokeEntitlement({ userId, source: "paddle" });
    break;
}

Best for: indie products, small teams selling internationally, digital downloads, anyone without a finance function.

3. App store billing (Apple IAP, Google Play, via RevenueCat)

If you ship a native app and sell digital features inside it, you don't get to choose. The platform is the seller.

15–30% depending on program tier and revenue.
Two platforms, two receipt formats, two server-notification systems with different semantics. This is why RevenueCat exists.
Subscriptions are managed in the store. Cancellations and refunds happen there; you react to events.
Cross-platform users are the hard part: subscribed on iPhone, logged in on web, expects access.

Client-side in React Native, RevenueCat collapses both stores into one call:

import Purchases from "react-native-purchases";

Purchases.configure({ apiKey: Platform.OS === "ios" ? IOS_KEY : ANDROID_KEY });
await Purchases.logIn(user.id); // ties store purchases to YOUR user id

const { customerInfo } = await Purchases.purchasePackage(pkg);
const hasPro = customerInfo.entitlements.active["pro"] !== undefined;

Server-side, RevenueCat's webhook feeds the same entitlement table as Stripe and Paddle:

// RevenueCat webhook → same grant/revoke
if (["INITIAL_PURCHASE", "RENEWAL", "UNCANCELLATION"].includes(event.type)) {
  await grantEntitlement({
    userId: event.app_user_id,
    plan: event.entitlement_ids[0],
    source: event.store.toLowerCase(), // "app_store" | "play_store"
    expiresAt: new Date(event.expiration_at_ms),
  });
}
if (["CANCELLATION", "EXPIRATION"].includes(event.type)) {
  await revokeEntitlement({ userId: event.app_user_id, source: event.store.toLowerCase() });
}

Best for: any native app selling digital features. Not a preference — a constraint to design around early.

The part you'll write regardless: the entitlement layer

Every option above ends in the same two functions. One table, one question: does this user have this plan right now?

create table entitlements (
  user_id     text not null,
  plan        text not null,
  source      text not null,          -- 'stripe' | 'paddle' | 'app_store' | 'play_store'
  expires_at  timestamptz not null,
  updated_at  timestamptz default now(),
  primary key (user_id, source)
);

export async function hasAccess(userId: string, plan = "pro") {
  const row = await db.entitlements.findFirst({
    where: { userId, plan, expiresAt: { gt: new Date() } },
  });
  return !!row;
}

Notice source is part of the primary key. A user can hold a Stripe subscription and an App Store one at the same time (it happens more than you'd think). hasAccess doesn't care where it came from. That single design choice is what makes "subscribed on iPhone, logged in on web" work.

If you're generating the app scaffold rather than hand-wiring every project, tools like RapidNative ship this entitlement pattern with the provider hooks already in place for React Native, which lets you make the provider decision without also paying the integration tax each time.

The decision table

	Processor (Stripe)	Merchant of Record	App Store IAP
Who is the seller	You	Them	Apple / Google
Typical fee	~3%	~5% + fixed	15–30%
Global tax	Your problem (tools help)	Handled	Handled
Checkout control	Full	Limited	Minimal
Webhook complexity	High	Medium	High (two platforms)
Payout speed	Daily	Bi-weekly / monthly	Monthly
Best fit	Web SaaS, custom billing	Indie, global, small teams	Native mobile

What actually decides it

Fees get all the attention and matter least under a few thousand in MRR. What actually decides it:

Where is the app? Native mobile means IAP for the in-app path. Plan web checkout as a separate, cheaper channel from the start.
Where are the customers? More than two or three tax jurisdictions and an MoR pays for itself in hours not spent.
Who owns billing bugs? If nobody on the team wants to debug a proration edge case at 11pm, that's an MoR signal.
Do you need one entitlement layer? Yes, the moment you have a second channel. Build it first.

Two mistakes I keep seeing: picking Stripe because it's the "serious" choice and discovering three months in that the founder is filing VAT returns instead of talking to users. And wiring IAP first, then realising web checkout could have captured the same users at a third of the fee.

The short version

Native mobile → IAP in-app plus web checkout on the side. Small team selling globally → Merchant of Record. Web SaaS with engineering capacity and custom billing → Stripe.

Pick based on who you want responsible for tax and disputes, not the fee percentage. The fee is visible. The operational cost isn't, and it's usually bigger.

Which stack are you running, and would you pick it again? Drop it in the comments — especially if you've moved between two of these, I'd like to hear how the migration went.

React Native CI/CD in 2026: EAS Build + GitHub Actions, done properly

Sarah — Mon, 21 Sep 2026 05:40:42 +0000

TL;DR

GitHub Actions owns the code (lint, types, tests). EAS owns the binary (build, sign, submit).
If a step needs Xcode, Ruby, or a keychain, it goes to EAS. Everything else stays on cheap Ubuntu runners.
Use three eas.json profiles (development, preview, production) and appVersionSource: "remote".
The only GitHub secret you need is EXPO_TOKEN. Signing material lives in EAS managed credentials.
Ship JS-only changes with eas update in ~90 seconds, and use fingerprint runtime versions so OTA never hits an incompatible binary.

Every React Native team eventually hits the same wall: the app works, the code is clean, and shipping is still a manual, terrifying ritual. Certificates expire on Fridays. Someone's laptop holds the only working keystore. A junior dev opens Xcode for an OTA-worthy typo fix.

This post is the pipeline I'd give my past self. It splits work across two systems on purpose - GitHub Actions for JS, EAS for native - and covers the exact eas.json, the exact workflow YAML, and the parts nobody warns you about.

Why not just do it all in GitHub Actions?

You can. You'll spend $50–200/month on macOS runner minutes, you'll rebuild your keychain in YAML every commit, and your iOS builds will take 15+ minutes because there's no caching layer that understands React Native.

EAS is a service built by the Expo team specifically for compiling and signing React Native binaries. It caches by fingerprint (JS-only PRs skip native rebuild), manages certificates for you, and submits to TestFlight/Play with one flag. It's not free, but neither is a macOS runner at $0.08/minute.

Rule of thumb: if a step needs Xcode, Ruby, or a keychain, EAS does it. Everything else stays on GitHub Actions.

The `eas.json` that actually works

Most tutorials show a one-profile eas.json. That's a trap. You want three:

{
  "cli": {
    "version": ">= 12.0.0",
    "appVersionSource": "remote"
  },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal",
      "env": { "APP_ENV": "development" },
      "ios": { "simulator": true }
    },
    "preview": {
      "distribution": "internal",
      "channel": "preview",
      "env": { "APP_ENV": "preview" }
    },
    "production": {
      "channel": "production",
      "env": { "APP_ENV": "production" },
      "autoIncrement": true
    }
  },
  "submit": {
    "production": {
      "ios": {
        "appleId": "you@example.com",
        "ascAppId": "1234567890",
        "appleTeamId": "ABCD123456"
      },
      "android": {
        "serviceAccountKeyPath": "./google-service-account.json",
        "track": "internal"
      }
    }
  }
}

The one setting worth calling out: appVersionSource: "remote". This kills version-bump merge conflicts forever because EAS owns the build number, not your repo.

The GitHub Actions workflow

Drop this into .github/workflows/ci.yml:

name: CI/CD

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm run lint
      - run: npm run type-check
      - run: npm test -- --ci

  preview-build:
    needs: quality
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci
      - run: eas build --profile preview --platform all --non-interactive --no-wait

  production-release:
    needs: quality
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci
      - run: eas build --profile production --platform all --auto-submit --non-interactive

  ota-update:
    needs: quality
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci
      - run: eas update --channel production --message "${{ github.event.head_commit.message }}"

Notes worth reading before you copy-paste:

--no-wait on preview builds - Actions kicks off the EAS build and returns. Don't burn Ubuntu minutes waiting.
--auto-submit on production - EAS builds AND submits to TestFlight/Play in one command.
ota-update runs in parallel with production-release so JS-only changes reach users in ~90 seconds even if the native binary takes 20 minutes.

Code signing without pain

Store EXPO_TOKEN as a GitHub Actions secret. That's the only secret you need.

Signing certs, provisioning profiles, keystore, service account JSON - all of it lives inside EAS as managed credentials. eas build prompts you once on the first run, generates or uploads them, and never asks again. Certificates rotate automatically before expiry.

The alternative - storing certs and keys in GitHub Actions secrets - technically works. Then a certificate expires and you're debugging Fastlane at 11pm on a Friday. Don't do it.

The OTA / native update boundary

Runtime version + fingerprint policy is the setting that keeps this system honest. In app.json:

{
  "expo": {
    "runtimeVersion": { "policy": "fingerprint" }
  }
}

EAS hashes the parts of your project that affect the native binary. If your PR only touches JS/TS, the fingerprint doesn't change and the OTA update reaches the existing binary. If you add expo-camera, the fingerprint changes, and EAS refuses to serve the OTA to the old binary - forcing a native rebuild. This is exactly the behavior you want; without it, an OTA update can crash users' apps in production.

What breaks first (from experience)

Expired iOS provisioning profiles - solved by EAS managed credentials.
Keystore password mismatch after a team member leaves - solved by EAS managed credentials.
EXPO_TOKEN scoped to the wrong project - check expo whoami and the token's project scope in your Expo dashboard.
Native module added but runtime version pinned - switch to fingerprint policy.

One shortcut: start from a CI-ready project

If you're generating your Expo project with an AI tool like RapidNative, the export already ships with eas.json, fingerprint runtime version, and the monorepo layout expo-github-action expects - so this workflow drops in without rewiring.

Wrapping up

Regardless of where the project came from: build the pipeline once, and every future release is a git push. That's the whole payoff.

What does your React Native release pipeline look like right now - all-in on EAS, Fastlane on macOS runners, or still building from someone's laptop? Drop a comment with what you're building and what broke last. I'll answer with code.

DEV Community: Sarah

File-Based Routing: Your Folder Structure Is Your Navigation

TL;DR

Files → routes

The 6 conventions

1. Index routes

2. Dynamic segments

3. Catch-all

4. Layouts

5. Route groups

6. Not-found

A real structure

Navigating

Where it bites

Renaming = breaking change

Non-route files in app/

Deep nesting

Auth guards are still code

Should you switch?

Wrap-up

We deleted our docs framework. The replacement is 400 lines of Next.js + MDX.

The entire dependency list

The file tree

1. One route for every page

2. The "content layer" is fs + gray-matter

3. Rendering: MDX on the server, zero MDX runtime on the client

4. The sidebar is not alphabetical. On purpose.

The kill list

Framework vs hand-rolled, honestly

Don't do this if…

References

Expo Push Notifications in React Native: The Production Guide the Quickstart Skips

The mental model (get this wrong and nothing else helps)

Before you write any code

1. Install and configure

2. Channels first, and by intent

3. Don't burn your one iOS prompt

4. Get the token without crashing launch

5. A user is not a token

6. Send from the server, never the app

7. Check receipts and prune dead tokens

8. Foreground notifications and taps

Foreground: be selective

Taps: cover the cold start

Limits cheat sheet

Your Supabase Auth Is Only as Good as Your RLS Policies. So Test Them.

TL;DR

The bug nobody notices

The schema we'll protect

Four ways RLS quietly breaks

The tests

Running it locally (and in CI)

The rule I follow now

React Native Accessibility in 2026 — Mapping WCAG 2.2 AA to the Props You Actually Write

Why you should care (even though the deadline moved)

The whole toolbox in one component

Perceivable + Operable

1.1.1 Non-text Content (A)

1.3.1 Info and Relationships (A)

1.4.3 Contrast (Minimum) (AA)

1.4.4 Resize Text + 1.4.10 Reflow (AA)

2.1.1 Keyboard (A)

2.4.3 Focus Order (A) + 2.4.11 Focus Not Obscured (AA, new)

2.5.8 Target Size (Minimum) (AA, new)

2.5.7 Dragging Movements (AA, new)

Understandable + Robust

3.3.1 Error Identification (A) + 3.3.3 Error Suggestion (AA)

3.3.2 Labels or Instructions (A)

3.3.8 Accessible Authentication (Minimum) (AA, new)

4.1.2 Name, Role, Value (A)

4.1.3 Status Messages (AA)

The 5 bugs you'll find in almost every audit

Testing: the 4-layer workflow

Where to start today

Build vs Buy a Boilerplate: What Your React Native Starter Actually Costs

TL;DR

The boilerplate you think you're building

The boilerplate you actually build

1. Env validation

2. Session storage

Non-route files in `app/`

2. The "content layer" is `fs` + `gray-matter`

Apple's native `container`

The `eas.json` that actually works