For instance, current translation systems know how to differentiate the meaning of "bank" in a sentence like:

"I can't make the bank deposit today," and "We shall meet near the river bank."

Both sentences have "bank" in them, but with different meanings.

So how did we get here? This huge revolution started back in June of 2017 when a team of 8 Google researchers, notoriously known as the "8 Samurai," released a research paper titled "Attention Is All You Need". This date marked a turning point in modern AI systems and architecture.

For context, this framework is the bedrock of current LLMs like ChatGPT and all large language models.

The 8 Google researchers who created the Transformer architecture

So, what is NMT, and how were Google engineers able to develop a framework that enables machines to understand the semantic meaning of each word in a sentence?

Table of Contents

• Demystifying NMT: The Brain Behind the Screen

• How the Transformer Sees the World

• Why This Matters

• The Democratization of AI

• What is QVAC?

• The Architecture Supported by QVAC

• The Inference Pipeline

• Setting Up the Project

• Complete Implementation

• Conclusion

• Resources and Further Reading

Demystifying NMT: The Brain Behind the Screen

To understand this breakthrough, we first have to pull back the curtain on what NMT (Neural Machine Translation) actually means.

For decades, computer translation was "rule-based." The computer was essentially given a massive bilingual dictionary and a set of grammar rules. It would translate a sentence word-by-word, swap a few positions around, and hope for the best.

This is why early translations felt so incredibly stiff and robotic: the computer was trying to solve language like a math problem.

NMT changed the game by introducing Neural Networks, computer systems inspired by the human brain. Instead of memorizing strict rules, an NMT system learns by looking at millions of existing human translations. It looks at how humans translate phrases, captures patterns, and learns how words actually interact in the real world.

But even early NMT systems had a massive flaw: they read sentences sequentially, from left to right. If a sentence was too long, the system would "forget" how it started by the time it reached the end.

This is where the Google researchers made their historic leap.

How the Transformer Sees the World

The "Attention Is All You Need" paper solved the memory problem by introducing a brand-new architecture called the Transformer. Instead of reading a sentence word-by-word, the Transformer reads the entire sentence all at once.

To do this, it splits the job into two main parts: the Encoder and the Decoder.

The Encoder (The Reader)

Think of the Encoder as a highly analytical reader. When you feed a sentence into the system, the Encoder’s job is to read it and build a "mental map" of what the sentence actually means.

It does this using a mechanism called Self-Attention. You can think of Self-Attention as a series of spotlights. When the computer looks at a specific word, it shines spotlights on all the other words in the sentence to see how they relate.

Going back to our earlier example:

"We shall meet near the river bank."

When the Encoder processes the word "bank," its Self-Attention spotlight instantly flags the word "river." Because those two words are highly connected on the AI's mental map, the system immediately knows we're talking about land next to water, not a financial institution. It locks in this "semantic meaning" before moving to the next step.

The Decoder (The Writer)

Once the Encoder has mapped out the true meaning of the sentence, it hands this blueprint over to the Decoder.

The Decoder is the writer. Its only job is to translate that blueprint into the target language. But it doesn't just output a pre-written template. It builds the new sentence word-by-word, constantly looking back at the Encoder's blueprint (using a trick called Cross-Attention) to make sure it maintains the correct context, tone, and grammar.

If it's translating our river bank sentence into French, it knows to write "la rive" (the bank of the river) instead of "la banque" (the financial bank), because the Encoder's blueprint warned it ahead of time.

Why This Matters

By teaching machines to look at the whole picture rather than individual words, Google’s engineers didn't just build a better translator. They built a system that finally understands the nuances, idioms, and context of human language.

And as it turns out, if an AI can understand the context of a sentence well enough to translate it, it can also use that same context to write essays, answer complex questions, and code. The 2017 translation engine accidentally became the foundation of the entire AI era.

The Democratization of AI

A few years after the Transformer's invention, building with it was strictly a toy for the rich. If you wanted to implement even a simple translation feature, you had to pay Big Tech giants like Google a fortune once you went beyond their tiny free tier.

Trying to bypass their dominance was almost impossible because there were practically no resources for independent developers. Back then, just understanding the basic math of a Transformer required an academic PhD. Without a massive research department at your back, trying to build your own solution from scratch was an incredibly expensive nightmare.

Thankfully, the open-source developer community has worked tirelessly to democratize access to AI. Today, we have incredibly powerful models that anyone can download and use freely.

On top of that, the processors in our personal devices have become exceptionally capable. This hardware evolution means that sophisticated AI models can now run locally directly on your smartphone, ensuring maximum data privacy and removing the dependency on external servers.

As the saying goes, "Today it needs a full building to function, tomorrow it will fit in your pocket." Of course, I totally made that quote up 😅, but you get my point!

To put this in action, we'll build a mobile application with Expo and QVAC that translates English to French.

What is QVAC?

QVAC (QuantumVerse Automatic Computer) is a decentralized, local-first AI development platform and SDK created by Tether.

Unlike traditional AI tools that require cloud connectivity, QVAC allows users to run AI models entirely on their own devices. By keeping the computation local and offline, it ensures your data remains private, secure, and entirely under your control.

Key Concepts for On-Device Translation

To understand how QVAC runs on a mobile device, we must keep a few key concepts in mind:

1. On-Device Inference:

Running model calculations locally. Rather than relying on a single engine or cloud API, QVAC supports specialized local inference backends depending on the task.

For translation, it uses the Bergamot engine under the hood. These engines memory-map quantized model weights directly into the device's RAM and run calculations using native hardware acceleration.

2. Quantization

A mathematical optimization technique that compresses the model's weights. This makes it possible for models to fit into the memory constraints of consumer mobile hardware while keeping output quality high.

The Architecture Supported by QVAC

Before writing code, it's crucial to understand what's actually happening under the hood. To handle local execution without melting your device, the QVAC SDK manages the hardware binding and model lifecycle while hooking into optimized inference backends.

For translation, QVAC utilizes the Bergamot engine. Originally developed as part of the Bergamot project (which powers Firefox's offline translation), this engine is highly optimized for fast, accurate Neural Machine Translation (NMT) on consumer hardware.

At its core, the Bergamot engine takes a source sentence, processes it through its Encoder-Decoder transformer architecture, and predicts the target language tokens in a highly efficient manner.

Understanding Language Pairs

It's important to understand the mechanics of how these models are trained. Translation models like the ones used by Bergamot are strictly unidirectional language pairs. This means the BERGAMOT_EN_FR model is designed exclusively to translate from English to French. It can't reverse the process.

If you want to translate French back to English, you would need to download and load a completely separate model trained specifically for that direction.

If a model is trained to be bidirectional (English ↔ French) or multilingual (translating dozens of languages like large language models do), it has to store mathematical representations, vocabulary, and grammar rules for multiple linguistic directions inside a single neural network. This balloons the parameter count, making the file size massive and requiring heavy RAM and compute power to process.

By isolating the task to a single direction (for example BERGAMOT_EN_FR), the model only needs the neural network to "understand" English inputs and "generate" French outputs. It doesn't need the capacity to generate English text.

This extreme specialization is exactly how Bergamot shrinks the model weights down to those incredibly tiny 15–35MB files that can run instantly on a local CPU without freezing your browser.

The Inference Pipeline

To visualize how we interact with the translation engine in our codebase, think of local translation as running a dedicated interpreter right in your phone's memory:

1. Hiring the interpreter (loading the model): We map the compressed model file (in this case, the BERGAMOT_EN_FR English-to-French model) directly into the device's RAM.

2. Handing over the script (text input): We pass the source text to the loaded engine.

3. The performance (inference): The engine reads the text and mathematically predicts the translated tokens, providing the translated result once the process is complete.

4. Closing the show (unloading): Because neural network models are memory-intensive, the model can be cleared from RAM to free up resources once the translation is complete or when the user leaves the screen.

Setting Up the Project

To ensure this guide is completely self-contained, let's start by quickly generating our new Expo application and installing the QVAC SDK. Open your terminal and run the following commands:

npx create-expo-app translator-app --template blank-typescript
cd translator-app
npm install @qvac/sdk jiti

Next, you need to add the following peer dependencies to your package.json for QVAC to work correctly. Add these lines to their respective sections:

  "dependencies": {
    "bare-rpc": "^1.0.0",
    "react-native-bare-kit": "^0.11.5"
  },
  "devDependencies": {
    "bare-pack": "^1.5.1"
  }

Once added, install the dependencies by running:

npm install
npx expo install expo-file-system expo-build-properties expo-device

Configuring the Expo Plugin with JITI

Next, we need to add the QVAC SDK plugin to our Expo project. Because the QVAC SDK's Expo plugin is distributed as a modern ECMAScript Module (ESM), but Expo's configuration file (app.config.js) runs in a standard Node.js CommonJS environment, we can't use a standard require().

This is why we installed jiti. It acts as a bridge, allowing us to synchronously load ESM modules inside CommonJS files without breaking the build process.

Create or update your app.config.js file at the root of your project and configure it like this:

const createJiti = require("jiti");
const jiti = createJiti(__filename);

// Synchronously require the ESM module using jiti
const qvacModule = jiti("@qvac/sdk/expo-plugin");
const withQvacSDK = qvacModule.withQvacSDK || qvacModule.default;

// (Include your withEscapeBundleShellScript helper if needed)

module.exports = ({ config }) => {
  config.plugins = [
    [
      "expo-build-properties",
      {
        android: { minSdkVersion: 29 },
      },
    ],
    withQvacSDK,
    "expo-router",
    [
      "expo-splash-screen",
      {
        backgroundColor: "#208AEF",
      },
    ],
    withEscapeBundleShellScript, // Custom helper if applicable
  ];

  return config;
};

This configuration applies the QVAC native setup scripts and ensures Android requires at least SDK version 29 (which is necessary for the native libraries).

With our base configuration ready to go, let's jump straight into the translation code.

Complete Implementation

Let's bring it all together. We'll implement an interface that takes English text, manages the downloading and loading states for the Bergamot engine, translates the text to French, and renders the output to the screen.

Replace your entry app file src/app/index.tsx with the following implementation:

import { View, ScrollView, TextInput, Text, TouchableOpacity, StyleSheet } from "react-native";
import { useState, useEffect } from "react";
import {
  loadModel,
  translate,
  unloadModel,
  BERGAMOT_EN_FR,
  getModelInfo,
} from "@qvac/sdk";
import { Stack } from "expo-router";

type TranslationStatus =
  | "Idle"
  | "Checking model..."
  | "Downloading model..."
  | "Model downloaded successfully."
  | "Loading model..."
  | "Translating..."
  | "Streaming translation..."
  | "Translation finished."
  | `Error: ${string}`;

export default function HomeScreen() {
  const [status, setStatus] = useState<TranslationStatus>("Checking model...");
  const [translatedText, setTranslatedText] = useState<string>("");
  const [inputText, setInputText] = useState<string>("");
  const [isTranslating, setIsTranslating] = useState<boolean>(false);
  const [isDownloaded, setIsDownloaded] = useState<boolean | null>(null);
  const [downloadProgressStr, setDownloadProgressStr] = useState<string>("");

  useEffect(() => {
    const checkModelStatus = async () => {
      try {
        const model = await getModelInfo({ name: BERGAMOT_EN_FR.name });
        setIsDownloaded(model.isCached);
        console.log("Model", model);
        setStatus("Idle");
      } catch (error) {
        console.error("Error checking model:", error);
        setStatus("Error: Failed to check model status");
      }
    };
    checkModelStatus();
  }, []);

  const handleDownload = async () => {
    try {
      setIsTranslating(true);
      setStatus("Downloading model...");
      setDownloadProgressStr("");

      const modelId = await loadModel({
        modelSrc: BERGAMOT_EN_FR,
        modelType: "nmt",
        onProgress: (progress: any) => {
          let pct = progress.percentage;
          let dl = progress.downloaded;
          let tot = progress.total;
          if (progress.shardInfo) {
            pct = progress.shardInfo.overallPercentage;
            dl = progress.shardInfo.overallDownloaded;
            tot = progress.shardInfo.overallTotal;
          }
          const formatBytes = (bytes: number) => {
            if (bytes === 0) return "0 B";
            const k = 1024;
            const sizes = ["B", "KB", "MB", "GB"];
            const i = Math.floor(Math.log(bytes) / Math.log(k));
            return (
              parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i]
            );
          };
          setDownloadProgressStr(
            `${pct.toFixed(2)}% (${formatBytes(dl)} / ${formatBytes(tot)})`,
          );
        },
        modelConfig: {
          engine: "Bergamot",
          from: "en",
          to: "fr",
          beamsize: 1,
          normalize: 1,
          temperature: 0.2,
          norepeatngramsize: 3,
          lengthpenalty: 1.2,
        },
      });

      await unloadModel({ modelId, clearStorage: false });

      setIsDownloaded(true);
      setStatus("Model downloaded successfully.");
    } catch (error: any) {
      console.error(error);
      setStatus(`Error: ${error.message}`);
    } finally {
      setIsTranslating(false);
      setDownloadProgressStr("");
    }
  };

  const handleTranslate = async () => {
    if (!inputText.trim()) {
      setStatus("Error: Please enter text to translate");
      return;
    }

    try {
      setIsTranslating(true);
      setTranslatedText("");
      setStatus("Loading model...");

      const modelId = await loadModel({
        modelSrc: BERGAMOT_EN_FR,
        modelType: "nmt",

        modelConfig: {
          engine: "Bergamot",
          from: "en",
          to: "fr",
          beamsize: 1,
          normalize: 1,
          temperature: 0.2,
          norepeatngramsize: 3,
          lengthpenalty: 1.2,
        },
      });

      setStatus(`Translating...`);

      const result = translate({
        modelId,
        text: inputText,
        modelType: "nmt",
        stream: false,
      });

      const text = await result.text;
      setTranslatedText(text);

      const stats = await result.stats;
      if (stats) {
        console.log(`▸ Processing stats:`, stats);
      }

      setStatus("Translation finished.");

      await unloadModel({ modelId, clearStorage: false });
    } catch (error: any) {
      console.error(error);
      setStatus(`Error: ${error.message}`);
    } finally {
      setIsTranslating(false);
    }
  };

  return (
    <>
      <Stack.Screen
        options={{
          headerTitle: "Translator",
          headerStyle: { backgroundColor: "#000" },
          headerTintColor: "#fff",
        }}
      />
      <ScrollView contentContainerStyle={styles.scrollContainer}>
        <View style={styles.card}>
          <View style={styles.header}>
            <Text style={styles.title}>
              English to French Translator
            </Text>
            <Text style={styles.subtitle}>
              Enter text to translate:
            </Text>
          </View>

          <View style={styles.content}>
            <TextInput
              style={[styles.input, isTranslating && styles.disabledText]}
              multiline
              placeholder="Type English text here..."
              placeholderTextColor="#888"
              value={inputText}
              onChangeText={setInputText}
              editable={!isTranslating}
            />

            <Text style={styles.statusText}>
              Status: {status}
              {downloadProgressStr ? `\n${downloadProgressStr}` : ""}
            </Text>

            {isDownloaded === null ? (
              <TouchableOpacity disabled style={[styles.button, styles.buttonDisabled]}>
                <Text style={styles.buttonText}>
                  Loading...
                </Text>
              </TouchableOpacity>
            ) : isDownloaded ? (
              <TouchableOpacity
                onPress={handleTranslate}
                style={[
                  styles.button,
                  (isTranslating || !inputText.trim()) && styles.buttonDisabled,
                ]}
                disabled={isTranslating || !inputText.trim()}
              >
                <Text style={styles.buttonText}>
                  {isTranslating ? "Translating..." : "Translate"}
                </Text>
              </TouchableOpacity>
            ) : (
              <TouchableOpacity
                onPress={handleDownload}
                style={[styles.button, isTranslating && styles.buttonDisabled]}
                disabled={isTranslating}
              >
                <Text style={styles.buttonText}>
                  {isTranslating ? "Downloading..." : "Download Model"}
                </Text>
              </TouchableOpacity>
            )}

            <View style={styles.outputContainer}>
              <Text style={styles.outputText}>
                {translatedText || "Translation will appear here..."}
              </Text>
            </View>
          </View>
        </View>
      </ScrollView>
    </>
  );
}

const styles = StyleSheet.create({
  scrollContainer: {
    flexGrow: 1,
    paddingHorizontal: 16,
    paddingTop: 16,
    paddingBottom: 24,
    backgroundColor: "#f9fafb",
  },
  card: {
    backgroundColor: "#ffffff",
    maxWidth: 450,
    width: "100%",
    alignSelf: "center",
    borderRadius: 12,
    padding: 16,
  },
  header: {
    marginBottom: 16,
  },
  title: {
    textAlign: "center",
    fontSize: 24,
    fontWeight: "bold",
    color: "#111827",
  },
  subtitle: {
    textAlign: "center",
    marginTop: 4,
    fontSize: 16,
    color: "#6b7280",
  },
  content: {
    gap: 24,
  },
  input: {
    borderWidth: 1,
    borderColor: "#e5e7eb",
    backgroundColor: "#ffffff",
    color: "#111827",
    padding: 12,
    borderRadius: 8,
    minHeight: 100,
    textAlignVertical: "top",
  },
  disabledText: {
    opacity: 0.5,
  },
  statusText: {
    fontSize: 14,
    color: "#3b82f6",
    fontWeight: "bold",
    textAlign: "center",
    marginTop: 12,
    marginBottom: 12,
  },
  button: {
    width: "100%",
    height: 48,
    borderRadius: 12,
    backgroundColor: "#3b82f6",
    alignItems: "center",
    justifyContent: "center",
  },
  buttonDisabled: {
    opacity: 0.5,
  },
  buttonText: {
    fontWeight: "600",
    fontSize: 18,
    color: "#ffffff",
  },
  outputContainer: {
    marginTop: 16,
    padding: 16,
    backgroundColor: "#f3f4f6",
    borderRadius: 8,
    minHeight: 100,
  },
  outputText: {
    fontSize: 16,
    color: "#111827",
  },
});

Here is a translation example from the application.

Input (English)

The location I told you was near the river bank

Output (French)

L'endroit où je vous ai dit était près de la rive de la rivière

Codebase Breakdown

Let’s lift the hood on how this local translation implementation manages native model lifecycles and processes the streamed tokens.

1. Managing the Native Lifecycle

Loading neural network weights for translation is computationally expensive. When the QVAC runtime initializes a model, it must read parameters from the local disk and copy the active weights into device RAM.

To handle this efficiently, we check if the model is cached before attempting to load it. This is used to check if the model is downloaded. That's the meaning of cached: it means the model has been downloaded to the user's disk:

const model = await getModelInfo({ name: BERGAMOT_EN_FR.name });
setIsDownloaded(model.isCached);

The loadModel function will automatically handle downloading the model from the Hugging Face hub if it hasn't been cached locally yet. Once the file is available locally, it directly memory-maps the weights.

2. Translating the Text

Once the model is loaded, we can pass our text to the translation engine:

const result = translate({
  modelId,
  text: inputText,
  modelType: "nmt",
  stream: false,
});

const text = await result.text;
setTranslatedText(text);

This waits for the full translation to complete before displaying the final result to the user.

3. Unloading the Model

After the translation is complete, we explicitly destroy the model via unloadModel:

await unloadModel({ modelId, clearStorage: false });

By unloading the model, we ensure that the device's RAM is freed up for other processes. Because the model is already downloaded and cached on the disk (and we explicitly set clearStorage: false), reloading the model the next time the user wants to translate something will be nearly instantaneous.

Conclusion

Transitioning translation from the cloud to on-device hardware offers a practical approach for mobile application developers. Running model inference locally eliminates reliance on remote internet connectivity, removes recurring API usage costs, and ensures that user text inputs never leave the physical device.

Integrating local translation can be highly beneficial for travel apps, secure communication tools, or educational platforms. As edge processors gain dedicated hardware acceleration cores and open-source models become even more efficient through quantization research, local-first architectures present a compelling alternative for developers prioritizing privacy, offline resilience, and predictable cost structures.

Resources and Further Reading

To dive deeper into local Neural Machine Translation, inspect the source code, or explore advanced configurations for your mobile applications, check out the following resources:

• QVAC Translation Docs: Official documentation for integrating local translation capabilities with QVAC.

• QVAC Expo Integration Docs: Learn more about configuring custom local models in Expo.

• Bergamot Project: Learn more about the underlying Neural Machine Translation engine.

• Attention Is All You Need: The original 2017 Google research paper that introduced the Transformer architecture.

• Full Code Example: Full code example's repository.

In this massive tutorial, you will develop a feature-rich grocery list app that runs seamlessly on both iOS and Android.

Throughout the lessons, you will get hands-on experience with some of the most powerful tools in the modern mobile ecosystem. You will use Expo and React Native for the core framework, ensuring your single codebase translates flawlessly across devices. For the backend and data management, the project integrates a Neon Postgres database managed with Drizzle ORM. You will also learn how to implement secure user authentication using Clerk, allowing users to seamlessly log in with Google, Apple, or GitHub.

Styling your mobile application is streamlined in this course, as it walks you through using NativeWind to apply Tailwind CSS classes directly to your React Native components. You will also master global state management with Zustand, making it remarkably simple to handle your application's complex data flow. Towards the end of the build, you will even integrate Sentry to create a native feedback form that captures user bug reports and feature requests in real-time.

You can watch the full course on the freeCodeCamp.org YouTube channel (4-hour watch).

The product requirement is identical on both platforms. The contracts underneath are opposites.

On iOS, Apple Push Notification service (APNs) updates a system-owned SwiftUI widget for you, and your app code never runs. On Android there's no system-managed remote update at all. A data-only Firebase Cloud Messaging (FCM) message wakes a background service, and your own code re-posts the notification every single time.

In this handbook you'll build both. You'll write one TypeScript API backed by two native implementations: a Swift one that talks to ActivityKit and a Kotlin one that talks to NotificationManager. You'll also write an APNs client and an FCM client from scratch, in about sixty lines each, with no libraries. And you'll learn the silent failure modes that make this API hard, because almost every mistake here produces no error at all.

I built a delivery-tracking demo called DropTrack to work through this. Everything below comes from that build, including a three-device Samsung investigation that ends with a screenshot of a hardcoded allowlist.

Table of Contents

1. Prerequisites

2. What Live Activities and Live Updates Actually Are

3. Where You Have Already Seen This Feature

4. Why You Need a Custom Native Module

5. How the iOS Contract Works

6. How to Build the Widget in SwiftUI

7. How to Bridge ActivityKit to JavaScript

8. Four iOS Gotchas That Cost Me an Evening Each

9. How to Drive iOS From a Server With APNs

10. How to Write an APNs Client From Scratch

11. How to Test on Real Hardware

12. Why Android Has No ActivityKit

13. How to Build the Kotlin Side

14. How to Drive Android From a Server With FCM

15. Three UX Gaps the Naive Implementation Leaves

16. How to Script the Simulators and Devices

17. How iOS and Android Compare

18. The Samsung Reality Check

19. The Demo Repository

20. What to Know Before You Start

21. Conclusion

22. Sources and Further Reading

Prerequisites

To follow along, you'll need:

• Node.js 20 or later.

• Xcode 26 or later, plus a paid Apple Developer account. APNs requires a real signing key and a device build. The simulator can't receive Live Activity pushes.

• Android Studio with an API 36 emulator built from a google_apis system image. Google Play services are required for FCM, and a bare Android Open Source Project image doesn't include them.

• A Firebase project, for the Android half.

• Working knowledge of Swift, Kotlin, and TypeScript. This is a native modules article, not a JavaScript-only one.

The versions I used throughout:

The androidx.core version isn't optional. Version 1.17.0 backports the Android 16 promotion APIs so they compile against base SDK 36. I'll explain why in a moment.

What Live Activities and Live Updates Actually Are

A Live Activity isn't a push notification. A notification is a fire-and-forget event. A Live Activity is a persistent, glanceable card with its own state that changes in place, a bounded lifetime, and dedicated system surfaces.

Here's where each platform landed:

• iOS 16.1 introduced lock-screen Live Activities. 16.2 added the Dynamic Island. 17.2 added push-to-start. 18 added broadcast channels. See Apple's ActivityKit documentation and the Live Activities Human Interface Guidelines.

• Android 16 (API 36) introduced Notification.ProgressStyle, the segmented progress bar.

• Android 16 QPR1 (API 36.1), the first Quarterly Platform Release, introduced the promotion pipeline: the status-bar chip and the elevated lock-screen slot. Google calls the whole feature progress-centric notifications.

I built DropTrack to exercise all of it. An order moves through seven steps, from "Order placed" to "Arriving now". A courier can be reassigned mid-run. The card is driven either locally from an in-app console or remotely from a push.

Where You Have Already Seen This Feature

Before any code, it helps to know why this API exists, because "a card on the lock screen" undersells it.

Think about the last time you ordered food. You place the order, lock your phone, and then what? Without a Live Activity, the app's only way to reach you is a push notification per state change. Order confirmed. Restaurant is preparing your food. Rider assigned. Rider is two stops away. Rider has arrived.

That's five notifications for one order. Multiply that by every order, and you've trained the user to mute you.

A Live Activity replaces all five with one card that mutates in place. Same information with one surface and no notification fatigue. That's the entire product argument.

Apple's own Human Interface Guidelines name the recurring use cases: sports scores, workouts, rides, and deliveries. Google's progress-centric notifications documentation converges on almost the same list, stating that "key use cases include rideshare, delivery, and navigation." That page even describes the delivery example in terms of progress points for food preparation and delivery milestones, and segments colored by traffic conditions, which is precisely the widget you're about to build.

Apps That Have Shipped it

Rather than repeat the roundup posts, I checked each app's own App Store listing, because a company describing its own feature is the strongest evidence available. Every app below states that it uses Live Activities in its own words:

Apple ships them in its own software, too. The Apple Sports support page says that with Live Activities turned on "you can get real-time information on your iPhone Lock Screen or your Apple Watch so that you can follow every moment of the game."

Two more are well documented by the technology press rather than by the companies themselves. Uber Eats rolled out Live Activities in May 2023, showing order status, estimated time of arrival, and the driver's name and photo. DoorDash followed in December 2023 with a real-time estimated time of arrival in the Dynamic Island.

Two honest caveats about that table. First, an app not mentioning Live Activities in its listing doesn't mean it lacks the feature, only that I couldn't confirm it first-hand. Uber Eats is exactly that case. Second, this reflects the listings as I read them, and any app can add or drop the feature in a release.

