This guide covers what edge functions actually are, how the runtime differs from Node.js, four patterns you can copy today, and the one architectural mistake that makes edge functions slower than the regional server they replaced.

The examples use Cloudflare Workers syntax. The same ideas apply to Vercel Edge Functions, Deno Deploy, Netlify Edge Functions, and Supabase Edge Functions with small changes.

What is an edge function?

An edge function is a small piece of server-side code that is deployed to many locations around the world at once. When a request arrives, the network routes it to the nearest location and runs your code there.

Compare that with a traditional backend:

• Regional server or serverless function: your code lives in one region, for example ap-south-1. A user in Sydney waits for the request to travel to Mumbai and back.

• Edge function: your code lives in hundreds of locations. The Sydney user is served from Sydney.

The network round trip to a distant region can cost 200 to 300 ms before your code runs a single line. Edge functions remove most of that.

How the runtime works: isolates, not containers

Traditional serverless platforms start a container or micro-VM for your function. If no warm instance exists, the user waits for a cold start, which can take hundreds of milliseconds.

Most edge platforms use V8 isolates instead. An isolate is the same sandbox that separates tabs in Chrome. Thousands of isolates can share one process, and a new one starts in a few milliseconds.

This design has two consequences:

1. Cold starts are close to zero. You can run code on every request without a latency penalty.

2. You do not get Node.js. You get a runtime built on Web standard APIs: Request, Response, fetch, URL, crypto.subtle, and streams. Packages that depend on native modules or on fs will not work. Node compatibility layers exist on most platforms, but they are partial.

Your first edge function

export default {
  async fetch(request, env, ctx) {
    const country = request.cf?.country ?? "unknown";

    return Response.json({
      message: "Hello from the edge",
      country,
    });
  },
};

A function receives a Request and returns a Response. That is the whole contract. request.cf is Cloudflare-specific and carries geolocation data; other platforms expose the same information through headers.

Edge functions vs serverless functions

These are not competing options. Most production systems use both: edge functions in front, regional functions or servers behind.

Four patterns worth copying

1. Verify auth before the request reaches your origin

Rejecting bad requests at the edge saves origin capacity and gives unauthenticated users a fast answer.

import { jwtVerify } from "jose";

export default {
  async fetch(request, env) {
    const header = request.headers.get("Authorization") ?? "";
    const token = header.replace("Bearer ", "");

    if (!token) {
      return new Response("Unauthorized", { status: 401 });
    }

    try {
      const secret = new TextEncoder().encode(env.JWT_SECRET);
      const { payload } = await jwtVerify(token, secret);

      // Forward to the origin with the verified user id attached
      const forwarded = new Request(request);
      forwarded.headers.set("x-user-id", payload.sub);
      return fetch(forwarded);
    } catch {
      return new Response("Invalid token", { status: 401 });
    }
  },
};

jose works here because it is built on the Web Crypto API. The popular jsonwebtoken package depends on Node's crypto module and is a common first stumbling block.

2. Proxy third-party APIs to keep keys out of your app

Any key you ship inside a mobile or web bundle can be extracted. An edge function is the cheapest place to hide it.

