That repetitive, necessary-but-uninteresting code has a name: boilerplate.

In this guide, we'll cover what boilerplate really is, where it shows up, the hidden cost of writing it by hand, and how to decide between rolling your own setup, using a generator, or starting from a production-ready boilerplate.

Where the word "boilerplate" comes from

The term predates software. In the early 1900s, newspaper syndicates distributed ready-made stories and ads to local papers as pre-cast metal printing plates. Because those plates looked like the rolled steel used to build boilers, printers called them "boilerplate." Local editors couldn't change the text; they just dropped it into the page.

Software borrowed the idea: boilerplate is code you include in many places with little or no change, because the project needs it to function, not because it expresses anything unique about your product.

What boilerplate looks like in practice

Boilerplate shows up at three levels.

1. Language-level boilerplate

Some languages require ceremony just to express simple ideas. The classic example is a Java data class before records existed:

public class User {
    private final String name;
    private final String email;

    public User(String name, String email) {
        this.name = name;
        this.email = email;
    }

    public String getName() { return name; }
    public String getEmail() { return email; }

    // ...plus equals(), hashCode(), and toString()
}

Modern Java (16+) collapses all of that into one line:

public record User(String name, String email) {}

Language designers spend years removing this kind of boilerplate because it adds noise without adding meaning.

2. Project-level boilerplate

This is the setup every app needs before it can do anything useful. In a React Native app built with Expo Router, a root layout often ends up looking like this:

// app/_layout.tsx
import { Stack } from 'expo-router';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { AuthProvider } from '../src/providers/auth-provider';
import { ThemeProvider } from '../src/providers/theme-provider';

const queryClient = new QueryClient();

export default function RootLayout() {
  return (
    <SafeAreaProvider>
      <QueryClientProvider client={queryClient}>
        <AuthProvider>
          <ThemeProvider>
            <Stack screenOptions={{ headerShown: false }} />
          </ThemeProvider>
        </AuthProvider>
      </QueryClientProvider>
    </SafeAreaProvider>
  );
}

None of these providers are your product. But skip one, and something breaks three weeks later.

3. Configuration boilerplate

Environment handling, type-safe config, lint rules, CI pipelines, and build profiles all fall here. A small but important example is validating environment variables at startup so the app fails loudly instead of silently:

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

const schema = z.object({
  EXPO_PUBLIC_API_URL: z.string().url(),
  EXPO_PUBLIC_SUPABASE_ANON_KEY: z.string().min(1),
});

// Expo only inlines EXPO_PUBLIC_* variables when they are
// referenced statically, so list each one explicitly.
export const env = schema.parse({
  EXPO_PUBLIC_API_URL: process.env.EXPO_PUBLIC_API_URL,
  EXPO_PUBLIC_SUPABASE_ANON_KEY: process.env.EXPO_PUBLIC_SUPABASE_ANON_KEY,
});

That comment alone is the kind of detail you learn by getting burned once. Good boilerplate encodes those lessons so you don't have to relearn them on every project.

Boilerplate vs. template vs. starter kit vs. framework

These terms get used interchangeably, but they mean slightly different things:

When developers say "I bought a boilerplate," they usually mean a starter kit: a working app with the boring 30–40% already done.

The hidden cost of writing boilerplate yourself

Writing setup code by hand feels productive. You're typing, things are compiling, the terminal is busy. But look at what a typical mobile app needs before the first real feature ships:

• Navigation structure and deep linking

• Authentication flows (sign up, sign in, password reset, session refresh)

• Theming with light and dark mode

• Form handling and validation

• API client, caching, and error states

• Environment config per build profile

• Linting, formatting, and type checking

• Build and release configuration for iOS and Android

Each item is "only a few hours." Together, they can eat the first week or two of a project, and every hour spent there is an hour not spent validating your idea with users.

There's a second cost too: consistency. Hand-rolled boilerplate drifts. Your third project's auth flow is different from your first, and fixing a bug in one doesn't fix it in the others.

When you should use a boilerplate

A starter kit makes sense when:

• You're building an MVP and speed to first user matters more than architectural purity.

• The problem is solved. Auth, theming, and navigation are not where your product differentiates.

• You're working in a team and want everyone to start from the same conventions.

• You're shipping multiple apps and want a consistent base across all of them.

If you're building in React Native, AppLighter offers ready-to-use React Native templates, so you can skip the setup phase and start on the screens that actually matter to your users.

When you shouldn't

Boilerplate isn't always the answer. Skip it when:

• You're learning. Wiring up auth and navigation yourself once is the best way to understand them.

• Your architecture is genuinely unusual. If the starter kit's assumptions don't fit, you'll spend more time ripping things out than you saved.

• The kit is abandoned. An outdated boilerplate is technical debt you chose on day one.

How to evaluate a boilerplate before you commit

Before adopting any starter kit, run through this checklist:

1. Is it actively maintained? Check the last commit date and whether it tracks recent SDK versions.

2. Is the stack one you'd choose anyway? Don't adopt a state library you dislike just because it came bundled.

3. Can you remove what you don't need? Good boilerplate is modular; bad boilerplate is tangled.

4. Is it typed end to end? TypeScript coverage saves you from silent breakage when you start customizing.

5. Does it include the boring-but-critical parts? Error boundaries, env validation, and loading states matter more than flashy UI.

6. Is there documentation? If you can't understand the folder structure in 10 minutes, neither can your next teammate.

Going beyond boilerplate: generating and shipping the rest

Boilerplate solves the setup problem. Two other stages still slow teams down: building the first screens and getting the app into the stores.

On the building side, AI tools have changed what "starting from scratch" means. With RapidNative, you can describe an app, upload a PRD, or drop in a screenshot and get working React Native code back, which is effectively boilerplate tailored to your specific idea instead of a generic one.

On the shipping side, store submission brings its own repetitive work: certificates, provisioning profiles, store listings, screenshots, and review back-and-forth. If that's where your project stalls, RapidNative Deploy handles the process of getting your app live on the App Store and Google Play.

Put together, the modern workflow looks like this:

Starter kit / template  →  AI-generated screens  →  Your custom features  →  Managed deployment
   (setup boilerplate)       (UI boilerplate)          (your actual product)     (release boilerplate)

Only one of those four stages is truly unique to your app. The goal is to spend most of your time there.

Key takeaways

• Boilerplate is code that's necessary but not distinctive: it appears across projects with little or no change.

• It exists at three levels: language, project setup, and configuration.

• Writing it by hand has a real cost in time and long-term consistency.

• Use a starter kit when the problem is already solved and speed matters; skip it when you're learning or your architecture is unusual.

• Evaluate any boilerplate for maintenance, stack fit, modularity, types, and docs before committing.

The best developers aren't the ones who write the most code. They're the ones who write the right code and let everything else be boilerplate.

What's the piece of boilerplate you find yourself rewriting on every project? Share it in the comments.

This is the setup I've converged on after enough of those mornings: Docker for the database, migrations as the only way schema changes happen, a seed script that's fast enough to run on every branch switch, and a couple of habits that keep local and production from drifting.