Food delivery is the canonical case, and it's what DropTrack models. Ride-hailing is the highest-stakes version: "driver arriving in 3 minutes", the plate number, the trip in progress, glanced at while you stand on a curb with a locked phone. The Dynamic Island's compact presentation exists almost for this: a glyph and a percentage read in half a second.

Finance is the case people forget, and it's where a segmented bar would earn its keep. A crypto deposit isn't "pending, then done". It's "3 of 12 network confirmations", which is a segmented progress bar with discrete steps, mapping cleanly onto ProgressStyle's segments and points and onto the SwiftUI capsules you will write below. The same shape fits a bank transfer clearing or a card payment settling.

I want to be careful here, though: I checked the App Store listings for the major exchanges and neobanks and found none that documents a Live Activity. Treat this one as an obvious fit that the category hasn't yet taken up, not as prior art.

Here's the table I wish someone had shown me before I started:

Look at the third column. In every commercially interesting case the update is driven by your server, not by the device. That means the entire value of the feature lives in the push path. And the push path is exactly where the two platforms diverge, where the failures are silent, and where most of this handbook's pain is concentrated.

The pretty SwiftUI card is the easy half. Getting a backend to reliably mutate that card while the app is dead is the hard half, and it's different on each platform.

Why You Need a Custom Native Module

Before writing a line of Swift, I evaluated the shortcuts. Both fail, for instructive reasons.

expo-live-activity ships a predefined widget layout and a fixed content-state shape. DropTrack needs a custom segmented progress bar, a rider-reassignment treatment, and its own Dynamic Island layouts. All of those require owning ActivityAttributes and the SwiftUI that renders it. You reach first render fastest, and then you eject.

Notifee, the notification library most React Native developers reach for, is archived. As of this writing its GitHub repository is marked archived, its last published release was @notifee/react-native@9.1.8 in December 2024, and its Android module still targets compileSdk 34. It has no Live Updates support. A custom module is currently the only React Native route to Android 16 Live Updates.

So: one local Expo module, one TypeScript API, two native backends.

modules/droptrack-live/
├── expo-module.config.json   ← autolinking (apple + android)
├── index.ts                  ← the public JS API
├── src/                      ← TS types, native binding, web no-op
├── ios/
│   ├── DeliveryAttributes.swift    ← the ActivityKit contract
│   └── DroptrackLiveModule.swift   ← JS to ActivityKit
└── android/
    ├── DroptrackLiveModule.kt      ← JS to NotificationManager
    ├── DeliveryNotifier.kt         ← the shared notification builder
    └── DroptrackFcmService.kt      ← push to NotificationManager

The JavaScript surface is deliberately small, and identical across platforms:

// The dynamic half of the card: every update replaces this object wholesale.
// Keep it small. iOS rejects an ActivityKit push payload over 4 KB.
export type DeliveryState = {
  status: string;           // free text shown as the headline: "Picked up"
  progress: number;         // 0.0 to 1.0, drives the bar on both platforms
  etaEpochMillis: number;   // Unix ms, the shape JS speaks. Swift converts it.
  stopsRemaining: number;   // renders as "2 stops away" / "you're next"
  courierName: string;      // dynamic, because riders get reassigned mid-run
  riderReassigned: boolean; // flips the courier row to the "new rider" style
};

// Three verbs, mirroring the ActivityKit lifecycle. Android fakes the same
// shape with notify / notify / cancel, so callers never branch on platform.

// Starts the activity and returns the system-assigned id. Hold on to it:
// every later call needs it, and it does NOT survive an app restart.
startDelivery(info: DeliveryInfo, state: DeliveryState): Promise<string>;

// Replaces the ContentState in place. The card mutates, it does not re-appear.
updateDelivery(id: string, state: DeliveryState): Promise<void>;

// Final state, then dismissal. Omit dismissAfterSeconds to let the card linger.
endDelivery(id: string, state: DeliveryState, dismissAfterSeconds?: number): Promise<void>;

isSupported(): boolean;          // false on iOS < 16.2, Android < 16, and web
areActivitiesEnabled(): boolean; // false if the USER switched them off in Settings

Those last two are separate on purpose. A device can support Live Activities while the user has switched them off in Settings, and only areActivitiesEnabled() catches that. Activity.request throws in that case, so startDelivery throws too.

The dismissAfterSeconds argument maps onto ActivityKit's dismissal policy. Under the default policy, Apple's documentation says "the system keeps a Live Activity that ended on the Lock Screen for up to four hours after it ends." Passing a value shortens that window.

This project uses Expo's Continuous Native Generation (CNG), which means the ios and android folders are generated by prebuild and aren't committed. Every line of native code therefore lives in the module or in a config plugin, so it survives prebuild --clean. The widget extension itself is generated by @bacons/apple-targets for the same reason.

One structural detail matters later: the module compiles as its own CocoaPod, not into the app target.

How the iOS Contract Works

An ActivityKit activity is split in two. ActivityAttributes holds static data, set once and never changed. Its nested ContentState holds the dynamic half, which every update replaces wholesale.

Most tutorials state that rule and move on. It's worth understanding why the platform forces it, because the reason tells you exactly which half any given field belongs in.

Why the Split Exists

The split isn't a style convention. It's about what can physically cross the wire.

When you call Activity.request(...), you hand ActivityKit two things at once: the attributes and the first content state. The system files the attributes away and never accepts a new copy of them. From that moment on, the only thing you can ever send is a new ContentState.

You can see this in the shape of an ActivityKit push payload. Here's what my APNs client actually transmits:

aps: {
  // Older-than-last timestamps are discarded by APNs (ordering guard).
  timestamp: Math.floor(Date.now() / 1000),
  event,                        // "update" or "end"
  'content-state': contentState, // the only field that carries data
}

There is no attributes key. There can't be one. Nothing in the payload can reach the static half.

So "should this field be static or dynamic?" is really the question "will my server ever need to change this value?" If the answer is yes, the field must live in ContentState, because that's the only thing a push can move.

That's the whole design. ActivityAttributes is the activity's identity, fixed at birth. ContentState is its current reading, replaced wholesale on every update rather than patched. Send a content state that omits a field and you haven't left that field alone, you've failed to decode. The Codable conformance is what lets the system serialize the state across a process boundary, and the Hashable conformance lets it tell whether an incoming state actually differs from the one already on screen.

The Bet I Lost

Here's what I wrote first. It looks reasonable:

// BEFORE: courierName is static. This compiles, ships, and works fine,
// right up until a dispatcher reassigns the rider mid-delivery.
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var status: String
    var progress: Double
    var eta: Date
    var stopsRemaining: Int
  }
  var orderId: String
  var courierName: String   // the bet: a delivery has one courier
}

Putting a field in the static half is a bet that it can never change for the activity's lifetime. I bet that a delivery has one courier. Then I built rider reassignment, where a dispatcher swaps the courier mid-run, and the bet came due.

Because courierName was static, there was no way to express the change. Not through activity.update(), not through a push, not at all. The only escape would have been to end the activity and start a new one, which means the card disappears from the lock screen and returns as a different card, mid-delivery. That's not a fix, it's a regression.

So the field moved:

// AFTER: only orderId is genuinely immutable. Everything a dispatcher
// can change lives in ContentState, because ContentState is the only
// thing an APNs push can carry.
struct DeliveryAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    /// Human-readable status, e.g. "Picked up", "2 stops away"
    var status: String
    /// Overall delivery progress, 0.0 ... 1.0
    var progress: Double
    /// Estimated arrival time
    var eta: Date
    /// Stops before the courier reaches the user
    var stopsRemaining: Int
    /// Courier display name, dynamic since riders can be reassigned mid-run
    var courierName: String
    /// True right after a reassignment, drives the "new rider" treatment
    var riderReassigned: Bool
  }

  /// Order identifier shown on the card, the only truly immutable fact
  var orderId: String
}

Moving one field touched twelve files, because the contract is duplicated at every layer that has to encode or decode it:

9  DeliveryNotifier.kt          Android notification builder
3  DroptrackLive.types.ts       the TypeScript contract
3  DroptrackLiveModule.swift    the Swift bridge record
3  App.tsx                      React state and the push handler
2  DeliveryLiveActivity.swift   the widget's SwiftUI
2  DeliveryAttributes.swift     the module's copy
2  DeliveryAttributes.swift     the widget's copy (yes, twice)
2  DroptrackLiveModule.kt       the Kotlin bridge record
1  DroptrackFcmService.kt, dispatch-server.mjs, push-update.mjs,
   apns.test.mjs, delivery.ts

The asymmetry here is what matters. A dynamic field you never change costs you a few bytes in every push. A static field you need to change costs you the entire stack. When in doubt, put the field in ContentState. In the end, only orderId earned its place in the static half.

The Identical-Copy Trap

The widget extension is a separate binary. It's a different process, launched by the system, that doesn't link your app's code. Your app target compiles the module's DeliveryAttributes.swift. The widget target compiles its own. Two compilations produce two independent types that merely share a name.

At runtime, ActivityKit has to connect them. Your app says "start an activity of type DeliveryAttributes", and the system asks the widget whether it has a WidgetConfiguration for a type by that name whose ContentState decodes this data. The match is structural, on the type's name and its Codable shape, performed by a system daemon, at runtime, across a process boundary.

Now rename courierName to riderName in one copy and forget the other. The app compiles. The widget compiles. Both are internally consistent. Activity.request() succeeds and returns an id. But when the system hands the encoded state to the widget, the widget's decoder looks for riderName, doesn't find it, and throws inside a daemon in another process, where your breakpoints and your log statements don't exist.

The card never appears. No crash, no warning, no console line, and Activity.activities still lists the activity as running. You'll spend an hour on your SwiftUI layout, and the layout was never the problem.

Two things follow. A shared source file doesn't save you, because the module compiles as its own CocoaPod rather than into the app target, so no build phase naturally covers both. And since the compiler will never catch this, the check has to be external:

diff modules/droptrack-live/ios/DeliveryAttributes.swift \
     targets/widgets/DeliveryAttributes.swift

If that command ever prints anything, your Live Activity is already broken. It costs nothing to wire into a pre-commit hook, and it's the single highest-value guardrail in this project.

How to Build the Widget in SwiftUI

The widget declares one Widget with two presentations: the lock-screen card and the Dynamic Island.

Before reading the code, hold one idea in your head: these closures are a pure function from state to view. The widget extension isn't a running program. The system launches the process, calls your closure with the current ContentState, keeps the rendered result, and kills the process.

When a push delivers a new state, it runs the closure again. There's no @State, no timer, no network call, and no onAppear doing work. That's also why widget extensions have no network access: there's nobody home to make a request.

Two things about the type signature before the code. Widget is a WidgetKit protocol, not a SwiftUI View, and body returns some WidgetConfiguration, not some View. You're not describing pixels, you're declaring what kind of widget this is.

And the for: argument on line 3 is the binding point from the previous section: this is the exact spot where the app's DeliveryAttributes and the widget's copy are matched by name and Codable shape, so it's where the identical-copy trap either works or silently fails.

struct DeliveryLiveActivity: Widget {
  var body: some WidgetConfiguration {
    ActivityConfiguration(for: DeliveryAttributes.self) { context in
      // Closure 1 of 2: the lock screen and banner.
      DeliveryCardView(context: context)
        .activityBackgroundTint(Color(red: 0.07, green: 0.07, blue: 0.12))
        .activitySystemActionForegroundColor(.white)

    } dynamicIsland: { context in          // closure 2 of 2, labelled
      DynamicIsland {
        // Expanded (long-press): four named slots, arranged around the cutout.
        DynamicIslandExpandedRegion(.leading) {
          Image(systemName: "bicycle").foregroundStyle(brandOrange)
        }
        DynamicIslandExpandedRegion(.trailing) {
          Text(context.state.eta, style: .time).font(.callout.bold())
        }
        DynamicIslandExpandedRegion(.center) {
          Text(context.state.status).font(.callout.weight(.semibold)).lineLimit(1)
        }
        DynamicIslandExpandedRegion(.bottom) {
          VStack(spacing: 4) {
            SegmentedProgressBar(progress: context.state.progress)
            HStack {
              CourierLabel(state: context.state, compact: true)
              Spacer()
              Text(stopsLabel(context.state.stopsRemaining))
            }
            .font(.caption2).foregroundStyle(.secondary)
          }
        }
      } compactLeading: {                   // the default pill, left of the cutout
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      } compactTrailing: {                  // ...and right of it
        Text("\(Int(context.state.progress * 100))%").font(.caption2.bold())
      } minimal: {                          // when another app shares the island
        Image(systemName: "bicycle").foregroundStyle(brandOrange)
      }
      .keylineTint(brandOrange)
    }
  }
}

That's one state object rendered four ways, and a few of the choices are load-bearing:

• The two closures: ActivityConfiguration takes a content closure and a dynamicIsland: closure. The bare-then-labelled form is Swift's multiple-trailing-closure syntax, not two separate statements. The first is the lock-screen and banner card, and the second is every Dynamic Island form.

• context: Each closure receives context.state, the dynamic ContentState replaced on every update, and context.attributes, the static half, read exactly once, for the order id on the card.

• The two .activity… modifiers: These are ActivityKit-specific, not general SwiftUI. You don't draw the system's swipe-to-end chrome, so all you can do is tint it.

• eta, style: .time renders a localized clock time such as "5:42 PM", honouring the user's 12- or 24-hour setting. It's not a countdown. A ticking countdown would use style: .timer, which the system animates with no push at all, which is how a timer-style activity stays live with zero server traffic.

• lineLimit(1) isn't decoration. The centre slot is a few dozen points wide, and an unbounded status string wraps and wrecks the layout. The bar lives in .bottom for the opposite reason: it's the only region wide enough.

• .font and .foregroundStyle on the HStack apply to both children through SwiftUI's environment, and a child's explicit modifier still wins over the inherited one, which is how CourierLabel overrides the colour on a reassignment.

• Int(progress * 100) truncates rather than rounds, so 0.999 would render as "99%". The scripted steps end on exactly 1.0 so it lands on 100, but server-computed progress would want .rounded().

• minimal is the presentation people forget. When another app's activity is also running, the island shrinks yours to a single circle. Skip it and your activity looks broken whenever a timer is going. keylineTint sets the glow the system draws around the whole island on update.

The Segmented Progress Bar

The capsule bar is an HStack of rounded rectangles. ContentState carries progress as a double rather than a step index, so the widget derives how many segments to fill.

private struct SegmentedProgressBar: View {
  let progress: Double
  var segments: Int = 7   // one capsule per delivery step

  // ContentState carries a 0...1 fraction, never a step index, so the bar has
  // to work backwards to a segment count. Keeping the wire format numeric means
  // the widget never needs to know what the seven steps are called.
  private var filled: Int {
    // Clamp first: a server that sends 1.4 must not paint 10 of 7 segments.
    let clamped = min(max(progress, 0), 1)
    // .rounded(.up) so a step that has merely BEGUN already lights its capsule.
    // progress 0.05 * 7 = 0.35 -> ceil -> 1 segment lit, not 0.
    // The outer min() guards the exact 1.0 case against a 8th segment.
    return min(segments, Int((clamped * Double(segments)).rounded(.up)))
  }

  var body: some View {
    HStack(spacing: 5) {
      // ForEach over a constant range, so `id: \.self` on the index is safe.
      ForEach(0..<segments, id: \.self) { i in
        RoundedRectangle(cornerRadius: 3, style: .continuous)
          // The only stateful decision in the whole view: lit, or track colour.
          .fill(i < filled ? brandOrange : trackGray)
          // Fixed height, no width: the HStack divides the width evenly, so the
          // same view fits the wide lock-screen card and the narrow island.
          .frame(height: 7)
      }
    }
  }
}

With progress values of 0.05, 0.15, 0.35, 0.55, 0.7, 0.85, 0.95, and 1.0, rounding progress * 7 upward fills one through seven segments in lockstep with the steps. The same view renders on the lock-screen card and inside the expanded island, so the component reads as one thing across surfaces.

The Reassignment Treatment

Reassignment is an in-place update: same activity id, same step, new courierName, and riderReassigned set to true. The courier row swaps its icon and copy.

// Shared by the lock-screen card and the expanded island, so a reassignment
// reads identically wherever the user happens to be looking.
private struct CourierLabel: View {
  let state: DeliveryAttributes.ContentState
  let compact: Bool   // true inside the island, where horizontal space is scarce

  var body: some View {
    // Both branches are driven purely by ContentState. No local state, because
    // the widget process does not live long enough to hold any.
    if state.riderReassigned {
      Label(
        // The island cannot fit "New rider · Tunde", so it drops the prefix and
        // leans on the swap icon plus the orange tint to carry the meaning.
        compact ? state.courierName : "New rider · \(state.courierName)",
        systemImage: "arrow.triangle.2.circlepath"
      )
      // An explicit style on the child overrides the .secondary the parent
      // HStack pushed down through the environment. This is what makes the
      // swapped rider the one thing on the card that draws the eye.
      .foregroundStyle(brandOrange).bold()
    } else {
      // Steady state: inherits the parent's caption font and secondary colour.
      Label(state.courierName, systemImage: "bicycle")
    }
  }
}

Advancing a step retires the badge. That's the whole feature, and the reason courierName had to leave the static half.

How to Bridge ActivityKit to JavaScript

Expo's Record type gives you type-safe bridging. Expo validates the JavaScript object against these fields before your function body runs.

// A Record is Expo's typed bridge struct. Every @Field is decoded out of the
// JS object BEFORE your function body runs, so a missing or wrong-typed key
// fails at the boundary with a clear error rather than deep inside Swift.
// The defaults are what a field falls back to when JS omits it.
struct DeliveryStateRecord: Record {
  @Field var status: String = ""
  @Field var progress: Double = 0
  @Field var etaEpochMillis: Double = 0   // Double, not Int: JS numbers are f64,
                                          // and epoch ms overflows Int32.
  @Field var stopsRemaining: Int = 0
  @Field var courierName: String = ""
  @Field var riderReassigned: Bool = false

  // The bridge type and the ActivityKit type are deliberately NOT the same
  // struct. This function is the single place the two vocabularies meet.
  @available(iOS 16.2, *)
  func toContentState() -> DeliveryAttributes.ContentState {
    DeliveryAttributes.ContentState(
      status: status,
      // Clamp at the boundary, so no downstream view has to defend itself.
      progress: min(max(progress, 0), 1),
      // JS speaks Unix milliseconds; Foundation.Date wants seconds. Divide once,
      // here, rather than scattering /1000 through the codebase.
      eta: Date(timeIntervalSince1970: etaEpochMillis / 1000),
      stopsRemaining: stopsRemaining,
      courierName: courierName,
      riderReassigned: riderReassigned
    )
  }
}

And the module itself:

AsyncFunction("startDelivery") { (info: DeliveryInfoRecord, state: DeliveryStateRecord) -> String in
  // Runtime OS guard: the module compiles against older targets, so this is
  // what stops it calling into a framework that isn't there.
  guard #available(iOS 16.2, *) else { throw LiveActivityUnsupportedException() }

  let activity = try Activity.request(
    attributes: DeliveryAttributes(orderId: info.orderId),                  // static half, set once
    content: ActivityContent(state: state.toContentState(), staleDate: nil), // dynamic half
    pushType: .token                                                        // ask APNs for a token
  )
  return activity.id   // the only handle JS gets, and the one it forgets on reload
}

AsyncFunction("updateDelivery") { (activityId: String, state: DeliveryStateRecord) in
  let activity = try Self.findActivity(id: activityId)
  // .update() replaces the whole ContentState. There is no partial-patch API.
  await activity.update(ActivityContent(state: state.toContentState(), staleDate: nil))
}

A few notes on the arguments, so they stay out of the code. AsyncFunction (rather than Function) is what makes the JS side a Promise, and Expo infers the rest of the signature from the parameter types.

staleDate: nil means the card is never marked stale. Pass a date and, once it passes, the system flips the activity's state so your widget can read context.isStale and render a degraded view, but it doesn't grey the card out for you.

And pushType: .token is what asks APNs for a per-activity token, where passing nil instead gives you a purely local activity that no server can update.

Notice findActivity. Activities are looked up fresh by id on every call rather than cached in a property, because activity handles live inside ActivityKit, not in your process. That distinction matters enormously, as the next section shows.

@available(iOS 16.2, *)
private static func findActivity(id: String) throws -> Activity<DeliveryAttributes> {
  // `Activity.activities` is a live, system-owned list. It survives an app
  // relaunch, a JS reload, and a process kill. Caching a handle in a Swift
  // property would not, which is precisely why this lookup runs every time.
  guard let activity = Activity<DeliveryAttributes>.activities.first(where: { $0.id == id }) else {
    // Reached when the user swiped the card away, or the activity aged out.
    throw ActivityNotFoundException(id)
  }
  return activity
}

Four iOS Gotchas That Cost Me an Evening Each

Each of these wasted an evening because the failure looked like a bug in my code when it was really a quirk of the platform. They share a shape, so I've written each one the same way: the symptom you see, why it happens, and what to do about it.

Gotcha 1: The Compact Island Looks Broken

You build the compact Dynamic Island, run the app, and it never appears.

This happens because the compact presentation is hidden while your own app is in the foreground. This is by design, but nothing tells you so, and I spent twenty minutes certain my layout was wrong.

To fix this, lock the device, or switch to another app, before you judge whether the island works. There's nothing to fix in the code.

Gotcha 2: An Old Activity Renders Nothing After a Rebuild

You change the widget, rebuild, and an activity that was already running goes blank. No error appears anywhere.

This happens when an activity is tied to the exact build that started it. Once you rebuild the widget extension, the running activity no longer matches the code on the device.

To fix this, after any change to the widget extension, end the stale activity and start a fresh one. Don't expect a warning to remind you.

Gotcha 3: Reinstalling Can Jam the System Daemon

Right after simctl install, your first activity refuses to render. Activity.activities says it's active, yet the screen shows nothing.

This happens because Live Activities are drawn by a background system process called chronod. A reinstall can leave it wedged: in my case it threw widgetDescriptorNotFound and logged internal errors, and no amount of ending and restarting the activity cleared it.

This is a fault in the daemon, not in your app, which is why the usual checks mislead you. Listing the extension with pluginkit -m shows it present and healthy while the daemon behind it is stuck.

To fix this, reboot the simulator with simctl shutdown && boot, then start a fresh activity.

Gotcha 4: Tapping the Card Opens an App That Forgot Everything

This is the subtle one, the most visible to users, and the reason for the next two code samples.

The user taps the live card to open your app. The app launches into an empty screen that insists nothing is being tracked, every control disabled, while the card sits right there on the lock screen still updating.

This happens because tapping the card cold-starts the app, which means your JavaScript begins from scratch. The activity id lived in React state, and that state died with the previous process.

The activity itself is completely fine: Activity.activities still lists it, and an APNs push to it still returns 200. (A dead activity returns 410, which makes a handy liveness probe.) The app simply forgot the id it needs to reconnect.

To fix this, stop treating your in-memory id as the source of truth, and ask the system what is running on launch. Expose the live activities to JavaScript.

AsyncFunction("getRunningActivities") { () -> [[String: Any]] in
  guard #available(iOS 16.2, *) else { return [] }

  // The system's list, populated even on a brand-new process. That is the point.
  return Activity<DeliveryAttributes>.activities.map { activity in
    self.observePushToken(of: activity)   // resubscribe: see note below
    let state = activity.content.state    // the live state, kept current by push
    return [
      "activityId": activity.id,                // the handle JS lost
      "orderId": activity.attributes.orderId,   // the static half
      "status": state.status,
      "progress": state.progress,
      "courierName": state.courierName,
      "riderReassigned": state.riderReassigned,
    ]
  }
}

That observePushToken call is the line everyone misses. The for await loop watching this activity's push token died with the previous process, so without resubscribing here the card recovers. But the server never learns the token again after a rotation, and pushes quietly stop landing.

Then rehydrate on mount, and again on every foreground, because a push that lands while you're backgrounded updates the widget without running your JavaScript at all. React Native's AppState gives you the hook.

useEffect(() => {
  const sync = () => {
    void DroptrackLive.getRunningActivities().then((running) => {
      const activity = running[0];
      if (!activity) return;   // nothing running: leave the empty state alone

      setActivityId(activity.activityId);   // this line re-enables the whole UI
      setRider({ name: activity.courierName, justReassigned: activity.riderReassigned });

      // The card carries a status string, not a step index. Guard the -1.
      const index = STEPS.findIndex((s) => s.status === activity.status);
      if (index >= 0) setStepIndex(index);
    });
  };

  sync();   // case 1: cold start (e.g. the user tapped the card and we launched)
  const sub = AppState.addEventListener("change", (s) => {
    if (s === "active") sync();   // case 2: resume from background
  });
  return () => sub.remove();
}, []);

The whole tracking interface is gated on activityId, so restoring it is what turns the app back on. Miss that one line and the app looks dead while the card is live on the lock screen.

The two call sites cover the two ways state goes stale. sync() on mount handles a cold start, and the AppState listener handles a resume, because the mount effect won't re-run and a push may have advanced the card while you were backgrounded without executing any JavaScript. The empty dependency array means this wiring is set up once, for the app's lifetime.

That last gotcha generalises into the sentence I wish I'd read first: Live Activities are owned by the system, not by your process. The API hands you an activity id and it's easy to assume the id is yours to keep. It's not. The activity outlives the variable, and the moment a user is most likely to open your app, by tapping the live card, is precisely the moment your in-memory copy of that id doesn't exist.

How to Drive iOS From a Server With APNs

Here's the payoff: updating the card while the app is fully force-quit. The API surface is almost insultingly small. You change one argument. Apple documents the flow in Starting and updating Live Activities with ActivityKit push notifications.

let activity = try Activity.request(
  attributes: attributes,
  content: ActivityContent(state: state.toContentState(), staleDate: nil),
  pushType: .token   // this was `nil`. That is the entire feature.
)

Task {
  for await tokenData in activity.pushTokenUpdates {
    let token = tokenData.map { String(format: "%02x", $0) }.joined()   // raw Data -> hex
    NSLog("[DropTrack] push token for %@: %@", activity.id, token)       // NSLog, so devicectl sees it
    self.sendEvent("onPushTokenReceived", ["activityId": activity.id, "token": token])
  }
}

pushTokenUpdates is an AsyncSequence, not a one-shot getter, which is why this is a for await loop and not a single read. Reading activity.pushToken right after request() reliably returns nil, because the token hasn't arrived from APNs yet, and it can also rotate mid-flight.