export default {
  async fetch(request, env) {
    if (request.method !== "POST") {
      return new Response("Method not allowed", { status: 405 });
    }

    const { prompt } = await request.json();

    const upstream = await fetch("https://api.openai.com/v1/chat/completions", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${env.OPENAI_API_KEY}`,
      },
      body: JSON.stringify({
        model: "gpt-6-luna",
        messages: [{ role: "user", content: prompt }],
      }),
    });

    return new Response(upstream.body, {
      status: upstream.status,
      headers: { "Content-Type": "application/json" },
    });
  },
};

The client only ever sees your endpoint:

const res = await fetch("https://api.example.com/ai", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ prompt: "Summarise my notes" }),
});
const data = await res.json();

This pattern matters most for React Native and Expo apps, where there is no server by default. If you generate your app with RapidNative, put a proxy like this in front of every paid API before you ship. Add rate limiting per user as well, because a hidden key behind an open endpoint is still an open wallet.

3. A/B testing without flicker

Client-side experiments load the page and then swap content, which users see as a flash. Deciding the variant at the edge avoids it.

export default {
  async fetch(request) {
    const cookie = request.headers.get("Cookie") ?? "";
    let variant = cookie.match(/variant=(a|b)/)?.[1];
    const isNew = !variant;

    if (isNew) {
      variant = Math.random() < 0.5 ? "a" : "b";
    }

    const url = new URL(request.url);
    url.pathname = `/${variant}${url.pathname}`;

    const response = await fetch(new Request(url, request));
    const result = new Response(response.body, response);

    if (isNew) {
      result.headers.append(
        "Set-Cookie",
        `variant=${variant}; Path=/; Max-Age=2592000`
      );
    }

    return result;
  },
};

4. Cache API responses close to the user

export default {
  async fetch(request, env, ctx) {
    const cache = caches.default;

    let response = await cache.match(request);
    if (response) return response;

    response = await fetch(request);
    response = new Response(response.body, response);
    response.headers.set("Cache-Control", "public, max-age=60");

    ctx.waitUntil(cache.put(request, response.clone()));
    return response;
  },
};

ctx.waitUntil lets the cache write finish after the response has been sent, so the user does not wait for it.

The mistake that makes edge functions slower

Here is the part most tutorials skip. Your function runs in Sydney. Your Postgres database runs in Virginia. Every query crosses the Pacific.

If a handler makes three sequential queries, you have paid for three long round trips instead of one. A regional function sitting next to the database would have been faster.

There are four ways to deal with this:

• Cache reads at the edge. Use the Cache API or a key-value store for data that tolerates being slightly stale.

• Use a globally distributed data store. Edge KV stores, replicated SQLite, or Postgres read replicas put the data near the function.

• Use an HTTP-based driver or connection pooler. Isolates cannot hold long-lived TCP connection pools the way a server can. Without a pooler you can exhaust database connections quickly.

• Move the function to the data. Several platforms let you pin a function to a region. For write-heavy endpoints this is often the right answer.

A simple rule: if a handler makes more than one uncached database round trip, measure it before you assume the edge is faster.

Other limitations to plan for

• CPU time limits. Image processing, PDF generation, and large JSON transforms can hit the ceiling.

• Bundle size limits. Large dependencies may not fit.

• Package compatibility. Check that a library supports edge runtimes before you design around it.

• Observability. Code running in hundreds of locations needs structured logs and a request id on every line.

When to use edge functions

Use them when the logic is:

• short,

• run on most requests,

• sensitive to latency, and

• not dependent on a far-away database.

Auth checks, redirects, geolocation, personalisation, API proxying, webhooks, and caching all fit.

Use regional serverless functions or a server for heavy computation, long-running jobs, native dependencies, and transactional database work.

Shipping it

For a mobile app, the practical stack is usually a client, a thin edge layer for auth and proxying, and a regional backend for data. If you would rather not wire that together by hand, RapidNative Deploy handles shipping the app and its backend from one place, and a starter kit such as AppLighter gives you a pre-configured Expo project to start from.

Summary

• Edge functions run your code in many locations, on V8 isolates, with almost no cold start.

• The runtime is Web standard APIs, not Node.js. Check your dependencies.

• They are ideal for auth, proxying, A/B tests, and caching.

• They do not fix a slow database path. If your data is in one region, cache it, replicate it, or run the function next to it.

• Use edge and regional functions together, each for the work it suits.

This post covers that week one day at a time. Each day has the lesson it taught me and the code or process I now ship by default in every React Native + Expo + Supabase project. Paying for the same lesson twice is a tax I refuse to keep paying.

TL;DR

• Treat your money path as production infrastructure. Make webhooks idempotent, add retries, and page yourself when they fail.

• Test RLS in CI. A policy in a migration file proves nothing.

• Reply to public complaints the same day, with specifics and a date.

• Build only what paying customers ask for in writing.

• Charge more than feels comfortable.

• Take one day off a week. Burnout is a production incident.

Monday — the webhook that wasn't

I woke up to seven emails from customers who had paid but hadn't been granted access. Stripe said the charges succeeded. My database said no licenses existed.

A dependency bump I'd pushed on Friday night had broken my charge.succeeded handler. The endpoint had been returning 500s for three days. Nothing alerted me, because my "monitoring" was me remembering to check the dashboard.

The lesson arrived before coffee: your money path is a production system and deserves production-grade observability. I'd spent an afternoon tuning animations but shipped Stripe with no retries, no dead-letter handling and no paging.

I rebuilt the webhook that morning. The design has four parts:

1. The endpoint verifies the signature, records the event, and returns 200 within 2 seconds.

2. A unique index on stripe_event_id makes the write idempotent, so Stripe's retries can't double-grant anything.

3. An async consumer does the real work and records any failures.

4. A cron job retries pending events and pages me after three failed attempts.

The webhook route

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

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

export async function POST(req: Request) {
  const sig = req.headers.get("stripe-signature");
  if (!sig) return new Response("missing signature", { status: 400 });

  const body = await req.text();
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch (err) {
    return new Response(`bad signature: ${(err as Error).message}`, { status: 400 });
  }

  // Idempotent write — unique index on stripe_event_id.
  const { error } = await supabaseServer
    .from("webhook_events")
    .insert({
      stripe_event_id: event.id,
      type: event.type,
      payload: event as unknown as object,
      status: "pending",
    });

  if (error && error.code !== "23505") {
    // Insert failed for a non-duplicate reason — tell Stripe we failed, let it retry.
    return new Response("db failure", { status: 500 });
  }

  // Fire-and-forget to the async consumer. Return 200 within 2s regardless.
  queueMicrotask(() => processEvent(event.id).catch(() => {}));
  return new Response("ok", { status: 200 });
}

The async consumer

// modules/stripe/processEvent.ts
export async function processEvent(stripeEventId: string) {
  const { data: row } = await supabaseServer
    .from("webhook_events")
    .select("*")
    .eq("stripe_event_id", stripeEventId)
    .single();

  if (!row || row.status === "done") return;

  try {
    await handle(row.payload);
    await supabaseServer
      .from("webhook_events")
      .update({ status: "done", processed_at: new Date().toISOString() })
      .eq("stripe_event_id", stripeEventId);
  } catch (err) {
    const attempts = (row.attempts ?? 0) + 1;
    await supabaseServer
      .from("webhook_events")
      .update({
        status: attempts >= 3 ? "failed" : "pending",
        attempts,
        last_error: (err as Error).message,
      })
      .eq("stripe_event_id", stripeEventId);
    if (attempts >= 3) await page("stripe webhook failed", stripeEventId);
  }
}

The schema

create table public.webhook_events (
  id uuid primary key default gen_random_uuid(),
  stripe_event_id text not null unique,
  type text not null,
  payload jsonb not null,
  status text not null default 'pending',
  attempts int not null default 0,
  last_error text,
  processed_at timestamptz,
  created_at timestamptz not null default now()
);

create index webhook_events_pending_idx
  on public.webhook_events (status, created_at)
  where status = 'pending';

A cron job runs every 15 minutes. It picks up rows with status = 'pending' that are older than 2 minutes and reruns processEvent. With that in place, the webhook survives bad deploys, rate limits, Supabase blips and me being asleep.

The pattern took one afternoon to build and would have saved me the entire Monday. If you'd rather not build it from scratch, the AI Voice Notes template ships with this exact pattern already wired into its Supabase schema.

Tuesday — the one-star review

My first paying customer, the one I'd personally messaged to thank, left a one-star App Store review: "Doesn't work, waste of money, don't buy."

I drafted an angry reply, then a defensive one, then a self-pitying one. Then I closed the laptop and went for a walk. On the walk I realised two things:

• They weren't attacking me. They'd paid $79, hit a bug, and the review was the only way they had to tell me.

• Everyone reading that review would believe them unless I replied.

So I replied in public within three hours. I named the bug, named the fix date (Friday), and gave them my direct email. Two weeks later they changed the review to five stars and mentioned the fast response.

This is the reply template I now use:

Thanks for taking the time to leave this. The bug you hit is a [specific name], caused by [specific cause]. The fix will ship by [specific date]. If you'd like, email me at [email] and I'll make sure your account is covered through next month either way.

A good reply names the bug and the cause, gives a date, and doesn't get defensive. Public complaints are free QA and free marketing. One honest reply converts better than a hundred testimonials.

Wednesday — the RLS hole

Mid-afternoon, a stranger on Twitter sent me a screenshot. A select * against my user_subscriptions table returned every row, not just his own.

The RLS policy was in my migration file. But the enable row level security statement had failed silently during a bad deploy six weeks earlier. The policy existed in my repo but had never been applied in production.

Thirty minutes of panic later, I'd done four things:

• applied the policy

• rotated the anon key

• audited the logs, which showed nobody else had queried the table

• emailed every affected customer

There was no real damage, and that was pure luck.

The lesson: your database security is only as good as the test that proves it works. The migration file proves nothing, and neither does SQL sitting in your repo. Only a test does. Every sensitive table now gets a pgTAP fixture that runs on every PR:

-- supabase/tests/rls_user_subscriptions.sql
begin;
select plan(3);

set local role authenticated;
set local request.jwt.claim.sub = '00000000-0000-0000-0000-000000000001';

-- 1. RLS must be ON
select ok(
  (select relrowsecurity from pg_class where relname = 'user_subscriptions'),
  'row level security is enabled on user_subscriptions'
);

-- 2. User can see their own rows
select results_eq(
  'select user_id from user_subscriptions',
  array['00000000-0000-0000-0000-000000000001'::uuid],
  'user can see own subscription'
);

-- 3. User cannot see other users' rows
select is_empty(
  'select 1 from user_subscriptions where user_id != ''00000000-0000-0000-0000-000000000001''',
  'user cannot see others subscriptions'
);

select * from finish();
rollback;

If RLS is off, CI fails loudly and I find out before a stranger does. The Applighter docs include the full set of RLS fixtures that ship with every template. Supabase's own RLS guide covers the underlying policies.

Thursday — the features nobody wanted

On Thursday I did the maths I'd been avoiding. I listed every feature I'd shipped in four months, who asked for it, and whether anyone used it.

Worse, one of the two requested features was still half-finished, because I'd been distracted by the other twelve.

The lesson is the oldest one in the indie book: you are not your user. Your taste is a liability until customers validate it. Every feature now goes through this gate in the issue template:

## Feature gate
- [ ] At least three different paying customers have asked for this, by name, in writing.
- [ ] Each ask is linked below.
Asks: _links_

If both boxes aren't ticked, the feature waits in maybe.md. Here's how my prioritisation changed:

Friday — the shipping day

On Friday I shipped the Stripe fix, the RLS fix, and the half-finished requested feature. Then I sent every customer a changelog email, written the way a competent friend would tell you what broke:

This week: three bugs fixed, one security issue patched, one feature added. Named and dated below.

Bug: Stripe webhook failure. Seven customers didn't receive their license on Monday. All affected accounts were fixed manually the same day. The webhook is now idempotent with automatic retries.

Security: RLS was off on user_subscriptions in production. No evidence of data access by anyone else. Policy applied, anon key rotated, automated RLS tests added to CI.

Feature: [X] — requested by three of you, by name. Shipped today.

I expected churn and got the opposite. Three customers upgraded, two referred a friend, and the one-star reviewer became my unofficial beta tester.

Transparency builds trust faster than polish does. People don't expect perfection from indie founders. They expect to hear from you.

Saturday — the pricing

Revenue divided by hours worked that week came to $4.80/hour. Demand wasn't the problem. I was charging \(29/month for something that solved a \)500/month problem for small studios.

So I doubled the price overnight:

• Existing customers stayed on the old rate.

• New signups moved to $59/month.

• I added an annual plan at $499, which cost me nothing to offer.

Signups dropped about 20%, and revenue per signup roughly doubled. I made more money, and the new users were more serious and complained less.

If your pricing feels comfortable, it's almost certainly too low.

Starting from a solid foundation also changed what I could charge:

Sunday — the day off

On Sunday I slept until noon, read a novel in the sun, and didn't open the laptop. The business didn't fall over. I haven't worked a Sunday since. My revenue is up, my churn is down, and my code is better.

The founder is the biggest single point of failure in the business. Protect your Sunday the way you protect your Stripe webhook, or it will page you later.

The seven patterns, as a checklist

1. [ ] Webhook returns 200 within 2 seconds and is idempotent via a unique index on the provider's event ID

2. [ ] Retry cron, dead-letter status, and paging after N failed attempts

3. [ ] A pgTAP RLS fixture for every sensitive table, running in CI

4. [ ] A public reply within 24 hours to every public complaint, naming the bug and a date

5. [ ] Feature gate: three paying customers asked for it, in writing

6. [ ] Price raised until it feels uncomfortable

7. [ ] One weekly day off, non-negotiable

Where this stack lives

I wouldn't have survived that week on a stack I'd built myself. The webhook pattern, the RLS tests, the deduplication table and the retry cron were all paid for in 2am support tickets, by me or by founders like me. That's why every one of them ships pre-wired in Applighter's React Native + Expo + Supabase templates. Each template comes with a 7-day refund policy if it doesn't fit what you're building.

If you're six months in and still writing auth boilerplate, take this as me on the kitchen floor telling you to stop.

The external docs I keep coming back to:

• Stripe webhook signatures

• Supabase row-level security

• Expo EAS Update, for shipping emergency fixes in hours instead of waiting on app-store review

• React Native performance

What's the worst production week you've had as a founder, and what pattern did it leave you with? Tell me in the comments.

None of these failures throw an error. That's what makes push notifications hard: the happy path is easy, and every failure is silent.

This guide covers the parts that break in production. It uses expo-notifications and the Expo Push Service, with a Postgres/Supabase-style backend for token storage. The code is TypeScript throughout.

What you'll build

• A permission flow that asks at the right moment (and only once)

• Token registration that survives offline launches, token rotation and shared devices

• A sender that batches, respects rate limits and stores push tickets

• A receipts job that prunes dead tokens automatically

• Tap handling that deep links correctly, including from a cold start

How a push actually travels

Before writing code, get the mental model right, because most production bugs come from misreading one of these hops:

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

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

The most misunderstood part is the difference between a ticket and a receipt:

• A ticket with status: "ok" means Expo accepted your message. Nothing more.

• A receipt tells you whether FCM or APNs accepted it. This is where errors like DeviceNotRegistered and InvalidCredentials show up.

Even an ok receipt doesn't guarantee the device displayed the notification, since a phone that's switched off won't receive it. But if you only look at tickets, you're blind to most failures.

Before you start: Expo Go won't work

Since SDK 53, remote push notifications don't work in Expo Go on Android. You need a development build. Local (scheduled) notifications still work in Expo Go, which confuses a lot of people into thinking push "half works."

You also need credentials:

• Android: an FCM V1 service account key uploaded to your EAS project

• iOS: an APNs key, which eas build will offer to generate the first time you build with push enabled (or run eas credentials manually)

Push works on physical devices, Android emulators with Google Play services, and iOS simulators on Xcode 14+.

Step 1: Install and configure

npx expo install expo-notifications expo-constants

Add the config plugin. The icon and color only apply to Android, and they're build-time settings, so changing them means a new build:

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

The Android notification icon must be an all-white PNG with a transparent background (96×96). A full-colour app icon renders as a solid white square in the status bar, one of the most common "why does my notification look broken" issues.

Step 2: Design your Android channels first

Every notification on Android 8+ belongs to a channel, and users can mute channels individually. That's a feature, not a chore: if your promotional pushes and your chat messages share one channel, a user annoyed by promos mutes everything, including the messages they actually want.

Create channels by intent, not by convenience:

// 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,
  });
}

Two rules that bite people:

1. Create channels before requesting a token. On Android 13+, the OS permission prompt doesn't appear until at least one channel exists.

2. Never send to a channel the device hasn't created. If your payload sets channelId: "orders" and that channel doesn't exist on the device, the notification is silently not shown. Ship channel changes in the app before your backend starts using them.

Also note that after a channel is created, Android only lets you change its name and description. Pick importance levels carefully the first time.

Step 3: Ask for permission at the right moment

On iOS, you effectively get one shot at the system prompt. If the user taps "Don't Allow," your app can't show it again; the user has to go to Settings. Asking on first launch, before the user knows why your app would ever notify them, burns that shot.

Use a soft prompt: your own screen that explains the value, shown at a moment when the value is obvious (after placing an order, after sending a first message). Only trigger the system dialog if they tap 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) {
      // The system prompt is gone for good; send them to Settings instead.
      await Linking.openSettings();
      return onDone();
    }

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

  return (
    <View>
      <Text>Know the moment your order ships</Text>
      <Text>We only send 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" costs you nothing. You can show the soft prompt again later. A system-level "Don't Allow" is close to permanent.

On iOS, permissions are more granular than a single yes/no. Check ios.status on the permission response rather than only the root status, especially if you use provisional authorization.

Step 4: Get the token (and keep it fresh)

getExpoPushTokenAsync makes a network request to Expo's servers, so it can fail on a flaky connection. The quickstart example alerts and gives up. In production, retry with backoff and return null instead of crashing the launch path:

// 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';

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 on next app start
}

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

  await supabase.rpc('register_push_token', {
    p_token: token,
    p_platform: Platform.OS,
  });
  return token;
}

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

Tokens can also rotate while the app is running. Subscribe once near your root so a rotated token reaches your backend immediately:

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

Step 5: Store tokens like they belong to devices, not users

The most common schema mistake is a single push_token column on the users table. Users have phones and tablets. They reinstall. They share devices. One user maps to 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);

Notice there's no insert or update policy. When user B signs in on a phone that used to belong to user A, the token has to move to user B. A plain upsert would fail under RLS because the existing row belongs to someone else. A security definer function handles the handover safely, always attributing the token to whoever is calling:

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;
$$;

And on sign-out, deactivate the device's token before clearing the session, or user A keeps receiving user B's notifications.

If you want to iterate on this schema, RLS policy and RPC locally without running the full Supabase Docker stack, tinbase runs a Supabase-compatible backend (real Postgres with RLS, auth, edge functions, database webhooks and cron) as a single process, and the official supabase-js client works against it unchanged. It's still in alpha, so treat it as a local-dev and prototyping tool, and push the same migrations to hosted Supabase for production.

You'll also want a table for tickets, which the receipts job reads later:

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

Step 6: Send from your server, never from the app

The quickstart sends a push straight from the device with fetch. Fine for a demo, wrong for production. Sending belongs on your server, where you can batch, throttle, log and protect it.

The official Node SDK handles chunking, gzip and rate limiting for you:

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);
        }
      }),
    );
  }
}

Three production details in there:

• Keep the payload small. The total payload must be at most 4,096 bytes. Send an ID and a route, then fetch the full content in the app. Don't stuff the order object into data.

• Pass an access token. By default, anyone holding a user's Expo push token can send to it. Turn on enhanced push security in your EAS dashboard and pass accessToken to the SDK (v3.6.0+). Requests without it then fail with UNAUTHORIZED.

• Keep that token server-side. The access token and the service role key belong in an edge function or server environment, never in the app bundle.

That last rule is one of the defaults baked into AppLighter's full-stack React Native + Expo templates: every secret lives in a Supabase edge function, with RLS on every table. If you're starting a new app, a sender like the one above slots into that structure instead of a project you have to secure from scratch.

Step 7: Check receipts and prune dead tokens

This is the step almost every tutorial skips, and it's the one that keeps your sends healthy over time. Expo recommends checking receipts about 15 minutes after sending. Receipts are cleared after 24 hours, so a job that runs every 15 minutes is a good fit:

// server/push/receipts.ts — run every 15 minutes (cron)
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') {
        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);
  }
}

Here's what each error actually means and what to do about it:

InvalidCredentials is the scary one: it means every push to that platform is failing. Alert on it, don't just log it.

A practical note: DeviceNotRegistered arrives whenever Apple or Google decide the device is gone, which can take an undefined amount of time. You can't reliably test it by uninstalling the app and sending a push a minute later.

Step 8: Handle foreground notifications and taps

Foreground: decide per notification

By default, a notification that arrives while your app is open is not shown. You opt in with a handler, and the handler must respond within 3 seconds or the notification is discarded.

Don't just return true for everything. If the user is already looking at the chat a message belongs to, a banner on top of it is noise:

// app/_layout.tsx (module scope)
import * as Notifications from 'expo-notifications';
import { getActiveRoute } 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,
    };
  },
});

shouldShowAlert is deprecated; use shouldShowBanner and shouldShowList.

Taps: cover the cold start

A tap can open your app from three states: foreground, background, or fully killed. The response listener alone misses the killed case, because the listener isn't registered yet when the tap happens. Read the last response on mount and subscribe for new ones:

// app/_layout.tsx
import { useEffect, useRef } from 'react';
import * as Notifications from 'expo-notifications';
import { Slot, router, type Href } from 'expo-router';

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; // avoid double navigation
      handledId.current = id;

      const url = response.notification.request.content.data?.url;
      // Only follow internal routes; never navigate to arbitrary URLs 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() {
  useNotificationObserver();
  return <Slot />;
}

Two things worth knowing when you test this:

• The startsWith('/') check matters. Your payload is data from a server, and a compromised or buggy sender shouldn't be able to push users to an external URL.

• On Android debug builds, launching from a notification can glitch the splash screen. It's a known debug-only issue, so test cold-start taps in a release build (npx expo run:android --variant release) before you decide something is broken.

Limits cheat sheet

Two delivery settings worth understanding: priority defaults to normal on Android and high on iOS, and normal-priority messages can be delayed on sleeping Android devices. Setting ttl very low (like 0) can mean a notification never reaches an Android device in Doze mode. Use high priority and a sensible TTL only for genuinely time-sensitive messages.

Shipping it

Push notifications are the feature most likely to work in your development build and fail in the store build, because production uses different credentials and a different APNs environment. Before release, send a real push to a TestFlight or internal-testing build, not just your dev client.

Also read the store rules before you plan your notification strategy. Apple's App Review Guidelines (4.5.4) say push notifications can't be required for the app to work, and can't be used for promotions or direct marketing unless the user has explicitly opted in through consent language in your app, with a way to opt out. That's another reason the separate promotions channel and an in-app notification settings screen are worth building from day one.

If store submission is the part standing between you and launch (certificates, provisioning, privacy labels, Google Play's closed-testing requirement for new personal accounts), RapidNative Deploy handles the full App Store and Play Store submission for React Native and Expo apps, including fixes and resubmissions until the app is approved.

Production checklist

• [ ] Testing on a development build, not Expo Go

• [ ] FCM V1 and APNs credentials configured in EAS

• [ ] White, transparent Android notification icon

• [ ] Android channels created by intent, before requesting a token

• [ ] Soft prompt shown at a moment of value; Settings fallback when canAskAgain is false

• [ ] Token fetch retries on failure and never blocks app launch

• [ ] Tokens stored per device, with ownership handover on shared devices

• [ ] Token deactivated on sign-out

• [ ] addPushTokenListener re-registers rotated tokens

• [ ] Sending happens server-side, with enhanced push security enabled

• [ ] Payloads carry IDs and routes, not full objects

• [ ] Tickets stored; receipts checked ~15 minutes later

• [ ] DeviceNotRegistered tokens deactivated automatically

• [ ] Alerting on InvalidCredentials

• [ ] Foreground handler suppresses banners for the screen the user is on

• [ ] Cold-start taps handled and tested in a release build

• [ ] Marketing pushes opt-in only, on their own channel

Wrapping up

The quickstart proves that push can work. Production is about making sure you find out when it doesn't: tickets tell you Expo got the message, receipts tell you whether Apple and Google did, and a pruned token table keeps every future send honest.

If you're still at the stage of building the app around these notifications, RapidNative generates React Native + Expo screens from a plain-English prompt, so you can get to the order-tracking or chat screens your pushes deep link into much faster.

What's the push notification bug that cost you the most time? Drop it in the comments. I'm collecting the weird ones for a follow-up on background (headless) notifications.

TL;DR — Applighter runs on Next.js 16, Supabase, Stripe, Resend, Listmonk, Rewardful, Slack, Outrank, Meta CAPI, Cloudflare Stream, and a bash script that calls Claude. ~$235/mo fixed. No PostHog, no Sentry, no Inngest. Here's the file-by-file walkthrough.

Every indie SaaS stack post names the same four tools — Next.js, Supabase, Stripe, Resend — and calls it done. That's the easy half. The hard half is what sits around them: the ops glue, the webhooks, the sync scripts, the cron jobs that quietly keep the business running.

This is the full picture of what runs Applighter.

Part 1: What ships code

Framework: Next.js 16.1.1 with React 19.2.3. App Router. Server Components. No pages/ directory. Tailwind CSS 4 through @tailwindcss/postcss. TypeScript 5.

UI primitives: Radix for behavior (dialog, dropdown, accordion, navigation menu), class-variance-authority + clsx for variants, lucide-react for icons, sonner for toasts. All wrapped into a small internal component library. No shadcn copy-paste — we fork what we need and version it inside the repo.

Markdown: next-mdx-remote for the docs site, react-markdown + remark-gfm for blog bodies, rehype-pretty-code + shiki for syntax highlighting. Shiki runs at build time so there's no client-side highlighter payload.

Hosting: Vercel. @next/third-parties loads Google Tag Manager without tanking Core Web Vitals. @vercel/blob for file storage. Cloudflare Stream for template demo videos.

Security headers in next.config.ts:

{
  'Strict-Transport-Security': 'max-age=63072000; includeSubDomains; preload',
  'X-Frame-Options': 'SAMEORIGIN',
  'X-Content-Type-Options': 'nosniff',
  'Referrer-Policy': 'strict-origin-when-cross-origin',
  'Content-Security-Policy': '...'
}

Plus about 32 explicit 301 redirects for retired blog URLs. SEO hygiene matters more than any individual post — this config is the first thing to check if you're running a React Native template business.

Part 2: Data and auth

Database: Supabase Postgres through @supabase/supabase-js 2.90.

modules/db/supabaseServer.ts   // service role, bypasses RLS, used in API routes
modules/db/supabaseClient.ts   // anon key, respects RLS, used in client components

No ORM. The Supabase client is thin enough that writing the SQL directly is simpler than wrangling a type-level DSL. 23 migrations live in supabase/migrations/ with ISO timestamps.

Core schema:

Auth: NextAuth 5.0.0-beta. Two providers: Google OAuth and a custom Credentials provider wired to magic_link_tokens. The magic-link email is a React Email component rendered by @react-email/render and sent through Resend.

Note on NextAuth beta: If I were starting today, I'd evaluate Better Auth before locking in. Betaware in the auth layer is nerve-wracking. That said, v5-beta has been stable in production for us for six months.

Part 3: The Stripe webhook (where business happens)

The single most important file in the repo is app/api/webhook/stripe/route.ts. On checkout.session.completed, seven things happen in order:

export async function POST(req: Request) {
  // 1. Verify signature
  const body = await req.text()
  const sig = req.headers.get('stripe-signature')
  const event = stripe.webhooks.constructEvent(body, sig, SECRET)

  if (event.type !== 'checkout.session.completed') {
    return new Response(null, { status: 200 })
  }

  // 2. Pull product slug and license tier from session metadata
  const session = event.data.object
  const { user_id, product_slug, license_tier } = session.metadata

  // 3. Record transaction
  await supabaseServer.from('transactions').insert({
    stripe_session_id: session.id,
    user_id,
    amount: session.amount_total,
    currency: session.currency,
  })

  // 4. Grant license
  await supabaseServer.from('user_product').insert({
    user_id,
    product_slug,
    license_tier,
    granted_at: new Date().toISOString(),
  })

  // 5. Send download email
  await EmailService.sendPurchaseConfirmation({
    to: session.customer_details.email,
    product_slug,
    license_tier,
    download_url: await signedDownloadUrl(product_slug),
  })

  // 6. Slack notify
  await SlackService.notifyPurchase({
    product: product_slug,
    tier: license_tier,
    amount: session.amount_total,
  })

  // 7. Meta CAPI (server-side dedupe)
  await metaCAPI.sendPurchase({
    event_id: `purchase_${session.id}`,
    value: session.amount_total / 100,
    currency: session.currency,
    email: session.customer_details.email,
  })

  return new Response(null, { status: 200 })
}

All synchronous. Under 400ms end-to-end. No queue. No retry layer beyond Stripe's own webhook replay. The customer never sees a "pending" state because the license grant is atomic with the payment confirmation.

Part 4: The support stack

Transactional email: Resend 6.7 through modules/services/EmailService.ts. Every email is a React component rendered by @react-email/render 2.0.

// modules/emails/PurchaseConfirmation.tsx
export function PurchaseConfirmation({ product, downloadUrl }) {
  return (
    <Html>
      <Section>
        <Text>Thanks for buying {product.name}!</Text>
        <Button href={downloadUrl}>Download source</Button>
      </Section>
    </Html>
  )
}

Why React Email? Because <table border="0"> is a bad time, Gmail and Outlook render HTML inconsistently, and the only sane way to debug an email template in 2026 is to render it as a component and preview it in a browser.

Newsletter: Listmonk, self-hosted on a $12 DigitalOcean droplet. modules/services/ListmonkService.ts wraps the HTTP API. Signup forms POST a server action that calls Listmonk and mirrors the subscriber into Supabase's newsletter_subscribers table.

Why Listmonk over Beehiiv? API control. The Rewardful affiliate webhook needs to add a confirmed affiliate to a specific list and trigger a welcome email in the same request. Beehiiv's growth tools are better; Listmonk's integration surface is better.

Affiliates: Rewardful handles tracking and payouts. /api/webhook/rewardful/route.ts catches confirmation events:

// Verify HMAC-SHA256
const hmac = crypto
  .createHmac('sha256', REWARDFUL_SECRET)
  .update(rawBody)
  .digest('hex')

if (hmac !== req.headers.get('x-rewardful-signature')) {
  return new Response(null, { status: 401 })
}

// Sync to Listmonk
await ListmonkService.addToList(
  affiliate.email,
  LISTMONK_AFFILIATES_LIST_ID
)

// Welcome email
await EmailService.sendAffiliateWelcome(affiliate)

Internal ops: Slack webhooks through modules/services/SlackService.ts. Purchase alerts, failed-purchase alerts, support-ticket pings. Block-kit formatted with action buttons. I know within three seconds whenever someone buys something — more importantly, I know when a purchase fails before the support email arrives.

Part 5: The marketing stack (where most posts quit)

Blog content comes from two pipes.

Pipe 1 — Outrank: external AI content tool posts long-tail SEO articles to the Applighter blog through /api/outrank/webhook/route.ts. Flow:

// 1. Bearer token auth
if (req.headers.get('authorization') !== `Bearer ${OUTRANK_TOKEN}`) {
  return new Response(null, { status: 401 })
}

// 2. Parse article
const article = await OutrankArticleService.parse(await req.json())

// 3. Upsert
await supabaseServer
  .from('blog_posts')
  .upsert({ ...article }, { onConflict: 'slug' })

// 4. Invalidate cache
revalidateTag('blog-posts')

Pipe 2 — Claude CLI: scripts/blog-automation/generate-blog.sh. One cron, one script, one AI:

#!/usr/bin/env bash
TOPIC=$(next_topic_from_tracker)

claude code --skill /write-blog --topic "$TOPIC" --max-turns 25 \
  > "$OUTPUT_DIR/$TIMESTAMP.md"

parse_delimited_sections "$OUTPUT_DIR/$TIMESTAMP.md"

if [[ "$MODE" == "internal" ]]; then
  publish_to_outrank_webhook "$PARSED_DIR/canonical.md"
elif [[ "$MODE" == "external" ]]; then
  stage_slack_thread "$PARSED_DIR/medium.md" \
                    "$PARSED_DIR/devto.md" \
                    "$PARSED_DIR/hashnode.md"
fi

Queue and stats in scripts/blog-automation/blog-tracker.md. Config in config.json: 1x/day internal, 2x/day external, 30-day retention on raw output.

Analytics dual-track:

The problem: iOS 14+ tracking prevention eats client-side Meta Pixel fires. Attribution math stops working.

The fix: fire the same purchase event from the Stripe webhook, server-side, with the same event_id the pixel uses. Meta dedupes by event ID.

// lib/meta-pixel.ts (client)
fbq('track', 'Purchase', { value, currency }, {
  eventID: `purchase_${sessionId}`,
})

// lib/meta-capi.ts (server, from Stripe webhook)
await fetch(`https://graph.facebook.com/v21.0/${PIXEL_ID}/events`, {
  method: 'POST',
  body: JSON.stringify({
    data: [{
      event_name: 'Purchase',
      event_id: `purchase_${sessionId}`,
      user_data: {
        em: sha256(email.toLowerCase()),
        ph: sha256(phone),
      },
      custom_data: { value, currency },
    }],
    access_token: FB_ACCESS_TOKEN,
  }),
})

Server-side CAPI catches 100% of real purchases. Client-side pixel catches maybe 60%. Both carry the same event ID, so Meta deduplicates automatically.

SEO infrastructure:

• app/sitemap.ts — dynamic sitemap with blog, docs, and template routes. Wrapped in unstable_cache with a 1-hour revalidation window.

• app/robots.ts — explicit allow for GPTBot, ChatGPT-User, Claude-Web, PerplexityBot, Applebot-Extended. Explicit disallow for /admin, /dashboard, /api.

• components/json-ld.tsx — structured data: Organization, Website, Article, Breadcrumb, VideoObject.

Part 6: Comparison

Part 7: What's deliberately missing

• No PostHog. GTM + Meta CAPI answers the funnel questions that drive decisions. Session replay doubles the analytics bill for info that doesn't change what we ship.

• No Sentry. Vercel error dashboard + Supabase SQL logs are enough at current scale.

• No Inngest. No background jobs exist. Every webhook finishes synchronously.

• No Drizzle / Prisma. The Supabase JS client is thin enough that writing SQL directly beats wrangling a DSL.

Each omission is a decision, not a gap. The moment one of them starts hurting, we'll adopt the fix the same day. Not before.

Cost

Vercel Pro          $20/mo
Supabase Pro        $25/mo
Resend              $20/mo
Listmonk droplet    $12/mo
Rewardful           $49/mo
Outrank             $99/mo
Cloudflare Stream  ~$10/mo
──────────────────────────
Fixed total        $235/mo

Stripe fees are variable (2.9% + 30¢). Meta Pixel/CAPI free. GTM/GA free. Slack free tier. React Email, NextAuth, Shiki, Radix — all free npm packages.

For a one-person operation, this is cheap. For a team of three, it's a rounding error.

Takeaway

The best "indie SaaS stack 2026" article is the one you write yourself after a year of actually shipping. Everything above was added when a specific pain made the case for it. Nothing was added because a conference talk recommended it.

Pick four or five tools from the list that solve a pain you have today. Ignore the rest. Add them when they earn their spot.

If you'd rather start from a codebase that already has this pattern wired in, every React Native template in the Applighter catalog ships with Supabase auth and Stripe set up out of the box.

Full canonical version with FAQ: The indie SaaS stack behind Applighter in 2026

The code compiles. The demo works. Then a user goes offline, an API returns a 500, or a list re-renders with stale data, and the cracks show.

This guide covers the most common quality failures in AI-generated code, with real examples, and a practical workflow for catching them before they reach production.

Why AI Code Looks Right But Isn't

Large language models generate code by predicting what plausibly comes next, based on patterns in their training data. That leads to a few predictable traits:

• They favour the happy path. Most example code online skips error handling, so generated code often does too.

• They blend versions. Training data spans many library versions, so you get APIs that were deprecated, renamed, or never existed.

• They lack your context. The model doesn't know your auth model, your data shapes, or the edge cases your users hit every day.

• They're confident regardless. Wrong code arrives with the same clean formatting and helpful comments as right code.

None of this means you shouldn't use AI. It means you should treat generated code like a pull request from a fast, well-read junior developer: useful, but reviewed.

Six Common Failure Modes (With Fixes)

1. Hallucinated or Outdated APIs

A classic in the React Native world: importing AsyncStorage from core, where it hasn't lived for years.

// ❌ AI-generated — AsyncStorage was removed from react-native core
import { AsyncStorage } from 'react-native';

await AsyncStorage.setItem('token', token);

// ✅ Use the community package
import AsyncStorage from '@react-native-async-storage/async-storage';

await AsyncStorage.setItem('token', token);

How to catch it: TypeScript in strict mode flags most of these immediately. If a generated import doesn't resolve or a method isn't on the type, don't "fix" it by casting to any — check the library's current docs.

2. Happy-Path-Only Network Code

This is probably the single most common issue in generated code.

// ❌ AI-generated — no status check, no timeout, untyped result
async function getUser(id: string) {
  const res = await fetch(`${API_URL}/users/${id}`);
  return res.json();
}

A 404 or 500 here doesn't throw — fetch only rejects on network failure. Your UI then tries to render an error body as a user object.

// ✅ Check status, add a timeout, and type the result
type User = { id: string; name: string; email: string };

async function getUser(id: string, timeoutMs = 10_000): Promise<User> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);

  try {
    const res = await fetch(`${API_URL}/users/${encodeURIComponent(id)}`, {
      signal: controller.signal,
    });

    if (!res.ok) {
      throw new Error(`getUser failed: ${res.status} ${res.statusText}`);
    }

    return (await res.json()) as User;
  } finally {
    clearTimeout(timer);
  }
}