It assumes you're comfortable with a terminal and have Docker installed. Everything else is explained.

Why not just install Postgres on the machine?

You can. It's how I started. Three things eventually push you off it:

Docker fixes all three: the version is pinned in a file, the data lives in a named volume you can throw away, and setup is one command.

Step 1: Pin the database in Docker Compose

Create docker-compose.yml at the project root:

services:
  db:
    image: postgres:16.4
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app_dev
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app", "-d", "app_dev"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pgdata:

Two things matter here:

• Pin the exact tag (postgres:16.4), not postgres:16 or latest. Check what production is running and match it. Minor versions rarely break anything, but "rarely" is the word that gets you at 2am.
• The healthcheck means anything that depends on the database (your app container, a migration step) can wait for it to actually accept connections rather than for the container to merely start.

Start it:

docker compose up -d db

Your connection string is now postgres://app:app@localhost:5432/app_dev. Put it in .env.local, not in the compose file's consumers' source.

Step 2: Migrations are the only way the schema changes

The rule that keeps a team sane: nobody runs ALTER TABLE by hand. Every schema change is a file in the repo, applied in order, tracked in a table so it never runs twice.

Which tool you use matters less than the rule. Pick one your stack already leans toward:

I default to plain-SQL tools (dbmate, goose) because a migration you can read without knowing the ORM is a migration anyone can review. Here's what one looks like with dbmate:

-- db/migrations/20260929120000_create_sessions.sql
-- migrate:up
CREATE TABLE sessions (
  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id     uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  started_at  timestamptz NOT NULL DEFAULT now(),
  ended_at    timestamptz,
  created_at  timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX sessions_user_started_idx ON sessions (user_id, started_at DESC);

-- migrate:down
DROP TABLE sessions;

dbmate up        # apply pending migrations
dbmate rollback  # undo the last one

Always write the down. You'll rarely use it in production, but locally it's how you back out of a branch without nuking the volume.

Timestamped filenames beat sequential numbers

001_, 002_, 003_ collide the moment two branches each add a migration. Timestamps (20260929120000_) don't. Most tools generate them for you; use that.

Step 3: A seed script you can run in under ten seconds

A migration builds the schema. A seed fills it with enough data to actually develop against. Keep them separate — migrations run in production, seeds never do.

The seed should be:

• Idempotent. Running it twice shouldn't double the data. Truncate first, or upsert.
• Fast. If it takes a minute, people stop running it and start working against stale data.
• Realistic in shape, small in size. Twenty users, a few hundred rows in the busy tables. Enough to hit pagination and empty states, not enough to wait for.

A minimal SQL seed:

-- db/seed.sql
TRUNCATE sessions, users RESTART IDENTITY CASCADE;

INSERT INTO users (id, email, name) VALUES
  ('11111111-1111-1111-1111-111111111111', 'ana@example.com', 'Ana'),
  ('22222222-2222-2222-2222-222222222222', 'ben@example.com', 'Ben');

INSERT INTO sessions (user_id, started_at, ended_at)
SELECT
  u.id,
  now() - (i || ' days')::interval,
  now() - (i || ' days')::interval + '45 minutes'
FROM users u, generate_series(1, 30) AS i;

psql "$DATABASE_URL" -f db/seed.sql

generate_series is the cheat code here — it produces sixty rows of plausible time-series data from two inserts.

Wrap the whole reset in one script so the README can say "run make db-reset":

db-reset:
	docker compose down -v db
	docker compose up -d --wait db
	dbmate up
	psql "$$DATABASE_URL" -f db/seed.sql

--wait respects the healthcheck from Step 1, so dbmate up doesn't race the container.

Step 4: Keep local honest with production

Match the extensions

If production uses pgcrypto, pg_trgm, or postgis, your first migration should be CREATE EXTENSION IF NOT EXISTS .... Discovering an extension is missing only when a query hits prod is a bad day. If you need PostGIS, switch the image to postgis/postgis:16-3.4 — same pinning rule.

Pull a scrubbed snapshot occasionally

Seeds are good for shape, bad for surprises. Once in a while, load a sanitised production dump to catch the slow query that only shows up with real data distribution:

# on a machine with prod access
pg_dump --no-owner --no-privileges -Fc "$PROD_URL" > snapshot.dump

# locally
pg_restore --no-owner --clean --if-exists -d "$DATABASE_URL" snapshot.dump

Scrub PII before it leaves the prod environment. A pg_dump with --exclude-table-data=users plus a seed for users is the simplest version of that.

Same tool, same config, in CI

Your CI pipeline should spin up the same image tag and run the same dbmate up before tests. If the compose file and the CI config both read the version from one place (a .env or a Makefile variable), they can't drift.

A few tools worth having

• pgcli — psql with autocomplete and syntax highlighting. pip install pgcli. The single biggest quality-of-life upgrade.
• EXPLAIN (ANALYZE, BUFFERS) — run it on any query you're unsure about, locally, against the snapshot. Reading a plan is a skill; get it early.
• \d+ tablename in psql — shows columns, indexes, and constraints. Faster than opening a GUI.
• A GUI when you want one — TablePlus, DBeaver, or the Postgres extension for VS Code. None are required.

Where this fits if you're building a mobile app

If the Postgres you're targeting is Supabase — increasingly the default for React Native and Expo apps — the local story is the same idea with the Supabase CLI wrapping it: supabase start brings up Postgres plus auth and storage in Docker, and supabase db push / supabase migration new play the migration role.

The part people skip is designing the schema before wiring it into screens. I've had good results describing the app and letting RapidNative generate the Expo project with a Supabase-backed data layer already wired, then treating that generated schema as migration zero and evolving it with the workflow above. The generated Postgres schema is a reasonable starting point, and it's easier to iterate a schema that already has screens depending on it than to guess at one in isolation.

When it's time to get that app onto devices, the deploy flow covers EAS builds and store submission, which is a separate rabbit hole from the database one.

Checklist

Paste this into your README and tick it off:

• docker-compose.yml with a pinned postgres:X.Y tag matching production
• Healthcheck on the db service
• Migration tool chosen; up and down for every migration; timestamped filenames
• db/seed.sql that's idempotent and runs in seconds
• One make db-reset (or equivalent) command that does everything
• Extensions created in migration 0001
• CI uses the same image tag and runs the same migrations
• A documented way to load a scrubbed prod snapshot

The goal is boring: a new developer clones the repo, runs one command, and has a database that matches what everyone else and production are running. Once that's true, most "works on my machine" database bugs stop existing.

If you've hit a local-Postgres failure mode this doesn't cover, I'd like to hear about it in the comments — that's how the checklist grows.

This tutorial covers how to build a fitness app with React Native end-to-end when there's a real wearable behind it: what to build, in what order, and where you can skip weeks of scaffold work by generating it with an AI mobile app builder.

A fitness wearable companion app lives on the phone but is defined by what happens on the wrist — Photo by William Hook on Unsplash

What a fitness wearable companion app actually is

A fitness wearable companion app is a phone app whose job is to pair with a physical wearable (a watch, a chest strap, a ring, a bike sensor), read health data from it in real time, persist that data, and present it back to the user. Roughly 60–70% of the code lives on the phone in React Native; the rest is native permissions, Bluetooth adapters, and background delivery bridges to Apple HealthKit and Android Health Connect.

If you've ever wired a Polar H10 heart-rate strap into a running app, or streamed cycling power from an Assioma pedal into a Strava-style dashboard, that's the shape of app this guide is about. It's structurally different from a "log your workouts" fitness app, and confusing the two is the number one reason people underestimate the timeline.

The tech stack

Lock in the stack before writing any code. Every library below solves a problem you don't want to solve yourself, and swapping any of them later costs weeks.

Two points worth stressing:

1. Use Expo, not bare React Native. Every fitness wearable library above ships an Expo config plugin now; the friction that used to justify bare has largely disappeared. The trade-offs are covered in more depth in why we chose Expo over bare React Native.
2. Health Connect replaced Google Fit's developer API in 2025. If a tutorial tells you to install react-native-google-fit, close the tab.

Step 1: Design the screens before you write code

The common mistake is starting with the BLE integration. It's the interesting part, which is why it will consume every hour you give it, and you'll end up with heart-rate data and no app to put it in. Design the screens first.

A minimum-viable fitness wearable companion app has six screens:

1. Onboarding — permission requests (Bluetooth, Location, HealthKit / Health Connect, Notifications)
2. Device pairing — scan for nearby BLE devices, pair, remember
3. Live session — active workout: real-time heart rate, elapsed time, distance, power
4. Session summary — post-workout: charts, splits, HR zones, calories
5. History — list of past sessions with quick stats
6. Profile & settings — units, connected devices, data export

That's the scaffold. You can hand-code it, or describe it to RapidNative and get all six screens, an Expo Router tree, a Zustand store, and a Supabase-backed data layer generated in one pass — leaving your time for the parts that can't be templated.

Get the scaffold out of the way before the integration work begins — Photo by Christopher Gower on Unsplash

Step 2: Wire up HealthKit and Health Connect

Whether or not your wearable talks to Apple Watch or Wear OS directly, you almost certainly want to write to HealthKit and Health Connect. Users expect their workouts to appear in Apple Health and Google Fit / Samsung Health. Skipping this is a bug report you'll receive in week one.

Install the libraries and add the config plugins

npx expo install react-native-health react-native-health-connect

In app.json, register the plugins and declare the HealthKit permissions you'll request:

{
  "expo": {
    "plugins": [
      [
        "react-native-health",
        {
          "isClinicalDataEnabled": false,
          "healthSharePermission": "Allow $(PRODUCT_NAME) to read your workout and heart rate data",
          "healthUpdatePermission": "Allow $(PRODUCT_NAME) to save your workouts"
        }
      ],
      "react-native-health-connect"
    ]
  }
}

Read today's step count on both platforms

import AppleHealthKit, { HealthValue } from 'react-native-health';
import { readRecords } from 'react-native-health-connect';
import { Platform } from 'react-native';

export async function getTodaySteps(): Promise<number> {
  const start = new Date(new Date().setHours(0, 0, 0, 0));
  const end = new Date();

  if (Platform.OS === 'ios') {
    return new Promise((resolve) => {
      AppleHealthKit.getStepCount(
        { date: end.toISOString() },
        (err, r: HealthValue) => resolve(err ? 0 : r.value),
      );
    });
  }

  const { records } = await readRecords('Steps', {
    timeRangeFilter: {
      operator: 'between',
      startTime: start.toISOString(),
      endTime: end.toISOString(),
    },
  });
  return records.reduce((sum, r) => sum + r.count, 0);
}

Two things this hides that will bite you later. Background delivery on iOS lets HealthKit wake your app when a new sample arrives — set it up once at boot, then treat it like a push. Android offers no equivalent background delivery from Health Connect; you poll on app resume instead, which is fine for most workouts but wrong for continuous monitoring.

Step 3: Talk to a wearable over Bluetooth Low Energy

This is where the real work is. Most consumer fitness wearables expose their data over BLE using either a standard GATT service (heart rate: 0x180D, cycling power: 0x1818, running speed and cadence: 0x1814) or a vendor-specific protocol you'll have to reverse-engineer from their SDK docs.

Install and configure react-native-ble-plx

npx expo install react-native-ble-plx

Add the plugin to app.json with the location and Bluetooth usage strings. iOS 13+ requires both; Android 12+ needs the BLUETOOTH_SCAN and BLUETOOTH_CONNECT runtime permissions:

[
  "react-native-ble-plx",
  {
    "isBackgroundEnabled": true,
    "modes": ["peripheral", "central"],
    "bluetoothAlwaysPermission": "Allow $(PRODUCT_NAME) to connect to your heart rate monitor"
  }
]

Subscribe to a standard heart-rate monitor

This is about 40 lines and works with any GATT-compliant strap on the market:

import { BleManager, Characteristic } from 'react-native-ble-plx';
import { Buffer } from 'buffer';

const manager = new BleManager();
const HR_SERVICE = '0000180d-0000-1000-8000-00805f9b34fb';
const HR_MEASUREMENT = '00002a37-0000-1000-8000-00805f9b34fb';

export function subscribeToHeartRate(
  deviceId: string,
  onBpm: (bpm: number) => void,
): () => void {
  const sub = manager.monitorCharacteristicForDevice(
    deviceId,
    HR_SERVICE,
    HR_MEASUREMENT,
    (error, characteristic: Characteristic | null) => {
      if (error || !characteristic?.value) return;
      const bytes = Buffer.from(characteristic.value, 'base64');
      const flags = bytes[0];
      const is16Bit = (flags & 0x01) !== 0;
      const bpm = is16Bit ? bytes.readUInt16LE(1) : bytes[1];
      onBpm(bpm);
    },
  );
  return () => sub.remove();
}

Two hard-won lessons from shipping BLE apps:

• Never scan continuously. BLE scanning on iOS wakes the radio and destroys battery. Scan for pairing only; once you know the device ID, call connectToDevice(id) directly next time and start it in the background so reconnect is instant.
• Reconnect is a state machine, not a callback. A worn HR strap disconnects whenever the user walks out of range, sweats too much, or moves their phone. Your app needs an explicit disconnected → reconnecting → connected state that survives foreground/background transitions.

Skip either of these and your five-star reviews become one-star "app drains my battery" reviews within a week of launch.

Step 4: Persist, sync, and survive backgrounding

You now have a hook streaming BPM in real time. Where does it go?

The pattern that works in production is a three-tier data store:

1. In-memory ring buffer — the last 60 seconds of raw samples for the live chart. Never persisted. Fastest possible read.
2. On-device SQLite (via expo-sqlite or WatermelonDB) — the durable copy of every session. Writes are batched every second, not per sample.
3. Cloud (optional) — Supabase or your own Postgres, synced when the network is available.

The on-device layer is non-negotiable. Users run out of cell coverage, and losing a workout because "the cloud sync failed" is unforgivable. Store first, sync opportunistically.

For background persistence during long workouts (a marathon, a bike ride), enable Expo's background modes:

{
  "ios": {
    "infoPlist": {
      "UIBackgroundModes": ["bluetooth-central", "location", "fetch"]
    }
  },
  "android": {
    "permissions": ["FOREGROUND_SERVICE", "FOREGROUND_SERVICE_HEALTH"]
  }
}

On Android 14+, a health-tracking foreground service is required if the app will keep BLE alive while the screen is off. Getting this wrong is a Play Store rejection.

Step 5: Ship it

Once your app runs, EAS Build handles the rest:

eas build --profile production --platform all
eas submit --platform ios
eas submit --platform android

Two App Store gotchas specific to fitness and health apps:

• HealthKit apps require a privacy policy URL in App Store Connect and detailed usage descriptions in Info.plist for every read/write category.
• Sign in with Apple is mandatory if you offer any other login method (Google, email, magic link). Adding the button takes 30 seconds; getting rejected and resubmitting takes 3–7 days.

If this is your first TestFlight submission, the walkthrough on publishing a React Native app to the App Store covers every step, including the signing pitfalls that catch first-time submitters.

Real fitness apps live or die on how well they survive the last 5% — background, offline, low-battery — Photo by Filip Mroz on Unsplash

The shortcut: generate the scaffold, then focus on the wearable

After building several of these, the pragmatic take is this: the parts that make a fitness wearable app yours — the device protocol, the training-load math, the coaching UX — are maybe 25% of the code. The other 75% is scaffold everyone builds identically: onboarding, permission flows, tab bar, session list, chart cards, settings, auth, a Postgres schema for sessions and samples, a Supabase client wired up correctly.

That 75% is what an AI app builder generates from a prompt. Describe the app once — "a fitness companion app with onboarding, device pairing, live session, session history, and settings; use Supabase for sessions" — and get a real Expo project with expo-router routes, a wired-up store, a Postgres schema with RLS policies, and a preview you can open on your phone via QR code. Drop the BLE code and HealthKit hooks from this article into that project and you're most of the way to shipping.

You still write the interesting code. You just don't rewrite the boilerplate.

Frequently asked questions

Can you build a fitness app with React Native?

Yes. React Native is one of the most common stacks for fitness apps because it gives you shared code across iOS and Android while still exposing native APIs like HealthKit, Health Connect, and Bluetooth Low Energy through well-maintained libraries (react-native-health, react-native-health-connect, react-native-ble-plx).

Does React Native support HealthKit and Health Connect?

Yes, both. react-native-health wraps Apple HealthKit on iOS, and react-native-health-connect wraps Health Connect on Android (which replaced Google Fit's developer API in 2025). Both ship Expo config plugins, so setup is a few lines in app.json rather than a manual native code edit.

How long does it take to build a fitness wearable app?

A solo developer working full-time can ship a first version — pairing, live session, HealthKit sync, one chart — in 4–8 weeks. Most of that time goes to the wearable integration and background reliability, not the UI. Generating the scaffold with an AI builder can compress the UI and data-layer work from roughly two weeks to a day.

Do I need bare React Native, or is Expo enough?

Expo is enough. Every library referenced in this guide — health, BLE, background modes — ships an Expo config plugin. The trade-off that used to justify bare React Native (needing to edit native code) largely no longer applies as of Expo SDK 52+.

Wrapping up

Building a fitness wearable app with React Native isn't hard because the tools are missing — it's hard because there are 30 small integrations (permissions, background modes, BLE reconnect, health-store round-trips) and every one has an edge case. Nail the stack (Expo + react-native-health + react-native-health-connect + react-native-ble-plx), design your screens before you touch a peripheral, and treat wearable disconnection as a first-class state, and you'll have a shippable app in weeks rather than quarters.

The scaffold is the boring part. Describe your fitness app to RapidNative to get the six screens, the store, and the Supabase-backed data layer generated in one shot — then spend your time on the wearable code that differentiates the product. It's free to start with 20 credits, no credit card required.

Every indie developer I know has shipped a build where notifications worked in the simulator, worked on their own phone, and silently did nothing for the first 200 real users.

Push is uniquely bad this way because nothing in the chain is yours. Your server talks to Apple's APNs or Google's FCM, they talk to the OS, the OS decides whether the user ever sees it. When it fails, you get no crash, no log line, no support ticket — just a retention chart that never bends upward.

And the failure modes compound the same way privacy rejections do:

• Prod certificate vs. dev certificate mismatch → fix, rebuild, resubmit → 24–48 hours in review

• Permission prompt fires on first launch → most users tap "Don't Allow" → you can never ask again in-app

• Android 13+ users never see the prompt at all because you forgot the runtime permission → whole platform is dark Apple rejects apps that spam the permission prompt or require push to function (Guideline 4.5.4). Google throttles apps that abuse high-priority messages. And the platforms keep moving: Android 13 made notifications opt-in, iOS 16 added Live Activities, Android 16 added Live Updates, iOS 26 added broadcast push and Apple Intelligence prioritization that can bury your message if it looks like noise.

This post is the checklist I wish I'd had before my first "why is nobody getting these?" week.

The four things you must have

Before push works in production, you need four linked-and-consistent pieces:

1. Platform credentials that match the build you ship

• iOS: an APNs auth key (.p8) — not a certificate. Keys don't expire, work for every app on your team, and work for both sandbox and production. Store the Key ID, Team ID, and Bundle ID next to it; you'll need all three on the server.

• Android: a Firebase project with the FCM HTTP v1 API enabled and a service-account JSON. The legacy FCM API was shut down in 2024 — if a tutorial mentions a "Server key" string, it's out of date.

• Entitlements: the aps-environment entitlement in your iOS build, and google-services.json in the correct Android flavor. A TestFlight build with development in the entitlement gets nothing from production APNs.

2. A permission flow the user actually says yes to

Both platforms now require explicit opt-in (iOS always has; Android from 13 / API 33). You get one system prompt. After a "no," the only recovery is sending the user to Settings.

So the prompt must come after the user understands the value: after they create their first reminder, follow their first thread, place their first order. Never on first launch.

3. A device-token pipeline that survives reality

Tokens change. They change on reinstall, on restore from backup, on OS upgrade, sometimes on a whim. Your app needs to:

• Register for a token on every launch (not just once)

• Send it to your backend whenever it differs from the last one sent

• Associate it with the user and the device, so logout clears it and multi-device works

• Handle the platform telling you a token is dead (APNs 410 Unregistered, FCM UNREGISTERED) by deleting it — keep sending to dead tokens and both platforms will start dropping valid ones

4. A payload contract your app version can parse

Notifications outlive app versions. The payload you send today gets opened by a build from six months ago. Define a small, versioned JSON shape (type, id, deeplink, v) and never change the meaning of a field, only add new ones.

Common failure patterns and what caused them

Pattern 1: Prompt on first launch

iOS opt-in rates sit in the mid-50s percent on average; apps that prompt cold do far worse. The fix is a pre-permission screen — your own UI explaining what the user gets, with a "Turn on" button that triggers the system prompt and a "Not now" that doesn't. If they tap "Not now," you've spent nothing and can ask again later.

Pattern 2: Works on iOS, silent on Android 13+

POST_NOTIFICATIONS is a runtime permission since API 33. If you never call requestPermission(), the OS never asks, and FCM delivers messages to a channel nobody can see. Also: every notification needs a channel on Android 8+. No channel, no notification, no error.

Pattern 3: Sandbox/production mismatch

Your server points at api.sandbox.push.apple.com but the TestFlight build is a production build (TestFlight is production for APNs). Or the reverse. Symptom: BadDeviceToken. Fix: derive the APNs host from the build's entitlement, and log which one you hit.

Pattern 4: Data-only messages that never wake the app

On iOS, a background push needs content-available: 1, the apns-push-type: background header, the remote-notification background mode enabled — and even then, the OS treats it as a hint, not a guarantee. On Android, data-only messages reach onMessageReceived only when the app is running or backgrounded; if the user force-quit it, or the device is in Doze, it waits. If a user must see it, send a notification message, not a data message.

Pattern 5: Rich media that never shows

Images and action buttons on iOS require a Notification Service Extension — a separate target that downloads the attachment before display. Skip the extension and the mutable-content flag and the notification renders as plain text. The extension gets ~30 seconds and limited memory; download small, fail gracefully.

Pattern 6: Push that requires push

Apple rejects apps that gate core functionality behind notification permission, and both stores reject notifications used for marketing without a separate opt-in. Ads-in-push are a rejection on iOS unless the user explicitly opted into them in-app.

A working payload + pre-permission template

APNs payload (server → Apple):

{
  "aps": {
    "alert": {
      "title": "Order #4821 is out for delivery",
      "body": "Arriving in about 20 minutes."
    },
    "sound": "default",
    "badge": 1,
    "mutable-content": 1,
    "thread-id": "order-4821",
    "category": "ORDER_UPDATE"
  },
  "v": 1,
  "type": "order.status",
  "id": "4821",
  "deeplink": "myapp://orders/4821",
  "image": "https://cdn.example.com/n/4821.jpg"
}

Headers: apns-topic: com.example.app, apns-push-type: alert, apns-priority: 10, apns-collapse-id: order-4821.

FCM v1 payload (server → Google):

{
  "message": {
    "token": "<device-token>",
    "notification": {
      "title": "Order #4821 is out for delivery",
      "body": "Arriving in about 20 minutes.",
      "image": "https://cdn.example.com/n/4821.jpg"
    },
    "data": {
      "v": "1",
      "type": "order.status",
      "id": "4821",
      "deeplink": "myapp://orders/4821"
    },
    "android": {
      "priority": "high",
      "collapse_key": "order-4821",
      "notification": { "channel_id": "orders" }
    }
  }
}

Note FCM data values must be strings. Keep the custom keys identical across both so the client parses one shape.

Pre-permission copy (adapt to your app):

Know when your order moves

We'll ping you when it ships, when it's nearby, and if anything goes wrong. Nothing else — no promos unless you ask.

[ Turn on notifications ] [ Not now ]

The key: every promise here has to be true. If you later send a promo without a separate opt-in, users disable everything, and both stores treat it as a policy issue.

How to keep push working as you add features

The failure mode I've seen most often: push works at launch; three months later you add a new notification type, ship it from the server first, and 40% of installs are on a build that crashes on the unknown payload — or you add a new Android channel in code but never create it, and that type silently vanishes.

The checklist that runs at every release:

• Did we add a new notification type? → Client ignores unknown type values gracefully; Android channel created on startup; iOS category registered.

• Did we change any payload field? → Only additive; v bumped if semantics changed.

• Did we touch credentials or bundle IDs? → Send a real test push to a TestFlight/internal-track build, not just the simulator.

• Did we add a platform (Web Push, watchOS, Live Activities/Live Updates)? → Separate token type, separate registration path, separate test.

• Are we cleaning dead tokens? → Check the 410/UNREGISTERED handler is still wired after any backend refactor.

• Is the permission prompt still gated behind a value moment? → Re-check after onboarding redesigns; this regresses constantly. Five minutes per release. Beats a week of "notifications are broken" tickets you can't reproduce.

Tools + services that help

• Apple Push Notification Console — send test pushes and inspect delivery from Apple's side. First stop for any "is it us or them?" question.

• Firebase Console → Messaging — compose test messages to a single token; use it to isolate client bugs from server bugs.

• Expo Notifications / OneSignal / Knock — managed token + delivery layers if you'd rather not run APNs/FCM clients yourself. Trade-off: another SDK in your privacy manifest.

• Knuff / NWPusher — desktop tools for firing raw APNs payloads at a token.

• LetsDeployIt — the service we're building for exactly this: pre-submission checks that catch sandbox/production mismatches, missing entitlements, and permission-prompt patterns that get rejected. (Yes, that's a plug. Debugging silent push failures is what motivated it.)

Closing

Push is the one feature where "it works for me" is nearly meaningless, because the interesting failures happen on other people's phones, on other builds, with tokens you issued months ago.

The four pieces — credentials, permission flow, token pipeline, payload contract — have to match the build you ship, and they have to keep matching as you add notification types and platforms.

Get this right the first time and your retention chart will show it. Get it wrong and you'll spend more time explaining why nobody got the notification than building the thing it was about.

Ship notifications people actually receive. Save the ship-day for the code.

If you're building anything with a "where" attached to it — a ride-share, a food delivery MVP, a fitness tracker, a real-estate app — you have essentially three library choices in 2026: react-native-maps, the veteran; expo-maps, the modern SwiftUI/Jetpack Compose alternative; and third-party wrappers like Mapbox. We'll walk through when to pick each, how to wire up markers and location tracking without leaking memory, and how AI mobile app builders like RapidNative scaffold this entire stack from a plain-English prompt.

Location-aware apps are the highest-value category in the App Store — and the most technically expensive to build correctly. — Photo by henry perks on Unsplash

What is React Native Maps and why does everyone use it?

React Native Maps is a cross-platform mapping library that renders native map views inside a React Native app — Google Maps on Android, and either Apple Maps or Google Maps on iOS. It exposes a declarative MapView component plus primitives like Marker, Polyline, Polygon, and Circle. Under the hood it bridges to com.google.android.gms.maps.MapView and MKMapView, so gestures, tiles, and rendering all happen at native speed rather than in JavaScript.

Two things made it the default choice: it works inside Expo Go without a config plugin, and it has close to a decade of production battle-scars — including AirBnB's early sponsorship. At the time of writing it does close to 100,000 weekly downloads on npm, which is roughly two orders of magnitude more than the closest alternative.

react-native-maps vs expo-maps: which one to pick in 2026

Expo shipped expo-maps as a modern rewrite built on SwiftUI and Jetpack Compose. Same idea, different tradeoffs. Here's the honest comparison:

Our recommendation for most teams in 2026: start with react-native-maps unless you have a hard requirement for the newest platform look-and-feel. The reason is not technical superiority — it's that every third tutorial, every Stack Overflow answer, and every LLM-produced snippet still assumes react-native-maps. When you hit a weird bug at 11pm before a release, that ecosystem matters more than an extra 200ms of startup time.

Setting up react-native-maps with Expo (without pain)

The install command is trivial. The problems come after.

npx expo install react-native-maps

For Google Maps on iOS or Android, you need API keys from the Google Maps Platform, and you configure them through Expo's config plugin system in app.json:

{
  "expo": {
    "ios": {
      "config": {
        "googleMapsApiKey": "YOUR_IOS_KEY"
      },
      "infoPlist": {
        "NSLocationWhenInUseUsageDescription": "We show nearby places on a map.",
        "NSLocationAlwaysAndWhenInUseUsageDescription": "We sync your route in the background so you can see the full trip."
      }
    },
    "android": {
      "config": {
        "googleMaps": {
          "apiKey": "YOUR_ANDROID_KEY"
        }
      },
      "permissions": ["ACCESS_FINE_LOCATION", "ACCESS_COARSE_LOCATION"]
    }
  }
}

Three gotchas that will bite you in this exact order:

1. API keys must be restricted per-platform. A single "any bundle ID" key will work in development and get flagged and rotated by Google's abuse detection within a week of going live. Restrict by iOS bundle identifier and by Android SHA-1 fingerprint.

2. iOS release builds need the key wired through Podfile modifications. If your map is blank in TestFlight but works in dev, this is almost always why.

3. Every NSLocation* string must explain why in plain user language. Apple's review team rejects generic strings like "We need your location." Write it like you're the user.

Getting react-native-maps to build cleanly in EAS is 70% configuration and 30% code. — Photo by Christina @ wocintechchat.com on Unsplash

Rendering a map and placing markers the right way

Here's a minimal MapView with a marker:

import MapView, { Marker, PROVIDER_GOOGLE } from 'react-native-maps';
import { StyleSheet, View } from 'react-native';

export default function LocationScreen() {
  return (
    <View style={{ flex: 1 }}>
      <MapView
        provider={PROVIDER_GOOGLE}
        style={StyleSheet.absoluteFill}
        initialRegion={{
          latitude: 37.78825,
          longitude: -122.4324,
          latitudeDelta: 0.0922,
          longitudeDelta: 0.0421,
        }}
      >
        <Marker
          coordinate={{ latitude: 37.78825, longitude: -122.4324 }}
          title="Union Square"
          description="Downtown San Francisco"
        />
      </MapView>
    </View>
  );
}

A few things that trip up almost every first-time build:

• initialRegion vs region. Use initialRegion for uncontrolled maps that the user pans freely. Use region only if you have a very good reason to re-center the map on every render — it fights the user's gestures and can feel broken.

• latitudeDelta and longitudeDelta set zoom, not radius. Roughly, 0.01 is city-block zoom, 0.1 is neighborhood, 1.0 is metro area. There is no zoom prop.

• PROVIDER_GOOGLE on iOS forces Google tiles. Omit it to fall back to Apple Maps on iOS, which loads faster and is often what Apple's review team prefers for iOS-first UX.

• StyleSheet.absoluteFill on the wrapping View. A MapView with flex: 1 inside a parent that isn't sized will silently render at zero height. This is the #1 cause of "the map is blank" bug reports.

Requesting location permissions without getting rejected

The map shows the world. To show the user in the world, you need location. This is where most tutorials wave their hands and where most App Store rejections come from. React Native Maps pairs with expo-location for the permission and GPS layer:

import * as Location from 'expo-location';

async function getCurrentPosition() {
  const { status: foreground } = await Location.requestForegroundPermissionsAsync();
  if (foreground !== 'granted') {
    return null; // User denied. Show a soft explainer, not a hard error.
  }

  const location = await Location.getCurrentPositionAsync({
    accuracy: Location.Accuracy.Balanced,
  });

  return location.coords;
}

Three rules that will save you an App Store rejection:

1. Never request permission on app launch. Trigger it when the user clicks a "Show my location" button or opens a screen that visibly needs it. Apple reviewers will download your app, see an unexplained permission prompt on the splash screen, and reject.

2. Foreground permission must be granted before you request background. iOS enforces this strictly. Your background permission call will silently fail otherwise.

3. Accuracy.Balanced is the correct default. Accuracy.BestForNavigation drains battery and is intended only for driving/running apps that literally need meter-level precision. Reviewers do notice.

For live tracking, Location.watchPositionAsync returns a subscription with a remove() method. You must call remove() on unmount, or you will leak GPS listeners, drain the battery, and eventually get 1-star reviews about "this app kills my phone."

import { useEffect } from 'react';

useEffect(() => {
  let subscription: Location.LocationSubscription | undefined;
  (async () => {
    subscription = await Location.watchPositionAsync(
      { accuracy: Location.Accuracy.Balanced, timeInterval: 3000, distanceInterval: 5 },
      (location) => setPosition(location.coords),
    );
  })();
  return () => subscription?.remove();
}, []);

Drawing routes, polylines, and geofences

Once you have coordinates flowing, you'll want to draw on the map. Polyline for routes, Polygon for regions, Circle for radii:

import { Polyline, Polygon, Circle } from 'react-native-maps';

<Polyline
  coordinates={route}          // array of { latitude, longitude }
  strokeColor="#2563eb"
  strokeWidth={4}
/>

<Circle
  center={{ latitude, longitude }}
  radius={500}                 // meters
  fillColor="rgba(37, 99, 235, 0.15)"
  strokeColor="#2563eb"
/>

For routing between two points (turn-by-turn directions), react-native-maps does not calculate the path itself. Pair it with the Google Directions API or Apple MapKit Directions and feed the resulting coordinate array into a Polyline. Libraries like react-native-maps-directions wrap this call for Google, but if you exceed the free tier you're paying per request — budget accordingly.

Geofencing (fire an event when the user enters/exits a region) is handled by expo-location's startGeofencingAsync, which uses the OS-level geofence APIs and continues to work when the app is fully backgrounded. This is what powers "welcome to the store" push notifications in retail apps.

Marker clustering: the invisible performance cliff

Here is the bug you cannot afford to learn about in production: react-native-maps renders every Marker as a native view. A hundred markers is fine. Five hundred markers is a slideshow on mid-range Android. Two thousand markers will crash iOS with an out-of-memory error.

The fix is clustering — grouping nearby markers into a single "cluster" pin that expands as you zoom in. Options in order of pragmatism:

• react-native-map-clustering — Drop-in replacement for MapView, uses supercluster under the hood. Fastest way to get working clustering for typical dataset sizes (up to ~10k markers).

• Server-side clustering — For anything above ~50k points, cluster on the backend and only send the visible viewport. This is how Zillow and Airbnb do it.

• Custom bitmap markers — If clustering isn't an option, rendering markers as pre-rasterized bitmaps (image prop pointing to a PNG) is dramatically faster than rendering custom React components as markers.

The last point deserves emphasis: custom <Marker> children re-render on every zoom, every pan, every state change. If you're rendering a <View> with a <Text> inside a <Marker>, wrap it in React.memo and hoist any callbacks. A slow map is almost always a re-rendering markers problem, not a tile problem.

Test map-heavy screens on a mid-range Android device, not the latest iPhone. Your users are on the Android. — Photo by Daniel Korpai on Unsplash

When AI can scaffold this for you

Wiring up a MapView, adding markers, requesting permissions, drawing a route, and handling the "location denied" state is roughly 200-400 lines of code and half a day of "why is my map blank" debugging. It is also the kind of code that changes very little from app to app — a delivery app, a fitness app, and a real-estate app all need the same skeleton, just wired to different data.

This is where AI mobile app builders earn their place in the toolkit. When you describe an app to RapidNative — "a food delivery app where couriers see nearby orders on a map" — the generator produces the entire React Native / Expo scaffold: react-native-maps installed and wired with the correct provider, expo-location permissions wired to the right Info.plist strings, initialRegion derived from the user's coordinates, and a Marker list bound to a Supabase-backed data model. What comes out isn't a mockup or throwaway prototype — it's real React Native code you can export, open in your own editor, and modify by hand.

You can also start from other input modes — a whiteboard sketch of your map screen, a PRD describing the location features you need, or a screenshot of a competitor's app — and the resulting Expo project ships to real iOS and Android builds. The pricing page has the credit breakdown for the free and paid tiers.

The point isn't that AI replaces your engineer. It's that the boilerplate — the config plugin, the permission strings, the initial region math, the memoized marker — is done by the time you sit down to work on the parts that actually differentiate your app.

FAQ

How do I fix a blank map in React Native?

The blank map is almost always one of four things: (1) the map's parent view has no explicit height, (2) the Google Maps API key isn't wired into the release build, (3) the key is restricted to a bundle ID that doesn't match your build, or (4) you forgot the config plugin in app.json. Check them in that order.

Is react-native-maps free?

The library itself is free and MIT licensed. However, Google Maps tiles are billed by the Google Maps Platform after a monthly free quota (currently $200 of usage credit). Apple Maps on iOS is free with no quota. For map-heavy apps at scale, this billing detail matters more than the library choice.

Can I use react-native-maps in Expo Go?

Yes. This is one of the main reasons to prefer it over expo-maps if you rely on Expo Go for development. expo-maps requires a custom development client via EAS Build. Both can be used in production Expo apps.

How do I track a user's location in the background?

You need NSLocationAlwaysAndWhenInUseUsageDescription on iOS and the ACCESS_BACKGROUND_LOCATION permission on Android, plus an Info.plist UIBackgroundModes entry with location. Then use expo-location's startLocationUpdatesAsync with a registered task. Foreground permission must be granted first. Apple review is strict here — you must justify why continuous location is needed for the app's core function.

Ship it

Location-based apps are among the most valuable and most technically demanding categories in mobile. Getting react-native-maps to render is the easy part; getting it to pass App Store review, stay under battery quota, and not stutter with 500 markers is the real work. The good news is that all of that work is well-charted — the patterns above cover 90% of what you'll hit.

The other good news: you no longer have to write the scaffold by hand. Describe the app in a sentence, and let the AI produce the React Native and Expo project — including maps, permissions, and a real backend. Start building on RapidNative for free — 20 credits, no credit card. Or read more on the RapidNative blog for practical guides on integrating third-party APIs, handling state, and shipping to the stores.

Five years on, the ecosystem has sorted itself out nicely. The good news: you can keep your Dockerfiles, your docker compose habits, and your registry workflows and swap out almost everything underneath. This article walks through the real alternatives, grouped by what they actually replace.

First, know what you're replacing

"Docker" is really three things stacked on top of each other:

1. The runtime — containerd and runc, which actually create and run containers. This layer is open source and shared by almost everyone, including Kubernetes.

2. The engine and CLI — the docker command and the daemon it talks to.

3. Docker Desktop — the macOS/Windows app that bundles a Linux VM, a GUI, and the licensing that started all this.

Most people who say "I want a Docker alternative" mean layer 3. Some mean layer 2. Almost nobody needs to replace layer 1. Figure out which you mean and the choice gets much easier.

Engine and CLI alternatives

Podman

Podman is the most complete drop-in replacement for the Docker engine. It's daemonless (no long-running root process) and rootless by default, which is why security-focused teams and most Linux distros have gravitated toward it. The CLI mirrors Docker closely enough that alias docker=podman works for the vast majority of day-to-day commands.

It pairs with two sibling tools from Red Hat: Buildah for building images without a daemon, and Skopeo for inspecting and copying images between registries. Podman also has a native concept of "pods" (groups of containers sharing a network namespace), and can generate Kubernetes YAML directly from running containers, which is handy if you're heading toward k8s anyway.

Trade-offs: Compose support (podman compose) has improved a lot but occasionally diverges from Docker Compose on edge cases. Some third-party tools still assume a Docker socket.

nerdctl (containerd directly)

If you're comfortable going one layer lower, nerdctl gives you a Docker-compatible CLI straight on top of containerd. It's what many of the desktop tools below use internally. You get lazy-pulling, image encryption, and other containerd features that Docker itself doesn't expose. It's a great fit for Linux servers and CI runners where you want minimal moving parts.

Docker Desktop alternatives (macOS and Windows)

This is where most of the action is, because on a Mac or Windows machine you need a Linux VM somewhere, and how that VM is managed makes a huge difference to speed and battery life.

OrbStack (macOS)

OrbStack has effectively become the default on Mac. It's a commercial tool, but the performance gap is real: memory usage sits around a third of Docker Desktop's, and it starts in under two seconds. File sharing and port forwarding just work, it runs Linux VMs alongside containers, and it ships Kubernetes via K3s. It's free for personal use and $8 per user for commercial use, so it clears the licensing hurdle at a lower price point than Docker Desktop but isn't free for teams.

Trade-offs: macOS only. Closed source.

Colima (macOS and Linux)

Colima is the free, no-frills choice. It's a thin wrapper around Lima that spins up a VM with either the Docker engine or containerd, and you keep using your normal docker CLI. One brew install colima and colima start and you're running. It's terminal-only and needs a little more manual tuning (CPU, memory, mount type) than OrbStack, but it's rock-solid and fully open source.

Lima

Lima is the layer under Colima: a tool for running Linux VMs on macOS with automatic file sharing and port forwarding. Use it directly if you want full control over the VM, or want multiple VMs with different runtimes. It's not a container tool by itself, but it's the foundation many of the others are built on.

Finch (AWS)

Finch is AWS's open-source bundle of Lima, containerd, nerdctl, and BuildKit in one package. Think of it as "Colima with opinions": a single install, a finch command that behaves like docker, and no daemon. It's a reasonable pick if you're an AWS shop and want something with a big vendor behind it.

Rancher Desktop

Rancher Desktop is the pick for Kubernetes-first developers. It gives you a GUI, a local k8s cluster you can pin to a specific version, and lets you flip between containerd and the Docker engine as the runtime. It's heavier than the CLI tools because Kubernetes is always along for the ride, but if your workflow already involves kubectl, that's a feature rather than a cost.

Podman Desktop

The GUI companion to Podman, now well into its 1.x releases with serious Red Hat backing. It manages containers, pods, images, and Kubernetes connections, and it's the natural choice if you've already committed to Podman on Linux and want the same model on your laptop. It's also the one option that's free at any company size and has a graphical interface.

Apple's Container framework (macOS)

Worth watching: Apple announced a native Container framework at WWDC 2025, and as of 2026 it ships as part of macOS itself. It runs each container in its own lightweight VM, which is a different (and more isolated) model from everything else here. It's still early and the tooling around it is thin, but it means the OS now has a container runtime built in, and the other tools may start building on it.

Quick decision guide

One piece of advice

Whatever you pick, pick it as a team. Five developers on five different local setups is a support burden that quickly outweighs whatever you saved on licensing. Standardize the choice, put the setup in a script, and move on.

And remember: none of this touches your Dockerfiles, your Compose files, or your images. The OCI standards are what made this whole ecosystem possible, and they're the reason switching is a lot less scary than it sounds.

If you're a solo dev or a two-person team about to sell paid code for the first time, this is the write-up I wish I'd had before launch.

TL;DR

• The first 20 customers took 3 months. The next 80 took 2.

• Long-tail SEO and brand search drove the overwhelming majority of sales.

• Twitter/X, Product Hunt, and paid ads were all dead ends for us.

• The real problem in month 1 isn't "no customers." It's no evidence.

The situation, in numbers

• 7 templates live at launch (all Expo SDK 54 + TypeScript + Supabase)

• $79 per single-app license

• 7-day no-questions-asked refund

• Zero email list, zero Twitter following, zero backlinks

• First sale: day 12

• Customer #100: about 5 months in

• Total revenue by #100: modest four figures

The path was not linear. Once compounding starts, everything changes, but you have to survive the flat months first.

The cold-start problem, defined

The cold-start problem for paid templates is not "no customers." That's a symptom. The disease is no evidence: no reviews, no case studies, no Google rank, no name recognition, no referrals. Every channel that scales in month 12 requires evidence that doesn't exist in month 1.

So the entire game of the first 100 sales is one thing: build evidence faster than your runway burns. Copy, pricing tiers, and the color of the buy button are rounding errors next to that.

Channel 1: Long-tail SEO (biggest lever, slowest payoff)

We don't try to rank for "react native template." We rank for queries like:

• react native supabase template with rls and storage

• streaming ai responses to react native

• expo eas build cost calculator

• how to sign urls in supabase storage for private buckets

These have search volume in the low hundreds per month. That's the point. The developer typing that exact query has already decided to build the thing. They're not tire-kicking. They convert.

Here's the funnel breakdown from month 6:

Long-tail wins on volume. Brand search wins on conversion. Together they account for 75 of the 84 attributed sales. Everything else is noise on the tail.

Why it works: every technical essay is a permanent asset. Written once, it ranks for years and keeps producing sales. Measured as labor hours against recurring sales, this is the highest-paid work I've done as a founder.

The catch: the payoff window is 3 to 6 weeks minimum after publishing. Google has to index you, judge you, rank you, and get a real human to click. That loop runs no matter how good the essay is, and most founders quit at week three.

Channel 2: Reddit, done carefully

Not r/reactnative. The moderator culture there is heavily anti-promo, and we got flagged twice.

What worked:

• r/expo: answering technical questions with real depth, mentioning the template at the end only when directly relevant.

• r/indiehackers: long-form "here's how I built this" posts with numbers.

• r/SideProject: same, slightly more casual.

• r/Supabase: bug threads where our stack overlapped.

The rule: you can promote in a comment after you've given three comments of pure help. Reddit's spam radar, human and algorithmic, is exceptional at spotting drive-bys.

Channel 3: Open source as credibility

We open-sourced two things. First, a tiny Supabase migration generator:

export function generateMigration(schema: SchemaDefinition) {
  const columns = schema.columns.map(colToSql).join(',\n  ');
  return `create table ${schema.table} (\n  ${columns}\n);`;
}

Second, our Stripe-to-Supabase license-grant webhook pattern:

export async function POST(req: Request) {
  const event = stripe.webhooks.constructEvent(
    await req.text(),
    req.headers.get('stripe-signature')!,
    process.env.STRIPE_WEBHOOK_SECRET!,
  );

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object as Stripe.Checkout.Session;
    await supabase.from('license_grants').insert({
      user_id: session.metadata!.user_id,
      product_slug: session.metadata!.product_slug,
      granted_at: new Date().toISOString(),
    });
  }
  return new Response(null, { status: 200 });
}