The token arrives as raw Data, so it's hexed before use. It's logged with NSLog rather than print because a standalone Release build has no Metro to receive console.log, and NSLog is what devicectl --console surfaces. And the token is per-activity, so it's keyed by activity id when handed to JS rather than stored globally.

Everything after that is plumbing, and two pieces of it fail without a single error message.

pushType: .token does nothing without the aps-environment entitlement. Activity.request still succeeds. Local updates still work. The token stream simply never yields. Nothing logs. Add the entitlement in app.json:

"ios": {
  "entitlements": {
    "aps-environment": "development",
    "com.apple.security.application-groups": ["group.com.fasarticle.droptrack"]
  }
}

Two notes on those values, since app.json can't carry comments. aps-environment set to development means your tokens are only valid against api.sandbox.push.apple.com. A shipping build needs production, and mixing the two produces an afternoon of BadDeviceToken. The application group is the shared container between the app and the widget extension, and both targets must carry the identical group id or shared reads silently return nothing.

Then verify that the entitlement survived signing, because an entitlement in your config isn't the same as an entitlement in your binary:

# Reads the entitlements actually baked into the signed .app.
# If aps-environment is absent here, the token stream will never yield,
# no matter what app.json says.
codesign -d --entitlements - --xml Build/Products/Release-iphoneos/DropTrack.app

The push token is per-activity, not per-device. It arrives asynchronously after request() returns, and the system can rotate it mid-flight. Consume the pushTokenUpdates async sequence. A single read of activity.pushToken immediately after request() is reliably nil. Every startDelivery mints a brand-new token. I verified that by starting two activities and comparing the hex.

How to Write an APNs Client From Scratch

You don't need a library. Two Node.js built-ins and about sixty lines will do it.

Sending one push comes down to three steps. First, sign a token that proves the request is really from you. Second, open a connection to Apple and attach a precise set of headers. Third, send the state you want the card to show. The rest of this section walks each step, then covers the two ways it fails silently.

One thing to get out of the way first: APNs speaks HTTP/2 only, so fetch() can't reach it. You need Node's node:http2 module, which is why this is written by hand rather than as a fetch call.

Step 1: Sign a Token That Proves Who You Are

APNs won't accept a push until you prove you own the app. You do that with an ES256 JSON Web Token, signed by the .p8 key you download from Apple, following Establishing a token-based connection to APNs. A JWT is just three base64url chunks joined by dots: a header, a claims object, and a signature over the first two.

import { createPrivateKey, sign } from "node:crypto";

const b64url = (buf) => Buffer.from(buf).toString("base64url");   // JWT uses base64url, not base64

export function mintJWT({ keyPath, keyId, teamId }) {
  const header = b64url(JSON.stringify({ alg: "ES256", kid: keyId }));   // kid: the 10-char key id
  const claims = b64url(JSON.stringify({ iss: teamId, iat: Math.floor(Date.now() / 1000) }));
  const signingInput = `${header}.${claims}`;   // a JWT signs header AND claims joined

  const signature = sign("sha256", Buffer.from(signingInput), {
    key: createPrivateKey(readFileSync(keyPath, "utf8")),
    dsaEncoding: "ieee-p1363",   // THE line. The default (DER) fails silently. See below.
  });

  return `${signingInput}.${b64url(signature)}`;
}

That one dsaEncoding line is the whole reason to write this by hand rather than trust a snippet off the internet.

Node signs in DER format by default, which wraps the signature's two halves in an envelope, but the JWT standard (RFC 7518) wants those two halves raw and joined. Use the wrong one and APNs answers 403 InvalidProviderToken, which reads like your key is bad and sends you re-downloading the .p8 for an hour, when the key was fine all along.

Two smaller details. kid is the ten-character key id (it is in the .p8 filename), and it tells APNs which of your registered keys should check the signature. And the iat timestamp can't be more than an hour old, per Apple, which also asks you to refresh it no more than once every 20 minutes, so cache the token instead of minting a fresh one for every push.

Step 2: Open the Connection and Send the Push

With the token in hand, open an HTTP/2 session to the APNs host and make one POST. The headers have to be exact, and the one people get wrong is the topic: it's your bundle id with .push-type.liveactivity appended, not the bundle id on its own.

// Pseudo-headers (":method", ":path") are HTTP/2's way of encoding the request
// line. `client` here is an http2 session opened against the APNs host.
const req = client.request({
  ":method": "POST",
  // The device token in the path is the PER-ACTIVITY token, not a device token
  // from UNUserNotificationCenter. Those are different values entirely.
  ":path": `/3/device/${token}`,
  authorization: `bearer ${jwt}`,   // lowercase "bearer" is what APNs expects

  // Live Activity pushes get a SUFFIXED topic. Send the bare bundle id and
  // APNs rejects the request outright.
  "apns-topic": `${bundleId}.push-type.liveactivity`,
  "apns-push-type": "liveactivity", // must match the topic suffix
  "apns-priority": "10",            // 10 = deliver immediately, 5 = opportunistic
  "apns-expiration": "0",           // 0 = do not retry a failed push
});

req.end(JSON.stringify({
  aps: {
    // Ordering guard, in SECONDS. APNs discards a push whose timestamp is older
    // than the last one it applied, so out-of-order retries cannot rewind the card.
    timestamp: Math.floor(Date.now() / 1000),
    event: "update",              // "update" mutates the card, "end" finishes it
    // Decoded straight into the widget's Codable ContentState. Field names and
    // types must match that struct EXACTLY. See the eta trap below.
    "content-state": contentState,
  },
}));

The body is small on purpose. timestamp is an ordering guard in seconds: APNs drops any push older than the last one it applied, so a delayed retry can't rewind the card. event is "update" to change the card or "end" to finish the activity, and there's no "start" here because push-to-start is a separate token that needs iOS 17.2. Everything else lives in content-state, which the widget decodes directly, and that's where the second silent failure hides, below.

How to Test Your Auth Without a Phone

This one trick saved me the most time, so do it before you involve a device at all. Send a push to the sandbox using a deliberately fake device token, and read the response code APNs gives back.

• 400 BadDeviceToken is the good outcome. It means your key, key id, team id, and JWT encoding are all correct, and APNs got far enough to look up the token and simply not find it. Your auth works.

• 403 InvalidProviderToken means the token itself is wrong, so the problem is your key or your signing, not the device.

That single request separates "my auth is broken" from "my token is broken" with no phone in the room. On this project it returned 400 on the first try, which told me the auth was solid and I should look elsewhere for the real bug. That was exactly the reassurance I needed.

The eta Trap: a 200 That Renders Nothing

This is the most instructive bug in the project, and it hit the moment a second code path reused a shared helper.

The same delivery data takes two different routes to the widget, and the routes expect two different shapes. The native module path carries etaEpochMillis (Unix milliseconds), and Swift converts it into a Date on the way through. The push path skips Swift entirely: the JSON content-state is decoded directly by the widget's Codable struct, which expects a field literally named eta, holding seconds since 2001 (Apple's reference date), and knows nothing about etaEpochMillis.

So if you reuse the native-bridge object as a push payload, APNs returns 200, iOS quietly throws the update away because it won't decode, and nothing is logged anywhere. The fix is to translate at the boundary, converting to the widget's shape only when building a push.

const APPLE_EPOCH_OFFSET = 978_307_200;   // seconds between 1970 and 2001

// The shape the WIDGET decodes, not the shape the native bridge takes.
function toContentState({ etaEpochMillis, ...rest }) {
  return {
    ...rest,
    eta: Math.floor(etaEpochMillis / 1000) - APPLE_EPOCH_OFFSET,   // ms->s, then rebase to 2001
  };
}

Two details make this work. Foundation.Date's reference point is 2001-01-01, not the Unix epoch, and Swift's Codable encodes a Date as seconds since that date, which is why the offset is subtracted. And destructuring etaEpochMillis out of rest is what drops the wrong key: leave it in and the widget's Codable init sees an unexpected field next to a missing eta, fails to decode, and the update vanishes after a 200.

The lesson generalises past the eta field. A 200 from APNs means only that Apple accepted your bytes, not that the card changed. Any content-state that fails to decode is discarded with no error on any surface, so confirm on the lock screen every time rather than trusting the status code.

Two last environment traps to note. Development-signed builds must talk to api.sandbox.push.apple.com, because the production host returns 400 BadDeviceToken for a sandbox token, which looks exactly like a malformed token and sends you debugging the wrong layer. And if you push frequently, add NSSupportsLiveActivitiesFrequentUpdates to your Info.plist, or the system budgets and drops your rapid pushes.

How to Test on Real Hardware

The simulator will lie to you about push, so at some point you need a real phone. Four things can trip you up there that the documentation never mentions. Here is each one with the fix.

Build in Release, not Debug

A Debug build expects to download its JavaScript from Metro over your local network. The build script bakes your Mac's network address into the app, so the moment the phone is on a different network, or simply not tethered to your Mac, it shows a red screen reading No script URL provided. There's no adb reverse equivalent on iOS to paper over this.

Build with --configuration Release instead, which embeds the JavaScript bundle inside the app. That's the more honest test anyway, because a Release build is the only way to fully force-quit the app and prove the push, not a live Metro connection, is doing the work.

Read Logs with devicectl, Not console.log

Once you drop Metro, console.log has nowhere to go. To read something like a push token off the device, you need the app's real standard output, and NSLog in the Swift code plus devicectl on the Mac is the reliable way to get it.

# --console            stream the app's stdout/stderr back to this terminal
# --terminate-existing kill a running copy first, so we catch launch-time logs
# --device             the COREDEVICE id (see the identifier trap below)
xcrun devicectl device process launch --console --terminate-existing \
  --device <coredevice-id> com.fasarticle.droptrack
# → [DropTrack] push token for 3095ACA0-...: 80875cb137590013a4c9...
#   ^ the hex string the dispatch server scrapes and pushes to

Know Which of the Two Device Identifiers You Need

The same phone has two identifiers, and the tools disagree about which they want. expo run:ios --device wants the hardware UDID, listed by xcrun xctrace list devices. The devicectl command above wants the CoreDevice identifier, listed by xcrun devicectl list devices.

Pass one where the other belongs and you get No device UDID or name matching, which reads as though the phone is unplugged. It's not, so check that you copied the right kind of id before you check the cable.

Handle Cold-start Deep Links, Not Just Live Ones

If your test driver opens the app with a deep link, note that devicectl ... --payload-url cold-starts the app, so the link arrives through Linking.getInitialURL() rather than the url event that the simulator's simctl openurl fires. A driver that listens only for the url event will appear to do nothing on a device. Handle both entry points.

With all four handled and the app confirmed fully quit, I drove three pushes through it (a status change, a rider reassignment, and an "arriving now"). Each one rendered on the lock screen and in the Dynamic Island.

One bonus comes free. Sign the Mac into the same Apple ID, and Continuity mirrors the same Live Activity onto the macOS menu bar, segmented bar, and all. One APNs push, three surfaces.

Why Android Has No ActivityKit

Android has no equivalent of ActivityKit, so there's no system-owned card and no framework keeping it up to date. What you have instead is an ordinary notification that you keep re-posting.

The trick is the notification id. Re-post under the same id and Android replaces the existing notification in place, which reads as an update. Post under a new id and you get a second notification instead. So the three lifecycle verbs map onto plain notification calls:

• start is notify() with a fresh id.

• update is notify() again under that same id.

• end is a final notify() with ongoing = false, followed by a delayed cancel().

That is the entire model. The catch is that everything iOS did for you (keeping the card current, recovering it after a restart, and updating it from a push) is now code you have to write.

The Trap That Shapes Everything: Android 16 is Two Releases in One

One versioning quirk shapes the whole Android side, so it's worth thirty seconds up front. "Android 16" ships as two releases that share a single API number:

Both report 36 because Build.VERSION.SDK_INT, the value your code reads to check the OS version, is a plain integer with no room for a .1. Two different releases, one number.

That collision is the entire source of the friction, and it leaves you three things to handle. None is hard once you know it is coming.

1. Compile through the backport, not the platform classes

The promotion methods (setRequestPromotedOngoing, setShortCriticalText, and the POST_PROMOTED_NOTIFICATIONS permission) live only in the 36.1 SDK, and React Native 0.86 compiles against base 36. Call them on the platform classes directly and the build fails with "no such method" before the app ever runs. One dependency fixes that:

dependencies {
  // NotificationCompat backports the 36.1 promotion APIs so they compile
  // against base SDK 36. Without this, ProgressStyle, setRequestPromotedOngoing
  // and setShortCriticalText are simply not on the classpath.
  implementation 'androidx.core:core-ktx:1.17.0'
}

Call the NotificationCompat versions rather than the platform ones. They compile against 36, take effect on a real 36.1 device, and are ignored on older releases, so one build is safe everywhere.

2. Read SDK_INT_FULL only when you truly need the minor version

A normal SDK_INT >= 36 check can't tell base 36 from 36.1, since both say 36. When you genuinely need to know which release you are on, Build.VERSION.SDK_INT_FULL carries the minor version, with named values in Build.VERSION_CODES_FULL. Because of rule 1 you rarely need it for the promotion request itself. You reach for it to decide what to show the user, or to guard the call in rule 3.

3. Wrap the capability check so it can't crash you

NotificationManager.canPostPromotedNotifications() reports whether the device will actually honour a promotion. Its reference lists it as added in API 36, so in theory it belongs to base Android 16, while the POST_PROMOTED_NOTIFICATIONS permission it depends on only arrived in 36.1. On the pre-QPR build I tested, though, the call was absent at runtime and threw. A capability probe should never be the thing that crashes your app, so wrap it and default to false:

Function("canPostPromotedNotifications") {
  // Function, not AsyncFunction: this is a cheap synchronous read, and the UI
  // wants it during the first render to decide what to disable.
  val manager = notificationManager ?: return@Function false

  // Cheapest gate first: below API 36 there is nothing to promote to.
  if (Build.VERSION.SDK_INT < 36) return@Function false

  // Docs list this as added in API 36, but on the pre-QPR build I tested it was
  // absent at runtime and threw. runCatching stops a capability probe from
  // crashing the app, defaulting to false when the call is unavailable.
  return@Function runCatching { manager.canPostPromotedNotifications() }.getOrDefault(false)
}

How to Build the Kotlin Side

Here's the notification builder. Notice how many of these lines are promotion requirements rather than cosmetics.

// Whole percent, clamped: a server that sends 1.4 must not become 140.
val progressPercent = (progress.coerceIn(0.0, 1.0) * 100).toInt()

val builder = NotificationCompat.Builder(ctx, CHANNEL_ID)
  .setSmallIcon(R.drawable.ic_delivery)
  .setContentTitle(status)                     // promotion REQUIRES a title
  .setContentText(courierLine(courierName, riderReassigned, stopsRemaining))
  .setSubText("Order $orderId")
  .setOngoing(ongoing)                         // promotion REQUIRES ongoing
  .setOnlyAlertOnce(true)                      // buzz once, then update silently
  .setColor(BRAND_ORANGE)                      // NOT setColorized: that disqualifies it
  .setShortCriticalText("$progressPercent%")   // text inside the status-bar chip
  .setRequestPromotedOngoing(ongoing)          // the promotion request itself

// `when` is the ETA in the header. It must be in the future (see note below).
if (etaEpochMillis > System.currentTimeMillis()) {
  builder.setWhen(etaEpochMillis.toLong()).setShowWhen(true)
}

if (Build.VERSION.SDK_INT >= 36) {
  val style = NotificationCompat.ProgressStyle()
    .setStyledByProgress(true)                 // colour follows the value
    .setProgress(progressPercent)
    .setProgressTrackerIcon(IconCompat.createWithResource(ctx, R.drawable.ic_delivery))
    .setProgressSegments(listOf(               // segments: spans of the bar
      NotificationCompat.ProgressStyle.Segment(100).setColor(BRAND_ORANGE)
    ))
    .setProgressPoints(listOf(                 // points: milestone dots on top
      NotificationCompat.ProgressStyle.Point(35).setColor(Color.WHITE)
    ))
  builder.setStyle(style)
} else {
  builder.setProgress(100, progressPercent, false)  // pre-16 fallback bar
}

val notification = builder.build()
if (Build.VERSION.SDK_INT >= 36) {
  Log.d(TAG, "hasPromotableCharacteristics=${notification.hasPromotableCharacteristics()}")
}
manager.notify(notificationIdFor(activityId), notification)   // stable id = update in place

Several of those lines carry non-obvious weight:

• setOnlyAlertOnce(true) stops each of the seven re-posts per delivery from buzzing the phone. Only the first notify() alerts, and the rest land silently.

• setColor versus setColorized: setColor tints the notification and is fine, but setColorized(true) would disqualify it from promotion. They're not interchangeable.

• setWhen must be a future timestamp, or the update can be skipped entirely. One UI renders it as an absolute clock time, Pixel as a relative countdown.

• ProgressStyle segments versus points: Segments are spans of the bar (one Segment(100) fills the whole thing, several draw the divided look). Points are milestone dots painted on top at a given percent.

• The else branch: Below API 36 the compat layer has no ProgressStyle at all, so it falls back to the classic determinate bar.

Two runtime checks are your only debugging signal, and they answer different questions:

• hasPromotableCharacteristics(), logged after build(), tells you whether you satisfied every promotion precondition. It says nothing about the device.

• canPostPromotedNotifications() tells you whether the device will honour the request. The two genuinely disagree on Samsung, which is why you need both.

And notificationIdFor() derives a stable int from the activity id, so a re-post under the same id updates the card in place. A different id would post a second notification, the classic "why do I have seven delivery cards" bug.

Promotion eligibility is all-or-nothing, and silent. It flips true only when every condition holds: notification permission, setRequestPromotedOngoing(true), ongoing, a content title, an allowed style, importance above MIN, and not colorized. Miss one and you get an ordinary notification with no explanation. Log hasPromotableCharacteristics() after every build(), and surface canPostPromotedNotifications() in your development interface. Those two booleans are the only debugging signal the platform gives you.

Note also that custom RemoteViews aren't allowed for promoted notifications. You get the ProgressStyle template, or you get no promotion. That's the biggest design constraint compared with iOS, where you write arbitrary SwiftUI.

When it does promote on a real API 36.1 build, you get the chip and the elevated lock-screen slot.

The same APK behaves three different ways:

How to Drive Android From a Server With FCM

This is the deepest difference between the two platforms.

On iOS, APNs updates the widget through the system, and your app code never runs. On Android, there's no system-managed remote update. A data-only FCM message wakes a FirebaseMessagingService, and your code re-posts the notification. The app is the updater, even from the background.

// Registered in the manifest, so Android can instantiate it WITHOUT your
// Activity, your React context, or your module ever existing.
class DroptrackFcmService : FirebaseMessagingService() {

  // Called on install, and again whenever FCM rotates the token. Never assume
  // the token you saw at startup is still valid.
  override fun onNewToken(token: String) {
    Log.i(DeliveryNotifier.TAG, "[DropTrack] fcm token: $token")
  }

  override fun onMessageReceived(message: RemoteMessage) {
    // FCM `data` is always Map<String, String>. Every number and boolean was
    // stringified on the way out and has to be parsed back here.
    val d = message.data

    // No activityId means we cannot address a notification. Bail rather than
    // guess: posting under the wrong id creates a duplicate card.
    val activityId = d["activityId"] ?: return
    val event = d["event"] ?: "update"

    // This service is a SEPARATE entry point. It cannot see the module's
    // in-memory state, so every field must come from the payload, and every
    // parse must be defensive, because a crash here kills the update.
    DeliveryNotifier.ensureChannel(this)   // the process may be brand new
    DeliveryNotifier.post(
      ctx = this,
      activityId = activityId,
      // Every `?:` below is load-bearing. toDoubleOrNull returns null rather
      // than throwing on malformed input, so a bad payload degrades the card
      // instead of killing the service.
      orderId = d["orderId"] ?: "",
      status = d["status"] ?: "",
      progress = d["progress"]?.toDoubleOrNull() ?: 0.0,
      etaEpochMillis = d["etaEpochMillis"]?.toDoubleOrNull() ?: 0.0,
      stopsRemaining = d["stopsRemaining"]?.toIntOrNull() ?: 0,
      courierName = d["courierName"] ?: "",
      riderReassigned = d["riderReassigned"]?.toBoolean() ?: false,
      // "end" clears `ongoing`, which lets the user finally swipe the card away.
      ongoing = event != "end",
    )
  }
}

That "separate entry point" comment is the crux, so it's worth slowing down on. Android can start this service on its own to deliver a push, at a moment when the rest of your app isn't running. There's no React, no module instance, and none of the objects the app was holding in memory. So the push handler can't look up "what delivery is in progress" from app state, because there's no app state to look at. Everything it needs has to come from the push payload itself.

That forces a specific design. The code that builds a notification can't live inside the app and read app state. It has to be standalone code that takes plain values and nothing else.

So I pulled all of it into a shared DeliveryNotifier object, and both paths call it: the in-app path when JavaScript drives an update, and the push path when the service does. Because they run the same builder from the same inputs, they produce an identical notification, and that shared builder is the single most important structural change on the Android side.

The Four Rules of Android Push

Four things have to be right, or the push half quietly fails. In short: send the right kind of message, authenticate the harder way, read the error codes correctly, and wire the plugin through prebuild. Each one in full below.

Rule 1: send a data-only message, never one with a notification block

This is the rule that catches everyone. A message with a notification block, while the app is backgrounded or killed, is handled by the system tray, and your onMessageReceived code never runs, so the card never updates. Only a data-only message (no notification block) reaches your code in the background.

Firebase documents this in Receive messages in an Android app. Send data-only, and set android.priority to high so the app wakes promptly.

Rule 2: authenticate with a service-account token, not a static key

FCM v1 auth is heavier than APNs, with no one-shot .p8. You mint an RS256 JWT from a service account, exchange it for a short-lived OAuth access token, and send that access token as a bearer credential to projects.messages.send. The consolation is that FCM v1 is plain HTTPS, so fetch() works.

// `sa` is the parsed service-account JSON from Firebase. This JWT is not the
// credential you send to FCM; it is the one you trade for a short-lived token.
export function buildAuthJWT(sa) {
  const now = Math.floor(Date.now() / 1000);
  const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));  // RSA key, so no ieee-p1363 trap
  const claims = b64url(JSON.stringify({
    iss: sa.client_email,
    scope: "https://www.googleapis.com/auth/firebase.messaging",  // exact scope, or every send 403s
    aud: sa.token_uri,        // the JWT is FOR Google's token endpoint
    iat: now,
    exp: now + 3600,          // one hour, Google's maximum
  }));
  const signingInput = `${header}.${claims}`;
  const sig = createSign("RSA-SHA256").update(signingInput).sign(sa.private_key);
  return `${signingInput}.${b64url(sig)}`;
}

export async function sendDataMessage({ token, data, sa }) {
  const accessToken = await getAccessToken(sa);   // trades the JWT for a token; cache the result
  const res = await fetch(
    `https://fcm.googleapis.com/v1/projects/${sa.project_id}/messages:send`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        message: {
          token,                        // per-DEVICE token (APNs is per-activity)
          data,                         // note: NO `notification` key (see below)
          android: { priority: "high" },
        },
      }),
    }
  );
  const body = await res.json().catch(() => ({}));   // never throw on a bad error body
  return { status: res.status, reason: body?.error?.status ?? null };
}

The design turns on two absences and one indirection. The indirection is the token exchange. Unlike APNs, where the JWT is the credential, here you POST the JWT to Google's token endpoint, get back a short-lived access token, and send that, so cache it rather than re-minting per message.

The first absence is any notification key in the body, which is deliberate and covered next. The second is high priority over normal, because normal may be held until the device leaves Doze, by which time the delivery has finished.

On the response, 404 UNREGISTERED means drop the token while 400 INVALID_ARGUMENT means it was never a token. The caller needs to tell those apart, so the reason string is returned rather than swallowed.

FCM data values are a map of string to string, so everything is stringified on the way out and parsed on the way in. Unlike iOS, there's no silent shape mismatch, because you wrote the parser. But your parser must never throw.

Rule 3: treat 400 and 404 as different failures

FCM splits two cases that APNs collapses. A malformed token returns 400 INVALID_ARGUMENT, while a well-formed but unregistered token returns 404 UNREGISTERED (the full list is in the FCM ErrorCode reference).

APNs reports both as BadDeviceToken. This matters for the fake-token auth probe from the iOS section: on FCM a fake token gives INVALID_ARGUMENT, not UNREGISTERED. Either one still proves your auth works, since a bad service account fails earlier with 401 or 403. I wrote my probe expecting UNREGISTERED, and correcting the test is how I learned the distinction.

Rule 4: wire the google-services plugin through prebuild

The google-services plugin is what reads your Firebase config into the build. Because Continuous Native Generation regenerates the android folder on every prebuild, a config plugin has to re-place google-services.json and re-add the Gradle wiring each time, or the setting is lost on the next prebuild.

// plugins/withAndroidFcm.js
function withGoogleServicesJson(config) {
  // withDangerousMod runs arbitrary filesystem work during prebuild. It is
  // "dangerous" because nothing validates the result. It is also the only way
  // to place a file the Gradle plugin expects to already exist.
  return withDangerousMod(config, ["android", (cfg) => {
    // Kept at the repo root, gitignored, and copied in on every prebuild.
    const src = path.join(cfg.modRequest.projectRoot, "google-services.json");
    // Must land in android/app/, where the google-services plugin looks for it.
    const dest = path.join(cfg.modRequest.platformProjectRoot, "app", "google-services.json");

    // Fail loudly at prebuild. Without this the build succeeds, the app starts,
    // and FCM initialisation quietly no-ops at runtime.
    if (!fs.existsSync(src)) {
      throw new Error("[withAndroidFcm] google-services.json not found at project root");
    }

    fs.copyFileSync(src, dest);
    return cfg;
  }]);
}
// plus withProjectBuildGradle for the classpath,
// and withAppBuildGradle to apply the plugin.

Have it throw when the file is missing. Failing fast at prebuild beats a mystery at runtime.

The Honest Caveat

A data message can be dropped under Doze or after a force-kill. An iOS Live Activity is system-owned and updates regardless. High priority helps. This is a platform limitation to document rather than engineer around. Test with the app backgrounded, not swiped away, and be honest with your product team about the difference.

Three UX Gaps the Naïve Implementation Leaves

Because your code owns the Android side, you inherit three responsibilities that iOS handles quietly for you. I shipped all three only after hitting each one in testing.

Tapping the Notification Does Nothing