For production, go a step further and validate the response shape at runtime with a schema library like Zod, since a type assertion only tells the compiler what you hope the server returned.

3. Security Issues Hidden in Plain Sight

Generated code regularly puts secrets where they don't belong or builds queries by string concatenation.

// ❌ Secret shipped inside the app bundle
// EXPO_PUBLIC_ variables are inlined into client code — anyone can extract them
const apiKey = process.env.EXPO_PUBLIC_OPENAI_KEY;

// ❌ SQL injection waiting to happen
const rows = await db.query(
  `SELECT * FROM users WHERE email = '${email}'`
);

// ✅ Parameterized query
const rows = await db.query(
  'SELECT * FROM users WHERE email = $1',
  [email]
);

For third-party API keys, the fix is architectural: call your own backend (or a serverless function), and keep the key on the server. No amount of obfuscation makes a client-side secret safe.

4. Stale State and Race Conditions in React

AI tools frequently produce effects with incorrect dependency arrays, or with no protection against out-of-order responses.

// ❌ Runs once, ignores query changes, and can set state after unmount
useEffect(() => {
  searchProducts(query).then(setResults);
}, []);

// ✅ Re-runs on query change and ignores stale responses
useEffect(() => {
  let cancelled = false;

  searchProducts(query)
    .then((data) => {
      if (!cancelled) setResults(data);
    })
    .catch((err) => {
      if (!cancelled) setError(err);
    });

  return () => {
    cancelled = true;
  };
}, [query]);