Neither piece went viral. But both:

• Gave us a real GitHub org for buyers to click through

• Turned into two Indie Hackers threads and one Hacker News mention

• Continue to send small trickles of trust-first traffic

The HN mention alone drove 3 same-day sales and got us into Google's index for terms we didn't otherwise rank for.

Don't open-source the whole template. Open-source one useful piece. Buyers pay for the composition of the parts, not the parts.

Channel 4: Multi-SKU cross-linking

Once we had three or more templates, we cross-linked them on every product page. When AI Voice Notes started ranking, it pulled up Chat with PDF and AI Calorie Tracker with it. Same buyer intent, same domain authority.

This is the compounding advantage of a small catalog over a single hero product.

Channel 5: Refund policy on the pricing card

7 days, no questions asked. Refund rate to date: 3.1%. Moving the badge from the footer to the pricing card gave us a significant CVR lift, though it's hard to isolate cleanly from other changes we made at the same time.

Buyers of a $79 developer template are risk-buyers. A visible, generous refund is the cheapest way to reduce perceived risk. Our accountant hates it. Our conversion rate loves it.

What we buried

The pattern: broad-intent paid channels have bad economics. Specific-intent organic is the whole game.

Against ThemeForest

The category we sell into has been trained by ThemeForest to expect UI-only templates with mocked data. Every template we ship goes deeper:

• Full Expo SDK 54 source

• Supabase Row Level Security policies

• Working AI integrations with real API contracts

• Stripe-powered license grants provisioned to the repo the moment payment clears

• NativeWind, TypeScript, and an EAS Build config that actually builds

The gap between "UI template" and "working product" is what buyers pay for. It's also the gap you have to demonstrate, because writing "full-stack" on a landing page means nothing on day one.

If we started over

1. Ship one template. One.

2. Write 4 technical essays about problems your template solves.

3. Set up analytics before launch: Search Console, Plausible, a UTM convention.

4. Open-source one small, useful utility.

5. Show up in 2 or 3 communities regularly.

6. Put the refund policy on the pricing card.

7. Wait. Six months.

The founders who cleared the cold-start went through the same flat months you're in now. They just kept writing.

If you're selling code and stuck in those flat months, tell me in the comments which channel you're betting on. Happy to share what we saw.

Originally published on the Applighter blog.