NotificationCompat posts happily, but with no setContentIntent(PendingIntent) there is no tap target, so Android just expands and collapses the notification. Nothing in the documentation shouts this at you.

private fun launchIntent(ctx: Context, activityId: String): PendingIntent? {
  // Ask the package manager for our own launcher intent, rather than naming
  // MainActivity. Under Expo's Continuous Native Generation that class name is
  // generated, so hardcoding it breaks on the next prebuild.
  val intent = ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
    // SINGLE_TOP: reuse the existing task instead of stacking a second copy.
    // CLEAR_TOP: drop anything above it, so the user lands on the tracking screen.
    ?.apply { flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP }
    ?: return null

  return PendingIntent.getActivity(
    ctx,
    // The request code. Keyed per activity so two concurrent deliveries get
    // two distinct PendingIntents rather than silently sharing one.
    notificationIdFor(activityId),
    intent,
    // FLAG_IMMUTABLE is mandatory on Android 12+; omit it and this throws.
    // FLAG_UPDATE_CURRENT refreshes the extras of the existing PendingIntent
    // rather than handing back a stale one from an earlier delivery.
    PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
  )
}

FLAG_IMMUTABLE is required on Android 12 and later. Verify the result with adb shell dumpsys notification, which should show contentIntent=PendingIntent{... startActivity}.

A Push Updates the Notification But Not Your Interface

The service is a separate entry point from your JavaScript state, so a push arriving while the app is open leaves the app showing a stale step. The fix is a static bridge, set when a module instance exists and cleared when it does not.

companion object {
  // Static, because the FCM service cannot reach a module INSTANCE. @Volatile
  // because the service runs on a different thread than the one that sets this.
  // Nullable because, most of the time, there is no live module to emit into.
  @Volatile private var pushEmitter: ((Map<String, String>) -> Unit)? = null

  // Safe to call from anywhere. The `?.` is the entire "is the app alive?" check.
  fun emitPush(data: Map<String, String>) { pushEmitter?.invoke(data) }
}

override fun definition() = ModuleDefinition {
  // Declares the events JS may subscribe to. Emitting an undeclared name throws.
  Events("onFcmTokenReceived", "onDeliveryPush")

  // Register the bridge when a module instance exists...
  OnCreate  { pushEmitter = { data -> sendEvent("onDeliveryPush", data) } }
  // ...and tear it down when it does not. Skip this and you leak a closure
  // holding a dead React context, then crash on the next push.
  OnDestroy { pushEmitter = null }
  // ...
}

The service calls DroptrackLiveModule.emitPush(d) after notify(). It does nothing when the app is dead, in which case the notification still updates and there's simply nothing to sync. This is the Android analogue of the iOS foreground resync.

A Cold-started App Comes Up Empty

iOS recovers from Activity.activities. Android has no such store, so a killed app reopened by tapping its own notification shows "Not tracking". Persist the delivery to SharedPreferences on every notify(), then read it back.

// Same JS name as the iOS implementation, so App.tsx never branches on platform.
AsyncFunction("getRunningActivities") {
  val ctx = context ?: return@AsyncFunction emptyList<Map<String, Any?>>()

  // Our stand-in for iOS's Activity.activities: the record written on notify().
  val active = DeliveryNotifier.activeDelivery(ctx)
    ?: return@AsyncFunction emptyList<Map<String, Any?>>()
  val activityId = active["activityId"] as String

  // Phantom guard: trust the system's notification list over our own record.
  if (!DeliveryNotifier.isActive(ctx, activityId)) {
    DeliveryNotifier.clear(ctx)
    return@AsyncFunction emptyList<Map<String, Any?>>()
  }

  // Repopulate the per-process map, or a later update/end throws after cold start.
  deliveries[activityId] = DeliveryInfoRecord().apply { orderId = active["orderId"] as String }
  return@AsyncFunction listOf(active)
}

Two subtleties here I only found by breaking them. Guard the rehydration with getActiveNotifications(). Without that check, a stale record produces an uncancellable phantom delivery whose Cancel button throws ActivityNotFoundException. And make endDelivery forgiving. If the activity isn't in the in-memory map because you cold-started, still cancel the notification and clear the state rather than throwing. Tearing something down should never fail because you've forgotten about it.

Because the resync effect in App.tsx is cross-platform, implementing Android's getRunningActivities() lights up the existing cold-start path with no JavaScript changes. That's the payoff of keeping one API across two backends.

How to Script the Simulators and Devices

Two small tools saved more time than any feature.

The iOS simulator has no scriptable tap. There's no uiautomator equivalent, and synthetic clicks need macOS accessibility grants. So I added a development-only deep-link driver, fifteen lines, stripped from release builds.

useEffect(() => {
  // Dead code in release builds: the bundler strips the whole effect body.
  if (!__DEV__) return;

  // "droptrack://drive/next" -> "next" -> call actions.next().
  // actionsRef, not actions: the listener is registered once, so a plain
  // closure would capture the first render's handlers forever.
  const run = (url: string) => actionsRef.current[url.split("/").pop() ?? ""]?.();

  // Case 1: app already running. simctl openurl fires this event.
  const sub = Linking.addEventListener("url", ({ url }) => run(url));

  // Case 2: devicectl --payload-url COLD-STARTS the app: the URL arrives as the
  // initial URL and never fires the 'url' event. Handle both or device
  // automation silently does nothing while simulator automation works.
  void Linking.getInitialURL().then((url) => url && run(url));

  return () => sub.remove();
}, []);

# Drives the running app one step forward, with no tap and no accessibility grant.
xcrun simctl openurl booted "com.fasarticle.droptrack://drive/next"

For the push half I built a small web dispatcher. A browser cannot reach APNs or FCM, because of HTTP/2, missing cross-origin headers, and the fact that signing keys must never leave the server. So it talks to a zero-dependency local Node.js signing server that scrapes push tokens off the device console, streams them to the browser with server-sent events, and sends to whichever platform you select.

iPhone  --NSLog--> devicectl --console --+
Android --Log.i--> adb logcat -----------+
                                         | scrape
browser <--SSE /events-- dispatch-server (127.0.0.1:8787)
   \--POST /push--------> apns.mjs / fcm.mjs --> APNs / FCM --> device

Pick a step, pick a courier, and press one button. It turns a two-minute test into a ten-second one, and it made the Samsung investigation below possible at all.

How iOS and Android Compare

The Samsung Reality Check

Version numbers lie, and Samsung is where they lie loudest. I tested by hand across three real Galaxy devices using Samsung Remote Test Lab, whose Remote Debug Bridge turns out to be a full local adb tunnel to a phone in Korea. The entire emulator automation playbook (granting permissions, tapping, taking screenshots, and reading dumpsys) works unchanged against remote hardware.

Here's what the same unmodified APK did on each:

Two findings come out of that table.

1. On the base-36 device, the two capability checks disagree

The S25 Ultra runs base 36, which has no promotion pipeline, so nothing promotes. But hasPromotableCharacteristics() returns true there (Samsung backported some framework pieces) while canPostPromotedNotifications() returns false. A base-36 Pixel emulator returns false for both. So you can't infer one check from the other. Detect both at runtime, and trust canPostPromotedNotifications() for whether promotion will actually happen.

2. On the 36.1 devices, promotion works but only partly

Both the S26 Ultra and the A37 genuinely grant FLAG_PROMOTED_ONGOING to the unmodified APK, which you can confirm in dumpsys. You get top-of-shade pinning and the status-bar icon. You do not get the chip pill, the lock-screen card, or a Now Bar entry, even though the promotion succeeded.

That "only partly" was the mystery, until I found where the missing surfaces went. In Settings, under Lock screen and Always On Display, there's a page called Live notifications (searchable as "live notification", notably not as "Now bar"). It promises exactly the surfaces I was missing: the lock screen, the status bar, and the top of the notification panel, illustrated with the Now Bar pill. And directly below that promise sits a fixed, six-app allowlist: Audio broadcast, Emergency sharing, Google Finance, Maps, Media player, and Sports from Google.

DropTrack isn't on that list. Yet its promoted delivery was live on that very device at that very second, and the page's own "Not seeing Live notifications?" checklist (three notification permissions) was fully satisfied. The feature was working. Samsung simply doesn't offer its best surfaces to apps outside the six.

So the screenshot-backed conclusion for these units is this: One UI 8.5 accepts Google's promotion contract and ships the minor surfaces to any app, but reserves the headline ones for a hardcoded list. This reflects those specific devices at the time of testing, and Samsung may change it.

It leaves the three platforms in three different places. Apple offers a public API on every device. Google offers a public API on its own hardware. Samsung offers the framework to everyone but keeps the best stage by invitation.

The Demo Repository

Everything in this handbook is one working project, DropTrack, released under the MIT licence. It's not a snippet dump. It's a single React Native app whose one delivery-tracking feature reaches down through five layers. The point of reading it is to see how those layers connect rather than how any one of them looks in isolation.

Here's what lives in the repo, layer by layer:

A few things make it worth cloning rather than skimming:

• It genuinely runs on all three surfaces: The same DeliveryState object drives a SwiftUI Live Activity, an Android promoted notification, and a web console, so you can watch one API produce three very different results.

• The push clients have no dependencies: scripts/apns.mjs and scripts/fcm.mjs use only Node built-ins, so you can read the entire APNs and FCM path end to end without unpacking a library. Both have small test files next to them.

• Every gotcha in this article is written up in GOTCHAS.md: The long checklist that used to live in this section now lives there, next to the code it refers to, alongside DEVLOG.md (how the build unfolded) and ARTICLE_NOTES.md.

• It's safe to fork: The Firebase service account, the google-services.json, and the APNs .p8 key are all gitignored, so nothing sensitive is in the history. The README.md lists exactly which of those you supply to run the push phase yourself.

Clone it, run the app on a simulator, open the web console, and push an update to your own device. That loop is the fastest way to make everything above concrete.

What to Know Before You Start

The product feature is identical, and the platform contracts are opposites. iOS gives you a system-owned widget and updates it for you. Android gives you a notification and makes you the update engine, down to re-posting it from a background service on every message. Design your module's seam accordingly. The same three-function API can hide wildly different machinery, and that is exactly what a good native module is for.

The silent failures are the tax. Almost every hard bug in this project, from the mismatched widget struct, to the missing entitlement, the wrong epoch, the un-promoted notification, and the notification-instead-of-data message, fails with zero errors. So instrument aggressively. Log promotable characteristics. Verify entitlements survived signing. Probe push auth with fake tokens before you involve a device. Always confirm on the real surface rather than trusting a 200.

Version numbers lie, so detect features instead. Android 16 is two releases. Samsung's Android 16 is a third. canPostPromotedNotifications() and hasPromotableCharacteristics() can disagree on the same build. Check both at runtime, and never infer one from the other.

The system owns the activity, not your process. On iOS the activity outlives your variable, your React state, and your process. On Android the notification outlives your process too, but nothing recovers it for you. Both platforms punish you for assuming the id in your useState is the source of truth.

Conclusion

You now have a complete picture of both platforms. You built one TypeScript API over two native backends, a SwiftUI widget with four presentations, a Kotlin notification that satisfies Android's promotion contract, and two push clients written from scratch with no libraries. You also know the failure modes that produce no error message, which is most of them.

Three things are worth exploring next:

1. Push-to-start, on iOS 17.2 and later. You can start a Live Activity from a push, with no app launch at all. The token is per-app rather than per-activity, which rewrites the token plumbing described above.

2. Broadcast channels, on iOS 18. One push updates an activity for many users, which suits live scores. Every push in this handbook targets a single token.

3. An Android foreground service. It narrows the Doze and force-kill delivery gap. It won't close it, but it makes long-running deliveries more durable than a bare data message.

The interesting part was never Activity.request(). It was everything the two platforms decline to tell you when you get it wrong.

Sources and Further Reading

Apple, ActivityKit and APNs:

• ActivityKit and ActivityAttributes

• Displaying live data with Live Activities

• Starting and updating Live Activities with ActivityKit push notifications

• Live Activities, Human Interface Guidelines

• The aps-environment entitlement

• Sending notification requests to APNs, Establishing a token-based connection to APNs, and Handling notification responses from APNs

• Date, and the 2001 reference date

• WidgetKit

Android and Firebase:

• Progress-centric notifications in Android 16 and Android 16 overview

• Notification.ProgressStyle and NotificationCompat.ProgressStyle

• NotificationCompat.Builder, where setRequestPromotedOngoing and setShortCriticalText are backported

• Build.VERSION.SDK_INT_FULL and Build.VERSION_CODES_FULL, the 36 versus 36.1 distinction

• NotificationManager.canPostPromotedNotifications(), Notification.hasPromotableCharacteristics(), and getActiveNotifications()

• PendingIntent.FLAG_IMMUTABLE and SharedPreferences

• androidx.core release notes

• Doze and App Standby

• Firebase Cloud Messaging, Receive messages in an Android app, FirebaseMessagingService, projects.messages.send, and the FCM ErrorCode reference

• Using OAuth 2.0 for server to server applications and the google-services Gradle plugin

Apps that document their own Live Activity, cited in "Where You Have Already Seen This Feature":

• Chowdeck, ESPN, MLB, FotMob, CARROT Weather, and Structured, all via their App Store listings

• Flighty's Live Activities help page

• Apple Sports, following games in real time

• MacRumors on Uber Eats, May 2023 and DoorDash, December 2023

• MacStories, the iOS 16.1 Live Activities roundup

React Native, Expo, and tooling:

• Expo Modules API overview and the module API reference

• Expo config plugins and Continuous Native Generation

• @bacons/apple-targets, which generates the widget extension

• expo-live-activity, the packaged alternative

• Notifee, archived, and its last release @notifee/react-native@9.1.8

• React Native AppState and Linking

• Node.js crypto and http2

• RFC 7519, JSON Web Token and RFC 7518, JSON Web Algorithms, which define the ES256 and RS256 signature formats

• Samsung Remote Test Lab

Naturally, my first instinct was to look at cloud providers. While services like ElevenLabs offer incredible voice quality, I quickly ran the numbers. Between the API pricing, token consumption for lengthy tutoring sessions, and the sheer volume of users I anticipated, the math got ugly very quickly. Relying on a paid API for every single sentence spoken within the app simply wasn't sustainable for an independent developer.

If you’re about to ask, "How far did you get with QuizRope?", well honestly, I straight-up gave up on the project back then because I couldn't find a sane, affordable solution for the TTS feature.

Beyond the prohibitive cost, there was the latency. Waiting for a server to process a prompt, generate the audio, and stream it back down to a mobile device completely breaks the conversational illusion. And worst of all, it meant every question a student asked would be beamed to a third-party server.

That frustration became the catalyst for my search to find a reliable, offline, and completely zero-cost solution.

In this article, we’re going to build a React Native application that performs high-fidelity Text-to-Speech (TTS) completely offline using your device's own hardware.

If you haven't set up your environment or need a refresher on local inference fundamentals, I highly recommend reading my previous article, How to Run a Local LLM Offline in React Native with QVAC, where I cover project initialization, prebuilding, and native hardware dependencies.

This guide assumes you already have a project with the QVAC SDK configured and ready to run on a physical device.

Table of Contents

• Prerequisites

• What is QVAC?

• The Architecture Supported by QVAC

• The Inference Pipeline

• Environment and Dependency Config

• The Audio Utility Packaging

• Complete Implementation

• Codebase Breakdown

• Conclusion

• Resources and Further Reading

Prerequisites

To get the most out of this article, you should have a solid foundation in modern web and mobile development:

• JavaScript/TypeScript & React: Familiarity with React concepts and hooks, especially useState, useEffect, and useRef.

• React Native & Expo: Basic understanding of layout structures (such as View, ScrollView, TextInput) and styling conventions.

• Asynchronous JavaScript & Binary Buffers: Experience with async/await, Promises, and basic manipulation of arrays like Int16Array or Buffer.

• Development Build Environment: Familiarity with running local development compilation commands, specifically npx expo prebuild to build native iOS and Android modules.

• Physical Mobile Device: Because local machine learning models leverage device-specific hardware acceleration and native optimizations, the QVAC SDK doesn't support simulator environments. You must have a physical iOS or Android testing device with Developer Mode enabled.

What is QVAC?

To help you follow along more effectively, let’s establish what QVAC is and why it exists.

Developed by Tether, QVAC is a local-first AI SDK designed for building cross-platform, peer-to-peer (P2P) applications and systems.

Many mobile applications that utilize Large Language Models (LLMs) or Text-to-Speech (TTS) engines rely on network requests to cloud-hosted APIs (such as OpenAI or ElevenLabs). While convenient, this model introduces dependencies on network connectivity, recurring API usage fees, and transmission of user data to third-party servers.

QVAC provides an alternative by executing AI models directly on the client device. This local-first architecture offers several practical advantages:

• Local-first execution: Runs inference directly on the client hardware, eliminating the need for external APIs or active internet connections.

• Peer-to-peer (P2P) support: Allows distributing inference tasks across local networks, helping coordinate workloads without centralized servers.

• Cross-platform compatibility: Provides a single JavaScript/TypeScript interface that works consistently across different hardware and runtime environments.

• Unified capabilities: Exposes text generation, transcription, image generation, and speech synthesis within a single package.

Key Concepts for On-Device Inference

To understand how QVAC runs on a mobile device, we must keep a few key concepts in mind:

• On-Device Inference: Running model calculations locally. Rather than relying on a single engine, QVAC supports multiple specialized local inference backends depending on the task (such as llama.cpp for text, whisper.cpp for transcription, or custom diffusion backends for image generation). Under the hood, these engines memory-map quantized model weights directly into the device's RAM and run calculations using native GPU hardware acceleration.

• Quantization (GGUF format): A mathematical optimization technique that compresses the model's weights (for example, from a standard 16-bit floating-point precision down to 4-bit or 8-bit integers). This makes it possible for models to fit into the memory constraints of consumer mobile hardware while keeping output quality high.

• KV (Key-Value) Cache: A memory area that stores calculated states of previous tokens so the model doesn't have to re-evaluate the entire context window with every word or token it generates.

The Architecture Supported by QVAC

Before writing code, it's crucial to understand what's actually happening under the hood. To handle local execution without melting your device, the QVAC SDK manages the hardware binding and model lifecycle while hooking into optimized, community-maintained GGML inference backends.

Instead of a one-size-fits-all approach, the QVAC SDK supports two distinctly different neural architectures for speech synthesis. Depending on your application's needs — whether you want instant voice cloning or ultra-high-fidelity pre-trained voices — you'll choose between Chatterbox and Supertonic.

1. The Chatterbox Engine

Chatterbox is built on a transformer-based language model architecture. It treats audio generation similarly to how an LLM predicts the next word in a sentence, but instead, it predicts discrete acoustic tokens.

Because of this architecture, Chatterbox excels at zero-shot voice cloning. Instead of relying purely on pre-baked voices, you can pass an optional referenceAudioSrc (a short WAV file of someone speaking) alongside your text. The transformer analyzes the reference audio's acoustic properties and generates a cloned voice based on those features.

2. The Supertonic Engine

Supertonic takes a completely different approach, utilizing diffusion-based latent denoising — the same fundamental architecture used by AI image generators like Stable Diffusion, but applied to audio.

It starts with pure digital noise and iteratively refines it into a 44.1 kHz high-fidelity speech waveform based on the text prompt. Supertonic uses a single, unified GGUF file rather than a split model. Instead of dynamic voice cloning, it relies on highly optimized, pre-trained voice styles (for example, voice: "F1" or voice: "M1") baked directly into the model. This makes it incredibly efficient for generating crystal-clear, studio-quality speech when you don't need dynamic cloning capabilities.

For this tutorial, we'll use Supertonic. It yields fantastic results out of the box and avoids the complexity of loading multiple companion files.

The Inference Pipeline

To visualize how we interact with these engines in our codebase, think of local TTS (Text to Speech) as running a virtual recording studio right in your phone's memory:

1. Hiring the actor (loading the model): We map the compressed GGUF file directly into the device's RAM or GPU VRAM.

2. Handing over the script (text input): We pass plain text to the loaded engine.

3. The performance (inference): The engine reads the text and mathematically predicts the sound waves. Crucially, the AI doesn't emit a finished audio file. Instead, it outputs raw digital sound waves known as PCM samples.

4. Packaging the audio: Because a raw list of numbers can't be played by standard media players, we must manually wrap the PCM data in a standard WAV header.

5. Closing the studio (unloading): Because speech synthesis is memory-intensive and maintains a persistent state, the model is cleared from RAM to free up resources and flush its context.

Environment and Dependency Config

Before we jump into the codebase, there's a crucial dependency setup to keep in mind if your project uses the pnpm package manager.

Because QVAC plugins rely on transitive native peer dependencies, strict package managers like pnpm will lock these dependencies down inside hidden .pnpm subfolders.

To ensure the QVAC native bundler (bare-pack) can resolve your worker plugins correctly at build time, create a .npmrc file in the root of your project:

shamefully-hoist=true

IMPORTANT: After creating this file, you must run a clean dependency install (pnpm install). This ensures a flat layout in your root node_modules so that all QVAC-specific helper packages are resolved properly during your local npx expo prebuild compilation step.

The Audio Utility Packaging

Because QVAC outputs raw PCM arrays, we need to construct a valid WAV file in memory and write it to the device's storage before the native audio player can play it.

To achieve this, let's create a utility module inside src/lib/utils.ts to build the required WAV header, convert raw audio samples into a binary buffer, and write it to local storage.

import { Buffer } from "buffer";
import * as FileSystem from "expo-file-system/legacy";

/**
 * Creates a WAV header for 16-bit PCM audio
 */
export function createWavHeader(
  dataLength: number,
  sampleRate: number,
): Buffer {
  const buffer = Buffer.alloc(44);
  const channels = 1; // Mono
  const byteRate = sampleRate * channels * 2; // 16-bit audio
  const blockAlign = channels * 2;

  buffer.write("RIFF", 0);
  buffer.writeUInt32LE(36 + dataLength, 4);
  buffer.write("WAVE", 8);
  buffer.write("fmt ", 12);
  buffer.writeUInt32LE(16, 16); // Subchunk1Size
  buffer.writeUInt16LE(1, 20); // AudioFormat (PCM)
  buffer.writeUInt16LE(channels, 22);
  buffer.writeUInt32LE(sampleRate, 24);
  buffer.writeUInt32LE(byteRate, 28);
  buffer.writeUInt16LE(blockAlign, 32);
  buffer.writeUInt16LE(16, 34); // BitsPerSample
  buffer.write("data", 36);
  buffer.writeUInt32LE(dataLength, 40);

  return buffer;
}

/**
 * Converts the raw Int16Array samples from QVAC to a binary Buffer
 */
export function int16ArrayToBuffer(int16Array: Int16Array): Buffer {
  const buffer = Buffer.alloc(int16Array.length * 2);
  for (let i = 0; i < int16Array.length; i++) {
    buffer.writeInt16LE(int16Array[i] ?? 0, i * 2);
  }
  return buffer;
}

/**
 * Main function to package and save the file to local mobile storage
 */
export async function saveAudioToDevice(
  audioBuffer: Int16Array,
  sampleRate: number,
): Promise<string> {
  try {
    const audioData = int16ArrayToBuffer(audioBuffer);
    const wavHeader = createWavHeader(audioData.length, sampleRate);
    const finalWavBuffer = Buffer.concat([wavHeader, audioData]);
    const base64Data = finalWavBuffer.toString("base64");

    const filename = `tts-speech-${Date.now()}.wav`;
    const fileUri = `\({FileSystem.documentDirectory}\){filename}`;

    await FileSystem.writeAsStringAsync(fileUri, base64Data, {
      encoding: FileSystem.EncodingType.Base64,
    });

    console.log(`✅ File saved locally at: ${fileUri}`);
    return fileUri;
  } catch (error) {
    console.error("❌ Failed to save audio file locally:", error);
    throw error;
  }
}

Complete Implementation

Let's bring it all together. We'll implement an interface that takes user input, manages download and loading states for the Supertonic engine, packages generated raw waves into a playable local file, and renders an interactive visual waveform player.

Replace your entry app file src/app/index.tsx with the following implementation:

import { useState, useEffect } from "react";
import {
  TextInput,
  KeyboardAvoidingView,
  Platform,
  ScrollView,
} from "react-native";
import {
  loadModel,
  unloadModel,
  textToSpeech,
  downloadAsset,
  TTS_EN_SUPERTONIC_Q8_0,
  getModelInfo,
  type ModelProgressUpdate,
} from "@qvac/sdk";
import { saveAudioToDevice } from "@/lib/utils";
import { TtsModelLoader } from "@/components/tts-model-loader";
import { AudioPlayer } from "@/components/audio-player";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Button } from "@/components/ui/button";
import { Text } from "@/components/ui/text";

const SUPERTONIC_SAMPLE_RATE = 44100;

// Global reference for our model ID
let globalModelId: string | null = null;

type TtsStatus =
  | { phase: "idle" }
  | { phase: "synthesizing" }
  | { phase: "done"; audioUri: string }
  | { phase: "error"; message: string };