If the user types "sho" then "shoes", the first request can resolve last and overwrite the correct results. The cancelled flag prevents that. Better still, use a data-fetching library such as TanStack Query, which handles caching, deduping, and cancellation for you.

5. Duplication and Over-Abstraction

Ask for three similar screens and you'll often get three near-identical copies of the same logic. Ask the model to "make it reusable" and you may get a generic factory with five type parameters for something used twice.

Both hurt maintainability. A good rule: extract shared logic on the third repetition, not the first. When reviewing, look for copy-pasted validation, formatting helpers, and API clients that should live in one place.

6. Tests That Don't Test Anything

Generated tests often pass because they mock the very thing they're supposed to verify.

// ❌ This test can never fail
jest.mock('./pricing', () => ({
  calculateTotal: jest.fn(() => 100),
}));

import { calculateTotal } from './pricing';

test('calculates total', () => {
  expect(calculateTotal([{ price: 50, qty: 2 }])).toBe(100);
});

// ✅ Test real behaviour, including edge cases
import { calculateTotal } from './pricing';

describe('calculateTotal', () => {
  it('sums price × quantity', () => {
    expect(calculateTotal([{ price: 50, qty: 2 }])).toBe(100);
  });

  it('returns 0 for an empty cart', () => {
    expect(calculateTotal([])).toBe(0);
  });

  it('rejects negative quantities', () => {
    expect(() => calculateTotal([{ price: 10, qty: -1 }])).toThrow();
  });
});

A quick sanity check for any generated test: break the implementation on purpose and confirm the test fails.

Build Guardrails, Not Just Reviews

Manual review doesn't scale when code arrives this fast. The most effective teams let automated tooling catch the mechanical problems so humans can focus on logic and architecture.

Turn on strict TypeScript

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

noUncheckedIndexedAccess is especially useful with generated code, which loves to assume items[0] always exists.

Lint for the patterns AI gets wrong

// eslint.config.js (excerpt)
export default [
  {
    rules: {
      'react-hooks/rules-of-hooks': 'error',
      'react-hooks/exhaustive-deps': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/no-explicit-any': 'error',
      'no-console': 'warn',
    },
  },
];

Note that no-floating-promises requires type-aware linting, so you'll need to point the TypeScript ESLint parser at your tsconfig. It's worth the setup: unawaited promises are a frequent source of silent failures in generated code.

Enforce it in CI

# .github/workflows/quality.yml
name: Quality checks
on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npx tsc --noEmit
      - run: npx eslint .
      - run: npm test -- --coverage

If generated code can't pass type checks, lint, and tests, it doesn't merge. Simple.

Prompting for Better Output

You'll get noticeably better code if you tell the model what "good" means for your project. A few prompt additions that consistently help:

• "Handle network errors, non-2xx responses, and timeouts."

• "Use TypeScript with no any."

• "Target Expo SDK [version] and React Native [version]." (Pinning versions cuts down on hallucinated APIs.)

• "List any assumptions you made about the data shape."

• "Write tests that would fail if the implementation were wrong."

That last one sounds obvious, but explicitly asking for it changes the tests you get back.

Purpose-built tools also help. When you're generating mobile UI, a tool like RapidNative is aimed specifically at React Native output, rather than a general-purpose assistant guessing at your stack. You still review what comes out, but you start closer to the target.

A Review Checklist for AI-Generated Code

Keep this handy for every pull request that contains generated code:

Start From a Solid Foundation

A lot of quality problems trace back to the project setup, not the generated code itself. If your app has no consistent structure, no strict types, and no shared patterns for auth or data fetching, every AI-generated file invents its own conventions.

Starting from a well-structured base, such as AppLighter, gives generated code existing patterns to follow. Models are good at imitation: show them clean code and they tend to produce more of it.

The same applies at the end of the pipeline. Shipping is where untested assumptions finally meet real devices, so a repeatable release process matters as much as the code. If deployment is the bottleneck for your mobile app, RapidNative Deploy is worth a look.

Wrapping Up

AI-generated code isn't low quality by default, but it's unverified by default. The patterns that cause problems are consistent and predictable: missing error handling, outdated APIs, client-side secrets, stale state, and tests that can't fail.

The fix isn't to stop using AI. It's to:

1. Prompt with your standards so the first draft is closer to right.

2. Automate the mechanical checks with strict types, linting, and CI.

3. Review for logic and context, which is the part only you can do.

Do that, and you keep the speed while losing most of the risk.

What's the worst bug you've caught in AI-generated code? Share it in the comments — the stranger, the better.

I sell React Native templates for a living. My company is Applighter, and we ship production-ready Expo + Supabase apps that indie devs and small teams use to skip months of setup.

Six months in, we had seven templates, a 34-item roadmap, and a head of product who blocked our next planning offsite on the grounds that the roadmap had almost no traceability to actual buyer conversations. She was right. We rescheduled the offsite for two weeks later and used the intervening time to talk to 40 customers. We ended up with 47.

By the end of those two weeks, half the roadmap was gone and a completely different half had taken its place. This is the long-form debrief.

Cohort design (do this before you dial)

Interviewing 47 random buyers gives you 47 shrugs. We split the list three ways so that each cohort was answering a different question.

Recent buyers (n=22): why they bought, what they expected, what surprised them

Refund requesters (n=8): where the gap between promise and reality actually lived

Abandoned checkout (n=17): what stopped them at the last mile

Each call was 25 minutes on a calendar link. No slides. No demos. No pitching upcoming features. We recorded with consent, dropped transcripts into a shared doc, and tagged themes as we went.

Total founder time: about 20 hours across 12 days. It reshaped the roadmap more than the previous six months of engineering had.

The five signals that changed everything

Signal 1 — The First Hour is the Moment of Truth

Twelve of 22 recent buyers described some version of this evening:

"Bought around 10pm. Wanted to see it running on my phone before bed. Either got there, or gave up."

Nothing on the roadmap addressed that moment. We were leading with catalog breadth. Buyers didn't care.

What we shipped: a first-hour workstream. A npx applighter-bootstrap command that walks a new buyer from clone to running app on their own device, with a doctor that validates every .env key, bootstraps a Supabase project, applies the migration set, and runs Expo prebuild — with fail-loud errors that name the specific missing thing rather than dumping a stack trace.

npx applighter-bootstrap my-app

✓ Node version >= 20
✓ Bun installed
✓ EAS CLI available
✗ Missing EXPO_PUBLIC_SUPABASE_URL
  → Get this from your Supabase project settings
  → https://app.supabase.com/project/_/settings/api

Signal 2 — Agent-Readiness is a Purchase Blocker

Nine of 17 abandoned-checkout buyers told us, unprompted, that the first thing they planned to do was open the codebase in Claude Code, Cursor, or Codex.

Nobody in 2026 buys a template to hand-write every screen. They buy expecting to extend it with an AI coding agent.

What we shipped:

1. A CLAUDE.md at the root of every template that explains the mental model to an agent on turn one.

2. A CI check that enforces "agent-ready" invariants: no orphaned exports, respected module boundaries, JSDoc on public APIs, naming consistency.

3. Marketing that says so out loud.

Here's the shape of the CI check:

# .github/workflows/agent-ready.yml
name: agent-readiness
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run agent:lint

And a slice of what agent:lint actually checks:

// scripts/agent-lint.ts
import { readFile } from 'node:fs/promises'
import { glob } from 'glob'

async function assertClaudeMd() {
  await readFile('CLAUDE.md', 'utf8')
    .catch(() => { throw new Error('CLAUDE.md missing at repo root') })
}

async function assertNoOrphanedExports() {
  // knip or ts-prune wrapper; fail on any unused public export
}

async function assertModuleBoundaries() {
  // dependency-cruiser wrapper; enforce app/ → modules/ → lib/ direction
}

await Promise.all([
  assertClaudeMd(),
  assertNoOrphanedExports(),
  assertModuleBoundaries(),
])

Within a month of shipping, buyers were mentioning it in support tickets as a reason they'd chosen us.

Signal 3 — "Supabase lock-in" is Code Shape, Not Database Choice

Three of 8 refund conversations cited some version of "I don't want to be locked into Supabase." When we probed, none of them were actually complaining about Postgres. They were afraid the frontend was so entangled with the backend that swapping would mean a rewrite.

What we shipped: a repository interface in front of every table.

// modules/data/notes.repository.ts
export interface NotesRepository {
  list(userId: string): Promise<Note[]>
  get(id: string): Promise<Note | null>
  create(input: NewNote): Promise<Note>
  update(id: string, patch: Partial<Note>): Promise<Note>
  delete(id: string): Promise<void>
}

The Supabase implementation lives next to it:

// modules/data/notes.supabase.ts
import { supabase } from '@/modules/db/supabaseClient'

export const supabaseNotes: NotesRepository = {
  async list(userId) {
    const { data, error } = await supabase
      .from('notes')
      .select('*')
      .eq('user_id', userId)
      .order('created_at', { ascending: false })
    if (error) throw error
    return data
  },
  async get(id) {
    const { data, error } = await supabase
      .from('notes')
      .select('*')
      .eq('id', id)
      .maybeSingle()
    if (error) throw error
    return data
  },
  async create(input) {
    const { data, error } = await supabase
      .from('notes')
      .insert(input)
      .select()
      .single()
    if (error) throw error
    return data
  },
  async update(id, patch) {
    const { data, error } = await supabase
      .from('notes')
      .update(patch)
      .eq('id', id)
      .select()
      .single()
    if (error) throw error
    return data
  },
  async delete(id) {
    const { error } = await supabase.from('notes').delete().eq('id', id)
    if (error) throw error
  },
}

Every screen imports NotesRepository, never supabase directly. Swap the impl for Drizzle + Neon, Firestore, or an in-memory mock in a single file. That refactor had been on the roadmap as "cleanup" for months. It was a sales objection wearing a technical costume.

Signal 4 — The Admin Dashboard Nobody Wanted

We'd been quietly building a customer-facing admin dashboard for four months. Zero of 47 mentioned it unprompted. When asked directly, 41 said some variant of "I already have a way to do that." Two would pay for it. One would use it if free.

That's not a product. That's a hobby.

What we shipped: the delete key. The engineer moved to Signal 2 and shipped the agent-readiness system.

This was the single hardest call and the single most obviously correct one. If you cannot delete things from your roadmap after an interview program, the program has failed.

Signal 5 — Bundles

Six recent buyers had bought a second template within two weeks of the first. Two abandoned-checkout buyers said they were waiting for a bundle price.

What we shipped: bundle SKUs, live in three weeks. The Stripe side is a one-time price with a metadata list of included template IDs; the entitlement side is a Supabase edge function that expands the metadata into row-level grants.

// supabase/functions/grant-bundle/index.ts
import { serve } from 'https://deno.land/std/http/server.ts'
import Stripe from 'https://esm.sh/stripe@14'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!)
const supabase = createClient(
  Deno.env.get('SUPABASE_URL')!,
  Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!,
)

serve(async (req) => {
  const { userId, sessionId } = await req.json()
  const session = await stripe.checkout.sessions.retrieve(sessionId)
  const templates = session.metadata?.templates?.split(',') ?? []

  const { error } = await supabase.from('license_grants').insert(
    templates.map((templateId) => ({
      user_id: userId,
      template_id: templateId,
      source: 'bundle',
      stripe_session_id: sessionId,
    })),
  )
  if (error) return new Response(error.message, { status: 500 })
  return new Response('ok')
})

The roadmap diff