export default function TextToVoiceScreen() {
  const [text, setText] = useState("");
  const [status, setStatus] = useState<TtsStatus>({ phase: "idle" });

  const [isModelLoaded, setIsModelLoaded] = useState(!!globalModelId);
  const [isDownloading, setIsDownloading] = useState(false);
  const [downloadProgress, setDownloadProgress] = useState(0);

  const isBusy = status.phase === "synthesizing";

  useEffect(() => {
    async function checkAndAutoLoad() {
      if (globalModelId) return;
      try {
        const info = await getModelInfo({ name: TTS_EN_SUPERTONIC_Q8_0.name });
        if (info.isCached) {
          setIsDownloading(true);
          setDownloadProgress(1);

          globalModelId = await loadModel({
            modelSrc: TTS_EN_SUPERTONIC_Q8_0,
            modelConfig: {
              ttsEngine: "supertonic",
              language: "en",
              voice: "F1",
              ttsSpeed: 1.05,
              ttsNumInferenceSteps: 5,
            },
          });

          setIsModelLoaded(true);
          setIsDownloading(false);
        }
      } catch (err: unknown) {
        console.warn("Failed to auto-load cached model on mount:", err);
        setIsDownloading(false);
      }
    }
    checkAndAutoLoad();
  }, []);

  const handleDownloadModel = async () => {
    if (isDownloading || isModelLoaded) return;

    try {
      setIsDownloading(true);
      setDownloadProgress(0);

      await downloadAsset({
        assetSrc: TTS_EN_SUPERTONIC_Q8_0,
        onProgress: (p: ModelProgressUpdate) => {
          setDownloadProgress(p.percentage / 100);
        },
      });

      setDownloadProgress(1);

      globalModelId = await loadModel({
        modelSrc: TTS_EN_SUPERTONIC_Q8_0,
        modelConfig: {
          ttsEngine: "supertonic",
          language: "en",
          voice: "F1",
          ttsSpeed: 1.05,
          ttsNumInferenceSteps: 5,
        },
      });

      setIsModelLoaded(true);
      setIsDownloading(false);
    } catch (err: unknown) {
      console.error("Failed to download or load model:", err);
      setIsDownloading(false);
      setStatus({
        phase: "error",
        message: err instanceof Error ? err.message : String(err),
      });
      setIsModelLoaded(false);
    }
  };

  const handleSubmit = async () => {
    if (!text.trim() || isBusy || !globalModelId) return;

    try {
      setStatus({ phase: "synthesizing" });

      // 1. Unload and reload the model to reset its state and clear the KV cache.
      if (globalModelId) {
        await unloadModel({ modelId: globalModelId });
      }
      globalModelId = await loadModel({
        modelSrc: TTS_EN_SUPERTONIC_Q8_0,
        modelConfig: {
          ttsEngine: "supertonic",
          language: "en",
          voice: "F1",
          ttsSpeed: 1.05,
          ttsNumInferenceSteps: 5,
        },
      });

      // 2. Synthesize text to raw PCM samples
      const result = textToSpeech({
        modelId: globalModelId,
        text: text.trim(),
        inputType: "text",
        stream: false,
      });

      const audioBuffer = await result.buffer;

      // 3. Package and save WAV file using our local util
      const samplesInt16 = new Int16Array(audioBuffer);
      const wavUri = await saveAudioToDevice(
        samplesInt16,
        SUPERTONIC_SAMPLE_RATE,
      );

      // 4. Show player
      setStatus({ phase: "done", audioUri: wavUri });
    } catch (err: unknown) {
      console.error("TTS error:", err);
      const msg = err instanceof Error ? err.message : String(err);
      setStatus({ phase: "error", message: msg });
    }
  };

  const buttonLabel =
    status.phase === "synthesizing" ? "Synthesizing…" : "Synthesize Speech";

  if (!isModelLoaded) {
    return (
      <TtsModelLoader
        onDownload={handleDownloadModel}
        isDownloading={isDownloading}
        progress={downloadProgress}
      />
    );
  }

  return (
    <KeyboardAvoidingView
      behavior={Platform.OS === "ios" ? "padding" : "height"}
      className="flex-1 bg-black"
    >
      <ScrollView contentContainerClassName="flex-grow p-6  justify-center">
        <Card className="border border-border bg-card max-w-md w-full mx-auto">
          <CardHeader>
            <CardTitle variant="h3" className="text-white text-center">
              Text to Voice
            </CardTitle>
            <CardDescription className="text-center mt-1">
              Type or paste your content to synthesize speech
            </CardDescription>
          </CardHeader>

          <CardContent className="gap-6">
            <TextInput
              className="bg-muted text-white border border-border rounded-lg p-4 h-48 text-base leading-6"
              multiline
              numberOfLines={8}
              placeholder="Type your message here..."
              placeholderTextColor="#666"
              value={text}
              onChangeText={setText}
              style={{ textAlignVertical: "top" }}
              editable={!isBusy}
            />

            {status.phase === "error" && (
              <Text className="text-destructive text-sm text-center">
                {status.message}
              </Text>
            )}

            {status.phase === "done" && <AudioPlayer uri={status.audioUri} />}

            <Button
              onPress={handleSubmit}
              className="w-full h-12 rounded-xl"
              disabled={!text.trim() || isBusy}
            >
              <Text className="font-semibold text-lg">{buttonLabel}</Text>
            </Button>
          </CardContent>
        </Card>
      </ScrollView>
    </KeyboardAvoidingView>
  );
}

Codebase Breakdown

Let’s lift the hood on how this local Text-to-Speech implementation manages native model lifecycles and processes raw audio arrays.

1. Managing the Native Lifecycle

Loading neural network weights for speech synthesis is computationally expensive. When the QVAC runtime initializes a model, it must read parameters from the local disk and copy the active weights into device RAM.

To handle this efficiently, we declared the reference variable outside the component scope:

let globalModelId: string | null = null;

If globalModelId were tracked inside component states, navigating away from the text-to-speech screen would clean up the state, causing the app to unnecessarily drop the reference. Storing the ID globally ensures we hold onto it across layout transitions.

2. Flushing the KV Cache: Unload and Reload

One of the most important aspects of offline generation using GGML engines is state management:

// 1. Unload and reload the model to reset its state and clear the KV cache.
if (globalModelId) {
  await unloadModel({ modelId: globalModelId });
}

globalModelId = await loadModel({ ... });

WARNING about acoustic hallucinations: If you continuously synthesize sentences on a single TTS model instance without resetting it, the model's Key-Value (KV) cache fills up. It begins treating your new sentence as a continuation of the previous one, leading to heavy robotic distortion, echoing, and repeated voices.

By explicitly destroying the model via unloadModel and immediately booting a fresh instance with loadModel, we're forcing a pristine, empty context window. Since the model is already downloaded and memory-mapped, reloading the model directly from local flash storage is extremely fast, typically completing in a fraction of a second on modern mobile hardware to ensure a seamless user experience while guaranteeing artifact-free audio.

3. Demystifying the WAV Header Structure

Operating systems and built-in mobile media decoders are unable to parse raw, naked PCM (Pulse Code Modulation) sound waves directly. A raw PCM buffer is simply a stream of numerical coordinates representing audio wave amplitudes.

We resolve this by prepending-formatting our PCM buffer with a standard 44-byte RIFF/WAVE header.

This header acts as a passport, defining:

• AudioFormat (1): Signals uncompressed linear PCM.

• NumChannels (1): Mono audio.

• SampleRate (44100): The clock frequency required for Supertonic playback.

• BitsPerSample (16): 16-bit word length (2 bytes per sample).

Additionally, writing the file is handled via Base64 encoding to safely cross React Native's JavaScript-to-Native bridge without dropping binary data:

const base64Data = finalWavBuffer.toString("base64");
await FileSystem.writeAsStringAsync(fileUri, base64Data, {
  encoding: FileSystem.EncodingType.Base64,
});

4. Visual Waveform Player

Rather than using a basic headless native audio player that fires immediately in the background, we pass the local WAV file path to a custom <AudioPlayer> component powered by @simform_solutions/react-native-audio-waveform.

This module analyzes our newly written WAV file and draws a sleek, WhatsApp-inspired interactive visual waveform, giving the user full control over playback, dynamic speed adjustments (1x, 1.5x, 2x), and seeking. It's a vast UX improvement that makes the final result feel premium and polished.

Conclusion

Transitioning Text-to-Speech from the cloud to on-device hardware offers a practical approach for mobile application developers. Running model inference locally eliminates reliance on remote internet connectivity, removes recurring API usage costs, and ensures that user text inputs never leave the physical device.

Integrating local speech synthesis can be highly beneficial for interactive, educational, or conversational apps. For example, in voice-guided systems, on-device TTS allows applications to function in private or offline environments. As edge processors gain dedicated hardware acceleration cores and open-source models decrease in memory size through quantization research, local-first architectures present a compelling alternative for developers prioritizing privacy, offline resilience, and predictable cost structures.

Resources and Further Reading

To dive deeper into local Text-to-Speech inference, inspect the source code, or explore advanced configurations for your mobile applications, check out the following resources:

• QVAC Expo Integration Docs: Learn more about configuring custom local models in Expo.

• react-native-audio-waveform: Learn more about interactive React Native audio visualizations.

• GGUF Model Hub on Hugging Face: Browse compatible quantized open-source models.

• Latent Denoising Deep Dive: Technical deep dive into Diffusion-based acoustic generation.

• https://github.com/DjibrilM/QVAC-TTS-Expo-Implementation: Full implementation code.

The library requires React Native's New Architecture (Fabric), so you'll need version 0.76 or newer.

In this tutorial, you'll learn:

• How to use CSS transitions for state-driven animations

• When to use worklets for gesture and scroll interactions

• How to migrate from Reanimated 3 to 4

• Practical patterns for collapsing headers, bottom sheets, and carousels

• Performance optimization techniques

Prerequisites

You should have:

• React Native 0.76+ with New Architecture enabled

• Basic React hooks knowledge (useState, useEffect)

• Node.js and npm or yarn are installed

Table of Contents

• Installation and Setup

• Understanding the Two Approaches (CSS Animations and Worklets)

• How to Migrate from Reanimated Version 3 to Version 4

• CSS Animations Tutorial

• Worklets Tutorial

• Real-World Patterns

• Performance Optimizations

• Debugging Tips

• Conclusion

Installation and Setup

To get started, you'll need to install the required packages:

# For Expo
npx expo install react-native-reanimated react-native-worklets

# For React Native CLI  
npm install react-native-reanimated react-native-worklets
cd ios && pod install && cd ..

Update babel.config.js (the plugin must be last):

module.exports = {
  presets: ['module:metro-react-native-babel-preset'],
  plugins: [
    'react-native-worklets/plugin', // Must be last
  ],
};

Then clear the cache and rebuild:

npm start -- --reset-cache
npx react-native run-ios

Understanding the Two Approaches

React Native Reanimated is an animation library that runs animations on the native thread instead of the JavaScript thread. This means your animations stay smooth even when your JavaScript code is busy processing data or handling user interactions.

Unlike React Native's built-in Animated API, Reanimated executes animation logic directly on the UI thread. This eliminates the performance bottleneck caused by communication between JavaScript and native code, which enables Reanimated to maintain 60 FPS even during complex operations.

Reanimated 4 offers two animation systems, each designed for different use cases.

CSS Animations

CSS animations work declaratively, meaning you describe what you want to happen rather than how to make it happen. You define which properties should animate (like width, color, or opacity), specify the timing and easing, then simply change the values through React state updates. Reanimated automatically handles the animation between the old and new values.

This approach excels at predictable, state-driven animations where you know both the starting and ending states. It's ideal for:

• Showing and hiding UI elements (modals, tooltips, notifications)

• Expanding and collapsing content (accordions, dropdown menus)

• Visual feedback for state changes (button hover effects, selection highlights)

• Loading indicators and progress animations

• Color and opacity transitions

Worklets

Worklets take a different approach by giving you imperative, frame-by-frame control over animations. They run on the UI thread and use "shared values" – special variables that can be accessed and modified from both JavaScript and native code without any communication overhead.

Worklets are essential for interactive animations that need to respond in real-time to user input or continuous data streams. They're best for:

• Gesture-driven interactions (drag-and-drop, swipe-to-dismiss, pinch-to-zoom)

• Scroll-linked effects (parallax images, collapsing headers, sticky elements)

• Physics-based animations (spring effects, momentum scrolling)

• Sensor-based animations (responding to device orientation)

• Any animation requiring dynamic, real-time control

Now that you understand the two approaches Reanimated offers, let's look at how to migrate from version 3 if you're already using the library.

How to Migrate from Reanimated Version 3 to Version 4

If you're currently using Reanimated 3, you'll be happy to know that version 4 maintains backward compatibility. Your existing animations using worklets, shared values, and useAnimatedStyle will continue to work without modification.

But version 4 introduces some architectural changes and removes deprecated APIs, so you'll need to make a few updates to your project configuration and code. Let's walk through the migration process step by step.

What Changed in Version 4

The most significant change is that worklets have been extracted into a separate package called react-native-worklets-core. This modular approach allows other libraries beyond Reanimated to leverage worklet functionality.

Because of this separation, you'll need to update your Babel configuration. Change the plugin from react-native-reanimated/plugin to react-native-worklets/plugin.

Version 4 also exclusively supports React Native's New Architecture (Fabric). The old Paper renderer is no longer compatible. If your project hasn't migrated to the New Architecture yet, you'll need to either upgrade to React Native 0.76+ (which has New Architecture enabled by default) or stay on Reanimated 3.x until you're ready to make that transition.

Removed APIs

Several APIs that were deprecated in version 3 have been removed in version 4. Here's what you need to replace:

• useAnimatedGestureHandler → Use the Gesture API from react-native-gesture-handler 2.x instead

• useWorkletCallback → Use useCallback with the 'worklet' directive

• combineTransition → Use EntryExitTransition.entering().exiting()

The useScrollViewOffset hook has been renamed to useScrollOffset. The old name still works but is deprecated, so update your code to use the new name.

Spring Configuration Change

The spring animation configuration has changed to feel more natural. The duration parameter now represents "perceptual duration" rather than exact milliseconds. The actual animation runs approximately 1.5 times longer than the specified duration, creating springs that feel more organic and less mechanical.

// Version 3
withSpring(100, { duration: 300 }) // Runs for exactly 300ms

// Version 4  
withSpring(100, { duration: 200 }) // Runs for approximately 300ms

If you need to maintain the exact timing from version 3, divide your duration values by 1.5.

Step-by-Step Migration Process

Here's how to migrate your project from Reanimated 3 to version 4:

Step 1: Verify your project is using React Native 0.76 or newer with New Architecture enabled. Check your iOS Podfile for ENV['RCT_NEW_ARCH_ENABLED'] = '1' and your Android gradle.properties for newArchEnabled=true.

Step 2: Install the new versions of Reanimated and the worklets package:

npm install react-native-reanimated@^4.1.0 react-native-worklets@^0.5.0

Step 3: Update your babel.config.js to use the new worklets plugin:

module.exports = {
  plugins: [
    'react-native-worklets/plugin', // Changed from react-native-reanimated/plugin
  ],
};

Step 4: Search your codebase for the removed APIs and replace them:

• Replace useAnimatedGestureHandler with the Gesture API

• Replace useWorkletCallback with useCallback and add 'worklet' directive

• Replace combineTransition with EntryExitTransition.entering().exiting()

• Rename useScrollViewOffset to useScrollOffset

Step 5: Rebuild your native apps:

cd ios && pod install && cd ..
npx react-native run-ios
# or for Android
npx react-native run-android

After completing these steps, your app should be running on Reanimated 4 with all your existing animations working as before. You're now ready to start using the new CSS animation features alongside your existing worklet-based animations. In the next section, you'll learn how to build animations using the CSS syntax.

CSS Animations Tutorial

CSS animations provide a clean, declarative way to handle transitions that are triggered by state changes. Instead of manually managing animation values, you simply declare which properties should animate and how, then update your component state – Reanimated handles the rest.

This approach is particularly powerful for animations where you know the start and end states ahead of time. It's perfect for UI elements that toggle between different visual states, like modals appearing and disappearing, buttons providing feedback on press, or content expanding and collapsing.

Basic Transitions

A transition animates the change between two property values. When you specify a property that should transition, Reanimated automatically interpolates between the old and new values over the specified duration.

Let's look at an expandable card that grows when tapped:

import React, { useState } from 'react';
import { Pressable, Text } from 'react-native';
import Animated from 'react-native-reanimated';

function ExpandableCard() {
  const [expanded, setExpanded] = useState(false);

  return (
    <Pressable onPress={() => setExpanded(!expanded)}>
      <Animated.View style={{
        width: expanded ? 300 : 200,
        height: expanded ? 200 : 100,
        backgroundColor: expanded ? '#4ade80' : '#86efac',
        transitionProperty: ['width', 'height', 'backgroundColor'],
        transitionDuration: 300,
        transitionTimingFunction: 'ease-in-out',
      }}>
        <Text>Tap to toggle</Text>
      </Animated.View>
    </Pressable>
  );
}

Here's what's happening: The card's width, height, and background color are controlled by the expanded state. The transitionProperty array tells Reanimated which properties to animate. When expanded changes, Reanimated smoothly animates from the current values to the new values over 300 milliseconds, using an ease-in-out timing function that starts slow, speeds up, then slows down again.

Keyframe Animations

While transitions handle changes between two states, keyframe animations let you define multi-step sequences with precise control over each stage. You create an object where each key represents a percentage of the animation timeline, and the value defines what properties should look like at that point.

Here's a pulsing badge that scales up and fades slightly, then returns to normal:

const pulseAnimation = {
  '0%': { scale: 1, opacity: 1 },
  '50%': { scale: 1.05, opacity: 0.8 },
  '100%': { scale: 1, opacity: 1 },
};

function PulsingBadge() {
  return (
    <Animated.View style={{
      width: 50,
      height: 50,
      borderRadius: 25,
      backgroundColor: '#ef4444',
      animationName: pulseAnimation,
      animationDuration: 2000,
      animationIterationCount: 'infinite',
    }} />
  );
}

The animation starts at 0% (normal size and opacity), grows and fades at the 50% mark, then returns to the original state at 100%. By setting animationIterationCount to 'infinite', the animation loops continuously. This creates the pulsing effect you often see on notification badges or live indicators.

Built-in Animations

Reanimated includes a collection of pre-built animations for common entrance and exit effects. These save you from writing animation configurations for standard patterns like fading, sliding, and zooming.

Here's a modal that fades in when shown and fades out when hidden:

import { FadeIn, FadeOut } from 'react-native-reanimated';

function Modal({ visible, children }) {
  if (!visible) return null;

  return (
    <Animated.View 
      entering={FadeIn.duration(300)}
      exiting={FadeOut.duration(200)}
    >
      {children}
    </Animated.View>
  );
}

The entering prop automatically applies the fade-in animation when the component mounts, and exiting applies the fade-out before unmounting. Other commonly used built-in animations include SlideInRight, SlideOutLeft (for drawer-style entrances), and ZoomIn, ZoomOut (for attention-grabbing pop-ins).

Now that you understand CSS animations for state-driven transitions, let's explore worklets for creating interactive animations that respond to user input in real-time.

Worklets Tutorial

While CSS animations excel at predefined state transitions, many animations need to respond dynamically to user input. This is where worklets come in. Worklets give you frame-by-frame control over animations, allowing them to follow gestures, scroll position, or any other real-time input source.

Interactive animations differ from CSS animations in that they don't have predefined start and end states. Instead, they continuously update based on user input. For example, a draggable element needs to follow your finger precisely as you move it – there's no way to know ahead of time where you'll drag it. This requires imperative control, where you directly manipulate animation values in response to events.

Basic Worklet Animation

Shared values are the foundation of worklet-based animations. They're special variables that exist simultaneously in both the JavaScript and UI threads, allowing you to update them from JavaScript while the UI thread reads them to update the display – all without any communication overhead.

Here's a button that scales down when pressed and bounces back when released:

import Animated, { 
  useSharedValue, 
  useAnimatedStyle, 
  withSpring 
} from 'react-native-reanimated';
import { Pressable } from 'react-native';

function BouncyButton() {
  const scale = useSharedValue(1);

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ scale: scale.value }],
  }));

  return (
    <Pressable
      onPressIn={() => { scale.value = withSpring(0.9); }}
      onPressOut={() => { scale.value = withSpring(1); }}
    >
      <Animated.View style={[styles.button, animatedStyle]}>
        <Text>Press Me</Text>
      </Animated.View>
    </Pressable>
  );
}

The useSharedValue(1) creates a shared value initialized to 1 (normal scale). The useAnimatedStyle hook creates a style object that depends on this shared value and runs on the UI thread. When you press the button, scale.value = withSpring(0.9) updates the shared value, and withSpring creates a spring animation to the new value. The useAnimatedStyle hook automatically re-runs, updating the transform with the new scale value.

Gesture Animations

Gestures require even tighter integration between user input and animation. The react-native-gesture-handler library provides high-performance gesture recognition that works seamlessly with Reanimated.

First, install the gesture handler:

npm install react-native-gesture-handler
cd ios && pod install && cd ..

Next, you need to wrap your app with GestureHandlerRootView. This component sets up the gesture handling system at the root of your application. Without it, gestures won't work. Think of it as activating the gesture system for your entire app:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      {/* Your app content goes here */}
    </GestureHandlerRootView>
  );
}

Now you can create gesture-driven animations. Here's a box you can drag around the screen that springs back to center when released:

import { Gesture, GestureDetector } from 'react-native-gesture-handler';

function DraggableBox() {
  const offsetX = useSharedValue(0);
  const offsetY = useSharedValue(0);

  const pan = Gesture.Pan()
    .onChange((event) => {
      offsetX.value += event.changeX;
      offsetY.value += event.changeY;
    })
    .onEnd(() => {
      offsetX.value = withSpring(0);
      offsetY.value = withSpring(0);
    });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [
      { translateX: offsetX.value },
      { translateY: offsetY.value },
    ],
  }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.box, animatedStyle]} />
    </GestureDetector>
  );
}

The Gesture.Pan() creates a pan gesture recognizer. The .onChange() callback fires continuously while you're dragging – event.changeX and event.changeY tell you how much the finger moved since the last frame. By adding these values to the offsets, the box follows your finger. When you lift your finger, .onEnd() fires and springs the box back to the center (0, 0).

Scroll-Linked Animations

Another common use case for worklets is creating effects that respond to scroll position, like headers that shrink as you scroll down or parallax backgrounds.

Here's a header that collapses as you scroll:

function ParallaxHeader() {
  const scrollY = useSharedValue(0);

  const scrollHandler = useAnimatedScrollHandler({
    onScroll: (event) => {
      scrollY.value = event.contentOffset.y;
    },
  });

  const headerStyle = useAnimatedStyle(() => {
    const height = interpolate(
      scrollY.value,
      [0, 150],
      [200, 60],
      'clamp'
    );

    return { height };
  });

  return (
    <>
      <Animated.View style={[styles.header, headerStyle]}>
        <Text>Header</Text>
      </Animated.View>
      <Animated.ScrollView
        onScroll={scrollHandler}
        scrollEventThrottle={16}
      >
        {/* Content */}
      </Animated.ScrollView>
    </>
  );
}

The useAnimatedScrollHandler creates a scroll event handler that runs on the UI thread. Every time you scroll, it updates scrollY with the current scroll position. The interpolate function maps the scroll position to the header height – when scrollY is 0 (top of the scroll), height is 200. When scrollY reaches 150, height is 60. The 'clamp' option prevents the height from going outside this range.

With these fundamentals of CSS animations and worklets covered, let's look at how to apply them to common real-world scenarios.

Real-World Patterns

Now that you understand both CSS animations and worklets, let's combine them to build three patterns you'll frequently encounter in production apps. These examples demonstrate when to use each animation approach and how to structure your code for maintainability.

In this section, you'll learn how to build a collapsing header that shrinks as users scroll (using worklets for scroll tracking), a bottom sheet that responds to drag gestures (using worklets for gesture control), and a swipe-to-delete interaction for list items (combining worklets for gesture detection with animations for the deletion effect).

Collapsing Header

A collapsing header is a navigation bar that starts tall and shrinks as you scroll down. This pattern is popular because it maximizes content space while keeping navigation accessible. You'll use worklets here because the animation needs to follow the scroll position in real-time.

function CollapsibleHeader() {
  const scrollY = useSharedValue(0);
  const HEADER_MAX = 200;
  const HEADER_MIN = 60;

  const scrollHandler = useAnimatedScrollHandler({
    onScroll: (event) => {
      scrollY.value = event.contentOffset.y;
    },
  });

  const headerStyle = useAnimatedStyle(() => ({
    height: interpolate(
      scrollY.value,
      [0, HEADER_MAX - HEADER_MIN],
      [HEADER_MAX, HEADER_MIN],
      'clamp'
    ),
  }));

  return (
    <View style={{ flex: 1 }}>
      <Animated.View style={[styles.header, headerStyle]}>
        <Text>My App</Text>
      </Animated.View>
      <Animated.ScrollView
        onScroll={scrollHandler}
        scrollEventThrottle={16}
      >
        <View style={{ height: 1000, padding: 16 }}>
          <Text>Scroll to see header collapse</Text>
        </View>
      </Animated.ScrollView>
    </View>
  );
}

This pattern tracks scroll position in scrollY and uses interpolate to map it to header height. When you're at the top (scrollY = 0), the header is 200 pixels tall. As you scroll down 140 pixels, the header shrinks to 60 pixels. The animation happens on every frame as you scroll, which is why worklets are necessary – CSS animations couldn't track scroll position this smoothly.

Bottom Sheet

A bottom sheet is a panel that slides up from the bottom of the screen, commonly used for action menus, filters, or additional content. Users can drag it to different heights or dismiss it with a swipe down. This requires worklets because it needs frame-by-frame gesture tracking.

function BottomSheet({ children }) {
  const translateY = useSharedValue(300);
  const context = useSharedValue({ y: 0 });

  const pan = Gesture.Pan()
    .onStart(() => {
      context.value = { y: translateY.value };
    })
    .onChange((event) => {
      translateY.value = Math.max(
        event.translationY + context.value.y,
        -300
      );
    })
    .onEnd((event) => {
      if (event.velocityY > 500) {
        translateY.value = withSpring(300); // Dismiss
      } else if (translateY.value > -100) {
        translateY.value = withSpring(-50); // Collapsed
      } else {
        translateY.value = withSpring(-300); // Expanded
      }
    });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateY: translateY.value }],
  }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.bottomSheet, animatedStyle]}>
        <View style={styles.handle} />
        {children}
      </Animated.View>
    </GestureDetector>
  );
}

The bottom sheet starts off-screen at translateY = 300. When you start dragging, .onStart() saves the starting position in context. As you drag, .onChange() updates the position, but Math.max() prevents it from going below -300 (fully expanded). When you release, .onEnd() checks the velocity – if you swiped down quickly (velocity > 500), it dismisses. Otherwise, it snaps to either the collapsed (-50) or expanded (-300) position based on where you released it.

Swipe to Delete

Swipe-to-delete lets users remove items from a list by swiping left. It's a common pattern in email apps and to-do lists. This uses worklets for gesture tracking and timing functions for the deletion animation.

function SwipeToDelete({ children, onDelete }) {
  const translateX = useSharedValue(0);
  const itemHeight = useSharedValue(60);

  const pan = Gesture.Pan()
    .activeOffsetX([-10, 10])
    .onChange((event) => {
      if (event.translationX < 0) {
        translateX.value = event.translationX;
      }
    })
    .onEnd(() => {
      if (translateX.value < -100) {
        translateX.value = withTiming(-500, { duration: 200 });
        itemHeight.value = withTiming(0, { duration: 200 }, () => {
          runOnJS(onDelete)();
        });
      } else {
        translateX.value = withSpring(0);
      }
    });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.value }],
    height: itemHeight.value,
  }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.item, animatedStyle]}>
        {children}
      </Animated.View>
    </GestureDetector>
  );
}