Half the items are new. Half the old items are gone. The roadmap is smaller than it was six months ago, and it's the first time it has felt like the right size.

The pattern behind every change

Every roadmap change traces back to the same insight: buyers are hiring the product to de-risk their next 90 days of shipping, not to admire it.

• First-hour experience matters because a broken first hour is a 90-day risk.

• Agent-readiness matters because the buyer is planning to use an agent for the rest of those 90 days.

• Backend swap-ability matters because lock-in gets worse as the code grows.

• Bundles matter because a buyer with two templates has twice the 90-day surface area.

• The admin dashboard didn't matter because it wasn't on anyone's 90-day critical path.

If a roadmap item doesn't reduce a real risk on a real buyer's real 90 days, it's optional. That heuristic alone deleted eight items from our doc.

The new operating rhythm

• 15 interviews minimum per quarter. No planning cycle starts until they're done.

• Themes are published internally so every engineer reads the top five before picking a task.

• Refund requests get a $50 credit for a 20-minute call. Refund is the only real churn signal in a one-time-purchase business.

• The backlog tab is deleted. If it's not in the current or next cycle, it doesn't exist.

• Bundles, agent-readiness, and setup DX have permanent owners. They're pillars, not features.

Templates the interviews built

• AI Voice Notes — the first template with the provider-abstracted AI service layer

• Chat with PDF — with the pgvector extension recipe first-class in docs

• AI Calorie Tracker — first template with the setup doctor baked in

Full catalog: applighter.com/apps. Refund policy still 7 days — because refunds are how we hear the truth.

Further reading

• Expo docs

• Supabase RLS guide

• Rob Fitzpatrick, The Mom Test — the definitive interview-questions book

If you've bought an Applighter template and want to be in the next round of interviews, my calendar link is on the site.

The headline finding is simple. The framework isn't the problem. The perimeter around the framework is.

This post walks through the top ten problems, what causes each one, and how to fix it.

How the tickets were classified

Every ticket received three labels:

platform: ios | android | web
layer:    build | backend | ui | auth | payment | ai
severity: blocker | degraded | question

The data was aggregated across seven templates (Weather, Fitness, E-Learning, Taxi Booking, AI Calorie Tracker, AI Voice Notes, Chat with PDF) and every Expo SDK from 50 through 53. Feature requests, refund questions, and anything that turned out to be a typo were excluded. What remains is reproducible, teachable friction.

The top 10 problems

1. EAS build fails on first run

The single largest category. In nearly every case it comes down to one of three causes.

Version mismatch

bunx expo doctor

Run this before every EAS build. According to the ticket data, roughly half the reports in this category are resolved by acting on the doctor's output alone.

Missing token in CI

export EXPO_TOKEN=xxxx

If the build runs in CI, EXPO_TOKEN must be set in the environment. Without it, EAS fails before it starts.

Wrong build profile

eas build --profile development --platform ios
# ^ Targets a physical device by default. For the simulator:
eas build --profile development --platform ios --local

The official Expo build troubleshooting page covers most of the specific error strings.

2. Supabase RLS returns empty arrays

The symptom is confusing because nothing errors:

const { data, error } = await supabase.from('projects').select('*');
// data: []   error: null

The user is signed in. The row exists. The client returns nothing.

Debug ladder

// 1. Confirm the session is real
const { data: { session } } = await supabase.auth.getSession();
console.log('user id:', session?.user?.id);

// 2. Log the access token as it changes
supabase.auth.onAuthStateChange((_, session) => {
  console.log('access token:', session?.access_token?.slice(0, 20));
});

// 3. Query with a hardcoded filter
await supabase.from('projects').select('*').eq('user_id', session.user.id);

If step 3 returns rows but the unfiltered query didn't, the RLS policy isn't reading auth.uid(). Check the policy definition:

create policy "users see own projects"
on projects for select
using (auth.uid() = user_id);

The most common mistake is writing the policy correctly but forgetting to enable RLS on the table itself. Policies then don't apply at all, and everything is returned for anon-key requests.

The Supabase RLS documentation is the canonical reference, but the mental-model shift — policies are WHERE clauses that always run — is the hard part. For the auth layer specifically (session persistence, OAuth, Apple Sign In), Applighter's complete guide to Supabase auth in React Native covers the full pattern.

3. Environment variables not reaching the production binary

Expo does not automatically pull .env into a production build. Two rules apply:

1. Any variable read at runtime in the JS bundle must be prefixed EXPO_PUBLIC_.

2. Secrets must be uploaded to EAS Secrets or declared in eas.json.

{
  "build": {
    "production": {
      "env": {
        "EXPO_PUBLIC_API_URL": "https://api.example.com"
      }
    }
  }
}

The tell-tale symptom: console.log(process.env.API_URL) prints correctly in development and prints undefined after eas build --profile production. Anything without the EXPO_PUBLIC_ prefix is dropped from the client bundle at build time.

4. Metro cache poisoning after a dependency bump

Every project should ship a reset script:

{
  "scripts": {
    "reset": "watchman watch-del-all && rm -rf node_modules ios/Pods .expo && bun install && bunx expo prebuild --clean"
  }
}

A large share of Metro tickets close the moment the developer runs bun reset rather than typing the sequence by hand. Metro's cache invalidation is aggressive and occasionally wrong — Metro's own troubleshooting docs acknowledge as much.

5. iOS Info.plist permission strings missing

Add NSCameraUsageDescription, NSMicrophoneUsageDescription, and any other required usage strings in app.json under ios.infoPlist:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSCameraUsageDescription": "Used to scan meals for the calorie tracker.",
        "NSMicrophoneUsageDescription": "Used to record voice notes for transcription."
      }
    }
  }
}

Apple's review team rejects vague strings. Each description should say why the permission is needed, not just that it is.

6. Android package rename breaks the build

Change android.package in app.json, then run expo prebuild --clean. Don't hand-edit AndroidManifest.xml — the safest approach on managed Expo is to delete the android/ folder, change the config, and let the tooling regenerate it. Applighter's app renaming guide lists every location the name appears.

7. Android push notifications silently dropping

Three things to check:

• FCM credentials are configured in the Expo dashboard.

• Notification channels are created in code (required on Android 8+).

• Battery optimisation on Xiaomi and Samsung devices kills background delivery. This can't be fixed in code; document it for end users.

The full stack — credentials, channels, token registration, and testing on both platforms — is covered in Applighter's definitive guide to push notifications in Expo.

8. AI streaming stalls or drops tokens

Use expo/fetch (SDK 52+), not the global fetch, for ReadableStream support. React Native's fetch polyfill doesn't stream reliably.

import { fetch } from 'expo/fetch';

const res = await fetch(url, { method: 'POST', body });
const reader = res.body?.getReader();

Applighter's guide to streaming AI responses to React Native walks through the full pattern, including a Server-Sent Events fallback.

9. Stripe → Supabase Edge Function webhook fails

• Verify the signing secret is set: supabase secrets set STRIPE_WEBHOOK_SECRET=...

• Mark the Edge Function as public so Stripe can reach it without a JWT.

• Keep a test-webhook.sh that fires a dummy checkout.session.completed event, so the integration can be tested without a real purchase.

10. Voice transcription latency on mid-range Android

• Chunk audio at roughly 4-second intervals rather than sending whole recordings.

• Fall back to a smaller model on lower-end devices.

• Show a token-level typing indicator so the interface doesn't feel dead while waiting.

The meta observation

Nine of the top ten problems live at the seam between React Native and its environment. Not one is a React Native re-render, hook, or bundler internal.

The framework has stabilised. The perimeter — build tooling, backend policies, native permissions, AI providers, payment webhooks — is where the bleeding happens.

For anyone evaluating a starter kit, the practical takeaway is to pick one whose vendor sees this kind of ticket data and iterates on it. A template that hasn't had a commit in six months isn't stable; it's abandoned.

For twelve months I've been running Applighter's support inbox and tagging every incoming ticket by platform, layer, and severity. Every ticket. Not just the interesting ones. Every "the build won't run" ticket, every "the RLS policy is doing something weird" ticket, every "why is my white screen white" ticket. By the end of the year the tags had shape. Support tickets aren't just noise — they're the closest thing to a research instrument that a template vendor gets.

This is what those tickets told me about what React Native developers actually struggle with in production.

Methodology

Every ticket got three tags:

• platform: — one of ios, android, web

• layer: — one of build, backend, ui, auth, payment, ai

• severity: — one of blocker, degraded, question

We threw out feature requests, refund questions, and "when will X ship" tickets. What remained: reproducible, teachable problems where a developer got stuck.

The data spans:

• 7 Applighter templates: weather-app, fitness-app, e-learning-app, taxi-booking-app, ai-calorie-tracker, ai-voice-notes, chat-with-pdf

• Expo SDK 50 through SDK 53

• iOS 16 through iOS 18

• Android 12 through Android 15

• Supabase versions across the year

• A rotating cast of AI providers (OpenAI, Anthropic, Deepgram, Whisper)

The ranked results

"Blocker rate" is the share of tickets in that category where the developer literally could not ship — i.e., no workaround.

What each one actually is

1. EAS build fails on first run

The single biggest source of pain in the ecosystem, and — this is the interesting part — none of it is React Native's fault.

$ eas build --profile production --platform ios
✔ Compressing project files and uploading to EAS Build
✖ Install pods
   › Pod install failed

Three root causes account for 90% of these:

Root cause A: Expo SDK / eas-cli version drift. The dev cloned an SDK 50 template into an SDK 53 CLI, or vice versa. Fix:

bunx expo install --check
bunx expo doctor

Every red line in expo doctor is a candidate.

Root cause B: iOS credentials never generated. EAS asks for these interactively on first build, but if you're in CI, the prompt vanishes and the build dies.

eas credentials

Run this locally, verify the profile is generated in App Store Connect, then re-run the build.

Root cause C: Wrong profile. If you're just trying to test in the simulator, you don't want --profile production. You want --profile development --local.

We added an expo doctor preflight to every template's postinstall after seeing this pattern for the tenth time. Ticket volume in this category dropped 42% the following quarter.

2. Supabase RLS returns empty arrays

This one has a specific mental model shift that has to happen for a developer before the problem clicks.

The mental model: RLS policies are WHERE clauses that always run. Every query, silently, gets a WHERE appended based on the policy. If the policy's WHERE filters out every row, the query returns []. The client doesn't get an error — the query "succeeded," it just returned zero rows.

The debug ladder:

// Step 1: Verify session
const { data: { session } } = await supabase.auth.getSession();
if (!session) throw new Error('No session — auth failed');

// Step 2: Verify JWT is being sent
// Enable network logs, look for Authorization: Bearer <token>
// on the request to /rest/v1/projects

// Step 3: Verify the policy matches the row
// In SQL editor:
// select auth.uid();  -- what does the JWT resolve to?
// select user_id from projects limit 5;
// If auth.uid() != user_id, your policy will always filter.

The most common bug we see is developers writing:

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

...and then forgetting to actually enable RLS:

alter table projects enable row level security;

Without the enable statement, the policy exists but is inert.

If you want the full auth setup — email, OAuth, Apple Sign-In, and the RLS policies that go with each — our Supabase auth guide for React Native walks through it end to end.

3. Environment variables not in production binary

The tell: works in expo start, breaks in the standalone binary.

Expo has three environment variable systems that developers routinely confuse:

1. process.env.FOO — only bundled if FOO starts with EXPO_PUBLIC_

2. Constants.expoConfig.extra.foo — bundled from app.json's extra field

3. EAS Secrets — server-side only, used during the build itself, never reach the client

The rule: if the client JS needs to read it at runtime, it must be EXPO_PUBLIC_*.

// ✅ Works in all environments
const API_URL = process.env.EXPO_PUBLIC_API_URL;

// ❌ Undefined in the production binary
const API_URL = process.env.API_URL;

4. Metro bundler cache poisoning

React Native's Metro bundler caches everything and its invalidation logic is famously imperfect. When you bump a dependency, sometimes Metro serves you stale bytes and the app crashes with a cryptic Cannot resolve module error.

Ship this script and tell users to run it whenever anything breaks after a dependency change:

#!/usr/bin/env bash
set -euo pipefail
watchman watch-del-all
rm -rf node_modules
rm -rf ios/Pods
rm -rf .expo
rm -rf $TMPDIR/metro-*
bun install
bunx expo prebuild --clean

We call ours bun reset. It resolves ~80% of "it was working yesterday" tickets in the Metro category.

5. iOS Info.plist rejections

Apple rejects builds that touch camera/mic/photos/location without a properly-worded NSXxxUsageDescription string.

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSCameraUsageDescription": "This app scans documents to extract text.",
        "NSMicrophoneUsageDescription": "This app records voice notes.",
        "NSPhotoLibraryUsageDescription": "This app lets you attach images to notes.",
        "NSLocationWhenInUseUsageDescription": "This app shows nearby stores."
      }
    }
  }
}

Two rules Apple applies aggressively in 2026:

• The string must explain why the app needs access.

• Generic strings ("This app uses the camera") get rejected.

6. Android package name rename

The template ships with com.applighter.starter. The dev wants com.acme.myapp. They change it in app.json and the Android build breaks.

The correct sequence:

# 1. Update app.json
# "android": { "package": "com.acme.myapp" }

# 2. Nuke the existing android/ folder
rm -rf android

# 3. Let expo regenerate everything
bunx expo prebuild --clean --platform android

Do not hand-edit AndroidManifest.xml or the Java package folders. Let the tooling regenerate them.

7. Android push silently dropping

Configuration checklist for Android push in Expo:

1. Firebase project created, google-services.json uploaded to the Expo dashboard

2. Notification channel created in JS (Android 8+ requirement)

3. Battery optimization exemption requested if you need reliable delivery on Xiaomi/Samsung

4. Foreground handler set separately from background handler

import * as Notifications from 'expo-notifications';

// Android needs an explicit channel
if (Platform.OS === 'android') {
  await Notifications.setNotificationChannelAsync('default', {
    name: 'default',
    importance: Notifications.AndroidImportance.MAX,
  });
}

// Foreground handler
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: false,
  }),
});

That checklist is the short version. The long version — FCM setup, APNs keys, background handlers, and the OEM battery quirks — is in our push notifications guide for Expo.

8. AI streaming stalls

React Native's global fetch polyfill doesn't support the streaming Response body the way the browser does. The workaround shipping in most of our AI templates:

import { fetch as expoFetch } from 'expo/fetch';

const response = await expoFetch(url, { method: 'POST', body: JSON.stringify(payload) });
const reader = response.body!.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  handleChunk(chunk);
}

There's more to it in practice — SSE parsing, cancellation, and backpressure on slow devices — which we cover in the streaming AI responses guide.

9. Stripe → Supabase webhook

Four things to verify, in order:

1. STRIPE_WEBHOOK_SECRET is set in Supabase secrets and matches the endpoint's secret in the Stripe dashboard.

2. The Edge Function is marked public in supabase/config.toml:

   [functions.stripe-webhook]
   verify_jwt = false
   

3. The webhook URL in Stripe points at the production Supabase URL, not a preview.

4. You've enabled the specific events (checkout.session.completed, customer.subscription.updated) in the Stripe dashboard.

10. Android STT latency

Not a bug — physics. Real-time speech-to-text on a mid-range Android device is slower than on an iPhone Pro. The fix is UX, not code:

• Chunk audio in 4-second windows instead of 10-second.

• Show a token-level typing indicator while transcription runs.

• Fall back to a smaller/cheaper model tier on lower-end devices.

The meta observation

Zero of the top ten problems are React Native itself. All ten are at the seam between React Native and the rest of the stack.

That's the story of the ecosystem in 2026. The framework is stable. Everything around it — build tooling, native permissions, backend policies, push infrastructure, AI providers, payment webhooks, platform-specific device quirks — is where the friction lives.

Templates that just give you screens don't help. Templates that ship real backend policies, real EAS configs, real webhook setups, and real device-tier fallbacks do. That's the bar we hold every Applighter template to, and this dataset is why.

Read more

The full canonical post on Applighter includes the "how we changed our templates" section — the preflight scripts, the baked-in RLS migrations, and what each change did to ticket volume.

If you've hit one of these ten in your own project, I'd like to hear which one and how you got past it — the comments are open.

Every week another founder pings me with the same message. Two paragraphs about their MVP, then the ask: "Do we build our React Native app from scratch or buy a template?"

I tell all of them the same thing: that's the wrong question. The build-vs-buy debate treats two options as opposites when they're actually complements, and the founders who ship fastest are the ones who figure that out first.

The right question has three parts, and none of them are "build or buy":

1. Where is my differentiator actually located?

2. What's the 80% of my app that's identical to every other app?

3. What's the cheapest legal way to skip building that 80% at production quality?

Answer those three and "build vs. buy" answers itself. Skip them and you'll spend a month arguing about it in Notion.

The short answer: buy the 80% every mobile app needs (auth, payments, navigation, Supabase schema, EAS builds, push notifications) and build the 20% that's actually your product. Founders lose weeks here because they frame it as a purity contest instead of an engineering allocation problem.

The founders who ask "build vs buy" have already lost a week

Founders don't usually ask this question because they need an answer. They ask because they want permission to keep procrastinating. "Should we build or buy?" is the last-mile version of "should we use TypeScript?" — a decision with an obvious right answer 90% of the time, dressed up as if it deserved a design doc.

Here's the pattern across dozens of pre-launch teams:

• A founder writes a Notion doc weighing "custom stack vs. template."

• The doc grows a comparison matrix.

• A co-founder pushes back on the matrix.

• Two weeks pass. No code is shipped.

• Someone eventually just picks one and gets on with it.

That eventual pick is almost always the right one. The two weeks were pure sunk cost. If you're currently in week one of that doc, close it and read the next section instead.

Why the binary is broken: two apps in a trench coat

Every consumer or prosumer mobile app is two apps in a trench coat. There's the generic app and there's the specific app, which is the reason your customers open it in the first place.

Layer 1 — table stakes (the 80%)

The generic app is the same everywhere. Nobody has ever pitched a VC on their password reset flow. Nobody gave you a five-star review because your dark mode was bespoke. Concretely, Layer 1 is:

• Email + OAuth + Apple Sign-In flows

• Password reset with deep-linked email tokens

• Row-Level Security policies on every table

• Push notifications with permission prompts and delivery receipts

• In-app purchases and/or Stripe checkout

• Offline-safe state management and cache invalidation

• Error boundaries, loading skeletons, empty states

• Accessibility labels and dynamic type

• EAS Build pipeline, code signing, TestFlight, Play Console

• OTA updates via Expo Updates

• Legal screens (privacy policy, terms), refund flows

Layer 2 — the differentiator (the 20%)

The AI pipeline, the recipe DB, the matchmaker, the workout planner, the marketplace mechanic — whatever your investor pitch spends 90% of the deck on. It's 20% of the code and 100% of the reason your product exists.

When founders ask "build vs. buy," they're implicitly asking whether to write Layer 1 themselves or use someone else's. They're not asking about Layer 2 at all — which is telling, because Layer 2 is the only interesting question.

A concrete cost estimate for Layer 1

Let's do the math founders never do. Assume a mid-market React Native engineer at $80/hour. Here's the breakdown for the 80% you'd otherwise get from a well-scoped full-stack React Native template:

Forty thousand dollars, before you write your first line of Layer 2. And "realistic" is generous — it assumes a senior engineer who has shipped push notifications on production Android before. If you don't have one, you're looking at the harder version of the same problem: how long it actually takes to ship a React Native app. Spoiler: longer than you think.

Then there's the tail. Apple deprecates old push cert formats. Supabase changes its auth SDK's error shape. React Native ships a new architecture. You own all of it forever.

Now compare that to a modern full-stack template that actually ships Layer 1 — real Postgres schema, working auth, EAS pre-configured — at $79 to $299 one-time. The gap is not a rounding error. The gap is your seed round.

Why "build from scratch" feels safer than it is

Three reasons I hear, none of which survive contact with reality.

"We need to control the code." You control code you write from scratch, sure. You also control the code you get with source-available templates. "Control" is not the same as "wrote from scratch."

"Templates lock you in." Only if you buy the wrong template. A modular template — one where the AI provider, the backend, and the auth layer are cleanly separated — lets you swap Supabase for Firebase, or GPT-4o for Claude, without rewriting the app. Ask before you buy.

"We'll build it exactly how we want it." You will build it exactly the wrong way once, then rewrite it. Every senior React Native engineer I know has shipped auth wrong at least once, and re-shipped push notifications the second time because Apple deprecated something. Templates carry that scar tissue for you.

The honest reason many founders build from scratch is that it feels more like being a real engineer. Great reason for a hackathon. Terrible reason for a company.

Why "buy a template" fails when it fails

The mirror trap is easier to spot but harder to admit to your co-founder. You bought a $59 template on a marketplace, threw it into a repo, and three weeks later you're stripping half of it out because:

1. It was UI-only. The marketing copy said "full-stack," but what shipped was 20 screens of hardcoded mock data with no backend, no auth, no data layer. This is the most common failure mode in the sub-$60 tier.

2. The license was booby-trapped. \(49 for a single-app license, then \)199 for multi-app, then $499 for an "extended" license that lets you ship in a paid app at all. Read licenses before you buy.

3. The code was copy-paste soup. Three state-management libraries in one repo. Two navigation patterns. Class components mixed with function components. This is unmaintainable and it's what turns your AI agent into a paperweight — Cursor and Claude Code extend well-organized code and give up on soup.

4. The vendor was dead. No commits in a year. React Native two majors behind. You'd have to do the upgrade before you started your product.

5. The AI/backend layer was locked in. Hardcoded to a specific model or backend, no abstraction. When the model gets deprecated (roughly quarterly right now), you're doing a full migration.