The .activeOffsetX([-10, 10]) setting means the gesture only activates after you've moved 10 pixels horizontally, preventing accidental triggers during vertical scrolling. The if (event.translationX < 0) check ensures you can only swipe left, not right. If you swipe past -100 pixels and release, it triggers the deletion: the item slides off-screen (-500), the height collapses to 0, and runOnJS calls your delete function from the UI thread back to JavaScript.

These patterns demonstrate the power of combining Reanimated's animation approaches with gesture handling. Now, let's look at how to keep these animations performing smoothly.

Performance Optimizations

Even though Reanimated runs on the UI thread, poorly structured animations can still drop frames. Here are four key optimizations that will keep your animations consistently smooth at 60 FPS.

Memoize Animations

Every time your component re-renders, any animations you create inside the render function are recreated. This wastes memory and processing time.

Don't do this – creating a new animation object on every render:

{items.map(item => (
  <Animated.View entering={FadeIn.duration(300)} key={item.id} />
))}

Instead, create the animation once outside the component or memoize it:

const fadeIn = FadeIn.duration(300);
{items.map(item => (
  <Animated.View entering={fadeIn} key={item.id} />
))}

By storing the animation in a constant, you create it once and reuse the same object for all items. This reduces memory allocation and garbage collection, keeping your animations smooth even with long lists.

Use useDerivedValue

If you're doing expensive calculations inside useAnimatedStyle, those calculations run every frame, even if the dependencies haven't changed.

Don't do this – recalculating every frame:

const animatedStyle = useAnimatedStyle(() => ({
  width: Math.min(Math.max(offset.value * 2, 100), 500),
}));

Instead, use useDerivedValue to compute the value only when dependencies change:

const width = useDerivedValue(() => 
  Math.min(Math.max(offset.value * 2, 100), 500)
);

const animatedStyle = useAnimatedStyle(() => ({
  width: width.value,
}));

Now the complex calculation only runs when offset.value changes, not on every frame. The useAnimatedStyle just reads the pre-computed width, which is much faster.

Batch Updates

When you update multiple shared values, each update can trigger a separate re-render. This creates unnecessary work for the UI thread.

Don't do this – triggering multiple re-renders:

scale.value = withSpring(1.2);
opacity.value = withSpring(0.8);

Instead, batch the updates using runOnUI:

runOnUI(() => {
  'worklet';
  scale.value = withSpring(1.2);
  opacity.value = withSpring(0.8);
})();

The runOnUI function ensures both updates happen in the same frame, so the UI only re-renders once. This is especially important when updating many values at once, like in complex gestures or choreographed animations.

Prefer Transform Over Layout

Animating layout properties like width, height, or margins forces React Native to recalculate the position of every element that depends on the changing element. This is expensive.

Don't do this – expensive layout recalculation:

width: withSpring(newWidth)

Instead, use transform properties, which only affect the visual appearance without triggering layout:

transform: [{ scaleX: withSpring(scale) }]

Transform operations are hardware-accelerated and don't affect layout, making them dramatically faster. Whenever possible, use translateX/Y instead of changing position, scale instead of changing size, and rotate instead of changing orientation.

These optimizations will keep your animations buttery smooth. Now let's look at how to debug issues when they arise.

Debugging Tips

Even with proper setup, you may encounter issues with animations. Here are the most common problems and their solutions, written as complete troubleshooting steps.

Animations Not Working

If your animations aren't running at all, the most common cause is a missing or incorrectly configured Babel plugin. Open your babel.config.js file and verify that react-native-worklets/plugin is present in the plugins array and is the last plugin in the list. The order matters because the worklets plugin needs to process your code after all other transformations.

After confirming the plugin is correctly configured, clear your Metro bundler cache by running npm start -- --reset-cache, then rebuild your app completely. Simply reloading JavaScript won't work because Babel transformations happen during the build process.

App Crashes on Startup or Reload

If your app crashes immediately after installing Reanimated or when you reload, the native modules likely aren't properly linked. With React Native 0.76+, this usually means the pods weren't installed or the native build is out of sync.

For iOS, run cd ios && pod install && cd .. then do a clean build with npx react-native run-ios. For Android, clean the build with cd android && ./gradlew clean && cd .. then rebuild with npx react-native run-android.

If you're getting build errors about missing headers or modules, make sure you've added both react-native-reanimated and react-native-worklets to your package.json dependencies.

"TurboModuleRegistry Not Found"

If you see an error message saying "TurboModuleRegistry.get('NativeReanimated'): 'NativeReanimated' could not be found", it means the native code hasn't been properly linked to your JavaScript code.

First, verify you're using React Native 0.76 or newer, as Reanimated 4 requires the New Architecture. Check your ios/Podfile for ENV['RCT_NEW_ARCH_ENABLED'] = '1' and android/gradle.properties for newArchEnabled=true.

Then rebuild completely: cd ios && pod install && cd .. && npx react-native run-ios.

Logging and Inspecting Shared Values

If you try to debug worklets using console.log(), you'll notice nothing appears in your console. This is because worklets run on the UI thread, which doesn't have direct access to the JavaScript console.

To log values from worklets, use the useDerivedValue hook:

const offset = useSharedValue(0);

useDerivedValue(() => {
  console.log('Offset:', offset.value);
  return offset.value;
});

For more advanced debugging, React Native's built-in debugger (accessed through dev menu → "Open Debugger") now supports debugging both threads. You can set breakpoints in worklets and inspect shared values in real-time.

Monitor Performance

To see if your animations are actually running at 60 FPS, enable the Performance Monitor built into React Native. Shake your device (or press Cmd+D in the iOS simulator, Cmd+M in Android emulator) to open the dev menu, then select "Show Perf Monitor".

The monitor displays two critical numbers: JS thread FPS and UI thread FPS. Your animations run on the UI thread, so watch that number. If it stays at 60 FPS, your animations are smooth. If it drops below 60, your animations are skipping frames and will appear janky. The JS thread FPS shows whether your React code is keeping up – if this drops, it indicates issues with your component renders, not your animations.

For more detailed debugging information and advanced troubleshooting, check the official debugging guide here.

Conclusion

Reanimated 4 gives you two powerful approaches to animation: CSS animations for simple state changes and worklets for complex, interactive animations that need real-time control.

Start with CSS transitions when building your next animation feature. They're simpler to write, easier to maintain, and perfect for the majority of UI animations. Reach for worklets when you need gesture control, scroll effects, or any animation that requires frame-by-frame updates.

The official documentation provides complete API references, detailed guides, and interactive examples. The GitHub repository includes production-ready sample code you can study and adapt.

Building smooth animations isn't just about technical capability – it's about creating experiences that feel responsive, intuitive, and delightful to use. Reanimated 4 makes achieving that standard straightforward, whether you're animating a simple button press or building a complex screen transition with multiple coordinated elements.

We just published a course on the freeCodeCamp.org YouTube channel that will teach you all about React Native. This beginner-friendly course, created by Dave Gray, is packed with over four hours of clear, hands-on instruction. Whether you're completely new to app development or have some experience with React, this tutorial will guide you through the essentials of React Native, helping you build functional, visually appealing, and dynamic mobile apps.

What You’ll Learn

The course is structured into eight chapters, each focusing on a critical aspect of React Native development. Here’s a breakdown of what you can expect:

1. Intro
   A quick introduction to React Native, what it is, and why it’s such a popular choice for mobile development. You’ll set up your environment and get ready to code.

2. Chapter 1: Start Here
   This chapter introduces the basics of React Native, including setting up your development environment and understanding the fundamental building blocks of a React Native app.

3. Chapter 2: Build an App
   Dive into building your first simple app. You’ll learn how to create components, style them, and structure your app for better readability and functionality.

4. Chapter 3: Navigation
   Learn how to implement navigation between different screens using React Navigation. This is essential for creating multi-screen apps that feel seamless to users.

5. Chapter 4: List Views
   Explore how to display and manage lists in React Native, an essential skill for creating dynamic and interactive user interfaces.

6. Chapter 5: CRUD App
   Build a simple CRUD (Create, Read, Update, Delete) application. This chapter introduces you to state management and handling user input, two critical concepts in app development.

7. Chapter 6: Data Storage
   Learn how to store and retrieve data locally, which is crucial for offline functionality and saving user preferences.

8. Chapter 7: Dynamic Routing
   Expand your knowledge of routing by implementing dynamic routes that adapt to the user’s input or app state.

9. Chapter 8: EAS Development Builds
   Get introduced to Expo Application Services (EAS), a powerful tool for building and deploying your React Native apps.

Why Learn React Native?

React Native is a popular framework because it allows you to use JavaScript—a widely used programming language—to build mobile apps. This means you can transition from web development to mobile development without needing to learn a completely new language. Plus, React Native’s community and ecosystem are rich with resources, making it easier for beginners to find support and tools.

Start Building Today

This course provides everything you need to get started with React Native, from understanding the basics to deploying your app. By the end, you’ll have built multiple projects, gaining the confidence and skills to tackle your own mobile app ideas.

Ready to start your mobile app development journey? Check out the full course on the freeCodeCamp.org YouTube channel (4-hour watch).

We just published a course on the freeCodeCamp.org YouTube channel that will teach you all about developing native mobile apps using React Native, Supabase, Stripe, and Next.js. This course is designed to take you through the entire process of building a complete e-commerce platform, making it an ideal project for anyone looking to strengthen their full-stack development skills. Whether you're new to mobile development or looking to expand your knowledge, this course covers everything step by step. Alaribe Bright developed this course.

What You’ll Learn

1. React Native & Expo: You'll start by creating a React Native app using Expo, a powerful framework that simplifies mobile app development. You'll dive into Expo Router for managing navigation with file-based routing, build dynamic pages for product categories, and manage cart functionality using Zustand, a lightweight state management library.

2. Supabase: This section introduces Supabase, an open-source alternative to Firebase. You'll learn to handle authentication, database management, and real-time updates. You'll implement secure user authentication, explore SQL functions, triggers, and set up row-level security for a secure back-end.

3. Next.js for Admin Panel: The admin panel is built using Next.js, known for its server-side rendering and API capabilities. You'll learn to manage categories and products, handle role-based access, and protect routes. The panel will allow you to perform CRUD operations (Create, Read, Update, Delete) efficiently on your platform’s data.

4. Stripe for Payments: This course will also guide you through integrating Stripe to handle payments securely. You’ll learn how to create Stripe customers, set up checkout sessions, and manage payments, all while keeping customer data safe.

5. Push Notifications: To enhance the user experience, you'll add real-time push notifications using EAS (Expo Application Services), ensuring your app can notify users of updates like order status changes in real time.

6. Deployment: Finally, you'll deploy your project to Vercel, ensuring your admin panel and the entire application are live and accessible. You'll also troubleshoot deployment fixes and ensure your app runs smoothly in production.

Conclusion

By the end of this course, you'll have a fully functioning e-commerce mobile app with an admin panel, payment integration, real-time updates, and secure authentication. This project is an excellent addition to your portfolio, demonstrating your ability to handle complex, full-stack development.

Watch the full course on the freeCodeCamp.org YouTube channel (12-hour watch).

You'll learn how to create an app that allows users to search and explore books using the Google Books API, manage personal bookshelves, and even generate AI-powered summaries. By the end of this course, you'll have a comprehensive understanding of building advanced MacOS applications.

Course Overview

This course, created by Brijen Makwana, provides a step-by-step guide to building a sophisticated MacOS app using React Native. You'll gain hands-on experience with essential tools and techniques, from setting up your development environment to implementing advanced features like AI-powered book summaries and state management.

Here are the key things you will learn:

• Setup and Initialization: Begin by setting up React Native on your Mac and initializing your project. You'll learn how to clean up the project structure to ensure a smooth development process.

• Building Components: Develop key components such as the SearchBar and BookItem, which are crucial for user interaction and displaying book information.

• Integrating Google Books API: Discover how to use Postman to test the Google Books API and integrate it into your project, enabling users to search and explore a vast library of books.

• State Management with Tanstack Query and Zustand: Learn how to manage application state efficiently using Tanstack Query and Zustand. You'll create custom hooks like useSearch and useBook to streamline data fetching and state updates.

• Navigation and Routing: Implement React Navigation to ensure smooth transitions between different screens in your app. You'll add routes for the Book Screen and Bookshelves Screen, enhancing the user experience.

• AI-Powered Features: Explore the integration of AI by setting up Google Generative AI and creating a custom hook, useAI, to generate book summaries. This feature adds a modern touch to your app, providing users with concise and insightful book overviews.

• Local Storage and Book Management: Implement local storage support to save user data and manage bookshelves effectively. You'll learn how to update and remove books using Zustand, ensuring a seamless user experience.

The course is structured into detailed sections, each focusing on a specific aspect of app development:

• Book Management MacOS App (React Native)

• Setup React Native on your Mac

• Initialize the Project

• Cleanup the Project

• SearchBar Component

• Intro to Google Books API

• Use Postman to test the API

• Integrate Google Books API in the Project

• Setup Tanstack Query

• useSearch Custom Hook

• BookItem Component

• Render Books on Home Screen

• Add support for Icons in the Project

• Rating in BookItem

• Setup React Navigation

• Add new Route for Book Screen

• useBook Custom Hook

• Implement Book Screen

• Add types to React Navigation

• SelectBookShelf Component

• Add new Route for Bookshelves Screen

• SegmentedButtons Component

• Intro to Zustand

• Setup Zustand

• Zustand store for Bookshelves

• BookShelfItem Component

• Render Books on Bookshelves Screen

• Implement update book in Zustand

• Implement remove book in Zustand

• Implement Local Storage Support

• AI Book Summary

• Setup Google Generative AI

• useAI Custom Hook

• Outro

Join Us Today

Head over to the freeCodeCamp.org YouTube channel to watch the course (3-hour watch). Whether you're looking to enhance your current projects or embark on new ones, this course will help you master MacOS application development.

This comprehensive tutorial will guide you through every step of the development process, from setting up your local development environment to implementing various screens and functionalities within the app. You'll also learn how to incorporate TypeScript for type safety, use NativeWind for styling, and manage your app's navigation and state effectively.

Here's a glimpse of what you'll learn in this course:

Introduction

You will start by understanding the fundamentals of creating a meditation app using Expo and React Native, providing a solid foundation for the rest of the project.

Setup Local Development Environment

Learn how to set up your local development environment, including installing necessary tools and dependencies to get started with Expo and React Native.

Add Static Assets and Define Constant Files

Understand how to add static assets such as images and icons to your project and define constant files for better organization and maintainability.

Setup NativeWind

Explore how to set up NativeWind for styling your application components in a consistent and efficient manner.

Implement Initial Screen

Implement the initial screen of your meditation app, laying the groundwork for a smooth user experience.

Splash Screen Image

Create an engaging splash screen image to enhance the visual appeal of your app during the startup phase.

The useRouter Hook

Learn to use the useRouter hook for handling navigation within your app, ensuring seamless transitions between different screens.

Add AppGradient Component and Tabs Directory

Enhance your app's UI by adding a gradient component and organizing your tabs directory for better structure and navigation.

The Meditation Index Screen

Build the Meditation Index Screen, where users can browse through available meditation sessions.

Use FlatList on the Meditation Index Screen

Implement FlatList to efficiently display a list of meditation sessions, ensuring a smooth scrolling experience.

The Affirmations Index Screen

Create an Affirmations Index Screen, allowing users to explore various positive affirmations.

The Affirmations Detail Screen

Develop the Affirmations Detail Screen to provide more information and details about each affirmation.

The Meditation Detail Screen

Implement the Meditation Detail Screen, giving users access to specific meditation session details and options.

Meditation Audio/Song

Incorporate meditation audio or songs into your app, enhancing the overall meditation experience for users.

React Context and Modal Screen

Learn how to use React Context for state management and create a modal screen for additional interactive elements within your app.

By the end of this course, you will have built a fully functional meditation app while gaining valuable experience with Expo, React Native, TypeScript, and other essential tools. Whether you're a beginner or an experienced developer, this course offers something for everyone, helping you grow your skills and create impactful mobile applications.

Watch the full course on the freeCodeCamp.org YouTube channel (2-hour watch).

When building mobile applications, one common requirement is the ability to save data locally on the device. This is when local storage comes into play. Async Storage, provided by React Native Expo, is a simple but powerful solution for saving data locally within your React Native Expo apps.

In this tutorial, we'll discuss the fundamentals of local storage, introduce Async Storage, and demonstrate how to properly integrate it into React Native Expo projects.

Table of Contents

• Prerequisites
• What is Local Storage?
• What is Async Storage?
• How to Get Started with Async Storage
• Understanding Async Storage Methods
• Advanced Usage and Best Practices
• Conclusion

Prerequisites

• Familiarity with React Native and JavaScript.
• Node.js and npm (or yarn) installed.

What is Local Storage?

Local storage is an essential component of mobile app development, allowing developers to store data on the user's device. Unlike other storage choices such as databases, Local Storage uses a straightforward key-value pair storage technique.

Developers can use it to save small quantities of data that remain stored even when they close the program or restart the device. This makes it excellent for storing user preferences, authentication tokens, and other important information.

Local storage is essential for boosting app speed because it eliminates the need to retrieve data from faraway servers regularly.

What is Async Storage?

Async Storage is a key-value storage system supplied by React Native Expo that allows you to manage local storage in mobile apps. It provides a simple key-value storage system that enables developers to store and retrieve data asynchronously.

Unlike synchronous storage methods, Async Storage allows you to save and retrieve data without interrupting the main thread, resulting in a more seamless user experience.

How to Get Started with Async Storage

To use Async Storage in your React Native Expo project, ensure that Expo is installed. If you haven't already set up a React Native Expo project, you can do so by installing Expo CLI:

$ npm install -g expo-cli

Create a new Expo project:

$ expo init MyProject
$ cd MyProject

To add Async Storage to your project, run the following command:

$ expo install @react-native-async-storage/async-storage

The @react-native-async-storage/async-storage is a community-maintained version of AsyncStorage. Once installed, you can then setup a file to handle the AsyncStorage methods such as setItem(), updateItem(), deleteItem(), and others. This file would be imported whenever you want to make a call to the local storage.

In this example, we'll create a folder named utils in the root path of our project and then create the AsyncStorage.js file to handle these methods:

Async Storage File Structure

Within the AsyncStorage.js file, you can define the AsyncStorage methods like this:

// utils/AsyncStorage.js

import AsyncStorage from '@react-native-async-storage/async-storage';

export const setItem = async (key, value) => {
  try {
    await AsyncStorage.setItem(key, JSON.stringify(value));
  } catch (error) {
    console.error('Error setting item:', error);
  }
};

export const getItem = async (key) => {
  try {
    const value = await AsyncStorage.getItem(key);
    return value != null ? JSON.parse(value) : null;
  } catch (error) {
    console.error('Error getting item:', error);
    return null;
  }
};

export const removeItem = async (key) => {
  try {
    await AsyncStorage.removeItem(key);
  } catch (error) {
    console.error('Error removing item:', error);
  }
};

export const mergeItem = async (key, value) => {
  try {
    await AsyncStorage.mergeItem(key, JSON.stringify(value));
  } catch (error) {
    console.error('Error merging item:', error);
  }
};

export const clear = async () => {
  try {
    await AsyncStorage.clear();
  } catch (error) {
    console.error('Error clearing AsyncStorage:', error);
  }
};

export const getAllKeys = async () => {
  try {
    return await AsyncStorage.getAllKeys();
  } catch (error) {
    console.error('Error getting all keys:', error);
    return [];
  }
};

export const getAllItems = async () => {
  try {
    const keys = await AsyncStorage.getAllKeys();
    const items = await AsyncStorage.multiGet(keys);
    return items.reduce((accumulator, [key, value]) => {
      accumulator[key] = JSON.parse(value);
      return accumulator;
    }, {});
  } catch (error) {
    console.error('Error getting all items:', error);
    return {};
  }
};

Moving forward, In the next section, we'll explain and break down the meaning of these AsyncStorage functions in the AsyncStorage.js file.

Understanding Async Storage Methods

By separating AsyncStorage functions into their own file, you can conveniently manage and reuse them throughout your React Native Expo project. This modular approach improves code maintenance and readability.

In the previous section, we created the AsyncStorage.js file and added several functions.

In the following sections, we'll talk about these methods and how to use them effectively.

setItem()

This method is essential for storing data locally on the device. It allows developers to store key-value pairs in AsyncStorage, where the key serves as a unique identifier and the value represents the data to be stored.

await AsyncStorage.setItem('username', 'freeCodeCamp');

getItem()

The getItem() method returns the value associated with a given key from local storage. It sends a parameter/key, which is the unique identification of the data being requested. And it returns the value associated with the supplied key, or null if no value is discovered for the given key.

const username = await AsyncStorage.getItem('username');

In this scenario, the value for the key username is fetched from local storage. This obtained value, freeCodeCamp, is then placed in the variable username, making it available for further use across the application.

removeItem()

This function deletes the object with the supplied key from local storage. It's useful when you want to remove a specific piece of data that's no longer required.

await AsyncStorage.removeItem('username');

In this example, the object identified by the key username is removed from local storage.

mergeItem()

The mergeItem() method combines the value of an existing key with the value supplied as input. If the key do not exists, it works similarly to setItem(), creating a new key-value pair.

await AsyncStorage.mergeItem('user', JSON.stringify({ name: 'John' }));

clear()

The clear() method deletes all items from local storage. It's useful when you wish to delete all local data, such as when you log out of a user or reset the application state.

await AsyncStorage.clear();

getAllKeys()

The getAllKeys() function returns all keys kept in local storage. It's useful when you need to loop through all keys or conduct operations based on the keys in local storage.

const keys = await AsyncStorage.getAllKeys();

multiGet()

The multiGet() function obtains several key-value pairs from local storage using an array of keys provided.

const data = await AsyncStorage.multiGet(['username', 'email']);

In this example, the values for the keys username and email are fetched from local storage.

Advanced Usage and Best Practices

While AsyncStorage provides a straightforward interface for local storage, there are several best practices to consider:

1. Data Serialization: When storing complex data types such as objects or arrays, remember to serialize them into a string format using JSON.stringify() before storing and deserialize them using JSON.parse() when retrieving.
2. Error Handling: Implement robust error handling to gracefully handle any failures that may occur during Async Storage operations.
3. Security Considerations: Be mindful of the sensitivity of the data being stored locally and implement appropriate security measures such as encryption for sensitive information.

Conclusion

In conclusion, using local storage into your React Native Expo projects is essential for developing robust and responsive mobile applications. Async Storage simplifies the process of storing and retrieving data on the device, providing a consistent user experience and enabling offline functionalities.

By following the steps provided in this article, you can utilize Async Storage to improve your apps local storage functionality.

Remember, if you have any questions or just want to say hi, feel free to reach me on X(Twitter) or my website. :)

Note that this tutorial is not applicable for apps created with Expo.

SVG Icon Image and Background

The first thing you need is an image. It can be in any format, but I recommend using SVG because, from it, you will generate icons of various sizes for different types of Android and iOS devices.

You will also need a background color that complements or contrasts your project's primary color. In my case, I will use #074C4E.

icon imagem and backgorund color

Add the Image to the Project

Next, add the SVG image to your project. It doesn't matter where. The most important thing is remembering the path because you will need to reference it later.

In my case, I placed it in src/assets/svgs/logo-vertical-white.svg.

How to Use the react-native-bootsplash Library

You will use the [react-native-bootsplash](https://github.com/zoontek/react-native-bootsplash) library to create native splash screens. This library will help you in three essential areas to guarantee your users an excellent experience when encountering the splash screen.

1. Native Splash Screens: React Native apps have a "JavaScript side" that only loads after the native side is ready. Therefore, to present a splash screen quickly, a native experience is necessary. The good news is that all the code is already inside the library, so you just need to connect it to your project.
2. Generation of Images and Files: When creating native splash screens, it is necessary to create specific image files for each platform. This can be done through tools like Xcode and Android Studio. Fortunately, the library comes with a CLI (command-line interface) that allows you to generate these files with just one command!
3. Hide at the Right Moment: In many cases, even after the native side has loaded, the app may still not be ready to display content to the user. On the JavaScript side, you still need to load your navigation stack, fetch the user's authentication status, or call the API to fetch some data. With the react-native-bootsplash, you can choose when to hide the splash screen.

First, let's add the library. As I am using Yarn as my dependency manager, I will execute the command:

yarn add react-native-bootsplash

Since the library has native dependencies, you need to install the pods on the iOS side. Inside the ios folder, run the following command:

pod install

Great, the library installation is complete 😁. In case you're wondering, the native Android dependencies are automatically installed when you run the yarn android command. We'll do this later after finishing the setup.

How to Generate the Splash Screen Files

In addition to installing the library, you need to generate the files and images mentioned earlier and update a few native files after that.

The react-native-bootsplash has a command that helps us create all the necessary native files and images to create a native Android and iOS splash screen.

It's worth mentioning that the library also has a premium option, where you can buy a license key to unlock extra CLI commands, like adding more than one icon on the screen and generating different images for Dark Mode. You will use the simplest splash screen, so you don't need a license key. But I highly recommend it if you have any of the use cases mentioned above and also to support the library's author, who does an incredible job.

To generate the files, you'll need the following to run the command, which you should customize according to your project:

1. File path and name: src/assets/svgs/logo-vertica-white.svg
2. The background color: 074C4E
3. The logo width: 105

yarn react-native generate-bootsplash src/assets/svgs/logo-vertica-white.svg \\
   --platforms=android,ios \\
   --background=074C4E \\
   --logo-width=105

After running this command, you will see that the native image files, color, and storyboard have been successfully generated.

terminal output

How to Connect the Library to the Project

It is time to integrate the library and newly created splash screen with the project by modifying some native files.

iOS - AppDelegate.mm

On iOS, the file where you configure libraries with native dependencies is the AppDelegate.mm.

And you will do this in two steps. First, import the library at the top of the file:

#import "RNBootSplash.h"

importing BootSplash on AppDelegate

The second change in this file is to add the function that will connect the native and JavaScript sides. Add this snippet at the end of the project before the last @end. The code will be different if you use a react-native version below 0.74.

// ⬇️ Add this before file @end (for react-native 0.74+)
- (void)customizeRootView:(RCTRootView *)rootView {
  [RNBootSplash initWithStoryboard:@"BootSplash" rootView:rootView]; // ⬅️ initialize the splash screen
}

// OR

// ⬇️ Add this before file @end (for react-native < 0.74)
- (UIView *)createRootViewWithBridge:(RCTBridge *)bridge
                          moduleName:(NSString *)moduleName
                           initProps:(NSDictionary *)initProps {
  UIView *rootView = [super createRootViewWithBridge:bridge moduleName:moduleName initProps:initProps];
  [RNBootSplash initWithStoryboard:@"BootSplash" rootView:rootView]; // ⬅️ initialize the splash screen
  return rootView;
}

In my case, I am on react-native 0.73, so my modification looks like this:

added createRootViewWithBridge (react-native < 0.74)

Android - styles.xml

On Android, you need to change three native files. Let's start with styles.xml.

Inside the android/app/src/main/res/values/styles.xml file, add the following code snippet inside the resources tag. Remember, there is already a style tag within it – do not replace it. Add an extra one.

<style name="BootTheme" parent="Theme.BootSplash">
    <item name="bootSplashBackground">@color/bootsplash_background</item>
    <item name="bootSplashLogo">@drawable/bootsplash_logo</item>
    <item name="postBootSplashTheme">@style/AppTheme</item>
</style>

styles.xml

Android - AndroidManifest.xml

To connect the splash screen in the file android/app/src/main/AndroidManifest.xml, you have to add the property android:theme="@style/BootTheme" inside the activity.

My AndroidManifest.xml

Android - Modify the MainActivity.java/kt

You need to initiate the splash screen within the MainActivity. Depending on your version of React Native, your file may have a Java or Kotlin extension. You have to modify or create the onCreate method if it does not exist.

I literally copied the code below from the library README file, so you don't need to jump there but feel free to check it here.

// Java (react-native < 0.73)
// …

// add these required imports:
import android.os.Bundle;
import com.zoontek.rnbootsplash.RNBootSplash;

public class MainActivity extends ReactActivity {

  // …

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    RNBootSplash.init(this, R.style.BootTheme); // ⬅️ initialize the splash screen
    super.onCreate(savedInstanceState); // super.onCreate(null) with react-native-screens
  }
}