That's what "template" means at the bottom of the market. It's why so many founders end up in the "just build it yourself" camp — not because building is smart, but because their first template was so bad that any custom code felt better.

The fix isn't to give up on templates. The fix is to only buy templates that don't have those failure modes.

The comparison founders should actually be running

Ignore the "custom vs. template" axis for a moment and compare what you actually get in the repo on day one:

The interesting axis isn't "custom vs. template." It's "does this template ship a real product or a mood board?"

The framework that actually works

Ask one question, honestly:

Where is my differentiator actually located?

Case A — Product-shaped

Your differentiator is in the product logic: the AI pipeline, the marketplace matcher, the recipe DB, the workout planner, the custom onboarding funnel. This is roughly 90% of consumer and prosumer apps.

Verdict: Buy a template. Skip Layer 1. Spend 100% of your engineering budget on Layer 2. This is not a compromise; this is the correct allocation. Building the 80% from scratch is a cost you're paying to feel more like a "real" engineer.

Case B — Infrastructure-shaped

Your differentiator is in the infrastructure: a novel native audio pipeline, a custom protocol, a privacy-preserving on-device ML model wired into the OS lifecycle. This is genuinely rare.

Verdict: Build from scratch, or fork a template and rewrite the parts that matter. You're doing something the template author didn't imagine.

Case C — Mixed

Mostly product-shaped, but one or two infra pieces are genuinely custom. Your onboarding logic is bespoke, or your data model needs three tables the template doesn't have.

Verdict: Buy a template and fork it aggressively. Rip out what you don't need and treat the rest as a scaffold. You still save the auth + Stripe + push weeks and keep the React Native navigation patterns, but you own the parts that matter. This is why the license structure of a template matters more than its price: a $49 template that legally lets you fork and ship is worth more than a "free" one with restrictive terms.

Most founders think they're in Case B. Most founders are in Case A. Be honest with yourself before you spend six weeks proving otherwise.

Five signs you should NOT build from scratch

1. No senior React Native engineer is committed full-time. Layer 1 requires production instincts you can't fake with docs.

2. Your deadline is under eight weeks. You will not hit it. Templates buy back six of those weeks.

3. Your product isn't infrastructure-shaped. If your pitch is a screen mock, not a systems diagram, you're a product company.

4. You'd have to write auth, payments, and push anyway. These are 30% of the effort and 0% of your moat.

5. Your AI agent is going to do most of the coding. Agents extend well-organized code with clear patterns. They flounder on greenfield sprawl.

Five signs you should NOT buy a template (or should return the one you bought)

1. It's UI-only. No Postgres, no auth, no edge functions. That's a Figma export, not a product.

2. The license is ambiguous or per-app. You'll pay more the moment you succeed.

3. The code fights your agent. Inconsistent patterns, mixed state libraries, dead files.

4. The vendor is dead. No commits in a year, no responses in Discord. You'll fork by month three.

5. You can't swap the backend or AI provider. Vendor lock-in disguised as convenience.

Applighter's FAQ addresses the last point directly: templates should be modular, so you can swap GPT-4o for Claude or Whisper for Deepgram without rewriting the app. If the one you're evaluating fails that test, keep looking.

A worked example

The AI Voice Notes template at $79 is a useful example because it sits at the cheaper end of the "actually ships Layer 1" bracket. What you get in the repo:

• 16+ production React Native + Expo screens, TypeScript everywhere.

• A working Supabase backend: schema, RLS policies, edge functions, storage buckets.

• The Layer 2 wiring for voice notes: recording, transcription, summarization.

• EAS Build config for TestFlight and Play Console.

• Single commercial license for one published app, upgradeable to multi-app.

• Lifetime updates. No subscription.

• A 7-day no-questions refund window.

Median time from purchase to TestFlight for founders I've watched use it: two to three weeks. Compare that to the 8–16 week build-from-scratch estimate — that founder is still writing auth error handlers while the template founder is on the App Store. The Fitness App, ChatPDF, and AI Calorie Tracker templates follow the same architectural pattern if your vertical is different.

Applighter isn't the only vendor in this category — see our honest boilerplate comparison — but the axes are the same regardless: does it ship a real backend, does it hold up under an agent, and does the license let you succeed without punishing you?

What to look for before you commit

If you're evaluating a template — Applighter or otherwise — this is the checklist:

1. Full source, TypeScript-first. No obfuscation. No "pro-only" branches.

2. Real backend included. Postgres schema, RLS, edge functions, migrations. Not just Firebase links in a README.

3. One state management library, one navigation pattern. Consistency over cleverness. This is the "agent-friendly" test.

4. Modular AI/backend layers. Swap providers without rewriting.

5. Commercial license from day one. Ideally upgradeable if you succeed.

6. Refund window that isn't hostile. A vendor confident in their product offers 7 days, no questions.

7. Active vendor. Commits in the last 90 days. Responses in Discord/support within a business day.

If a template fails any of the first four, it doesn't matter how nice the screens look — you'll rewrite the parts that matter within a month.

FAQ

Is buying a React Native template always cheaper than building from scratch? For the 80% of functionality that's the same in every app, yes — usually by an order of magnitude. Templates that include a real backend (Supabase, auth, RLS, migrations) can save 200+ engineering hours. UI-only templates save less than you think, because you still have to build the hard parts.

Can I customize a bought template after purchase? On a good template, yes — the code is yours to modify. On a bad template, the code is so tightly coupled that customization becomes a rewrite. This is why "full source, single commercial license" matters more than any feature list.

How do I know if a template is agent-friendly? Check three things: (1) is TypeScript used consistently? (2) is state management centralized (TanStack Query, Zustand, or similar), not scattered? (3) does the file structure follow one convention across all screens? If yes to all three, Claude Code and Cursor can extend it. If not, they'll fight you.

Do templates hurt my app's resale or acquisition value? No — acquirers care about metrics and code quality, not code origin. A working, well-organized codebase built on a template beats a scratch-built codebase with three abandoned rewrites.

What if I need to swap the backend later? That's the question to ask before you buy. A modular template lets you swap Supabase for Firebase, or GPT-4o for Claude, without rewriting the app. A locked-in template forces a full migration. Ask the vendor before you pay.

Reference reading

• Expo EAS Build documentation — the build system you'll actually be using.

• Supabase Row-Level Security — the mental model you need before evaluating any template's data layer.

• React Native New Architecture — check whether your candidate template supports it.

Closing

The build-vs-buy question is a symptom, not a decision. It's what founders reach for when they don't want to answer the harder question: what am I actually building? Answer that first. If your differentiator is product-shaped — and nine times out of ten it is — buy a template that ships a real Layer 1 and pour every remaining engineering hour into Layer 2. If your first template was bad, learn "this template was bad," not "all templates are bad."

If you can name your differentiator in one sentence, you already have your answer. And if you're mid-way through a Notion doc titled "Build vs. Buy Analysis," close the tab. Ship instead.

A single-binary deploy flips that model. You compile your entire application — server, templates, static files, migrations, even the database engine — into one executable. Deploying becomes scp and restart. Rolling back becomes mv.

This guide walks through how to build one, how to ship it, and where the approach breaks down.

Why single binaries are back

Single-binary deployment isn't new — it's how software shipped before containers. What changed is that modern toolchains made it practical for web services again:

• Static compilation is the default in Go and Rust. No shared library surprises on the target machine.

• Embedded filesystems let you bake HTML, CSS, JS, and migrations into the executable.

• Embedded databases like SQLite (and LiteFS/Litestream for replication) remove the "separate DB server" requirement for many workloads.

• Cross-compilation means you build a Linux ARM64 binary from a Mac with one environment variable.

The result is an artifact with zero runtime dependencies. If the binary runs on your staging box, it runs the same way on production, because there is nothing else to install.

What goes into the binary

Here's the mental model. Everything on the left collapses into the single file on the right:

Building one in Go

Go is the easiest place to start because embed is in the standard library. Here's a minimal but complete example.

Project layout

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

Embedding assets

package main

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

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

//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.Println("listening on :8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Running embedded migrations

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

For anything beyond a toy, use a proper migration library like golang-migrate with its iofs source driver — it reads straight from embed.FS and tracks applied versions.

Compiling for production

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags="-s -w" -o myapp .

Flag by flag:

• CGO_ENABLED=0 — fully static binary, no libc dependency

• GOOS / GOARCH — cross-compile for the target server

• -trimpath — strip local file paths from the binary

• -ldflags="-s -w" — strip symbol table and debug info (typically 30–40% smaller)

You now have one file, usually 10–20 MB, that contains your whole app.

The same idea in Rust

Rust gets you there with include_bytes! / include_str! or the rust-embed crate:

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();
}

Build with the musl target for a fully static Linux binary:

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

Deploying the binary

This is where the approach pays off. No registry, no image pull, no orchestrator.

1. Copy it to the server

scp ./myapp deploy@server:/opt/myapp/myapp.new

2. Swap it atomically

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, so there's never a moment where a half-written binary is on disk.

3. Run it under systemd

# /etc/systemd/system/myapp.service
[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

4. Roll back in one command

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

If you'd rather not manage the server, VPS, and systemd side yourself, hosted options like RapidNative Deploy take a compiled artifact and handle the hosting layer, so the "copy and restart" step becomes a push.

Handling configuration

Since there's no config folder shipping alongside the binary, configuration comes from two places:

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 var → compiled default. Everything has a working default so the binary runs with zero setup, and everything can be overridden in production without touching the file.

Versioning the binary

Bake the version in at build time so you always know what's running:

go build -ldflags="-s -w -X main.version=$(git describe --tags --always)" -o myapp .

var version = "dev"

http.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, `{"status":"ok","version":%q}`, version)
})

Now curl server/healthz tells you exactly which commit is live.

Where the model breaks

Single-binary deploy is not universal. Be honest about the trade-offs:

The sweet spot is a monolith or a small number of services, with traffic that one or a few boxes can handle — which describes most products, especially early on.

Pairing a single binary with a managed backend

One common hybrid: keep the binary as the application layer, but move persistence and auth out to a managed backend so the node stays stateless and trivially replaceable. Services like Tinbase fit that role — the binary handles routing and rendering, the backend handles data, and you can run N identical copies behind a load balancer without thinking about SQLite replication.

For mobile-first products where the "binary" is a React Native app calling into your API, builders like Applighter follow the same philosophy: one artifact, one deploy path, minimal infrastructure in between.

A minimal deploy script to copy

Putting it together, here's a deploy.sh you can drop into any Go project today:

#!/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, and a rollback that's one mv away.

Summary

• A single-binary deploy compiles code, assets, templates, migrations, and optionally the database into one static executable.

• Go's embed and Rust's rust-embed make this a few lines of code.

• Deploy is scp + atomic mv + systemctl restart; rollback is the reverse.

• Configuration comes from flags and env vars with compiled-in defaults.

• It shines for monoliths and small service counts; it struggles with heavy horizontal write scaling and very large asset bundles.

If you've been reaching for Docker by default, try shipping your next small service as a single binary. You may find the container was never solving a problem you actually had.