My final MainActivity.java

Hide the Splash Screen

The implementation is ready for both platforms! But before running the app, you must hide the splash screen at some point on the JavaScript side; otherwise, the app will open and get stuck.

Of course, where to put it depends significantly on what you need to load for your app to be ready to display to the user. A classic example is waiting for React Navigation to load the navigation stack, which is signaled through the onReady callback.

import BootSplash from 'react-native-bootsplash';
// ...

export function Router() {
    // ...
    return (
    <NavigationContainer onReady={() => BootSplash.hide({fade: true})}>
      {Stack}
    </NavigationContainer>
  );
}

You are ready to go!

Your splash screen is ready for use! However, since you modified native files, rebuilding the app is necessary. To do this, run the commands yarn ios and yarn android to see how your implementation works.

Thanks for reading! If you speak Portuguese and would like more content about React Native, subscribe to my YouTube channel here.

The application leverages some of Supabase's features, such as authentication and database storage, to build a secured full-stack mobile application.

Additionally, you'll learn how to create React Native applications with Expo, generate a set of questions and answers from ChatGPT, and perform CRUD operations and user authentication with Supabase.

To fully understand this tutorial, you'll need to have a basic knowledge of React Native and data fetching in React applications.

Table of Contents

• Mobile Application Demo
• How to set up a React Native application with Expo
• How to style the React Native application with Tailwind CSS
• How to build the application screens
• How to build the authentication screens
• How to build the tab screens
• How to build the stack screens
• How to generate quiz questions and answers from ChatGPT
• How to add Supabase to React Native
• How to add Supabase authentication to React Native applications
• How to sign up new users
• How to sign in existing users
• How to log users out of the application
• How to protect screens from unauthenticated users
• How to interact with the Supabase database
• How to save user's score to the database
• How to retrieve data from Supabase
• Conclusion

Mobile Application Demo

To preview the application, download Expo Go and paste the links below into the app URL field:

Android: exp://u.expo.dev/update/a4774250-e156-4d34-bcfc-a4f2549c2e1d
iOS: exp://u.expo.dev/update/7e5f8ba5-89c4-4c1d-b219-a613ace642df

Scan the QR code to preview the mobile quiz application within the Expo Go application

How to Set Up a React Native Application with Expo

Expo is an open-source platform that allows you to create cross-platform applications easily with JavaScript. It saves us from the complex configurations required to create a native application with the React Native CLI, making it the easiest and fastest way to build and publish React Native apps.

Execute the code snippet below to create a new Expo project that uses Expo Router for navigating between screens.

npx create-expo-app@latest --template tabs@50

Expo Router is an open-source file-based routing system that enables users to navigate between screens easily. It is similar to Next.js, where each file name represents its route name.

Start the development server to ensure that the app is working as expected.

npx expo start

How to style the React Native application with Tailwind CSS

Tailwind CSS is a CSS framework that lets you create modern and stunning applications easily.

However, to style Expo applications using Tailwind CSS, you need to install NativeWind – a library that uses Tailwind CSS as its scripting language.

Run the code snippet below to install NativeWind and its dependencies:

npx expo install nativewind@^4.0.1 react-native-reanimated tailwindcss

Execute npx tailwindcss init within your terminal to create a tailwind.config.js file. Update the file with the code snippet below:

/** @type {import('tailwindcss').Config} */
module.exports = {
    content: ["./app/**/*.{js,jsx,ts,tsx}"],
    presets: [require("nativewind/preset")],
    theme: {
        extend: {},
    },
    plugins: [],
};

Create a globals.css file within the root of your project and add the Tailwind directives below:

@tailwind base;
@tailwind components;
@tailwind utilities;

Update the babel.config.js file with the code below:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [
      ["babel-preset-expo", { jsxImportSource: "nativewind" }],
      "nativewind/babel",
    ],
  };
};

Create a metro.config.js file within the root of your project and paste the code snippet below into the file:

const { getDefaultConfig } = require("expo/metro-config");
const { withNativeWind } = require('nativewind/metro');

const config = getDefaultConfig(__dirname)

module.exports = withNativeWind(config, { input: './globals.css' })

Finally, import the ./globals.css file into the app/_layout.tsx file to enable you to style your application with Tailwind CSS:

//👉🏻 Within ./app/_layout.tsx

import "../globals.css";

Great job on creating the React Native project with Expo! Now, you're ready to add some style using Tailwind CSS. If you encounter any problems while installing NativeWind, check out the documentation for a step-by-step guide.

How to Build the Application Screens

Here, I'll guide you through building the application screens. They are divided into three categories:

• The Authentication screens – the register and login screens.
• The Tab layout screens – the dashboard, leaderboard, and profile screens.
• The Stack screens – the test and test completion screens.

The application prompts new users to create an account and log in before allowing access to the Tab layout screens.

On the dashboard screen, users can take tests on various topics. The leaderboard screen showcases the top ten users. Users can log out or preview their previous attempts on the profile page.

Application Demo

How to Build the Authentication Screens

The authentication screens accept the user's email and password and ensure the credentials are valid before creating an account or granting access to the application.

The Authentication Screens

Create an index.tsx and a register.tsx file within the app folder and a component that accepts the user's email and password using the React Native TextInput component.

import { Text, View, TextInput, Pressable, Alert } from "react-native";
import { Link, useRouter } from "expo-router";
import { useState } from "react";

export default function LoginScreen() {
    const [email, setEmail] = useState<string>("");
    const [password, setPassword] = useState<string>("");
    const [loading, setLoading] = useState<boolean>(false);
    const router = useRouter();

    //👇🏻 triggered when the user submits the email & password
    const handleLogin = () => {
        if (!email.trim() || !password.trim())
            return Alert.alert("Error", "Please fill in all fields");
        setLoading(true);
        console.log({
            email,
            password,
        });
        router.replace("/(tabs)/");
    };

    return (
        <View>
        {/** -- user interface--*/}
        </View>
    );
}

The code snippet stores the user's email and password in states using the React useState hook. The handleLogin function accepts the user's email and password when the form is submitted and ensures that they are not empty before logging them to the console and redirecting the user to the Dashboard page.

You can create the user interface using the code snippet below. It displays the input fields for the user's credentials and an interactive Sign-in button that executes the handleLogin function. Additionally, the loading state ensures that the button is only pressed once.

<View className=' flex-1'>
    <View className='w-full px-4'>
        <Text className='text-3xl mb-4 font-bold text-white text-center'>
            Log in
        </Text>

        <Text className='text-lg text-gray-200'>Email Address</Text>
        <TextInput
            className='w-full border-b-[1px] py-4 rounded-md mb-3 text-white font-bold'
            value={email}
            onChangeText={setEmail}
        />
        <Text className='text-lg text-gray-200'>Password</Text>
        <TextInput
            className='w-full border-b-[1px] py-4 rounded-md mb-3 text-white font-bold'
            secureTextEntry
            value={password}
            onChangeText={setPassword}
        />
        <Pressable
            className={`w-full ${
                loading ? "bg-orange-200" : "bg-orange-600"
            } rounded-xl p-4 border-[1px] border-orange-200`}
            disabled={loading}
            onPress={() => handleLogin()}
        >
            <Text className='text-white text-center font-bold text-xl'>
                {loading ? "Authenticating..." : "Sign in"}
            </Text>
        </Pressable>
        <Text className='text-center mt-2 text-orange-200'>
            Don't have an account?{" "}
            <Link href='/register'>
                <Text className='text-white'>Register</Text>
            </Link>
        </Text>
    </View>
</View>

For instance, the loading state becomes true when a user clicks the Sign-in button. The Pressable component (button) has a disabled attribute set to the loading state to ensure that the user does not press the button multiple times. Additionally, you can use the loading state to notify the user that the request is processing.

The register.tsx file is also similar to the login.tsx file. You only need to change the words from Login to Register.

How to Build the Tab Screens

The Tab Screens consist of the Dashboard, Leaderboard, and Profile screens.

The Tab Screens

Create a (tabs) folder containing index.tsx, leaderboard.tsx, profile.tsx, and _layout.tsx files within the app folder.

cd app
mkdir (tabs)
cd (tabs)
touch index.tsx leaderboard.tsx profile.tsx _layout.tsx

After creating the _layout.tsx file within the (tabs) folder, update the _layout.tsx to specify Tab screen navigation for the newly created screens. The screens use icons from the Expo Vector Icons library.

import { Tabs } from "expo-router";
import { Ionicons, MaterialIcons, FontAwesome5 } from "@expo/vector-icons";
import { ActivityIndicator } from "react-native";

export default function TabScreen() {
    return (
        <Tabs
            screenOptions={{
                tabBarActiveTintColor: "#f97316",
                tabBarInactiveTintColor: "gray",
                tabBarShowLabel: false,
                headerShown: false,
                tabBarStyle: {
                    backgroundColor: "#ffedd5",
                    borderTopColor: "#ffedd5",
                },
            }}
        >
            <Tabs.Screen
                name='index'
                options={{
                    tabBarIcon: ({ color }) => (
                        <Ionicons name='home' size={24} color={color} />
                    ),
                }}
            />
            <Tabs.Screen
                name='leaderboard'
                options={{
                    tabBarIcon: ({ color }) => (
                        <MaterialIcons name='leaderboard' size={24} color={color} />
                    ),
                }}
            />
            <Tabs.Screen
                name='profile'
                options={{
                    tabBarIcon: ({ color }) => (
                        <FontAwesome5 name='user-alt' size={24} color={color} />
                    ),
                }}
            />
        </Tabs>
    );
}

Next, update the RootLayoutNav component within the _app/layout.tsx file to render all the screens within the application.

function RootLayoutNav() {
    return (
        <Stack screenOptions={{ headerShown: false }}>
            <Stack.Screen name='(tabs)' />
            <Stack.Screen name='(stack)' />
            <Stack.Screen name='index' />
            <Stack.Screen name='register' />
        </Stack>
    );
}

The Dashboard Screen

Update the component to allow users to select four categories from a list of categories.

export default function HomeScreen() {
    const greet = getGreeting();
    const router = useRouter();
    const { session } = useAuth();
    const [loading, setLoading] = useState<boolean>(false);
    const [userCategories, setUserCategories] = useState<string[]>([]);

    const fetchQuestions = async () => {};

    const handleStartTest = async () => {
        Alert.alert("Start Test", "Are you sure you want to start the test?", [
            {
                text: "Cancel",
                style: "destructive",
            },
            {
                text: "Yes",
                onPress: () => fetchQuestions(),
            },
        ]);
    };

    return (
        <SafeAreaView className='flex-1 bg-orange-100 px-4 py-2'>
            <View className='flex flex-row items-center justify-between mb-2'>
                <View>
                    <Text className='font-bold text-2xl mb-[1px]'>
                        Good morning
                        <Ionicons name='partly-sunny-sharp' size={24} color='orange' />
                    </Text>

                    <Text className='text-lg'>Welcome User</Text>
                </View>
            </View>
            {userCategories.length === 4 && (
                <Pressable
                    className={`w-full h-[70px] flex items-center justify-center ${
                        loading ? "bg-orange-300" : "bg-orange-500"
                    } rounded-xl mb-2`}
                    disabled={loading}
                    onPress={() => handleStartTest()}
                >
                    <Text className='text-xl font-bold text-orange-50'>
                        {loading ? "Loading questions..." : "START TEST"}
                    </Text>
                </Pressable>
            )}

            <View className='w-full flex-1'>
                <Text className='text-xl font-bold text-orange-500 mb-4'>
                    Available Categories
                </Text>
                <FlatList
                    data={categories}
                    numColumns={2}
                    contentContainerStyle={{ width: "100%", gap: 10 }}
                    columnWrapperStyle={{ gap: 10 }}
                    renderItem={({ item }) => (
                        <Categories
                            item={item}
                            userCategories={userCategories}
                            setUserCategories={setUserCategories}
                        />
                    )}
                    showsVerticalScrollIndicator={false}
                    keyExtractor={(item) => item.id}
                />
            </View>
        </SafeAreaView>
    );
}

The code snippet above renders a list of categories where users can select only four categories to answer questions on and start the quiz.

The Dashboard Screen

The Leaderboard Screen

The Leaderboard screen displays the top ten users ranked in descending order.

import { Text, FlatList, SafeAreaView } from "react-native";
import Board from "../../components/Board";

interface Props {
    total_score: number;
    user_id: string;
}

export default function LeaderboardScreen() {
    const [leaderboard, setLeaderboard] = useState<Props[]>([]);

    return (
        <SafeAreaView className='flex-1 bg-orange-100 p-4'>
            <Text className='text-2xl font-bold text-gray-500 text-center mb-6'>
                Leaderboard
            </Text>

            <FlatList
                data={leaderboard}
                renderItem={({ item }) => <Board item={item} />}
                keyExtractor={(item) => item.user_id}
                showsVerticalScrollIndicator={false}
            />
        </SafeAreaView>
    );
}

The code snippet above renders a FlatList with ten items. You can create an array containing ten users and pass it into the FlatList for now.

The Profile Screen

The Profile Screen displays the user's image, recent attempts, and a log-out button that enables the user to sign out of the application.

export default function ProfileScreen() {
    const [loading, setLoading] = useState<boolean>(false);
    const [total_score, setTotalScore] = useState<number>(0);
    const [attempts, setAttempts] = useState<string[]>([]);

    const handleSignOut = async () => {
        setLoading(true);
    };

    return (
        <SafeAreaView className='flex-1 bg-orange-100 p-4'>
            <View className='flex items-center justify-center mb-6'>
                <Text className='text-gray-600 mb-[1px]'>
                    <FontAwesome name='star' size={20} color='red' />
                    <Text>45</Text>
                </Text>
                <Text className='text-gray-600 mb-2'>@dhastix</Text>

                <Pressable onPress={() => handleSignOut()} disabled={loading}>
                    <Text className='text-red-500'>
                        {loading ? "Logging out..." : "Log out"}
                    </Text>
                </Pressable>
            </View>

            <Text className='font-bold text-xl text-gray-700 mb-3 px-4'>
                Recent Attempts
            </Text>

            <FlatList
                data={attempts}
                contentContainerStyle={{ padding: 15 }}
                renderItem={({ item }) => <Attempts item={item} />}
                keyExtractor={(item, index) => index.toString()}
                showsVerticalScrollIndicator={false}
            />
        </SafeAreaView>
    );
}

The code snippet above displays the user's image, the sign-out button, and all the user's attempts. You can create an array of items for testing purposes.

How to Build the Stack Screens

The Stack Screens comprise two screens – the quiz screen and the screen that displays the user's score after completing a quiz session.

The Stack Screens

The Quiz Screen

The Quiz Screen displays a timer that countdowns from 15 seconds before moving to the next question. It shows the question, its category, available options, the Skip and Next buttons, and a cancel icon.

Create a similar screen to the one shown below. You can use this as a guide.

The Quiz Screen

The Quiz Completion Screen

It displays the user's score after completing a test.

import {
    SafeAreaView,
    Text,
    Pressable,
    View,
    ImageBackground,
} from "react-native";
import { MaterialIcons } from "@expo/vector-icons";
import { useLocalSearchParams } from "expo-router";

export default function CompletedScreen() {
    const { score } = useLocalSearchParams();

    return (
        <View className='flex flex-1 bg-orange-400'>
            <ImageBackground
                source={{ uri: "https://source.unsplash.com/NAP14GEjvh8" }}
                className='flex-1 p-4'
            >
                <SafeAreaView />
                <Pressable onPress={() => router.replace("/(tabs)/")}>
                    <MaterialIcons name='cancel' size={60} color='white' />
                </Pressable>

                <View className='flex-1 flex items-center justify-center'>
                    <View className='bg-orange-50 w-full py-[50px] rounded-xl p-4 flex items-center justify-center shadow-lg shadow-orange-500'>
                        <Text className='text-3xl text-orange-600 font-bold mb-4'>
                            {Number(score) > 20 ? "Congratulations🥳" : "Sorry! You lose 🥲"}
                        </Text>
                        <Text className='font-bold text-xl'>You scored {score}!</Text>
                    </View>
                </View>
            </ImageBackground>
        </View>
    );
}

The code snippet above accepts the user's score as a parameter after completing the quiz and displays the score to the user.

How to Generate Quiz Questions and Answers from ChatGPT

When building a quiz application, the first question is: how do you get the questions and options for the application? You can either create a list of questions or search for a suitable public API.

However, I'll guide you through creating a list of questions and options in JSON format using ChatGPT. Use this prompt to generate questions and answers from ChatGPT:

Generate 25 distinct questions on and ensure they are in JSON format containing an id, category which is , a question attribute containing the question, an options array of 3 options, and an answer property.

The prompt returns a JSON result containing the questions and answers. You can host them on GitHub or save them to a database.

The questions and answers I'm using in this mobile application are available on GitHub. Feel free to clone or copy the files.

Once your questions and answers are ready, you can connect the application to Supabase.

How to Add Supabase to React Native

Supabase is an open-source Firebase alternative that enables you to create secured and scalable software applications within a few minutes.

It provides a secured Postgres database, a complete user management system that handles various forms of authentication (including email and password, email sign-in, and social authentication), a file storage system that lets you store and serve files of any size, real-time communication, and many other features.

In this tutorial, I'll walk you through the following:

• How to authenticate users and control access to some application screens with Supabase.
• How to save the users' scores to the database to enable you to rank them based on their scores.

First, you need to install Supabase and its required dependencies. You can do that with the following commands:

npm install @supabase/supabase-js 
npm install react-native-elements @react-native-async-storage/async-storage react-native-url-polyfill
npx expo install expo-secure-store

Create a supabase.ts file within your project and copy the code snippet below into the file to initiate Supabase:

import "react-native-url-polyfill/auto";
import * as SecureStore from "expo-secure-store";
import { createClient } from "@supabase/supabase-js";

const ExpoSecureStoreAdapter = {
    getItem: (key: string) => {
        return SecureStore.getItemAsync(key);
    },
    setItem: (key: string, value: string) => {
        SecureStore.setItemAsync(key, value);
    },
    removeItem: (key: string) => {
        SecureStore.deleteItemAsync(key);
    },
};

const supabaseUrl = "YOUR_REACT_NATIVE_SUPABASE_URL";
const supabaseAnonKey = "YOUR_REACT_NATIVE_SUPABASE_ANON_KEY";

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
    auth: {
        storage: ExpoSecureStoreAdapter as any,
        autoRefreshToken: true,
        persistSession: true,
        detectSessionInUrl: false,
    },
});

Next, visit the Supabase homepage, sign in, and create a new organization and project.

Create a new Supabase project

Click the Settings icon on the sidebar and select API to copy the project URL and the public API key.

Supabase API settings containing project credentials

Create a .env.local file and copy the credentials into the variables. Update the supabase.ts file to use the Supabase URL and API key.

EXPO_PUBLIC_API_URL=<YOUR_SUPABASE_URL>
EXPO_PUBLIC_API_KEY=<YOUR_SUPABASE_API_KEY>

Congratulations! You can now interact with Supabase from your application and access various features such as authentication, database, file storage, and so on.

How to Add Supabase Authentication to React Native Applications

Supabase offers various forms of authentication. But we only need the email and password method of authentication for this application.

How to sign up new users

The code snippet below accepts an email and a password and creates an account for the user. Otherwise, it returns an error if any of the credentials is invalid.

//👇🏻 import supabase from supabase file
import { supabase } from "../lib/supabase";

//👇🏻 sign up function
const handleRegister = async () => {
    if (!email.trim() || !password.trim())
        return Alert.alert("Error", "Please fill in all fields");
    const { error } = await supabase.auth.signUp({ email, password });
    if (error) return Alert.alert("Error", error.message);
    router.replace("/");
};

With the supabase.auth.signUp() function, Supabase handles the authentication process. If successful, the user is redirected to the login page. Otherwise, it displays an error message.

How to sign in existing users

This function allows existing users to access the application. It accepts the user's email and password and logs the user into the application.

//👇🏻 import supabase from supabase file
import { supabase } from "../lib/supabase";

//👇🏻 register function
const handleLogin = async () => {
    if (!email.trim() || !password.trim())
        return Alert.alert("Error", "Please fill in all fields");
    const { error } = await supabase.auth.signInWithPassword({ email, password });
    if (error) return Alert.alert("Error", error.message);
    router.replace("/(tabs)/");
};

The supabase.auth.signInWithPassword() function validates the user's email and password and redirects the user to the Dashboard screen. Otherwise, it returns the necessary authentication error.

How to log users out of the application

Supabase also allows users to sign out of the application. You can execute this function when the user clicks a button within the Profile page.

//👇🏻 import supabase from supabase file
import { supabase } from "../lib/supabase";

//👇🏻 sign out function
const handleSignOut = async () => {
    try {
        const { error } = await supabase.auth.signOut();
        if (error) throw error;
    } catch (error) {
        console.log(error);
    }
};

How to protect screens from unauthenticated users

You've been able to add the sign-up, sign-in, and log-out functionalities to the React Native application. But the Dashboard and other screens containing sensitive data are still accessible to unauthenticated users.

How do we fix this?

In this section, I'll walk you through how to protect screens from unauthorized users using the React Context API.

The React Context API allows us to pass data through the component tree without needing to pass props down manually at every level.

Create an AuthProvider.tsx file. This is where the data to be passed down the application screens is stored. Copy the code snippet below into the file:

import { supabase } from "./supabase";
import { Session } from "@supabase/supabase-js";
import {
    PropsWithChildren,
    createContext,
    useContext,
    useEffect,
    useState,
} from "react";

type AuthData = {
    session: Session | null;
    loading: boolean;
};

//👇🏻 data to be passed down the components
const AuthContext = createContext<AuthData>({
    session: null,
    loading: true,
});

export default function AuthProvider({ children }: PropsWithChildren) {
    const [session, setSession] = useState<Session | null>(null);
    const [loading, setLoading] = useState(true);

    //👇🏻 fetches the current user's session
    useEffect(() => {
        const fetchSession = async () => {
            const {
                data: { session },
            } = await supabase.auth.getSession();
            setSession(session);
            setLoading(false);
        };

        fetchSession();
        supabase.auth.onAuthStateChange((_event, session) => {
            setSession(session);
            setLoading(false);
        });
    }, []);

    return (
        <AuthContext.Provider value={{ session, loading }}>
            {children}
        </AuthContext.Provider>
    );
}
//👇🏻 custom hook for using the context (data)
export const useAuth = () => useContext(AuthContext);

The code snippet retrieves the current user's session. If the user is signed in, the session and loading state variables are updated to show that the user is active, and they are passed into other components within the application.

The useAuth custom hook allows you to access the state variables (session and loading) within the application screens.

To access the context (data) available within the application screens, wrap the entire application with the AuthProvider. So now, update the RootLayoutNav component within the app/_layout.tsx file as shown below:

import AuthProvider from "../lib/AuthProvider";

function RootLayoutNav() {
    return (
        <AuthProvider>
            <Stack screenOptions={{ headerShown: false }}>
                <Stack.Screen name='(tabs)' />
                <Stack.Screen name='(stack)' />
                <Stack.Screen name='index' />
                <Stack.Screen name='register' />
            </Stack>
        </AuthProvider>
    );
}

Congratulations! You've successfully set up the context. Next, how do we read the context and ensure that only authenticated users can view some of the application screens?

You can do this using the custom useAuth hook. For example, you can protect the Tabs screens via the (tabs)/_layout.tsx file.

import { Tabs, Redirect } from "expo-router";
import { useAuth } from "../../lib/AuthProvider";
import { ActivityIndicator } from "react-native";

export default function TabScreen() {
    const { session, loading } = useAuth();

    if (!session) {
        return <Redirect href='/' />;
    }

    if (loading) {
        return <ActivityIndicator size='large' color='#f97316' />;
    } else {
        return (
            <Tabs
                screenOptions={{
                    tabBarActiveTintColor: "#f97316",
                    tabBarInactiveTintColor: "gray",
                    tabBarShowLabel: false,
                    headerShown: false,
                    tabBarStyle: {
                        backgroundColor: "#ffedd5",
                        borderTopColor: "#ffedd5",
                    },
                }}
            >
                {/**-- screens--*/}
            </Tabs>
        );
    }
}

The code snippet above checks if there is a session for the current user. If null, the application redirects the user to the login screen. If the application is yet to determine the user's status, it displays a loading icon.

How to Interact with the Supabase Database

In this section, I'll walk you through creating the database for the mobile application. You'll learn how to store and retrieve the user's scores and rank them based on their total score.

Before we proceed, note that the application calculates the user's score after answering each question on the test screen. Upon completion, the user's score is retrieved and displayed on the test completion screen.

const handleSave = () => {
    //👇🏻 checks if the user has not completed the test
    if (count < questions.length - 1) {
        //👇🏻 updates the user's score if the selected answer is correct
        if (questions[count].answer === userAnswer) {
            setUserScore((userScore) => userScore + 1);
        }
        //👇🏻 change the question, refresh the selected answer and time
        setCount((count) => count + 1);
        setSelectedBox(null);
        setTime(15);
    } else {
        //👇🏻 test completed
        router.push({
            pathname: "/(stack)/completed",
            params: { score: userScore },
        });
    }
};

Within your Supabase project, select Table Editor from the sidebar menu and create a new table containing the following columns:

• id – contains a unique ID for each row of data.
• created_at – represents the time the data was created.
• attempts – a text array containing the score and date attributes.
• total_score – represents a user's cumulative score. We'll rank users using this score
• user_id – a unique ID used to identify each user's data.

The Table Columns

Finally, you can add a Row Level Security that allows only authenticated users interact with the database.

The Table Row Level Security Policy

How to save the user's score to the database

Before you can save a user's score to the database, you need to check if the user's data already exists – meaning the user has taken a test before. If true, you need to update the user's score with the latest test score. Otherwise, add the data to the database.

The code snippet below accepts the user's score and user's ID (from the session data) and saves the user's score to Supabase.

export const saveScore = async (userScore: number, userID: string) => {
    try {
        //👇🏻 check if the user data exists
        const { data, error } = await supabase
            .from("scores")
            .select()
            .eq("user_id", userID);
        if (error) throw error;

        //👇🏻 if the user data does not exist, insert a new one
        if (error || !data.length) {
            const { data, error } = await supabase
                .from("scores")
                .insert({
                    attempts: [{ score: userScore, date: getCurrentDate() }],
                    total_score: userScore,
                    user_id: userID,
                })
                .single();
            if (error) throw error;
        } else {
            //👇🏻 if the user data exists, update the attempts and total_score
            const { data: updateData, error } = await supabase
                .from("scores")
                .update({
                    attempts: [
                        ...data[0].attempts,
                        { score: userScore, date: getCurrentDate() },
                    ],
                    total_score: data[0].total_score + userScore,
                })
                .eq("user_id", userID);
            if (error) throw error;
        }
    } catch (err) {
        console.log(err);
    }
};

How to retrieve data from Supabase

Recall that you need to rank the users based on their scores on the Leaderboard screen and retrieve the user's attempts on the Profile screen.

The code snippet below accepts a user's ID and retrieves the attempts and total score from the database.

export const getUserAttempts = async (userID: string) => {
    try {
        const { data, error } = await supabase
            .from("scores")
            .select("attempts, total_score")
            .eq("user_id", userID);
        if (error) throw error;
        return { attempts: data[0].attempts, total_score: data[0].total_score };
    } catch (err) {
        return { attempts: "", total_score: 0 };
    }
};

The code snippet below retrieves the top ten users from the database based on their score.

export const getLeaderBoard = async () => {
    try {
        const { data, error } = await supabase
            .from("scores")
            .select("total_score, user_id")
            .order("total_score", { ascending: false })
            .limit(10);
        if (error) throw error;
        return data;
    } catch (err) {
        return null;
    }
};

Congratulations! You've successfully completed the project for this tutorial.

Conclusion

In this tutorial, you’ve learned how to:

• build React Native mobile applications with Expo,
• style your mobile applications with Tailwind CSS,
• create stack and tab screen navigations using Expo Router,
• use Supabase and leverage its authentication and database features to build full-stack applications.

Supabase is an amazing tool that enables you to build a full-stack software application with no hassle. If you are looking forward to shipping great software products or side projects faster, consider using Supabase.

Expo also saves us from the complexities of setting up and developing mobile applications using the React Native CLI. It enables you to focus more on building your applications while it handles the necessary configurations, including deployment.

Feel free to customise the application using ChatGPT to generate questions and answers tailored to any niche or topic.

The source code for this tutorial is available in this GitHub repository.

Thank you for reading!

However, when developing mobile apps with React Native, integrating Tailwind CSS may be challenging. But guess what? Not anymore. With the development of tools such as NativeWind, React Native developers can leverage Tailwind CSS power to design stunning and responsive mobile UIs easily.

In this tutorial, you'll learn the process of integrating Tailwind CSS to your React Native Expo app using NativeWind. We'll also build a simple login screen with NativeWind.

Table of Contents:

• What's NativeWind?
• Prerequisites
• Getting Started
• How to Create A New Expo App
• How to Install NativeWind
• How to Set Up Tailwind CSS
• How to Configure NativeWind With Babel
• How to Style with NativeWind
• How to Build A Simple Login Screen
• Conclusion

What's NativeWind?

NativeWind acts as a bridge between Tailwind CSS and React Native Expo, allowing developers to take advantage of Tailwind's utility-first approach in their mobile app development workflow.

NativeWind provides various benefits to developers, some of these benefits include:

• Familiar Syntax: Developers that are familiar with Tailwind CSS can easily migrate to using NativeWind in their React Native projects, easing the learning curve.
• Consistent Styling: NativeWind ensures consistent styling across platforms by offering a single collection of components and services.
• Flexibility: NativeWind allows developers to easily adapt and extend styles to meet the app's design specifications.

Overall, It provides a collection of components and tools that are very similar to Tailwind CSS, allowing developers to create shorter, more concise code while preserving flexibility and consistency across platforms.

Tailwind makes writing code feel like I’m using a design tool - Didier Catz

Prerequisites

• Basic Understanding of React Native Expo and Tailwind CSS.
• Node.js and npm (or yarn) installed.
• Willingness to learn :)

Getting Started

Before you dive into integrating Tailwind CSS into your React Native Expo app, you'll need to ensure that you have the necessary tools set up.

If you haven't already installed Expo and expo-cli globally, you can do so using npm or yarn:

npm install -g expo-cli

or

yarn global add expo-cli

How to Create A New Expo App

With expo-cli installed, you can now create a new React Native Expo project.

Navigate to the directory where you wish to create your project and open the terminal. You can do this by pressing CTRL + ` on Visual Studio Code. Then execute this command in the terminal:

npx create-expo-app simpleproject

This command creates an expo project in your directory.

How to Install NativeWind

After creating your expo project, you can install NativeWind and its dependencies by running the following commands in your project's directory:

cd simpleproject
npm i nativewind
npm i --dev tailwindcss@3.3.2

or

cd simpleproject
yarn add nativewind
yarn add --dev tailwindcss@3.3.2

Next, you'll need to create a tailwind.config.js file. To do this, run this command in your terminal:

npx tailwindcss init

This would result in a tailwind.config.js file in your project's root directory.

How to Set Up Tailwind CSS

To set up Tailwind CSS in your project, navigate to your tailwind.config.js file, and under content, enter the paths to your components. Your tailwind.config.js file would then look like this:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./App.{js,jsx,ts,tsx}",
    "./<custom directory>/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

tailwind.conf.js file after adding paths to components

In the above example, you can replace <custom directory> with your directory's real name.

How to Configure NativeWind with Babel

You'll also need to configure NativeWind with Babel. To do this, include the NativeWind plugin in your project's babel.conf.js file:

plugins: ["nativewind/babel"],

The babel.conf.js file would look like this after adding the NativeWind plugin:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
    plugins: ["nativewind/babel"],
  };
};

babel.conf.js file after adding nativewind plugin

By including the NativeWind plugin in the Babel configuration file you ensure that NativeWind's functionality is properly incorporated into your project's JavaScript codebase.

🎉With this, NativeWind has been successfully integrated into your Expo app. The next step is to begin styling the app with NativeWind.

How to Style with NativeWind

To begin styling with NativeWind, go to your project's App.js file or the component you would like to style, which would look like this by default:

import { StatusBar } from "expo-status-bar";
import { StyleSheet, Text, View } from "react-native";

export default function App() {
  return (
    <View style={styles.container}>
      <Text>Open up App.js to start working on your app!</Text>
      <StatusBar style='auto' />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#fff",
    alignItems: "center",
    justifyContent: "center",
  },
});

App.js boilerplate code

Next, modify your component to get rid of any instances of StyleSheet abstraction. In this example, we'll modify the App.js code. After adjustments, we should have something like this:

import { StatusBar } from "expo-status-bar";
// import { StyleSheet, Text, View } from "react-native";
import { Text, View } from "react-native";

export default function App() {
  return (
    // <View style={styles.container}>
    <View className='flex-1 justify-center items-center bg-white'>
      <Text>Open up App.js to start working on your app!</Text>
      <StatusBar style='auto' />
    </View>
  );
}

// const styles = StyleSheet.create({
//   container: {
//     flex: 1,
//     backgroundColor: "#fff",
//     alignItems: "center",
//     justifyContent: "center",
//   },
// });

App.js component after modification

In the modified codeblock, we remove all occurrences of StyleSheet abstractions, including the import statement for stylesheet and the StyleSheet.create function, and we replace style with className in the App.js return function.

Having cleared that up, all you need to do is write Tailwind CSS classes into your app className to begin implementing Tailwind CSS in your application. You'll see this in a bit as we build a simple login screen with NativeWind.

How to Build A Simple Login Screen

Now, let's dive into building a simple login screen using NativeWind. We'll continue with the initial setup in the App.js file and gradually add components to create the login UI.

First, let's replace the existing code in the App.js file with the following:

import { StatusBar } from "expo-status-bar";
import { Text, View } from "react-native";

export default function App() {
  return (
    <View className='flex-1 justify-center items-center bg-white'>
      <StatusBar style='auto' />
      <Text className='text-center mt-3 text-2xl font-light text-orange-300'>
        Login
      </Text>
      {/* Additional components goes here */}
    </View>
 );
}

Starter code for login screen UI

The code above imports the essential components from React Native and Expo. We then use a View component to define the structure of our login screen, which is styled with NativeWind's utility classes. Inside the View, we have a Text component that displays "Login" with styling applied using NativeWind classes.

Next, you can add your login form components, such as username and password input fields, a login button, and any other necessary elements. Here is an example of how you can extend the login screen:

import { StatusBar } from "expo-status-bar";
import { Text, View, TouchableOpacity, TextInput } from "react-native";

export default function App() {
  return (
    <View className='flex-1 justify-center items-center bg-white'>
      <StatusBar style='auto' />
      <Text className='text-center mt-3 text-2xl font-light text-orange-300'>
        Login
      </Text>
      {/* Additional components goes here */}
      <View className='mt-5 mx-5'>
        <View>
          <Text className='text-gray-400'>EMAIL:</Text>
          <TextInput
            placeholder='Enter Email...'
            className='border border-dotted p-2 text-gray-500 border-amber-400 mt-1'
          />
        </View>
        <View className='mt-3'>
          <Text className='text-gray-400'>PASSWORD:</Text>
          <TextInput
            secureTextEntry
            placeholder='Enter Password...'
            className='border text-gray-500 border-dotted p-2 border-amber-400 mt-1'
          />
        </View>

        <TouchableOpacity className='bg-orange-300 p-3 mt-4'>
          <Text className='text-center text-base text-white'>Login</Text>
        </TouchableOpacity>

        <Text className='text-center font-normal text-gray-500 text-base mt-3'>
          OR
        </Text>
        <View className='mt-4'>
          <TouchableOpacity className='flex flex-row items-center justify-center p-2 bg-orange-300'>
            <Text className='text-white mx-2 text-sm'>Sign In With Google</Text>
          </TouchableOpacity>
        </View>
        <View className='mt-6 flex-row justify-center'>
          <Text className=''>New to FreeCodeCamp? </Text>
          <TouchableOpacity>
            <Text className='text-amber-500'>Create an Account</Text>
          </TouchableOpacity>
        </View>
      </View>
    </View>
  );
}

Extended login screen UI with additional components

In this expanded version, we've included TextInput components for the username and password input fields, as well as a TouchableOpacity for the login button. Styling is done with NativeWind's utility classes to provide a clean and consistent appearance.

Furthermore, once you've finished creating your login screen using NativeWind in your React Native Expo project, you'll want to test it to check if everything works properly. You can do this by running this command on your terminal:

expo start

This command will launch the bundler and generate a QR code. To open the app, scan the QR code displayed in the terminal with your emulator's camera, or press "a" for Android or "i" for iOS.

Output of the code in an emulator

If you need to, you can access the complete project code on GitHub.

Conclusion

Integrating Tailwind CSS into a React Native Expo project with NativeWind has various benefits, including increased developer efficiency, code consistency, and performance. Developers can easily create amazing mobile applications by leveraging the power of Tailwind CSS's utility-first approach and React Native's native features.

NativeWind makes it easy to apply Tailwind CSS to your React Native Expo app. Using Tailwind CSS in your mobile app development workflow opens up new possibilities for UI design and customization.

Remember, if you have any questions or just want to say hi, feel free to reach me on X(Twitter) or my website. :)

We just published a full React Native course on the freeCodeCamp.org YouTube channel.

Emma Williams created this course. She is a software developer who specializes in React Native.

Our comprehensive React Native course is specifically designed to take you from the basics of app development to creating your very own weather app with a sleek user interface and real-time data integration. The course will walk you through core concepts such as components, state management, hooks, and styling, while providing hands-on experience and practical examples.

Course Overview

Introduction
Start your journey into React Native with a brief overview of the framework, its benefits, and why it's the go-to choice for cross-platform mobile development.

What is React Native and Expo?
Understand the purpose of React Native and learn how Expo simplifies the development process by offering a suite of tools and services.

Setting Up Your Environment
Get up and running with Expo, set up a custom app, and configure Android Studio to kickstart your development process.

The Directory Structure, Linting, and Prettier
Familiarize yourself with the typical directory structure of a React Native project, and learn how to set up linting and Prettier for a clean and consistent codebase.

Debugging and Native Components
Discover the art of debugging in React Native and explore the power of native components to achieve a truly native look and feel.

Core Components and JSX
Understand the significance of core components and learn how to use JSX to build dynamic UIs.

Working with Components
Dive deep into the world of components, their purpose, and how to create your very first component.

Styling and Layout Props
Grasp the essentials of styling in React Native and learn how to use layout props to create responsive designs.

Building the Weather App
Put your newfound skills to the test as you create the current weather screen, upcoming weather component, and city screen. Learn to work with lists, images, and props, all while refining your codebase.

Navigation and State Management
Delve into the realm of navigation and state management, implementing tabs and using hooks like useState and useEffect to manage your app's state.

Fetching Data and Integrating APIs
Learn how to fetch data from the OpenWeatherMap API, get the user's location, and create your own custom hook to pass data to your components.

Updating Components and Installing Moment
Update your components to use real-time data, and install Moment to display dates and times in a user-friendly format.

Error Handling and Final Refactoring
Create an error screen to handle unexpected issues, and polish your app with some last refactoring.

Bonus Material
Enhance your React Native knowledge with bonus content covering advanced topics and best practices.

By the end of this comprehensive React Native course, you'll have the skills and confidence to build your own cross-platform mobile applications with ease. Whether you're an aspiring app developer or a seasoned professional looking to expand your toolkit, this course offers the perfect balance of theory and hands-on practice to elevate your React Native expertise.

Watch the full course on the freeCodeCamp.org YouTube channel (5-hour watch).

One of the key benefits of both these libraries is that they each have the ability to manage their own state within components. But managing state, along with sharable data, can be tricky – especially as the applications become more complex.

In this article, we will explore global state management – and in particular, how to use the Pullstate library. You'll learn how you can easily implement it into your React and React Native projects.

Pre-Requisites:

• Basic knowledge of React / React Native applications
• Basic knowledge of CSS and styling (not essential)

Note: in this article, I will be using TypeScript and React Native. But the implementation and concepts will be exactly the same for JavaScript users and React (without the strongly typed variables).

What is State?

State refers to an object that stores data which can change over time. It's a way to manage and update data within a component or application without affecting other parts of the application.

State in React is like a backpack you carry around with you, containing things you might need for your day. It's a way to store and manage data in your app that can change over time, like what you've picked up or dropped off along the way.

Local vs global state

Component state is local to a specific component. This means that it's only accessible and modifiable within that component. You use component state to manage data that's specific to a single component – for example like form validation messages, or the visibility of certain UI (User Interface) elements.

Global state, on the other hand, refers to data that can be accessed and modified from multiple components across the entire application. Global state would be something that is managed by a state management library. It's useful for managing shared data across multiple components, like authentication status, user preferences, or shopping cart contents.

Global state and component state both have their own advantages and disadvantages, depending on the specific needs of the application.

Global state can simplify data management and improve performance, but can also increase complexity if not managed correctly. Component state is simpler to manage and understand, but can lead to duplicated data and inconsistent behavior across the application.

What are State Management Libraries?

logos of popular state libraries

State management libraries in React are tools that help developers manage and organize the state of their applications more easily. These libraries are designed to handle complex state management scenarios in large-scale applications so you don't have to. They also help you create a more central, organized state.

When talking about state management and data sharing, the most commonly talked about solution is Redux. But Redux is often seen as overly-complicated because it adds an additional layer of complexity.

Redux is designed to manage application state in a predictable and consistent manner, but it requires developers to learn a new set of concepts, such as actions, reducers, and the store.

Some other popular state management libraries in React include Zustand, MobX, and Recoil. These libraries provide features like global state management, immutability, and optimized re-rendering to help make applications more performant and easier to maintain.

Using a state management library can make it easier for developers to handle the state of their application, and simplify the process of passing data between components. It can take some time to learn how to use these libraries effectively, but they can be very powerful tools for building complex React applications.

What is Pullstate?

Pullstate is a much simpler and more lightweight state management library for React. It simplifies the whole process and makes it easier to build scalable applications.

Since React Native is built on React, you can use Pullstate to build not only web applications but mobile ones, too. It is is based on the concept of "pulling" data from the state, rather than pushing data into it.

How to use Pullstate

In order to use Pullstate and get up an running, you'll first need to know which package manager you're using (yarn or npm).

Open your existing React / React Native project, and in the terminal enter the following commands depending on whether you use npm or yarn:

npm install pullstate
//or
yarn add pullstate

If you haven't already got a React Native application you can create one using the React Native cli.

First, you'll need to make sure you have Node.js installed.

Open the terminal to the folder where you would like to create your React Native application:

npm uninstall -g react-native-cli
npx react-native init myReactNativeApp --template react-native-template-typescript

How to Set Up the Store

The below code and corresponding image shows how to initialize the Pullstate store code for copying and pasting below (this is how I'll include all the code in this tutorial – code for copying, along with how it should look in a snapshot).

You can put the below code in its own file, for example store.ts , in your project root folder.

import {Store} from 'pullstate';

interface UIStore {
  user: {
    firstName: string;
    lastName: string;
    acceptedTnC: boolean;
  };
  preferences: {
    isDarkMode: boolean;
    pushNotifications: boolean;
  };
}

const initialStore: UIStore = {
  user: {
    firstName: '',
    lastName: '',
    acceptedTnC: false,
  },
  preferences: {
    isDarkMode: false,
    pushNotifications: false,
  },
};

export const store = new Store<UIStore>({
  user: {
    firstName: '',
    lastName: '',
    acceptedTnC: false,
  },
  preferences: {
    isDarkMode: false,
    pushNotifications: false,
  },
});

Here's the snapshot of what that should look like:

image showing code snapshot of store configuration

What is this code doing?

First, we created an interface for the Pullstate store. This holds all the information we will need to store in state across the app. We have things like the user's first name and last name (so we can use them across the application).

The store can also hold nested objects, for example our preferences object, making managing state cleaner.

To keep things simple and allow cleaner code in the future, I've created an initial store state. This resets all the state properties to their default values.
We can then (when needed) return the state back to its initial state quick and easily. This could be very useful in situations like logOut, onError, and so on.

Then we initialize the store and make it an exportable object. This means that after the first time we import the object (ideally at the top level of our application) it is then accessible throughout our app.

How to Retrieve Data from the Store

Ok, so we have our store, but how we do access this data within our component?
To retrieve the data from the store, we can utilize either the getRawState or useState functions.

getRawState() returns the raw state at this moment in time. When called it gives the live state of the pull state store. If the state is updated, the value will not be updated

For example in the code below, the acceptedTerms variable would be whatever value it was at time of calling store.getRawState():

example of using getRawState() function

useState() acts in the same way as the React useState() function works. When the Pullstate store is updated, the acceptedTerms value will be be updated too, thus causing a re-render of the component.

Think of useState in Pullstate as a listening function – it waits for a value to be updated and then provides you with that new updated value.

example of using the store.useState() function

Real Life Example:

Let's take a look at a real life example, involving accepting a terms and conditions page. The code below will:

• Create a card component with some terms, and
• Have two buttons, 'Back' and 'Next', which will run a function on clicking.

import React from "react";
import { StyleSheet, Text, View } from "react-native";
import { Card } from "react-native-paper";
import { store } from "./store";import { BlueButton } from "../atoms/button";

export const PullStateCard: React.FC = () => {  
    const handleAgreeTerms = () => {
        store.update((state) => {     
            state.user.acceptedTnC = true;    
        });  
    };  

    const handleDisagreeTerms = () => { 
        store.update((state) => {      
            state.user.acceptedTnC = false;    
        });  
    };  

    return (    
        <Card style={[styles.marginTop, styles.padding]}>
            <Text>Our services are provided on an as-is basis. 
            We do not guarantee the availability, accuracy, or completeness of our services. 
            You may use our services only for lawful purposes and in accordance with these terms and conditions.
            </Text>
            <Text style={{ marginTop: 16 }}>
                By clicking 'Next' you are agreeing to the terms and conditions of this app
            </Text>
            <View style={styles.row}>
                <BlueButton 
                    styleOverride={styles.button}
                    onPress={handleDisagreeTerms}
                    title="Back"/>        
                <BlueButton
                    styleOverride={styles.button}
                    onPress={handleAgreeTerms}
                    title="Next"/>
            </View>
        </Card>  

       )
}

My custom buttons:

import {
  StyleProp,
  StyleSheet,
  Text,
  TouchableOpacity,
  ViewStyle,
} from 'react-native';
import React from 'react';

interface BlueButtonProps {
  onPress: () => void;
  title: string;
  styleOverride?: StyleProp<ViewStyle>;
}

export const BlueButton: React.FC<BlueButtonProps> = ({
  onPress,
  title,
  styleOverride,
}) => (
  <TouchableOpacity onPress={onPress} style={[styles.button, styleOverride]}>
    <Text style={styles.buttonText}>{title}</Text>
  </TouchableOpacity>
);

const styles = StyleSheet.create({
  button: {
    backgroundColor: '#007AFF',
    borderRadius: 10,
    padding: 10,
    alignItems: 'center',
    marginVertical: 10,
  },
  buttonText: {
    color: 'white',
    fontSize: 16,
    fontWeight: 'bold',
  },
});

The Card component code would look like this:

Dissecting the handle functions

The handle functions are called when the buttons are clicked. Depending on which you click, a particular action will be carried out. But the underlying intent is the same, in that they both modify the state of the pull state store we created earlier.

One will set the user.acceptedTnC to true, and the other to false. We've used the .update()function on the store object we created earlier, and passed it an anonymous function to update the properties.

The method is not limited to update just the one property, and you can update multiple properties at once, for example:

store.update((state) => {  
    state.user.acceptedTnC = true;  
    state.user.firstName = "John";  
    state.user.lastName = "Doe";  
    state.preferences.pushNotifications = true;
});

Why is Pullstate and Global State Management So Useful?

The beauty of using state in this way means that the component doesn't handle the store, the application does. You can then share this across the whole app, and have other components listen to these changes.

Let's take the example above one step further and have a separate component that will show a relevant message that's dependent on the state of the acceptedTnC property.

const styles = StyleSheet.create({  
    disagree: {    
        color: "red",
        textDecoration: "italic",
    },
    accepted: {
        color: "#0d8009",
    },  
    marginTop: {
        marginTop: 10,
    },
});

export const AgreedToTerms: React.FC = () => {  
    const acceptedTerms = store.useState((state) => state.user.acceptedTnC);
    return (    
        <View style={styles.marginTop}> 
            {acceptedTerms ? (
                <Text style={styles.accepted}>
                    You have successfully accepted the Terms and Conditions                  </Text>) : (
                 <Text style={styles.disagree}>
                     Please accept the Terms and Conditions by pressing 'Next'        
                     </Text>)
            }
        </View>
    )
};

If you import these components and add your own styling to the App.tsx (App.js for JS) like so:

<PullStateCard />
<AgreedToTerms />

Your whole App.tsx code will look like this:

import React from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  View,
} from 'react-native';

import {AgreedToTerms, PullStateCard} from './src/pullstate/pullstate_example';

const App = () => {
  return (
    <SafeAreaView>
      <StatusBar barStyle={'light-content'} />
      <ScrollView contentInsetAdjustmentBehavior="automatic">
        <View style={styles.container}>
          <PullStateCard />
          <AgreedToTerms />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
};

const styles = StyleSheet.create({
  container: {
    height: '100%',
    paddingHorizontal: 16,
    paddingVertical: 16,
  },
});

export default App;

Once you have copied the code, you can add your own styling where necessary and run the app.

Click the Next button, and your text will turn green and inform you that you've accepted the the terms.

If you then click the Back button, you will see the text is red informing you that you need to accept the terms:

This is all powered by the global Pullstate store. There is no internal state on the AgreedToTerms component.

Decoupling Logic

Decoupling refers to the practice of separating different parts of your code so that they are not tightly dependent on / related to each other.

Think of it like building with LEGOs. When you build with LEGOs, each piece can connect to other pieces, but they can also be easily disconnected and reconnected with other pieces. This makes it easier to change and modify your LEGO build.

Similarly, in programming, when we decouple our code, we make it easier to change and modify without affecting other parts of our code. This is especially important in large applications with many different components or modules.

By moving the 'agreed to terms' acceptance state to Pullstate, it can be added and removed to any component that should need it. It's not tightly coupled with the AgreedToTerms component, and it becomes a re-usable piece of state that is globally updated. For example we could use it elsewhere in the app as an authorization mechanism, to show / hide UI elements, and much more.

Round up

I hope you've found this article useful and enjoyed this brief introduction to Pullstate and global state management.

What we've covered:

• What state management libraries are
• An introduction to Pullstate and how to integrate it into your application
• The benefits of Pullstate and how it works

For any more questions don't hesitate to reach out to me on Twitter.