We'll add a React Provider wrapping the entire app, granting us easy access to various actions and information, such as purchasing a subscription, obtaining details about our offerings, and more!

SpiroKit for SaaS

In case you want to save weeks of painful work & research on your next React Native app, checkout SpiroKit for SaaS. It's a starter template that comes with Purchases, Push Notifications, Authentication, Analytics, Error Reporting and more. It also includes a Notion template to guide you through the entire process. If you get a licence, you won't need to follow the rest of this guide ;)

Building a development client

Before we can begin working on the app, we need to run it locally to test our changes. Since react-native-purchases is a native package, we require a development build for our app. Execute the following command to obtain a dev-client with EAS.

# Replace platform based on your needs
eas build --platform [ios|android] --profile development

Once the development build is ready, you'll need to install it on an actual device, as the RevenueCat package cannot be tested on a simulator.

Adding a Purchases provider to your app

We could drop all the necessary logic to retrieve our offerings information directly into a component. However, I believe it would be even better to have a provider with all this logic encapsulated, wrapping the entire app, so you can easily access the information from any component. Let's begin by creating a few files:

mkdir context
touch context/PurchasesProvider.tsx
touch context/PurchasesContext.tsx

Copy & paste the following code:

// context/PurchasesContext.tsx
import { createContext } from "react";
import {
  CustomerInfo,
  MakePurchaseResult,
  PurchasesOffering,
  PurchasesPackage,
  PurchasesStoreTransaction,
} from "react-native-purchases";

export type PurchasesContextProps = {
  currentOffering: PurchasesOffering | null;
  purchasePackage: (
    packageToPurchase: PurchasesPackage
  ) => Promise<MakePurchaseResult>;
  customerInfo?: CustomerInfo;
  isSubscribed: boolean;
  getNonSubscriptionPurchase: (
    identifier: string
  ) => Promise<PurchasesStoreTransaction | null | undefined>;
};

const PurchasesContext = createContext<PurchasesContextProps | null>(null);

export default PurchasesContext;

// context/PurchasesProvider.tsx
import React, { useEffect, useState } from "react";
import PurchasesContext from "./PurchasesContext";
import Purchases, {
  CustomerInfo,
  LOG_LEVEL,
  PurchasesOffering,
  PurchasesPackage,
} from "react-native-purchases";
import { Platform } from "react-native";

type PurchasesProviderProps = {
  children: JSX.Element | JSX.Element[];
};

const androidApiKey = process.env.EXPO_PUBLIC_REVENUECAT_API_KEY_ANDROID!;
const iosApiKey = process.env.EXPO_PUBLIC_REVENUECAT_API_KEY_IOS!;

const PurchasesProvider: React.FC<PurchasesProviderProps> = ({ children }) => {
  const [initialized, setInitialized] = useState(false);
  const [offering, setOffering] = useState<PurchasesOffering | null>(null);
  const [isSubscribed, setIsSubscribed] = useState(false);
  const [customerInfo, setCustomerInfo] = useState<CustomerInfo>();

  const init = async () => {
    Purchases.configure({
      apiKey: Platform.OS === "android" ? androidApiKey : iosApiKey,
    });

    if (__DEV__) {
      Purchases.setLogLevel(LOG_LEVEL.DEBUG);
    }

    await getOfferings();

    // Add a listener to update the customerInfo state when the customer info changes, like when a user subscribes
    Purchases.addCustomerInfoUpdateListener((customerInfo) => {
      setCustomerInfo(customerInfo);
    });

    setInitialized(true);
  };

  /**
   * Fetch the current offerings from RevenueCat
   */
  const getOfferings = async () => {
    const offerings = await Purchases.getOfferings();
    const currentOffering = offerings.current;
    setOffering(currentOffering);
  };

  /**
   *
   * @param purchasedPackage The package to purchase
   * @returns The result of the purchase
   */
  const purchasePackage = async (purchasedPackage: PurchasesPackage) => {
    const result = await Purchases.purchasePackage(purchasedPackage);
    return result;
  };

  /**
   * Fetch the customer info from RevenueCat
   */
  const getCustomerInfo = async () => {
    const customerInfo = await Purchases.getCustomerInfo();
    setCustomerInfo(customerInfo);
  };

  /**
   * Check if the user is subscribed to any offering
   * @returns True if the user is subscribed to any offering
   */
  const checkIfUserIsSubscribed = async () => {
    if (!initialized || !customerInfo) return;
    const isPro = customerInfo.activeSubscriptions.length > 0;
    setIsSubscribed(isPro);
  };

  /**
   * Get the non-subscription purchase with the given identifier
   * @param identifier The identifier of the product to fetch
   * @returns The non-subscription purchase with the given identifier
   */
  const getNonSubscriptionPurchase = async (identifier: string) => {
    if (!initialized || !customerInfo) return null;

    const item = customerInfo.nonSubscriptionTransactions.find(
      (t) => t.productIdentifier === identifier
    );

    return item;
  };

  useEffect(() => {
    init();
    getCustomerInfo();
  }, []);

  useEffect(() => {
    // Check if the user is subscribed to any offering after the customer info changes
    checkIfUserIsSubscribed();
  }, [initialized, customerInfo]);

  // If the Purchases SDK is not initialized, return null
  if (!initialized) {
    return null;
  }

  return (
    <PurchasesContext.Provider
      value={{
        currentOffering: offering,
        purchasePackage,
        customerInfo,
        isSubscribed,
        getNonSubscriptionPurchase,
      }}
    >
      {children}
    </PurchasesContext.Provider>
  );
};

export default PurchasesProvider;

Using a custom hook for better developer experience

We'll need a custom hook to easily access all the exported members of our provider. Let's start by creating a new file for this.

mkdir hooks
touch hooks/usePurchases.tsx

Update the usePurchases.tsx with the following code:

// hooks/usePurchases.tsx
import React from "react";
import PurchasesContext, {
  PurchasesContextProps,
} from "@/context/PurchasesContext";

/**
 * Custom hook for managing purchases with RevenueCat.
 * @returns An object containing the following properties:
 *  - currentOffering - The current offering
 *  - purchasePackage - Purchase a package
 *  - customerInfo - The customer info
 *  - isSubscribed - Flag that indicates if the user is subscribed to any offering
 *  - getNonSubscriptionPurchase - Get the non-subscription purchase by identifier
 */
export const usePurchases = () =>
  React.useContext(PurchasesContext as React.Context<PurchasesContextProps>);

Wrapping the app with the new provider

Go to app/_layout.tsx and update the file to wrap the app with the PurchasesProvider.

// app/_layout.tsx

...
+ import PurchasesProvider from "@/context/PurchasesProvider";

...

export default function RootLayout() {
  ...
  return <RootLayoutNav />;
}

function RootLayoutNav() {
  const colorScheme = useColorScheme();

  return (
+   <PurchasesProvider>
      <ThemeProvider value={colorScheme === "dark" ? DarkTheme : DefaultTheme}>
        <Stack>
          <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
          <Stack.Screen name="modal" options={{ presentation: "modal" }} />
+         <Stack.Screen
+           name="subscriptions-paywall"
+           options={{ headerShown: false }}
+         />
        </Stack>
      </ThemeProvider>
+   </PurchasesProvider>
  );
}

Adding a "Paywall" route to show our products

This is where the magic happens! We need to create a new route for our Paywall screen.

touch app/subscriptions-paywall.tsx

With the following code, we render a horizontal FlatList component that displays all available subscription options. Feel free to modify this to suit your needs.

Additionally, we use the offering metadata to enhance the information and display the number of months for each product. This is also optional, and you can remove it if desired.

//app/subscriptions-paywall.tsx

import { usePurchases } from "@/hooks/usePurchases";
import { router } from "expo-router";
import React, { useState } from "react";
import {
  Dimensions,
  Platform,
  View,
  Image,
  ScrollView,
  Text,
  Button,
  Pressable,
  FlatList,
} from "react-native";
import { PRODUCT_CATEGORY, PurchasesPackage } from "react-native-purchases";

const screenHeight = Dimensions.get("window").height;
const screenWidth = Dimensions.get("window").width;

const SubscriptionsPaywall = () => {
  const { currentOffering, purchasePackage } = usePurchases();

  // Filter out non-subscription products from RevenueCat
  const filteredPackages = currentOffering?.availablePackages.filter(
    (item) => item.product.productCategory === PRODUCT_CATEGORY.SUBSCRIPTION
  );

  const [selectedPackage, setSelectedPackage] =
    useState<PurchasesPackage | null>(filteredPackages?.[0] || null);

  const [isLoading, setIsLoading] = useState(false);

  const handleContinue = async () => {
    if (!selectedPackage) return;

    try {
      setIsLoading(true);
      await purchasePackage(selectedPackage);
      router.back();
    } catch (error) {
      console.log(error);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <View style={{ gap: 16, flex: 1, backgroundColor: "white" }}>
      <Image
        source={{
          uri: "https://i.imgur.com/qUZLBVT.jpg",
        }}
        height={screenHeight * 0.3}
        alt="Background image showing food"
        resizeMode="cover"
      ></Image>

      <ScrollView contentContainerStyle={{ flexGrow: 1 }}>
        <View style={{ flex: 1, alignItems: "center", gap: 24, padding: 24 }}>
          <Text style={{ textAlign: "center" }}>
            {`Get access to our premium features`}
          </Text>
          <PackagesCarousel
            packages={filteredPackages}
            onSelectPackage={(packageToSelect) =>
              setSelectedPackage(packageToSelect)
            }
            selectedPackage={selectedPackage}
            metadata={currentOffering?.metadata as PackageMetadata}
          ></PackagesCarousel>
        </View>
        <View style={{ padding: 24, gap: 8, marginBottom: 24 }}>
          <Text style={{ textAlign: "center" }}>
            {`All Subscriptions include a 7-Day Free Trial`}
          </Text>
          <Text style={{ textAlign: "center" }}>
            {`You can cancel at any time before the 7 day trial ends, and you won't be changed any amount`}
          </Text>
          <Button
            disabled={isLoading}
            title={isLoading ? "Processing..." : "Try it free for 7 days"}
            onPress={handleContinue}
          />
        </View>
      </ScrollView>
    </View>
  );
};

type Subscription = {
  identifier: string;
  cycles: number;
  discount?: string;
};

type PackageMetadata = {
  subscriptions: {
    ios: Subscription[];
    android: Subscription[];
  };
};

type PackagesCarouselProps = {
  onSelectPackage: (packageToSelect: PurchasesPackage) => void;
  packages?: PurchasesPackage[];
  metadata: PackageMetadata;
  selectedPackage: PurchasesPackage | null;
};

const PackagesCarousel: React.FC<PackagesCarouselProps> = (props) => {
  const { packages, onSelectPackage, selectedPackage, metadata } = props;
  const subscriptions =
    metadata.subscriptions[Platform.OS === "ios" ? "ios" : "android"];

  console.log("subscriptions", subscriptions);

  const RenderItem = (item: PurchasesPackage) => {
    if (!selectedPackage) return null;
    const isSelected = selectedPackage.identifier === item.identifier;
    const packageMetadata = subscriptions.find(
      (s) => s.identifier === item.product.identifier
    );

    console.log("packageMetadata", packageMetadata);

    if (!packageMetadata) return null;
    const discount = packageMetadata.discount;
    const amountOfMonths = packageMetadata.cycles;

    return (
      <Pressable
        onPress={() => {
          onSelectPackage(item);
        }}
      >
        <View
          style={{
            marginRight: 16,
            borderColor: isSelected ? "red" : "black",
            borderWidth: 3,
            borderRadius: 6,
            overflow: "hidden",
            minWidth: screenWidth * 0.4,
          }}
        >
          {discount && (
            <Text
              style={{
                position: "absolute",
                width: "100%",
                color: "black",
                textAlign: "center",
                padding: 4,
                backgroundColor: "yellow",
              }}
            >
              {discount}
            </Text>
          )}
          <View
            style={{
              marginTop: 16,
              padding: 16,
              alignItems: "center",
            }}
          >
            <Text
              style={{
                fontSize: 70,
              }}
            >
              {amountOfMonths}
            </Text>
            <Text>{amountOfMonths > 1 ? "months" : "month"}</Text>
            <Text>{item.product.priceString}</Text>
          </View>
        </View>
      </Pressable>
    );
  };

  if (!packages) return null;

  return (
    <FlatList
      contentContainerStyle={{
        paddingBottom: 4,
        marginRight: -16,
        overflow: "hidden",
      }}
      horizontal={true}
      data={packages}
      pagingEnabled={false}
      keyExtractor={(item) => item.identifier}
      renderItem={({ item }) => <RenderItem {...item}></RenderItem>}
    ></FlatList>
  );
};

export default SubscriptionsPaywall;

Finally, we need a way to navigate to our Paywall screen. Update the app/(tabs)/index.tsx like this:

// app/(tabs)/index.tsx

import { Button, StyleSheet } from "react-native";

import EditScreenInfo from "@/components/EditScreenInfo";
import { Text, View } from "@/components/Themed";
+ import { router } from "expo-router";

export default function TabOneScreen() {
  return (
    <View style={styles.container}>
      ...
+     <Button
+       title="Navigate to Paywall"
+       onPress={() => {
+         router.push("/subscriptions-paywall");
+       }}
+     />
    </View>
  );
}

const styles = StyleSheet.create({
  ...
});

Ready to test?

Run the following command to start your app using the development client:

npx expo start --dev-client

If everything went as expected, you'll see a home screen with a button to navigate to the Paywall route you created before.

Select any of the subscription options and confirm to purchase the package.

What's next?

With this solid foundation, you can now start working on your app to check customer information and grant or deny access to specific features based on their subscription status.

You can also create a dedicated screen to offer other products, such as a one-time purchase to remove ads. Explore the PurchasesProvider; it's filled with helpful methods.

Final words

I know this has been a long series, but I hope you find it useful (please let me know in the comments). To be honest, I chose to share all this information because I spent countless hours trying to understand all the different configurations involved in this process.

Moreover, These kinds of difficult tasks are the main reason so many apps fail before being released to the stores. Now, focus on your idea instead of how to add Payments 😉

Happy coding!

Before diving into this third part, I highly recommend watching this video to become familiar with some essential RevenueCat concepts like Entitlements, Products, Packages, and Offerings.

Following with the example we presented on the previous post, we now need to set up our subscriptions and one-time payment in RevenueCat.

Scenario

Our example scenario includes:

• A monthly subscription with 7-day free trial

• A annual subscription with 7-day free trial

• A one-time purchase to remove ads from the app

The process

1. Create 2 entitlements: “Pro access” (used by the subscriptions) and “Ad free” (used by those who paid to remove the ads)

2. Create 6 products: “Pro monthly”, “Pro annual”, and “Ad free” (both for Android and iOS).

3. Associate products with entitlements

   1. The “Pro access” entitlement will include the “Pro monthly” and “Pro annual” products for both platforms.

   2. The “Ad free” entitlement will include the “Add free” product for both platforms.

4. Create 3 “packages”

   1. The “Pro monthly” package will include the “Pro monthly” products for both platforms

   2. The “Pro annual” package will include the “Pro annual” products for both platforms

   3. The “Ad free” package will include the “Ad free” products for both platforms.

5. Create 1 “offering” that will display the 3 packages mentioned before.

I know… take a 5 minute break to digest all these new concepts 😄

I’ll guide you through the entire process below 💪

SpiroKit for SaaS

In case you want to save weeks of painful hours of work & research on your next React Native app, checkout SpiroKit for SaaS. It's a starter template that comes with Purchases, Push Notifications, Authentication, Analytics, Error Reporting and more. It also includes a Notion template to guide you through the entire process

Creating the Entitlements

The first step is to create 2 entitlements: “Pro access” and “Ad free” (feel free to adapt this to your needs)

1. Visit https://app.revenuecat.com/ and navigate to your project dashboard.

2. In the sidebar, under the “Product catalog” section, click on “Entitlements”

   

3. On the top right corner, click on “New”

   

4. Choose an identifier and a description for your new entitlement

   

5. Repeat step 3 and 4 for the “Ad free” entitlement (feel free to adapt this to your needs)

Creating the Products

We’ll need to create 6 products: “Pro monthly”, “Pro annual”, and “Ad free” (both for Android and iOS).

Automatically importing Android products

1. In the sidebar, under the “Product catalog” section, click on “Products”

   

2. On the top right corner, click on “New”

3. Choose your Android App

4. Click on “Import products”

   

5. If everything went as expected, you should see something like this

   

6. Select all the products you want to import and click “Import” to confirm.

7. Repeat steps 2 to 4 for the iOS app. But there’s a small difference with Android. You’ll need to setup your App Store Connect API key

   

Automatically importing iOS products

Before you can automatically import the iOS products, you’ll need to setup your App Store Connect API key. In order to do that, follow these steps:

1. Visit the App Store Connect

2. Click on “Users and access”

   

3. Click on the “Keys” tab, and then click “+”

   

4. Assign a descriptive name, and assign the “App Manager” role that will be required by RevenueCat to import the products. Then, click on “Generate” to confirm

   

5. In the right corner, click on “Download”. Make sure to store this file in a safe place, as you won’t be able to download it again.

   

6. Once you downloaded the file, go back to your RevenueCat dashboard

7. In the sidebar, click on your iOS app

   

8. Scroll to the “App Store Connect API” section, and drop the file you just downloaded.

   

9. After that, you’ll be requested to complete two additional fields

   

10. You can get the Issuer ID in the App Store Connect, in the same page you just downloaded your API key

    

11. For the Vendor number, visit the “Payments and Financial Reports” section in the App Store Connect. You should see your vendor id in the top left corner

    

12. Click on “Save changes” to confirm

13. Now you can import your iOS products by following the same steps required for Android.

14. Make sure to select all the products and click “Import”

    

If everything went as expected, your “Products” section should look like this:

Attaching Products to Entitlements

1. Go back to “Entitlements” in the sidebar

2. Click on the “Pro access” entitlement

3. In the “Associated Products” section, click on “Attach”

   

4. You’ll need to add the 4 products related to “Pro access” which are:

   1. Monthly subscription (iOS / Android)

   2. Annual subscription (iOS / Android)

5. After adding all the products, it should look like this

   

6. Repeat steps 2 and 3 for the “Add free” entitlement. This time, make sure to only add the “Ad free” products (iOS / Android). It should look like this

   

Creating Offerings

1. In the sidebar, click on “Offerings”

   

2. In the top right corner, click on “New”

3. You’ll need to provide an “Identifier” and a “Description” for the offering.

4. In the “Metadata” section, add the following json structure. Make sure to provide your product identifiers, and set the discount based on your pricing. This information will be used later in the starter template, to show a “50% OFF” label in the annual subscription

    {
      "subscriptions": {
        "android": [
          {
            "cycles": 12,
            "discount": "50%",
            "identifier": "[YOUR_ANDROID_ANNUAL_PRODUCT_ID]"
          },
          {
            "cycles": 1,
            "identifier": "[YOUR_ANDROID_MONTHLY_PRODUCT_ID]"
          }
        ],
        "ios": [
          {
            "cycles": 12,
            "discount": "50%",
            "identifier": "[YOUR_IOS_ANNUAL_PRODUCT_ID]"
          },
          {
            "cycles": 1,
            "identifier": "[YOUR_IOS_MONTHLY_PRODUCT_ID]"
          }
        ]
      }
    }
   

5. Click “Save” to finish

   

In order to start using this Offering, you’ll need to add at least one package to it in the next section.

Adding Packages to Offerings

We’ll need to create 3 packages:

• The “Pro monthly” package will include the “Pro monthly” products for both platforms

• The “Pro annual” package will include the “Pro annual” products for both platforms

• The “Ad free” package will include the “Ad free” products for both platforms.

1. In the sidebar, go to “Offerings”

2. Click on the offering you just created in the previous section

   

3. In the “Packages” section, click on “New”

   

4. For the identifier, you can choose between a list of “standard identifiers” or choose “Custom” to create your own identifier. I decided to use the standards for monthly and annual subscriptions, but a custom identifier for the “Ad free” package.

   

5. Click on “Add” to confirm.

6. Now, click on the new package, and then click on “Attach” in the “Products” section.

   

7. Select the relevant product for each platform. In this case, I’m adding the monthly products like this:

   

8. Click “Attach” to confirm

9. The first package is complete with the products associated. Now, go back to the offering and repeat steps 3 to 8 for the “Annual” package and for the “Ad free” package.

10. If everything went as expected, your offering should look like this:

    

Congrats! You are done with all the boring part! Now, it's time to code 🥳

What's next?

In the next and final article of these series, I'll focus on creating a new React Native project and wiring everything together to create a Paywall screen where users can purchase your products.

You can read the next part of the series here:

SpiroKit for SaaS

In case you want to save weeks of painful hours of work & research on your next React Native app, checkout SpiroKit for SaaS. It's a starter template that comes with Purchases, Push Notifications, Authentication, Analytics, Error Reporting and more. It also includes a Notion template to guide you through the entire process

App Store Connect Setup (iOS)

Before we can offer subscriptions and/or in-app purchases on our iOS app, we need to setup in-app purchases in App Store Connect.

Creating a Subscription Group (App Store Connect)

1. Visit App Store Connect. Then click on “My Apps”, and choose your app.

   

2. 

   Click on “Subscriptions”, within the “Features” section in the sidebar

3. Under “Subscription Groups”, click on “Create”. As mentioned in the App Store Connect, All Subscriptions must be a part of a group. Subscription Groups are ways to organize your products in App Store Connect so users are able to switch between products.

   

4. Choose a “Reference Name” for the Subscription Group, and click on “Create” to confirm.

   The Reference Name is not user-facing. It’s just for you.

   

Adding a new product to the subscription group (App Store Connect)

Before we start adding new products to our app, I would like to define a useful example so you can follow along and tweak it based on your needs.

Let’s say we have an App that offers both a monthly and an annual subscription. Both come with a 7-day trial period, and give users access to premium features that are not available in the free version.

Besides the available subscriptions, we also want to offer a one-time in-app payment so our users can remove ads from the free version.

Annual Subscription

1. After creating the subscription group, click “Create” to add your first product.

   

2. You’ll need to provide:

   • Reference Name: The reference name will be used on App Store Connect and in Sales and Trends reports from Apple. It won't be displayed to your users on the App Store. We recommend using a human readable description of the purchase you plan to set up. The name can't be longer than 64 characters.

   • Product ID: The product Id is a unique alphanumeric ID that is used for accessing your product in development and syncing with RevenueCat. After you use a Product ID for one product in App Store Connect, it can’t be used again across any of your apps, even if the product is deleted. It helps to be a little organized here from the beginning. RevenueCat recommend using a consistent naming scheme across all of your product identifiers such as: <app>_<price>_<duration>_<intro duration><intro price>

     • App: Some prefix that will be unique to your app, since the same product Id cannot but used in any future apps you create.

     • Price: The price you plan to charge for the product in your default currency.

     • Duration: The duration of the normal subscription period.

     • Intro duration: The duration of the introductory period, if any.

     • Intro price: The price of the introductory period in your default currency, if any.

   • Based on this information, I’ll use the following product id for my example:

     • saasstarterdemo1_3999_1y_1w0

       • Name of my app: saas starter demo 1

       • Price: $39.99

       • Duration: 1 year

       • Intro/trial duration: 1 week

       • Intro/trial price: $0.00

3. Click on “Create” to confirm

   

Setting duration

After creating the new product, you’ll need to select a duration for the subscription. Choose “1 year” in the dropdown menu, and click “Save”

Setting availability

1. Scroll to the “Availability” section, and click “Set up Availability”

   

2. Choose the countries you want to offer the subscriptions, and click “Done” to finish.

3. Don’t forget to click “Save” in the top right corner

Setting price

1. You’ll need to set the subscription price. Scroll to the “Subscription Prices” section, and click “Add Subscription Price”

   

2. Choose your Country or Region, and select $39.99 for the price. Click on “Next”

   

3. You can optionally change the price for specific countries. Once you are done with that, click “Next” again and “Confirm” to finish.

Setting Introductory Offers (Optional)

1. You’ll need to setup the 7-day trial period. Scroll to the “Subscription Prices” section, and click on “View all Subscription Pricing”

   

2. Click on the “Introductory Offers” tab, and click on “Set up Introductory Offer”

   

   

3. Choose which countries you want to offer the free trial, and click “Next”.

4. For the Start/End date, I went with:

   1. Start Date: Current Date

   2. End Date: “No end date”

Click “Next” to continue

1. Choose “Free” as Type, and “1 Week” for duration. Click “Next” to continue, and finally “Confirm” to finish.

   

Adding Localizations

You’ll need to provide a name and description for the in-app purchase that the user will see.

1. From the “Subscription Pricing” page, go back to the home page for your subscription.

   

2. Scroll to the “App Store Localization” section. Click “Add Localization”.

   

3. Add the required information for at least one language.

   

4. If you scroll up, you may see the following message:

   

5. Make sure to visit that page and setup localizations for the Subscription Group you created earlier.

   

   

Adding Review Information

You’ll be asked to upload a screenshot of the paywall for an Apple reviewer. You also need to provide review notes to make the review process smoother.

1. Navigate to the “Review Information” section and complete the requested information. You can upload the screenshot later once you've build the paywall screen on your app.

   

   For the screenshot, you’ll need to upload an image with one of the following sizes: https://developer.apple.com/help/app-store-connect/reference/screenshot-specifications

2. Finally, click “Save” in the top right corner

   

Monthly Subscription

For the monthly subscription, you need to follow the exact same steps mentioned in the “Annual Subscription” section above.

Here’s the information I’m using for my example app:

One-time payment to remove ads

1. For one-time payments, you’ll need to go back to you app page in App Store Connect, and click on “In-App Purchases” in the sidebar (under the “Features” section). Then, click on “Create”

   

2. For “Type,” choose “Non-Consumable” because the “Remove ads” feature we’ll offer in our example app does not expire. Add your “Reference Name” and “Product ID” following a clear convention like you did before. Here’s what I used as example

   

3. As you did with the subscriptions before, you’ll need to setup “Availability”

   

4. Next, you’ll need to provide a price. Scroll to the “Price Schedule” section and click on “Add Pricing”

   

5. Choose a country and a price, then click “Next”. Review the prices for different countries if you like, then click “Confirm” to finish.

6. Scroll to the “App Store Localization” section, and choose a “Display Name” and “Description” as you did before in the subscriptions. Then, click on “Create”

   

7. Finally, complete the “Review Information” section with the screenshot and notes as before.

   

Google Play Billing Setup (Android)

To set up products for Android devices, start by logging into Google Play Console.

Set up a Google Payments merchant account

This step is only required if you are setting up payments in Google Play Console for the first time.

1. Select your app in Google Play Console.

2. In the sidebar, scroll to the “Monetize” section and click on “Subscription”.

3. If you don’t see this message, feel free to skip the rest of this step.

   

4. Click on “Set up a merchant account”, then click on “Create payments profile”

   

5. You’ll see a list of Payments Profiles. In my case, I already had a profile generated, but you can select “Create payments profile.” In any case, you’ll need to provide additional information.

6. Complete the form with the requested information, and click “Submit” to finish.

Introduction

I’ll guide you through the process to replicate the same subscriptions and in-app purchases I described above for iOS. This includes:

• An annual subscription ($39.99) - 1 week free trial

• A monthly subscription ($4.99) - 1 week trial

• A one-time purchase to remove ads ($2.99)

On Android, there are a few differences with the keywords I used for the iOS setup. On Android, You’ll only need to create one subscription that will serve both the annual and the monthly plans (called “Base plans” here). Then, each plan can have one or more “Offers” associated. We’ll add offers for the free trial.

• Subscription: Represents a user benefit, such as “Access to Premium features.” Independent of how it’s paid.

• Base Plans: Specify the duration, price, availability (countries), etc. You can create pre-paid plans (non-renewing) too.

• Offers: Allow eligible users to access a subscription at a discounted price. You can target offers at different user segments for acquisition and retention, or to incentivize users to upgrade.

Creating a new Subscription for the Annual and Monthly base plans

1. Once you logged in into Google Play Console, select your app from the app list.

2. In the sidebar, scroll to the “Monetize” section, and click on “Subscription”.

   

3. Click on “Create subscription”

   

4. You’ll need to provide a “Product ID” and a “Name”. For the Product ID, RevenueCat has a set of recommendations you can find in this link. I’m sharing an example below using the following structure: appname_subscriptioninfo_version

   

5. Click “Create” to proceed.

6. To complete the set up for the subscription, you’ll need to add at least a base plan. Feel free to also add the subscription benefits, which is recommended. We’ll cover the steps 2 and 3 in the following sections

   

Adding the Annual Base Plan

1. In the “Set up the subscription” section, click on “Add a base plan”

   

2. For the “Base Plan ID”, I’m using the structure: duration_type_price

3. In the “Type” section, select “Auto-renewing”, and choose a yearly billing period. Complete the other information based on your preferences. Here’s an example:

   

4. Next, you’ll need set prices and availability. Click the “Set prices” button on the right

   

5. Use the checkbox at the top of the countries table to select all the countries, and then click “Set Price” in the button below

   

6. Choose a price and click “Update”

   

7. In the bottom right corner, click “Save”

   

8. Finally, click “Activate” so you can start using this base plan

   

Adding the free trial for the annual base plan

1. From the base plan, go back to the subscription page

   

2. In the “Base plans and offers” section, click on “Add offer”

   

3. Choose the annual base plan you just created, and click “Add offer”

4. Choose a unique Offer ID, like free-trial-for-annual-subscription.

5. For “Eligibility Criteria”, select “New customer acquisition”

6. Scroll to the “Phases” section, and click on “Add phase”

   

7. Choose “Free Trial” and 1 week for the duration. Click “Apply”

   

8. Finally, click “Save”, and “Activate” to enable the free trial for the annual plan.

Adding the Monthly base plan

Repeat the steps mentioned above to setup the monthly base plan. Remember to also add the “Offer” for the free trial.

If everything went as expected, your subscription should look like this:

Adding in-app products to Remove Ads

1. Go back to your app dashboard. Scroll to the “Monetize” section in the sidebar, and click “In-app purchases”.

   

2. Click on “Create product”

   

3. In the “Create in-app product” screen, choose a Product ID like you did for the subscriptions. You can use the following structure: appname_description_price

4. Choose a “Name”, “Description”, and “Price” for the product.

5. Click “Save” and then “Activate” to finish.

Congrats! You are done with the product configuration for Android!

The next step is to set up everything on the RevenueCat side of things.

Congrats! You are done with the second part!

What's next?

In the next part of the series, I'll guide you through everything you need to setup in RevenueCat to import all the products you just created in both stores.

You can read the next part of the series here:

Happy coding!

Creating a mobile app involves numerous challenges and time-consuming tasks that must be completed before we can release our app in the stores.

In-app purchases and subscriptions are especially difficult examples of this. They require completing multiple steps in various locations, such as the Google Cloud Console, Google Play Console, App Store Connect, and more!

RevenueCat to the rescue

RevenueCat is a powerful and reliable in-app purchase server that makes it easy to build, analyze, and grow your subscriber base whether you're just starting out or already have millions of customers. It comes with powerful features such as Entitlements, Products, Offerings, and more.

Even thought RevenueCat has an amazing documentation, it's easier to get lost while navigating through all the different articles. Besides, there are certain details about the process that are not covered in details.

Why should I read this long article?

The goal of this article is to provide a one-stop location with everything you need to know to go from zero to a working app that displays all your products and allow users to purchase items or subscribe to your app using both Apple & Google native payments.

I also included a practical example that explains how to setup:

• A monthly subscription with a 7-days free trial.

• An annual subscription with a 7-days free trial.

• A one-time payment to remove Ads from the app.

Grab a cup of coffee. You'll need it!

SpiroKit for SaaS

In case you want to save weeks of painful hours of work & research on your next React Native app, checkout SpiroKit for SaaS. It's a starter template that comes with Purchases, Push Notifications, Authentication, Analytics, Error Reporting and more. It also includes a Notion template to guide you through the entire process

Account setup

Create a RevenueCat account and your first app

You'll need to create a RevenueCat account in order to proceed with the rest of the tutorial. If you already have a RevenueCat account, feel free to jump to the next section.

Otherwise, visit https://app.revenuecat.com/signup and create a new account.

During the signup process, you can choose to add your credit card later. RevenueCat won’t require you to enter your credit card until you have reached $2500/month in revenue.

First app flow

You’ll be ask to create your first app. Choose a name and click on “Create Project” to confirm

Existing customer flow

If you already have at least one app in RevenueCat, you’ll need to create a new project using the top navigation bar:

Creating a new React Native project

Let's start by creating a new Expo app

npx create-expo-app@latest --template tabs@50

Setup bundle identifier & package name

Before you can setup RevenueCat, you'll need to setup a bundle identifier for iOS, and a package name for Android. You can do that from the App.js file.

It's recommended to use the same identifier for both platforms for simplicity.

// App.json
{
  "expo": {
    ...
    "ios": {
      ...
+     "bundleIdentifier": "com.yourcompany.yourappname"
    },
    "android": {
      ...
+     "package": "com.yourcompany.yourappname"
    },
    ...
  }
}

Setup environment variables for RevenueCat platforms

You'll need to create a new .env file to include the API keys for both Android & iOS platforms on RevenueCat.

touch .env

//.env
EXPO_PUBLIC_REVENUECAT_API_KEY_ANDROID="[YOUR_EXPO_PUBLIC_REVENUECAT_API_KEY_ANDROID]"
EXPO_PUBLIC_REVENUECAT_API_KEY_IOS="[YOUR_EXPO_PUBLIC_REVENUECAT_API_KEY_IOS]"

We'll come back later to this file to replace the placeholder with the real API keys.

Adding missing dependencies

In order to use the RevenueCat SDK on your React Native app, you'll need to install the react-native-purchases by running the following command:

npx expo install react-native-purchases

Setting up your Android and iOS “Apps” or in RevenueCat

Creating your Play service credentials (Android)

In order for RevenueCat's servers to communicate with Google on your behalf, you need to provide a set of service credentials.

Note that this setup takes place on both the Google Play Console and the Google Cloud Console. Due to the nature of the process, there’s some switching back and forth between each console that can’t be helped, but each step will make clear which console you should be looking at.

Creating a project in Google Cloud Platform

Before we can use Google as a social provider in your Expo app, it is essential to create a project in Google Cloud Platform. To set up your project, follow these steps:

1. Visit cloud.google.comand sign in.

2. Click on the dropdown at the top left corner.

   

3. Click on "New Project" at the top right corner.

   

4. Fill in the form and click on "Create", and wait until the project is created. It could take a few seconds or even minutes.

   Warning: Once you confirm this form, you won’t be able to change your project id.

5. Once the project creation is finished, you receive a notification like in the image below. Click “Select project” to set your new project as active, and you’ll be redirected to your new project’s dashboard.

   

   

Enable the Google Developer and Reporting API (Google Cloud Console)

1. Visit your project dashboard in Google Cloud Console.

   1. Make sure to use the same project you created while following this guide

2. Search for “Google Play Android”, and select “Google Play Android Developer API”

   

3. Click on “Enable”

   

4. Once this is enabled, you will be redirected. Using the same search box, now search for “reporting api”, and select “Google Play Developer Reporting API”

   

5. Click on “Enable”

   

Create a Service Account (Google Cloud Console)

1. Using the same search bar we used before, now search for “service accounts” and choose “Service Accounts” from the result list. This is under the “IAM & Admin” section

   

2. Click on “Create Service Account”

3. Choose a name for the account, like “sa for revenue cat”, and click “Create and continue”

   

4. On the step named 'Grant this service account access to project', you'll add two Roles:

   • Pub/Sub Admin - this enables Platform Server Notifications

   • Monitoring Viewer - this allows monitoring of the notification queue

1. Click on “Done” to finish (the third step is not required)

2. You’ll be redirected to the Service Accounts list. Now, you need to click on the Actions dropdown menu on the right, and select “Manage Keys”

   

3. Click on “Add key” → “Create new key”

   

4. Select “JSON”, and click on “Create” to confirm. Make sure to store that file securely.

5. Finally, copy the email account associated with your new Service Account. You’ll need this email in the next step

   

Create a new app in Google Play Console

Before you can grant RevenueCat financial access to your app, you’ll need to create a new app in Google Play Console.

1. First, we need to login into Google Play Console. If you still don’t have a Google Play Console account, create a new one before proceeding.

2. In the right section, click on “Create app”

   

3. Complete the form, and click “Create app” to confirm

Grant Financial Access to RevenueCat (Google Play Console)

1. In Google Play Console, click on Click on “Users and Permissions” in the sidebar

   

2. Click on “Invite new users”

   

3. Paste the email address you got in the previous step after creating the service account. Then click the “Add app” button, and select your app. Click on “Apply”.

   

4. Grant at least the following permissions:

   • “View app information” & “View app quality information”

     

   • “View Financial data” & “Manage orders and subscriptions”

     

Feel free to read through all the available options and check any additional option based on your needs. Those described above are the bare minimum to integrate with RevenueCat.

1. Click “Apply”, then “Invite User”, and finally “Send Invite”.

   

Update the credentials JSON in RevenueCat

1. Visit your RevenueCat dashboard, and go to your Project page.

2. Select “Play Store - Android”

   

3. Choose a proper name to easily identify your Android app in RevenueCat

4. In the “Google Play Package” field, use the same package identifier that you set in the app.js, file under app.androidPackage

5. Upload the JSON file you generated for the Service Account before

6. Click “Save Changes” to finish.

The validation process may take up to 36 hours, as described in the RevenueCat documentation here

Getting the Api Key

1. In the sidebar, click on “API Keys” under the “Project settings” section

2. Click on “show key” and copy the API key.

   

3. Update the .env file in your React Native project, replacing the following line with the Android Key.

    #.env file
    EXPO_PUBLIC_REVENUECAT_API_KEY_ANDROID="[YOUR_EXPO_PUBLIC_REVENUECAT_API_KEY_ANDROID]"
   

Enable Google Real-Time Developer Notifications to speed up the verification process

RevenueCat does not require anything further than service credentials to communicate with Google, but setting up real-time server notifications is a recommended process that can speed up webhook and integration delivery times and reduce lag time for Charts.

Follow the instructions described in the official documentation

"Credentials needs attention"

After getting the Android App Id, you’ll probably see a warning message in RevenueCat that says they couldn’t validate permissions to certain APIs. This is normal. In my experience, you’ll need to build and submit a build to the Google Play Console before you can get rid of this warning.

So, don’t waste time with this warning. We’ll get back later to check if the status has chanced.

iOS setup

EAS Build setup to generate a bundle identifier

Before you can setup iOS, you need to create an app in App Store Connect, and before you can do that, you need to register a bundle identifier. This is usually a tedius process, but the good news is thanks to Expo Application Services, this is really easy. But you'll need to setup EAS in your project first

1. First, you’ll need to install eas-cli. It is the command line app you will use to interact with EAS services from your terminal. To install it, run the command:

    npm i -g eas-cli
   

2. Login into EAS using the eas-cli package:

    eas login
   

3. Run the following command to generate a new project in Expo.

   Make sure to set the slug property on your app.config.ts file before proceeding, as this will be the name of your project in Expo.

    eas build:configure
   

4. Follow the steps described, and make sure to copy the projectId from your terminal. You’ll need to update your app.js file like this:

    {
      ...
      extra: {
    +   projectId: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    }
   

Register your Bundle Identifier using EAS (iOS)

Before you can continue configuring RevenueCat, you’ll need to register your Bundle Identifier for iOS. The easiest way to do this is using EAS build. However, you don’t need to go through the entire build process, mainly because you are still missing the RevenueCat App Id for iOS. To avoid unnecesary builds, follow these steps:

1. Run the following command to start the build process

    eas build --profile development --platform ios
   

2. Enter your iOS credentials to sign in.

3. After a successful login, you should see a message that says that your bundle identifier was registered, like this

   

4. Feel free to cancel the build process. You’ll go back later after getting the RevenueCat App Id.

Create your iOS app on App Store Connect

With the Bundle Identifier registered, you can now create a new App in the App Store Connect and select the registered Bundle Identifier.

1. Go to App Store Connect

2. Click on “My Apps”

3. Click on the “+” button, and the select “New App”

   

4. Choose a name, and make sure to select the right bundle identifier.

5. Click on “Create” to confirm

Setup App Store Connect Shared Secret (iOS)

With your new app created in App Store Connect, follow these steps to get the Shared Secret.

1. Go to App Store Connect

2. Navigate to “My Apps” and select your app.

3. Select "App Information" under the "General" section from the left side menu

4. Select "Manage" under the App-Specific Share Secret section from the right side

   

5. Click on “Generate”

   

6. Copy your shared secret and save it safely. You’ll need to paste it in RevenueCat later.

In-App Purchase Key configuration (iOS)

For RevenueCat to securely validate purchases through Apple Store Kit 2, authenticate and validate Subscription Offers requests with Apple and enable customer lookup via Order ID for iOS apps, you need to upload an in-app purchase key, and you'll also need to provide an Issuer ID.

In-app purchase keys are generated in the Users and Access section of App Store Connect. You can use the same in-app purchase key for all of your apps.

1. Go to App Store Connect

2. Click on “Users and Access”

   

3. Click the “Keys” tab, and then the “In-App Purchase” option in the sidebar. Finally, click the “Generate In-App Purchase Key” button

   

4. Choose a name, and click “Generate” to confirm

   

5. Once your key is generated, it will appear in Active Keys and you get one shot to download it. Select “Download In-App Purchase Key” and store the file in a safe place, you'll need to upload this to RevenueCat in the next step.

   You can only download an individual API key once. Prepare to copy and save your key in a safe place that you can refer to later on.

   

Setup iOS App in RevenueCat

1. Visit your RevenueCat dashboard, and go to your Project page.

2. In the top right corner, click on “New”

   

3. Select “App Store”

   

4. Choose a proper name to easily identify your iOS app in RevenueCat

5. Copy the “App Bundle ID” name from the app.js file in your project

6. Upload the .p8 file you just created (In-App Purchase Key)

   

7. Click on “Set secret” and paste the Shared Secret you generated before.

8. Make sure to add the Key ID and Issuer ID. You can get those values from App Store Connect.

   

   

9. Click “Save Changes” to finish.

Getting the Api Key

1. In the sidebar, click on “API Keys” under the “Project settings” section

2. Click on “show key” and copy the API key.

   

3. Update the .env file in your app with the new api key

    #.env file
    EXPO_PUBLIC_REVENUECAT_API_KEY_IOS="[YOUR_EXPO_PUBLIC_REVENUECAT_API_KEY_IOS]"
   

Building your app with EAS

react-native-purchases is a native module, which means you won't be able to test your app using Expo Go on your phone. You'll need to use a development client

But first, you'll to run the following commands:

# Install EAS globally
npm i -g eas-cli

# Run initial configuration
eas build:configure

This will guide you through the EAS configuration and will create a eas.json file with two profiles: development (used for the dev client) and production (used for to publish to the stores)

Building & Submitting your Android app

1. Now that you have both keys generated, you'll need to build and submit a first version of your app to the Google Play Console.

2. To generate your first build, run the following command:

    eas build --platform android --profile production
   

3. You'll get a link to track the progress of your build on EAS. Once it's done, go to expo.dev, then select your project, and go the “Builds” section in the sidebar.

4. Download the latest Android production build.

5. Go back to Google Play Console, and select your app.

6. In the sidebar, click on “Testing” → “Internal testing”

   

7. Click on “Create new release”

8. Upload your app bundle, and add the requested information to create your first release.

Checking permission status for the APIs (Android)

Once you have submitted your first internal build to the Google Play Console, it’s time to go back to RevenueCat and make sure all the permissions to the different APIs are valid.

1. Go back to your RevenueCat dashboard, choose your app, and select the Android App.

   

2. Below the “Service Account Credentials JSON” file uploader, Make sure you see a label that says “Valid credentials” and everything is checked like this

   

Follow the troubleshoot if you have any issue. More information here

Congrats! You are done with the first part! I know it's tedious, but it will worth the pain in the end!

What's next?

In the next part of the series, I'll guide you through everything you need to setup in the stores to enable in-app purchases & subscriptions.

You can read the next part of the series here:

Happy coding!

Building a mobile app is a challenging task. From coming up with an idea, prototyping, and finally building the app, there are many things to consider and problems we'll have to figure out:

• How do we make sure the entire app looks consistent?

• Do we need to support dark mode?

• Should the app feel like an iOS or an Android app? Maybe something in between.

• Is our app accessible and inclusive?

If you are building everything from scratch, you may need years of design experience to create something that looks consistent and, at the same time, has a clear answer to all the questions we mentioned early. On the other hand, building an accessible app with dark mode support and a cohesive look and feel takes a lot of time.

React Native UI Kits

We already established that building a mobile app from scratch is challenging and takes time. The good news is that there's a solution for that problem: We can use a React Native UI Kit.

A UI kit is a collection of assets containing design elements such as UI components, styles, and rules. UI components are elements that convey meaning and provide functionality to users.

Why should we use a React Native UI Kit?

UI kits can help you improve a design and development workflow in many ways:

• Speed up the design and build processes: We can rely on ready-to-use UI elements from the kit instead of creating our own elements.

• Time to market: We can ship faster and test our ideas by drastically reducing the design and development phases.

• Don't reinvent the wheel: As developers and entrepreneurs, we aim to solve a critical problem for our users. Therefore, we should focus our time and energy on solving that problem instead of creating a custom interface.

• Achieve consistency in your app: The design elements from a UI kit have a consistency that can be hard to achieve if you are building everything from scratch.

• Become a better designer: UI kits allow us to inspect the different elements and learn from them.

Best React Native UI Kits

Here's a list of the best React Native UI kits you can use to build your next app.

SpiroKit

A library with more than two years in the making. SpiroKit is not only a UI Kit but a complete toolkit for indie hackers that includes: Figma templates, UI Kit, Boilerplates & App templates.

It comes with 17 ready-to-use color palettes combined with three shades of gray (warm, neutral, and cool). Besides, it includes a global ThemeProvider that allows you to add your own color palette, custom fonts, and much more!

Every component comes with dark mode support, meaning that you don't need to do anything besides implementing a simple toggle for your users.

SpiroKit also includes a complete documentation portal built with StorybookJS, where you can copy-paste hundreds of working code examples.

This is a paid product, but we support Purchase Power Parity, so if you are interested, check out the landing page to see if you are eligible for a discount.

If you are interested on building a SaaS, We recently announced the release of SpiroKit for SaaS, a React Native starter kit specially designed for SaaS, complemented by a companion management system built on top of Notion.

It comes with Social Authentication, Profile management, Analytics, Push Notifications, In-app Purchases & Subscriptions, Error Reporting, Internationalization, and more!

Resources & stats

• Links:

  • SpiroKit for SaaS - Website

  • SpiroKit UI Kit - Website

  • Storybook Docs

  • Blog

React Native Elements

This is easily one of the more popular options available. It's open source and has its own VSCode Extension for snippets with preview and auto import. About customization, it includes a global ThemeProvider that you can use to setup your own theme from scratch.

Resources & stats

• 24k stars on GitHub

• Links:

  • GitHub

  • Website

Gluestack UI

Gluestack UI is a new headless UI kit that strongly focuses on accessibility and customization. It was built by the same team behind NativeBase, but it's a complete rewrite.

Gluestack UI is just a part of a brother ecosystem that also includes:

• gluestack-styles: Universal styling library

• DSX: A design system creator tool (not available yet)

• Builder: A low code tool to build apps (not available yet)

Resources & stats

• 1.3k stars on GitHub

• Links:

  • GitHub

  • Website

  • Docs

React Native Paper

Another popular kit. It's cross-platform but based on Google's Material Design guidelines. It has a default theme, but you can implement your own using the global ThemeProvider.

It also includes a documentation portal with all you need to setup your project.

One thing to notice is that this kit doesn't have app boilerplates, so you must go through the installation process to add this UI kit to your projects.

Resources & stats

• 11.9k stars on GitHub

• Links:

  • GitHub

  • Website

UI Kitten

A beautiful cross-platform UI Kit based on Eva Design System.

It also includes:

• Complete documentation portal with examples to copy/paste

• App boilerplates

• ThemeProvider and light/dark mode support

• You can build your own themes.

• It has its own icon pack with 480 icons (based on Eva Design System).

Resources & stats

• 10k stars on GitHub

• Links:

  • GitHub

  • Website

Tamagui

A style system, UI kit, and optimizing compiler for React Native & Web

A cross-platform UI Kit for Universal apps with a fantastic innovation: It's also a compiler that optimizes the output on build time. If you are familiar with Svelte, this is similar, but for universal apps with React Native.

This kit also has a core package (@tamagui/core), which is a good option if you want to build your own design system with a solid foundation.

It includes excellent documentation, and the team behind this project is moving fast!

Resources & stats

• 9.3k stars on GitHub

• Links:

  • GitHub

  • Website

  • Docs

Conclusions

The React Native ecosystem is constantly evolving, with many unique projects like those mentioned above.

Here are a few questions you should ask yourself before choosing the best option for you:

• Do I need complete control to customize every component?

• How much time do I have to build my next app?

• Do I want to build my own theme / define my color palette?

• Is it easy to implement? Does it include good documentation?

Based on your answers, you'll find the best solution for your specific situation.

I've tackled this challenge many times over the last few years while working on client projects, and today, I'm excited to share some of the lessons I've learned along the way.

I'm pleased to announce that I've been working on a new React Native starter kit.

SpiroKit for SaaS

SpiroKit for SaaS is a React Native starter kit specially designed for SaaS, complemented by a companion management system built on top of Notion.

How does it work?

When you're ready to kick off a new project, start by cloning our Notion Management System. This system includes a dashboard with step-by-step instructions to guide you through the entire development process.

From creating a new project with the starter template to setting up features like push notifications, authentication, social login, in-app purchases, error reporting, localization, etc., to building and submitting your app to the store, we've got you covered.

Each module or feature in the starter kit comes with hooks, providers, or configuration files to streamline your development process. Everything that can be automated is included with the starter kit, and any manual steps are documented and added to an ordered task list in Notion.

Keep track of your progress by marking tasks as "Done" in Notion, and feel free to add custom tasks tailored to each project.

Features

• Analytics with Vexo

  • The starter kit sets up everything for basic tracking of your app usage. Additionally, we'll provide step-by-step guides on setting up Vexo Analytics and examples of how to track custom events.

• In-app and subscriptions with RevenueCat

  • The kit comes with a fully functional integration with RevenueCat, a trusted solution for managing in-app subscriptions and purchases.

  • This includes a working example and paywall components, allowing you to present your subscription plans in minutes.

  • Our Notion system will guide you through setting up your RevenueCat project, subscriptions in the stores, and configuring products and entitlements in RevenueCat.

• Authentication with Supabase

  • We'll integrate Supabase with our UI kit to provide an outstanding authentication experience out of the box. This includes sign-in, sign-up with a password, social login with Google and Apple, magic links, forgot password, change password, user profile, and more.

  • We'll also include all the required documentation to set up different social providers using Supabase.

• Error reporting with Sentry

  • The starter kit comes with Sentry configured, a React Error Boundary, and a fallback UI to gracefully present unexpected errors.

  • We've also included useful screens like "Connection Lost" or "Sign in to continue," so you don't need to build everything from scratch.

  • Our Notion system will guide you through setting up Sentry and obtaining the relevant keys.

• Push notifications with OneSignal

  • OneSignal is ready to use in the starter kit, abstracting the process of asking for relevant permissions from users into a convenient hook you can invoke on your home screen.

  • Relevant documentation and tasks in Notion will guide you through obtaining API keys, setting up in-app messages, etc.

• Internationalization with react-i18next

  • Our kit comes with a working setup for internationalization with react-i18next. This includes a resource file for English and Spanish, allowing you to add your localization keys.

  • We also included a section in the user profile screen to allow users to switch languages based on their preferences. This preference is persisted on Supabase, so the next time your user opens the app, this preference will be remembered.

• Build, update and submit with EAS (Expo Application Services)

  • Our starter comes with an eas.json file ready to fill with your api keys.

  • Documentation is included so you can set up your channels and branches with EAS updates, enabling you to ship updates instantly without dealing with store reviews.

  • Our Notion system will also include documentation and tasks covering the entire process, from your first development client build to your first over-the-air update and submission to the stores.

• Figma Asset Kit for the stores

  • If you've published an app before, you know how challenging it can be to gather all the required information about the size of each asset for each store.

  • Our kit includes a convenient Figma Kit for a fake app that includes all the necessary assets you'll need

If you want to learn more about this template or get your license, checkout the new landing page we built for it.

If you already have a SpiroKit license and want to purchase this starter, feel free to reach-out at mauro@spirokit.com

Feedback is appreciated

I would love to hear your thoughts on this Notion + Starter combo. Are there any important elements I might be missing? Did I get something wrong?

Let me know in the comments.

Happy coding!

As devs, we try to stay informed about the latest tech news on an almost daily basis. This can be challenging, considering how fast our world moves and how much information is published on the internet all the time.

RSS feed apps are great for keeping a curated source of news, including your favorite topics and authors. But what if we could enhance that experience even further with an assistant who can use your curated feed to answer any questions and help you find the articles you really want to read?

In this post, we’ll go through the process of building a mobile RSS news feed with an AI assistant, using React Native, Supabase, and the OpenAI API.

The assistant will read your feed and answer your questions about it. It’ll also provide references to the original sources so you can keep reading the full article and dive deeper into the subjects you want to prioritize.

This project was built in collaboration with Paula Santamaría, who took care of the backend side.

Stack

• React Native: React Native is a JavaScript framework for writing real, natively rendering mobile applications for iOS and Android.

• Expo: Expo is an open-source platform for making universal native apps. It aims to simplify the development process by providing a set of tools, libraries, and services.

• SpiroKit is a React Native toolkit, including a UI kit, interactive documentation, and tons of starter templates.

• Supabase: Supabase is an open-source Firebase alternative with a ton of features. Here are some we used in this project:

  • PostgreSQL: The database provided by Supabase. In our case, it was used to store the Feed, embeddings, and all the data required by the application.

  • JS Client Library: We used it to interact with the database and other Supabase features. It also has TypeScript support!

  • pgvector extension: pgvector is an open-source PostgreSQL extension that allows you to store embeddings and provides vector similarity search.

  • Edge Functions: We delegated the data transformations and processing to Edge Functions. They are essentially TypeScript functions powered by Deno that run on the server and are globally distributed.

  • DB Functions: Ideal for handling data-intensive operations, such as similarity search between vectors.

  • Migrations: We generated migrations that took care of creating tables and database functions.

  • CLI: It helped us generate and apply migrations and deploy edge functions directly from the terminal.

• OpenAI API: This API takes care of generating embeddings based on the content from the feed and the user input. It also generates chat completions from a prompt we built, combining the user input and feed context.

Building the app

To start working on the React Native app, we needed to create a new project. In this case, we decided to use SpiroKit as our UI Kit and bootstrap a new project using SpiroKit’s “Expo - Supabase Starter” template.

This template comes with Expo SDK 49 + Expo Router v2 + TypeScript configured. It also includes a Supabase context wrapping the entire app. We can easily access the Supabase client and execute queries using hooks.

Mobile app

We wanted to keep the app simple: A feed with a list of posts to read, a button to ask questions about the feed, and a section to add new sources of information.

Feed route (Home)

• The home screen includes a list of posts from different sources, ordered by publishing date.

• It also includes a floating button to ask for information about the feed using AI.

• AI will take information from different posts to reply and list all the relevant sources considered for the reply. Each source will navigate to the corresponding post.

• There’s a list of predefined prompts you can choose

• We used the ActionSheet component from SpiroKit for the “Ask a question” modal.

Sources route

• The sources tab allows you to manage all your sources of information. You can add new sources by specifying a name, URL, and color to identify the source in your feed.

• You can use the “Sync” button below to retrieve all the latest posts for all your sources.

  • Internally, here is where embeddings are processed so you can ask questions about the posts.

• We used the ActionSheet component from SpiroKit for the “New source” modal.

Post details route

• When you navigate to a specific post, you’ll see a header with the title and author, followed by the body with the article's content.

• We used an amazing library called react-native-render-html to process the HTML and render it as native elements, which is way better than using a WebView.

• We reused the same “Ask a question” modal, but we are sending the post-id as additional information to exclude the rest of the posts.

  • We are using the Skeleton component from SpiroKit to present a loading indicator that emulates the expected output.

Dark mode support

• We personally use dark mode for almost everything, so we thought it would be cool to adapt the entire app to provide dark mode support.

• Because SpiroKit components already come with Dark mode support, and the library includes tons of hooks to define colors for each color mode and switch between modes, this took us 20 minutes.

Model

We decided to keep the model simple for this proof of concept. We have a table for sources that stores the blogs the user would like to include in their feed, along with some metadata.

The feed_items table stores the articles found in each source. We only keep articles from the past week, and expired articles are removed during the sync.

Finally, the feed_item_sections table stores the relevant content extracted from each article, which is split into different sections. It also stores the embedding for each section in a vector column provided by pgvector.

Note: You'll notice that there is no user data in this model. Since this was a simple proof of concept, we decided to leave that out. However, in a production app, that could be a problem 😂.

Feed Sync

This Edge Function is responsible for synchronizing the Feed Items from the existing Sources and processing them to store the relevant content and embeddings in the feed_item_sections table.

We first get an array of feed items from each source’s RSS feed, using the module MikaelPorttila/rss:

export const getRssItems = async (url: string): Promise<FeedEntry[]> => {
    const feedResponse = await fetch(url);
    const { entries } = await parseFeed(await feedResponse.text());

    return entries;
};

Then we process the content of each entry, to extract the relevant content, and create the embeddings:

const embeddingsResponse = await openai.embeddings.create({
    input: content,
    model: "text-embedding-ada-002",
});

Then it’s just a matter of storing everything in the DB:

const { error } = await supabaseClient
  .from('feed_items')
  .insert(newFeedItems);

const { error } = await supabaseClient
  .from('feed_item_sections')
  .insert(sections);

// Remove expired feed items
const { error } = await client
    .from('feed_items')
    .delete()
    .lt(dateColumn, expirationDate.toISOString());

Now our feed_items and feed_item_sections tables are updated with the latest content in our feed!

Feed Chat

This is another critical Edge Function for this project. It’s goal is to provide an AI generated response based on the user input and the relevant context (through context injection).

First step is to find the relevant content in our feed_item_sections. To do that, we need to generate the embedding for the user input and execute a similarity search against the embeddings stored in our database.

pgvector will take care of the similarity search. This is the perfect opportunity to generate a DB Function to encapsulate that logic, so we can simply invoke it like this from within our feed_chat Edge function:

// supabase/functions/feed-chat/index.ts

const { data: sections, error } = await supabaseClient.rpc("find_sections", {
    input_embedding: embedding, // user embedding to compare
    min_distance: 0.8, // Min distance to match
    max_results: 10, // Max result to return
    optional_feed_item_id: feedItemId ?? null // If user is within a specific feed_item
});

The find_sections db function is a bit large to include in this post, but take a look at this post if you want to know more about similarity search.

We also had to make sure to check the number of tokens we included in the prompt, especially in the content sections, since the model we used supported 4097 tokens, max. We used a tokenizer called gpt3-tokenizer for that.

for (const { section_content, section_token_count } of sections) {
    tokenCount += section_token_count; // Calculated by tokenizer.

    if (tokenCount >= TOKEN_LIMIT) break;

    context += `${section_content.trim()}\\n`
}

Once we have the relevant sections, we can move on to building a prompt with all the context the AI needs to create an appropriate response:

• User input (what does the user want?)

• Relevant content sections (context injected for the AI to use)

• You can also include a personality and expected output format

  • E.g: “You’re an assistant that helps users process a news feed effectively”, “Answer with plain text”.

Now we can call OpenAI Chat Completions API, and get a completion response based on our prompt:

export const generateCompletions = async (prompt: string) => {
    const { choices } = await openai.chat.completions.create({
        messages: [{ content: prompt, role: 'user' }],
        model: 'gpt-3.5-turbo'
    });

        // it's an array but by default it only has 1 element.
    return choices[0]?.message.content; 
}

We had to run everything through the Moderation API beforehand to ensure that we didn't violate OpenAI's policies.

Finally, we return the AI response and the Feed Items used as context, so the user can dive deeper into anything they find interesting:

return {
  chat_response: completion, // Response from OpenAI API 
  feed_item_references: references 
};

Final thoughts

We built this proof of concept in a week, and that's in part thanks to the amazing tools we had the opportunity to work with. Both OpenAI and Supabase provide incredible docs that truly made our job much easier.

Once all the parts were hooked up, we were also blown away by the potential of this tool. We feel like we're just scratching the surface of what could be a really powerful tool for knowledge workers.

That being said, we truly appreciate the work bloggers and content creators do. We don't want to build something that will get in the way of people enjoying great human-produced content. Instead, we'd like this tool to help potential readers reach great content easily, so that's a challenge we don't take lightly.

We will continue to explore this technology and idea, and see how it goes. For now, we hope our experience with this project provides you with tools and inspiration!

Resources

• Supabase Clippy: ChatGPT for Supabase Docs: https://supabase.com/blog/chatgpt-supabase-docs

• pgvector: Embeddings and vector similarity: https://supabase.com/docs/guides/database/extensions/pgvector

• SpiroKit: A React Native toolkit https://www.spirokit.com/

• TypeScript Gamified: Level up your TypeScript skills. Complete levels, unlock achievements, face challenges, and have fun! https://www.typescriptgamified.com/

• Building a mobile authentication flow for your SaaS with Expo and Supabase https://blog.spirokit.com/building-a-mobile-authentication-flow-for-your-saas-with-expo-and-supabase

• GPT3 Tokenizer https://github.com/botisan-ai/gpt3-tokenizer

• Storing OpenAI embeddings in Postgres with pgvector https://supabase.com/blog/openai-embeddings-postgres-vector

This includes almost 200 new stories with code snippets ready to copy and paste on your next app.

If you have been using the previous docs portal, you'll notice that the new one is almost identical, and that's on purpose.

Just as I aimed to provide a great experience when migrating from SpiroKit v1 to v2, I also wanted to ensure a smooth transition for the interactive documentation portal.

Here are a few links from the new docs portal that you may find useful:

Dashboard
https://docs.spirokit.com

Installation guide:
https://docs.spirokit.com/?path=/docs/getting-started-installation--page

Setting up your local environment to work with SpiroKit:
https://docs.spirokit.com/?path=/docs/getting-started-setup-your-local-environment--page

Introduction to Theming in SpiroKit:
https://docs.spirokit.com/?path=/docs/getting-started-theme-00-introduction--page

App template catalog:
https://docs.spirokit.com/?path=/docs/app-templates-catalog--page

It took a little bit more than I initially expected, primarily because all the new templates use Expo Router v2 instead of React Navigation. 😅

I also took the time to rename all the existing templates, so v2 is the default now.

Remember that all these templates are included for free with your SpiroKit license. No matter when you bought it.

Here's the complete list of all the available templates:

expo-template-typescript

The official SpiroKit v2 blank template for Expo SDK 49 + Typescript + Expo Router v2

npx create-spirokit-app@latest --template expo-template-typescript

expo-template

The official SpiroKit v2 blank template for Expo SDK 49 + Expo Router v2 (JS only)

npx create-spirokit-app@latest --template expo-template

nextjs-template-typescript

The official SpiroKit v2 blank template for NextJS with Typescript (Web only)

npx create-spirokit-app@latest --template nextjs-template-typescript

universal-app-template

The official SpiroKit v2 universal app template with Solito + Expo SDK 49 + NextJS + Typescript

npx create-spirokit-app@latest --template universal-app-template

expo-supabase-template-typescript

The official SpiroKit v2 template for Supabase + Expo SDK 49 + Expo Router v2

npx create-spirokit-app@latest --template expo-supabase-template-typescript

ecommerce-app-template

A SpiroKit v2 E-Commerce app template with Typescript + SDK 49 + Expo Router v2

npx create-spirokit-app@latest --template ecommerce-app-template

travel-app-template-typescript

A SpiroKit v2 Travel app template with Typescript + SDK 49 + Expo Router v2

npx create-spirokit-app@latest --template travel-app-template

If you still want to use v1, most of the templates are available with the "-v1" suffix.

What's next?

Next week, I'll work on the new Storybook documentation portal for v2, so stay tuned!

As always, if you have any questions, please reach-out via email at mauro@spirokit.com or leave me a DM on Twitter.

Happy coding!

• Choose between 17 pre-defined color palettes:

  

• Add custom colors and use one of them as your primary color. e.g.: Using a custom "steelBlue" palette as the primary color:

  

• Light and dark color mode

  

• Accent color and color mode override at the component level:

  • You can switch between light/dark or accent color at the component level by passing the colorMode and accentColor props.

• Switch between light and dark mode at runtime.

Those were great features, and it's probably enough for most cases, but I was missing something.

What if you want to switch the accent color at runtime and allow your users to choose the color they want? Or what if you want to override the color mode or accent color for a group of components without passing the props to each component? This is especially annoying when you nest components inside of a modal or action sheet.

Theme Shifter

Theme shifter is a new set of features, only available with SpiroKit v2, that will allow you to:

• Switch between accent colors at runtime. This is especially useful if you want to allow your users to choose a custom color for the UI.

• Apply a new color mode (light/dark) or accent color to a group of components.

Let's see this in action!

Switching accent color & color mode at runtime

The useTheme hook now allows you to make the switch and also get the current accent color and dark mode like this:

import { useTheme } from "@spirokit/ui"

const { 
  accentColor, 
  setAccentColor,
  colorMode,
  setColorMode
} = useTheme()

return (
  <VStack space="$2">
    <LargeTitle>You are using the {accentColor} accent color and {colorMode} mode</LargeTitle>
    <Button onPress={() => setColorMode(colorMode === "light" ? "dark" : "light")}>
      Toggle color mode
    </Button>
    <Button onPress={() => setAccentColor("emerald")}>
      Switch to Emerald theme
    </Button>
)

You can safely store your user preference and call the setAccentColor or setColorMode during startup 😉

Override accent color & color mode for a group of components

There's a new component called Theme. You can use it to wrap a group of components so they can inherit a new accent color or color mode:

import { Theme } from "@spirokit/ui"

return (
  <>
    <Theme accentColor="blue" colorMode="dark">
      <VStack padding="$2" backgroundColor={"$primaryDark.0"} space="$2">
        <LargeTitle>Dark blue section</LargeTitle>
        <HStack space="$2">
          <Button flex={1}>Cancel</Button>
          <Button flex={1}>Confirm</Button>
        </HStack>
      </VStack>
    </Theme>
    <Theme accentColor="red" colorMode="light">
      <VStack padding="$2" backgroundColor={"white"} space="$2">
        <LargeTitle>Red light section</LargeTitle>
        <HStack space="$2">
          <Button flex={1}>Cancel</Button>
          <Button flex={1}>Confirm</Button>
        </HStack>
      </VStack>
    </Theme>
  </>
)

As you can see in the image below, all 3 components are now inheriting the new preferences:

Start using these new features today.

• If you are already using SpiroKit v2, run the yarn upgrade or npm upgrade command to get the latest version. The theme shifter functionality was added on v2.0.0-rc.15

• If you are using v1, I highly recommend you to upgrade to v2. I just published a comprehensive guide with everything you need to do.

  • You can also use our new starters for v2:

      # Starter with Expo SDK 49, Expo Router v2, TypeScript and SpiroKit v2
      npx create-spirokit-app@latest --template expo-template-typescript-v2
    
      # Web Starter with NextJS 13, TypeScript and SpiroKit v2
      npx create-spirokit-app@latest --template nextjs-template-typescript-v2
    

I hope you can enjoy using these new features! And let me know what you think.

Happy coding!

This document is a work in progress. I'll keep updating this in case I find an edge case I forget to document.

In this article, I'll describe the required steps to migrate an existing SpiroKit v1 project so you can use v2, which comes with an entire rewrite and uses Tamagui's compiler. If you want to learn more about v2, please check out this article.

If you are just starting a new project with SpiroKit, you can already use our two starter templates for v2:

# Starter with Expo SDK 49, Expo Router v2, TypeScript and SpiroKit v2
npx create-spirokit-app@latest --template expo-template-typescript-v2

# Web Starter with NextJS 13, TypeScript and SpiroKit v2
npx create-spirokit-app@latest --template nextjs-template-typescript-v2

Package.json

On v1, the package you installed from the private repo was called @spirokit/core. On v2, you need to remove that package, and add the following packages:

• For native development with Expo

  • @spirokit/ui

  • @spirokit/native

• For web development with NextJS

  • @spirokit/ui

  • @spirokit/web

Besides, SpiroKit is now using @tamagui/lucide-icons instead of react-native-heroicons (More info about how to replace the items below)

Here's an example of your package.json after the changes

{
    "name": "expo-example",
    "version": "1.0.0",
    "main": "index.js",
    "scripts": {
-        "start": "expo start",
+       "start": "TAMAGUI_TARGET=native expo start",
-        "android": "expo start --android",
+       "android": "TAMAGUI_TARGET=native expo start --android",
-        "ios": "expo start --ios",
+       "ios": "TAMAGUI_TARGET=native expo start --ios",
-        "web": "expo start --web",
+       "web": "TAMAGUI_TARGET=web expo start --web",
    },
    "dependencies": {
-        "@spirokit/core": "latest",
+       "@spirokit/ui": "next",
+       "@spirokit/native": "next",
+       "@shopify/flash-list": "^1.4.3",
        "@expo-google-fonts/poppins": "^0.2.2",
-       "@expo/webpack-config": "^0.17.2",
-       "expo": "^47.0.0",
+       "expo": "^49.0.0",
-       "expo-linear-gradient": "~12.0.1",
        "expo-status-bar": "~1.4.2",
        "react": "18.1.0",
        "react-dom": "18.1.0",
        "react-native": "0.70.5",
-       "react-native-heroicons": "2.0.2",
+       "@tamagui/lucide-icons": "1.40.0",
        "react-native-safe-area-context": "4.4.1",
        "react-native-svg": "13.4.0",
        "react-native-web": "~0.18.7"
    },
    "devDependencies": {
        "@babel/core": "^7.19.3",
        "@types/react": "~18.0.24",
        "@types/react-native": "~0.70.6",
        "typescript": "^4.6.3"
    },
    "private": true
}

If you can, start from scratch using our new templates mentioned above, and then copy / paste your code.

If you want to keep your current project, check the package.json from our v1 and v2 templates

• v1 expo template: https://github.com/spirokit/templates/blob/main/expo-template-typescript/package.json

• v2 expo template (with expo router): https://github.com/spirokit/templates/blob/main/expo-template-typescript-v2/package.json

Upgrading imports

Search for from "@spirokit/core" and replace all the occurrences for from "@spirokit/ui".

You may get errors on missing components like DateTimePicker and Pressable. More info about this below.

Tokens

One big change from v1 to v2, is that all the design tokens are now strings, and are pre-pended with a "$" sign. This is how Tamagui works. Let me show you an example:

// v1
return (
  <Box padding={4} marginTop={2}>
    <Body fontWeight="bold">Hello world</Body>
  </Box>
)

// v2
return (
  <Box padding="$4" marginTop="$2">
    <Body fontWeight="$bold">Hello world</Body>
  </Box>
)

On v1, you usually use numbers to set things like padding, margin, borderRadius, etc. But there were "special values" defined on this list that were mapped to other values:

• Use 4 to get 16px

• Use 6 to get 24px

That was convenient but also confusing: If you were using 32, you would get 128px, but if you used 33, you get 33px.

On v2, you can still use numeric values, but all the size tokens now are strings with the "$" prefix.

After migrating a few apps to v2, I came up with a list of things you may need to check and replace. Thankfully, VSCode provides an excellent tool to find and replace these tokens quickly.

Font tokens

• fontWeight

  • Search for fontWeight=

  • Add the "$" prefix. Here are the values

    • <Body fontWeight="bold" /> -> <Body fontWeight="$bold" />

• fontSize

  • Search for fontSize=

  • Add the "$" prefix. Here are the values

    • <Body fontSize="lg" /> -> <Body fontSize="$lg" />

• lineHeight

  • Search for lineHeight=

  • Add the "$" prefix. Here are the values

    • <Body lineHeight="xl" /> -> <Body lineHeight="$xl" />

• letterSpacing

  • Search for letterSpacing=

  • Add the "$" prefix. Here are the values

    • <Body letterSpacing="xl" /> -> <Body letterSpacing="$xl" />

Color tokens

• backgroundColor, borderColor, color, shadowColor, outlineColor

  • Search for backgroundColor=, borderColor=, shadowColor, outlineColor

  • Add the "$" prefix

    • <Box backgroundColor="primary.500" /> -> <Box backgroundColor="$primary.500" />

Size tokens

• margin, marginLeft, marginRight, marginTop, marginBottom

  • Search for margin={, marginLeft={, marginRight={, marginTop={, marginBottom={

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box margin={4} /> -> <Box margin="$4" />

    • <Box marginTop={4} /> -> <Box marginTop="$4" />

• padding, paddingLeft, paddingRight, paddingTop, paddingBottom

  • Search for padding={, paddingLeft={, paddingRight={, paddingTop={, paddingBottom={

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box padding={4} /> -> <Box padding="$4" />

    • <Box paddingBottom={4} /> -> <Box paddingBottom="$4" />

• marginX

  • Search for marginX={

  • On v2, it was renamed to use marginHorizontal instead

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box marginX={4} /> -> <Box marginHorizontal="$4" />

• marginY

  • Search for marginY={

  • On v2, it was renamed to use marginVertical instead

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box marginY={4} /> -> <Box marginVertical="$4" />

• paddingX

  • Search for paddingX={

  • On v2, it was renamed to use paddingHorizontal instead

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box paddingX={4} /> -> <Box paddingHorizontal="$4" />

• paddingY

  • Search for paddingY={

  • On v2, it was renamed to use paddingVertical instead

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box paddingY={4} /> -> <Box paddingVertical="$4" />

• space

  • Search for space={

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box space={4} /> -> <Box space="$4" />

• width, minWidth, maxWidth

  • Search for width={, minWidth={, maxWidth={

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box width={4} /> -> <Box width="$4" />

    • <Box width={"full"} /> -> <Box width="$full" />

• height, minHeight, maxHeight

  • Search for height={, minHeight={, maxHeight={

  • Search for values in the size scale, like 1 to 10, 12,16,20,24, etc. Replace those values with strings with the "$" prefix. Full list of values

    • <Box height={4} /> -> <Box height="$4" />

    • <Box height={"full"} /> -> <Box height="$full" />

Border-radius tokens

On v1, border-radius allowed numeric values and the following tokens:

{
    "none": 0,
    "xs": 2,
    "sm": 4,
    "md": 6,
    "lg": 8,
    "xl": 12,
    "2xl": 16,
    "3xl": 24,
    "full": 9999
}

On v2, you can still use numeric values, and the following tokens (as string, with the "$" prefix:

{
  0: 0,
  1: 3,
  2: 5,
  3: 7,
  4: 9,
  true: 9,
  5: 10,
  6: 16,
  7: 19,
  8: 22,
  9: 26,
  10: 34,
  11: 42,
  12: 50,
}

You can use the new tokens like this

• <Box borderRadius="2xl"/> -> <Box borderRadius="$6"

• <Box borderRadius="full"/> -> <Box borderRadius="$12"

Or you can replace the old tokens with the numeric values

• <Box borderRadius="2xl"/> -> <Box borderRadius={16}

Pseudo props

SpiroKit v1 was built on top of NativeBase. That's why you could use pseudo props like:

• _hover

• _pressed

• _focus

• Platform-specific

  • _web

  • _iOS

  • _android

On SpiroKit v2, we are inheriting pseudo props from Tamagui. Platform-specific props are not available yet, so you'll need to check for the platform and conditionally add styles for now.

But you can still use the hover, pressed, and focus props with a new name.

• _hover -> _hoverStyle

• _pressed -> _pressStyle

• _focus -> _focusStyle

Learn more about these props here

Media props

On v1, you were able to set responsive values like this:

<Box width={{ base: "full", lg: "1/2" }}/>

On v2, we have separated props for each breakpoint:

<Box width="$full" $gtLg="$1/2" />

Breaking changes in components

• The Pressable component was removed. Now all the common layout components like Box, VStack, HStack, etc already include a onPress prop.

• Button component

  • The size prop no longer include the value "xs". use "sm" instead.

    You may notice that the buttons are a little bit smaller than in v1. This was based on feedback from users.

• Badge and FlatList components

  • On v1, you could add style props like this:

      <Badge paddingX={4} paddingY={2}>Hello</Badge>
    

  • On v2, style props were moved into the _container prop

      <Badge _container={{ 
        paddingHorizontal: "$4", 
        paddingVertical: "$2"
      }}>Hello</Badge>
    

• Switch component

  • value prop was replaced with the checked prop.

• Use DateTimeInput instead of DateTimePicker

  • The DatePicker component was temporarily removed. v1 was built on top of react-native-modern-datepicker and it had performance issues.

  • I'll rebuild this component soon. In the meantime, you can use the new DateTimeInput component. Documentation with examples will be available soon.

• Select component

  • ItemComponent prop was renamed. Use renderItem instead.

    This component is now using FlashList by Shopify, so enjoy the new performance boost 😉

• Box, HStack, VStack, etc

  • LinearGradient is not available yet. Will be added later.

  • SafeArea props are no longer available. I'll probably add them again later. In the meantime, you can get the same functionality doing the following refactor:

      // v1
      <Box safeAreaTop />
    
      // v2
      import { useSafeAreaInsets } from "react-native-safe-area-context";
      const { top } = useSafeAreaInsets();
    
      <Box top={top}>
    

Upgrading icons

• SpiroKit v1 was using react-native-heroicons (292 icons)

• SpiroKit v2 is now using @tamagui/lucide-icons (1237 icons)

• Components like Button, Alert, Badge, HorizontalCard, VerticalCard, PortraitCard, Input, Tab, TextArea should still work with the old icons, but I highly recommend you to make the switch. You can search for all the available components here

Migration is straightforward:

// v1
import { MapIcon } from "react-native-heroicons/outline"
<Button IconLeftComponent={MapIcon}>

// v2
import { Map } from "@tamagui/lucide-icons"
<Button IconLeftComponent={Map}>

Hooks

useColorMode

• In v1, there was a "useColorMode" hook inherited from NativeBase. In v2, I decided to remove this hook, and unify all the features related to color mode and accent color in the "useTheme" hook. More information about this in an upcoming post introducing new features related to theming capabilities.

• If you were using this hook to check for the active color mode, or to toggle between dark and light mode, you can now use the "useTheme" hook to achieve the same

// v1
const { colorMode, toggleColorMode } = useColorMode()

// v2
const { colorMode, setColorMode, accentColor, setAccentColor } = useTheme()

Feedback is appreciated 🙏

If you are trying to migrate and you find another issue that is not included on this post, please feel free to reach out to me at mauro@spirokit.com or send me a DM on Twitter

In this post, I'll walk you through what's new in this version and explain the reasoning behind choosing a new framework.

A fresh start

SpiroKit v1 was built on top of NativeBase, a popular React Native UI kit.

A while ago, I began reading about significant performance issues inherited from NativeBase, which impacted SpiroKit users (particularly Android). Furthermore, the team behind it announced a new library and decided to kill NativeBase. In light of these performance problems and the news about NativeBase being replaced with a new (and entirely different) library, I started searching for a better long-term solution.

Before continuing, I would like to give a shoutout to the NativeBase team for their hard work. They are now developing a new library called Gluestack that appears to address these issues, and I'm grateful for their contribution, which laid the foundation for SpiroKit v1 🙌

Seeking new solutions

After some research, I found Tamagui, and it immediately caught my attention. They were building a compiler that optimizes for web and mobile, and the benchmarks were mind-blowing:

React Native:

Web:

If you want to read more about the benchmarks, here you can find all the details

On top of those numbers, they have a vibrant and active community, and it aligns perfectly with SpiroKit's mission to make development smoother without sacrificing performance.

What's new in SpiroKit v2

SpiroKit no longer depends on NativeBase. The new version was completely rebuilt from the ground up to take advantage of Tamagui's compiler. Nevertheless, I wanted to provide a smooth transition from v1, and that's why all the components and the vast majority of the props remain the same.

The theming system, colors, and tokens are also the same, meaning that you can mostly copy/paste code from SpiroKit v1 to v2, and it should work with minor adjustments. In other words, same interface but a new implementation.

Yes, there are breaking changes, but don't worry—I'm currently working on a simple guide to help you transition smoothly. This guide will be available soon, alongside the new documentation portal built on top of Storybook.

Try it today!

I'm excited to announce that the release candidate of SpiroKit v2 is now available on our private NPM registry! You can dive into the improvements right away if you're a licensed user, or You can get your license here (we support parity purchase power 🌎). You can expect to see the final version 2.0 in the upcoming days as I go through a few more bugs.

New Templates available

I've created two new blank templates to help you get started quickly with SpiroKit v2.

1. Expo SDK 49 + Expo Router v2 + TypeScript
   This is the perfect template if you just want to focus on mobile. You get a web app for free thanks to Expo Router.

npx create-spirokit-app@latest --template expo-template-typescript-v2

1. NextJS 13 Web-only template
   If you only want to focus on web, this template is for you.

npx create-spirokit-app@latest --template nextjs-template-typescript-v2

These are blank templates, with everything configured and ready so you can start building. If you don´t want to start from scratch, we are working on migrating the rest of the templates, including auth with supabase, e-commerce template with more than 20 screens, travel-app template, and more!

What's coming next?

Stay tuned as I work on migrating the rest of the templates from v1. Among these templates, I'm especially excited about the Universal app template, which combines NextJS, Expo, SpiroKit, and Solito for efficient cross-platform development.

Once everything is migrated, I'll resume my work on new components and more documentation to simplify things like authentication with Supabase, payment integrations with Stripe, and more!

Closing Words

SpiroKit v2 represents a big step forward in my journey to provide tools that simplify development while boosting creativity. I'm thankful for your support and can't wait to see the incredible applications you'll build with SpiroKit. As always, my goal is to empower developers and simplify React Native development, so you can focus on shipping your ideas instead of looking for the perfect color for a button 😉

I would love to hear your thought about this new direction, and let me know if you want me to focus on something in particular.

Happy coding 💪

In my previous post, I shared a comprehensive guide about setting up Storybook to work with Expo SDK 49, Expo Router v2, and TypeScript.

If you haven't read that article yet, I highly recommend checking it out, as I'll be using the repository from the last post as a starting point.

Using Storybook with Expo Router v2, SDK 49 & TypeScript

You can also fork my GitHub repo

Since the Storybook Native setup is already working with Expo SDK 49, Expo Router v2, and TypeScript on my repo, this article will focus on adding Storybook web, so we can easily share our components with the rest of the team, or even publish it with Vercel.

The SpiroKit UI Kit includes an interactive documentation portal that is built with Storybook and is publicly available here. Feel free to explore it for inspiration and gather some ideas.

Adding dependencies

TLDR

1. Update your package.json to include all the required and recommended dependencies

   {
    "scripts": {
      ...
    },
    "dependencies": {
      ...
    },
    "devDependencies": {
      "@babel/core": "^7.20.0",
      "typescript": "^5.1.3",
      "@types/react": "~18.2.14",
      "@babel/plugin-proposal-export-namespace-from": "^7.18.9",
      "@react-native-async-storage/async-storage": "^1.19.0",
      "@react-native-community/datetimepicker": "^7.4.0",
      "@react-native-community/slider": "^4.4.2",
      "@storybook/addon-actions": "^6.5.16",
      "@storybook/addon-controls": "^6.5.16",
   +   "@storybook/addon-essentials": "^6.5.16",
   +   "@storybook/addon-links": "^6.5.16",
      "@storybook/addon-ondevice-actions": "^6.5.4",
      "@storybook/addon-ondevice-controls": "^6.5.4",
   +   "@storybook/addon-react-native-web": "^0.0.21",
      "@storybook/react-native": "^6.5.4",
   +   "@storybook/react": "^6.5.16",
   +   "@storybook/builder-webpack5": "^6.5.14",
   +   "@storybook/manager-webpack5": "^6.5.14",
   +   "babel-plugin-react-docgen-typescript": "^1.5.1",
   +   "babel-plugin-react-native-web": "^0.18.10",
   +   "metro-react-native-babel-preset": "^0.77.0",
      "babel-loader": "^8.3.0"
    },
    "expo": {
      ...
    },
   + "resolutions": {
   +   "react-docgen-typescript": "2.2.2",
   +   "@storybook/react-docgen-typescript-plugin": "1.0.6--canary.9.cd77847.0"
   + },
   + "overrides": {
   +   "react-docgen-typescript": "2.2.2",
   +   "@storybook/react-docgen-typescript-plugin": "1.0.6--canary.9.cd77847.0"
   + },
   }
   

2. Run npm install

For the web setup, we need to add a few dependencies. Some are required, and some are optional (but recommended for a better experience).

• @storybook/addon-links (optional)

  • This addon can be used to create links that navigate between stories in Storybook.

• @storybook/addon-essentials (optional, but highly recommended)

  • Storybook ships by default with a set of “essential” addons that add to the initial user experience. There are many third-party add-ons as well as “official” add-ons developed by the Storybook core team, such as:

    • Docs

    • Controls

    • Actions

    • Viewport

    • Backgrounds

    • Toolbars & globals

    • Measure & outline

    • Highlight

  • @storybook/addon-react-native-web (Required)

    • This addon configures @storybook/react to display React Native (RN) projects using React Native for Web (RNW)

  • @storybook/builder-webpack5 & @storybook/manager-webpack5 (Required)

    • Builder implemented with webpack5 to spin up a dev environment, compile your code into an executable bundle, and update the browser in real-time.

  • @storybook/react (Required)

    • Storybook React renderer for the web

  • Babel plugins & presets (Required)

    • babel-plugin-react-docgen-typescript: Plugin to generate docgen data from React components written in TypeScript.

    • babel-plugin-react-native-web: Plugin that will alias react-native to react-native-web and exclude any modules not required by your app (keeping bundle size down).

    • metro-react-native-babel-preset: Babel preset for React Native applications. React Native itself uses this Babel preset by default when transforming your app's source code.

Storybook also allows you to use Vite instead of Webpack, but I didn't try it yet. If you are interested on that kind of setup, check out this link

Refactoring our project structure

After finishing the previous post, you'll have a .storybook folder in the root of your project, containing all the config files for Storybook Native. However, since Storybook Web uses different plugins and addons, we'll need to create separate main.ts and preview.ts files.

So, instead of having this project structure:

/.storybook
-- (Configs for native)
-- stories

We'll have something like this:

/.storybook
-- stories
-- web (Folder for the web setup)
---- main.ts
---- preview.ts
-- native (Folder for the native setup)
---- index.ts (exports the Storybook UI)
---- main.ts
---- preview.ts
---- storybook.requires.js (autogenerated)

1. Run the following command to create the required folders

    mkdir .storybook/web .storybook/native
   

2. Move the existing files inside the native folder

    mv .storybook/index.ts .storybook/native/index.ts
    mv .storybook/main.ts .storybook/native/main.ts
    mv .storybook/preview.ts .storybook/native/preview.ts
    mv .storybook/storybook.requires.js .storybook/native/storybook.requires.js
   

3. In the native folder, we need to update the main.ts file to look into the right paths:

   module.exports = {
   - stories: ["./stories/**/*.stories.?(ts|tsx|js|jsx)"],
   + stories: ["../stories/**/*.stories.?(ts|tsx|js|jsx)"],
    addons: [
      "@storybook/addon-ondevice-controls",
      "@storybook/addon-ondevice-actions",
    ],
   };
   

4. Create the main.ts and preview.ts files inside the web folder

    touch .storybook/web/main.ts .storybook/web/preview.ts
   

Storybook Web Configurations

Adding config files

As I mentioned earlier, we need a different configuration for Storybook Web.

1. Let's start by creating the main.ts and preview.ts files inside the .storybook/web directory:

    touch .storybook/web/main.ts
    touch .storybook/web/preview.ts
   

2. Then, add the following content to the main.ts file:

    module.exports = {
      stories: [
        "../../src/components/**/*.stories.mdx",
        "../../src/components/**/*.stories.@(js|jsx|ts|tsx)",
      ],
      addons: [
        "@storybook/addon-links",
        "@storybook/addon-essentials",
        "@storybook/addon-react-native-web",
      ],
      core: {
        builder: "webpack5",
      },
      framework: "@storybook/react",
    };
   

   Here are a few things to mention about this configuration:

   • It loads stories from the src/components directory with MDX, JS, JSX, TS, and TSX file extensions.

   • Includes essential add-ons, links, and React Native Web support.

   • Includes Webpack 5 setup to be used as the builder and set the framework to Storybook React.

3. Finally, add the following content to the preview.ts file. Although this file is the same for both Web and Mobile at the moment, it's ok to keep these files separated. That way, we can apply different customizations for each platform as needed.

    export const parameters = {
      actions: { argTypesRegex: "^on[A-Z].*" },
      controls: {
        matchers: {
          color: /(background|color)$/i,
          date: /Date$/,
        },
      },
    };
   

Setup babel to generate docs for TypeScript components

We need to add the babel-plugin-react-docgen-typescript plugin in our babel.config.js file, so we can get useful generated docs for our TypeScript components:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
    plugins: [
      "react-native-reanimated/plugin",
      require.resolve("expo-router/babel"),
+     ["babel-plugin-react-docgen-typescript", { exclude: "node_modules" }],
    ],
  };
};

Adding NPM Scripts for Storybook web

Remember how running npm start launches our native app? I wanted to add two more commands: one to run Storybook Web and another to build the web portal. The latter will be useful if you plan to deploy it to Vercel later.

Note that I also had to update the npm start command to point to the new config path. Make sure to check that as well; otherwise, you'll get an error. 🙃

{
  "scripts": {
-   "start": "sb-rn-get-stories && expo start",
+   "start": "sb-rn-get-stories --config-path .storybook/native && expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web",
    "storybook-generate": "sb-rn-get-stories",
    "storybook-watch": "sb-rn-watcher",
+   "storybook:web": "start-storybook --config-dir .storybook/web -p 6006",
+   "build-storybook": "build-storybook"
  },
  "dependencies": {
    ...
  },
  "devDependencies": {
    ...
  },
  ...
}

Final touch

Go to the app/index.tsx file and update the require statement to point to the new native folder like this

import React from "react";
import { Text, View } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";

const storybookEnabled = process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === "true";

const Index = () => {
  return (
    <SafeAreaView>
      <Text>Hello world</Text>
    </SafeAreaView>
  );
};

let EntryPoint = Index;

if (storybookEnabled) {
- const StorybookUI = require("../.storybook").default;
+ const StorybookUI = require("../.storybook/native").default;
  EntryPoint = () => {
    return (
      <View style={{ flex: 1 }}>
        <StorybookUI />
      </View>
    );
  };
}

export default EntryPoint;

Last but not least, add the storybook-static directory to your .gitignore to prevent static files from being included in your source control.

node_modules/
.expo/
dist/
npm-debug.*
*.jks
*.p8
*.p12
*.key
*.mobileprovision
*.orig.*
web-build/
+ storybook-static/

# macOS
.DS_Store

That's it! Now run npm run storybook:web and enjoy!

Recap

In this article, we installed additional dependencies and dealt with Babel configurations to successfully run Storybook web with our React Native components.

I love that everything related to Storybook configuration now resides in the .storybook folder, serving as a single source of truth (including the stories).

Now, you can write your stories once and run Storybook on both native and web platforms. 🪄

Additionally, you can publish your Storybook Web portal to Vercel using the build script.

If you found this article helpful, please let me know in the comments section or hit the like button, so I'll continue writing about this topic.

Happy coding!

Imagine having a web portal to showcase, document, test, and improve all your React Native components. A place where you can build your own library over time and then use that library to quickly build and release all those app ideas you have.

If that sounds appealing to you, you'll love Storybook.

In this post, I'll talk about what Storybook is, how it can help you, and how to add it to your Expo project, taking advantage of Expo SDK 49 new features and Expo Router v2.

At the end of the post, you’ll have a working repo with Expo SDK 49, Storybook for React Native, Expo Router v2, TypeScript, and more!

Show me the code

If you already know Storybook, and you just want a working repo to fork, here is the link to the Github repo

What is Storybook, and how can it help you?

Storybook is an open-source tool for building UI components and pages in isolation. In other words, it's a library you can add to your project to test and document your components.

Are you still confused? No worries. I had to read the official documentation and search for real-life examples before genuinely understanding how powerful this tool is. So, follow me with this basic example.

Let's say we have a simple "Button" component. It receives the following props:

• text (string)
• disabled (boolean)
• onPress (function)

If you are working for a company, chances are that you'll have to communicate how your new component works to the rest of the team.

Besides, your teammates must know that your Button component exists to avoid code duplication.

Last but not least, you will need to test your component with different props combinations to make sure everything works as expected. For example, what happens if we use a really long text for our button? Is our component responsive?

Storybook is the solution to all the problems I mentioned before. It helps you build a centralized component library with rich and interactive documentation so your teammates can reuse or even improve it.

Setup options

There are two main ways to use Storybook with Expo. Based on what you choose, the installation process will be different.

Storybook web

• You work on your React Native components as usual and reference those components as Stories that can be rendered directly into the browser.
• You setup your Storybook project using the react starter
• Then, you use Webpack to transpile your native modules into something you can run on your browser
• Pros
  • You can publish your Storybook web portal and share it with your teammates. Everyone can access the documentation and play with the components without having to install anything.
• Cons
  • Any native component like a Date time picker won't be rendered. For those components, you will need to use the other method described below.
  • Even if you test your UI in the browser, some issues will only appear while running on a native device, so it’s not completely reliable.

Storybook native

• You replace the entry point of your React Native app with the Storybook UI. Everything is presented directly within your native device.
• You setup your Storybook project using the react-native starter
• Then, you tweak metro bundler to handle the Storybook UI, which is rendered on a native device.
• Pros
  • You don't have any limitations to render native components like Date Time Picker because everything runs on your phone.
  • The tests are completely reliable because you are running your components on a native device
• Cons
  • Reading documentation directly from your phone is not the best option if you want to promote collaboration within your team. Having a web interface is always better for developers who will spend hours a day working with a design system.

This article will be focused on showing how to run Storybook on a native device, but let me know if you are interested in learning how to build and deploy a web interface to share with the rest of the team. Maybe I could write about it in the next post.

Setting up an Expo project with Expo Router v2 and SDK 49

As of the writing of this article (July, 2023), I couldn’t find an official expo template that comes with TypeScript and Expo Router v2 configured, so let’s start by using the vanilla JS Expo Router starter and add TypeScript later.

1. Run the following command to create an empty project with Expo Router configured.

    npx create-expo-app@latest -e with-router
   

2. Because this starter comes with Expo SDK 48, we’ll need to run the following command to update Expo to SDK 49

    expo upgrade
   

   Make sure to check if the starter already comes with SDK 49. Maybe it’s not necessary to do the upgrade anymore (The Expo team moves really fast)

   You may need to install the expo-cli globally before running the upgrade. If that’s the case, run npm i -g expo-cli

3. Based on Expo official docs, for Expo Router v2 is no longer necessary to include the resolutions and overrides sections in the package.json, so we can delete them like this:

   {
    "scripts": {
      "start": "expo start",
      "android": "expo start --android",
      "ios": "expo start --ios",
      "web": "expo start --web"
    },
    "dependencies": {
      ...
    },
    "devDependencies": {
      "@babel/core": "^7.20.0",
      "@babel/plugin-proposal-export-namespace-from": "^7.18.9"
    },
   -"resolutions": {
   -  "metro": "^0.73.7",
   -  "metro-resolver": "^0.73.7"
   -},
   -"overrides": {
   -  "metro": "^0.73.7",
   -  "metro-resolver": "^0.73.7"
   -},
    "name": "expo-router-storybook-starter",
    "version": "1.0.0",
    "private": true
   }
   

4. Run the following commands to create an empty src folder where our components will be added, and an app folder for our application routes.

    mkdir src
    mkdir app
   

Adding TypeScript

1. Create an empty tsconfig.json by running this command

    touch tsconfig.json
   

2. With the tsconfig.json created, you can run npx expo start. Expo will detect a tsconfig.json file, ask you to install the missing dependencies, and handle the required setup for you, inheriting a few defaults from Expo’s base config.

3. Update the package.json to move both typescript and @types/react dependencies under devDependencies.

Adding support for Path Aliases (Optional)

Expo SDK 49 introduces support for Path Aliases. You can optionally follow these steps to setup a path alias for the src directory

1. Update your app.json by adding the “experiments” section like this:

   {
    "expo": {
      "scheme": "acme",
      "web": {
        "bundler": "metro"
      },
      "name": "expo-router-storybook-starter",
      "slug": "expo-router-storybook-starter",
   +  "experiments": {
   +    "tsconfigPaths": true
   +  }
    }
   }
   

2. Update the tsconfig.json to apply this configuration to our src directory.

   {
    "compilerOptions": {
   +  "baseUrl": ".",
   +  "paths": {
   +    "@/*": ["src/*"]
   +  }
    },
    "extends": "expo/tsconfig.base"
   }
   

That’s it! Now you can import your components like this:

import Button from '@/components/Button';

Instead of doing this:

import Button from '../../components/Button'

Adding Storybook to the project

Thanks to the amazing Storybook CLI, adding Storybook to your project is as simple as executing the following command

npx storybook@latest init

A few things I would like to mention about this process:

• Storybook will detect your framework and add all the required dependencies to your project
• It will also add a few essential add-ons like:
  • @storybook/addon-actions
    • Can be used to display data received by event handlers in Storybook.
  • @storybook/addon-controls
    • Gives you a graphical UI to interact with a component's arguments dynamically, without needing to code. It creates an addon panel next to your component examples ("stories"), so you can edit them live.
  • @storybook/addon-ondevice-actions
    • Allows you to log events/actions inside stories in Storybook while running on a mobile device
  • @storybook/addon-ondevice-controls
    • Allows editing a component's arguments dynamically via a graphical UI without needing to code while running on a mobile device
• You’ll see a new folder called .storybook that will include all the initial configs so you can run Storybook with the essential add-ons activated.
  • Here you’ll also find a Button component with their stories. We’ll talk more about this component later

Opting out from package version validations for Storybook dependencies

During setup, Storybook will install a few additional dependencies that, at the time of this writing, will throw a warning when you run npx expo start due to a mismatch between the installed versions and the ones expected by Expo. I’m talking about @react-native-async-storage/async-storage and @react-native-community/datetimepicker

Because I want to keep these versions, I decided to take advantage of a new feature released with SDK 49, which allows you to opt out from package version validations for a list of dependencies.

Feel free to run expo doctor --fix if you want to downgrade your dependencies to the version expected by Expo.

To use this new feature, we need to update the package.json, adding an array with the dependencies we want to exclude from the validation.

{
  "scripts": {
    "start": "expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web",
    "storybook-generate": "sb-rn-get-stories",
    "storybook-watch": "sb-rn-watcher"
  },
  "dependencies": {
    ...
  },
  "devDependencies": {
    ...
  },
+ "expo": {
+   "install": {
+     "exclude": [
+       "@react-native-async-storage/async-storage",
+       "@react-native-community/datetimepicker"
+     ]
+   }
+ },
  "name": "expo-router-storybook-starter",
  "version": "1.0.0",
  "private": true
}

You can now run npm start and verify you no longer see the previous warnings

Using client environment variables to conditionally load Storybook UI

I wanted to use an environment variable to enable/disable the Storybook UI based on my needs during development, so I decided to try another new feature included in SDK 49: Client environment variables.

If you want to learn more about Environment variables in Expo, checkout the amazing official docs by the Expo team. They even included steps to migrate from different tools like direnv or react-native-config 🙌

When you use client environment variables, you can simply create an .env file, and add your keys using the EXPO_PUBLIC_ prefix, and Expo will automatically expose those keys through Metro. That means we no longer need the transform-inline-environment-variables babel plugin.

1. Remove the mentioned plugin from babel.config.js

   module.exports = function (api) {
    api.cache(true);
    return {
      presets: ["babel-preset-expo"],
      plugins: [
   -    "transform-inline-environment-variables",
        "react-native-reanimated/plugin",
        require.resolve("expo-router/babel"),
      ],
    };
   };
   

2. Create an empty .env file

    touch .env
   

3. Update the new .env file, adding the following environment variable

    EXPO_PUBLIC_STORYBOOK_ENABLED=true
   

4. Because we are using Expo Router, we need to create a layout route. On this route, we’ll simply export a React component with a Slot, so Expo Router can render the child route there.

    touch app/_layout.tsx
   

    // app/_layout.tsx
   
    import { Slot } from "expo-router";
   
    let RootApp = () => {
      return <Slot />;
    };
   
    export default RootApp;
   

5. Then, add a new Index.tsx file inside the app directory. In this file, we’ll check the value of the environment variable to decide what to render

    touch app/Index.tsx
   

    // app/Index.tsx
    import React from "react";
    import { Text, View } from "react-native";
    import { SafeAreaView } from "react-native-safe-area-context";
   
    const storybookEnabled = process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === "true";
   
    const Index = () => {
      return (
        <SafeAreaView>
          <Text>Hello world</Text>
        </SafeAreaView>
      );
    };
   
    let EntryPoint = Index;
   
    if (storybookEnabled) {
      const StorybookUI = require("../.storybook").default;
      EntryPoint = () => {
        return (
          <View style={{ flex: 1 }}>
            <StorybookUI />
          </View>
        );
      };
    }
   
    export default EntryPoint;
   

Updating metro config

Based on Storybook docs, we also need to customize our metro.config.js to use the sbmodern resolver field in order to resolve the modern version of storybook packages. Doing this removes the polyfills that ship in commonjs modules and fixes multiple long-standing issues such as the promises never resolving bug and more (caused by corejs promises polyfill).

1. Create a new metro.config.js file

    touch metro.config.js
   

2. Use the following configuration

    const { getDefaultConfig } = require("expo/metro-config");
   
    module.exports = (async () => {
      let defaultConfig = await getDefaultConfig(__dirname);
      defaultConfig.resolver.resolverMainFields.unshift("sbmodern");
      return defaultConfig;
    })();
   

Loading Storybook with npm start

We’ll need to update our start script so Storybook can load the stories before the app starts.

{
  "scripts": {
-   "start": "expo start",
+   "start": "sb-rn-get-stories && expo start",
    "android": "expo start --android",
    "ios": "expo start --ios",
    "web": "expo start --web",
    "storybook-generate": "sb-rn-get-stories",
    "storybook-watch": "sb-rn-watcher"
  },
  ...
}

With everything in place, we should be able to run our app and see the Storybook UI like this:

If you now go to your .env file and set EXPO_PUBLIC_STORYBOOK_ENABLED to false, you can hit reload on your running app, and instantly see how your app loads instead of the Storybook UI 🪄

After running your app for the first time with Storybook, you should see a new file that was automatically generated by Storybook. I’m talking about the storybook.requires.js file. Please avoid changing this file.

We could stop here, but I wanted to add a few stories using TypeScript, so everything is set up correctly. Let’s work on that!

Cleaning up

One thing I don’t like about the default Storybook setup, is that it adds two example files: .storybook/stories/Button.js and .storybook/stories/Button.stories.js. If you are new to React Native and to Storybook, you may think it’s a good idea to store all your components directly in the .storybook/stories directory. Instead, I want to create a Button.tsx component inside src/components, and then import that component into my Storybook story.

1. Create the new components folder inside the src directory

    mkdir src/components
   

2. Move the Button.js file into the new directory, and rename it so you can use TypeScript

    mv .storybook/stories/Button/Button.js src/components/Button.tsx
   

3. Move Button.stories.js to the .storybook/stories directory, and rename it to use TypeScript

    mv .storybook/stories/Button/Button.stories.js .storybook/stories/Button.stories.tsx
   

4. Remove the Button directory, as it is no longer needed

    rm -rf .storybook/stories/Button
   

5. Rename a few more files to use TypeScript

    mv .storybook/main.js .storybook/main.ts
    mv .storybook/preview.js .storybook/preview.ts
    mv .storybook/index.js .storybook/index.ts
   

Using TypeScript within components and Stories

1. Update the Button.tsx component to add a type for the props, and also add an additional flag for the disabled state

    // src/components/Button.tsx
   
    import React from "react";
    import { TouchableOpacity, Text, StyleSheet } from "react-native";
   
    export type MyButtonProps = {
      onPress?: () => void;
      text: string;
      disabled?: boolean;
    };
   
    export const MyButton: React.FC<MyButtonProps> = ({
      onPress,
      text,
      disabled
    }) => {
      return (
        <TouchableOpacity
          style={[styles.container, { opacity: disabled ? 0.3 : 1 }]}
          onPress={onPress}
          activeOpacity={0.8}
          disabled={disabled}
        >
          <Text style={styles.text}>
            {text}
          </Text>
        </TouchableOpacity>
      );
    };
   
    const styles = StyleSheet.create({
      container: {
        paddingHorizontal: 16,
        paddingVertical: 8,
        backgroundColor: "purple",
        borderRadius: 8,
      },
      text: { color: "white" },
    });
   

2. Update the Button.stories.tsx file to reference the Button component from the new location, and we’ll also use a few types from Storybook to get proper IntelliSense for the args on each story.

    import React from "react";
    import { View } from "react-native";
    import { MyButton, MyButtonProps } from "../../src/components/Button";
    import { Meta, StoryObj } from "@storybook/react-native";
   
    const meta: Meta<MyButtonProps> = {
      title: "Button",
      component: MyButton,
      argTypes: {
        onPress: {
          action: "onPress event",
        },
      },
   
      decorators: [
        (Story) => (
          <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
            <Story />
          </View>
        ),
      ],
    };
   
    export default meta;
   
    type Story = StoryObj<MyButtonProps>;
   
    export const Basic: Story = {
      storyName: "Basic",
      args: {
        disabled: false,
        text: "Tap me",
      },
    };
   
    export const Disabled: Story = {
      args: {
        disabled: true,
        text: "Disabled",
      },
    };
   

   • A few things to mention here:

     • We are using the Meta type from Storybook to get better intelliSense for args and argTypes.
     • We also added decorators to wrap and center stories within a View.

     You can use the argTypes object inside meta to describe what control you want for each arg. If you want to learn more about available controls, checkout this link

Conclusions and closing words

I hope you find this post valuable! I would like to mention that the starter React Native template from Storybook was an amazing starting point. I just wanted to go the extra mile to set up everything with SDK 49, Expo Router, and TypeScript.

I would also like to thank:

• oxeltra_beton for giving me the idea to combine Storybook, Expo Router v2, and SDK 49 and write about it.
• Daniel Williams for all his contributions to the React Native and Storybook communities. I remember doing similar experiments with Expo and Storybook a few years ago, and I can't believe how much easier it was this time around. Thanks again, Daniel!

Please let me know if I’m missing something, or if I’m making a silly mistake in the process. I’m here to learn and improve.

Happy coding.

In a previous article, we covered the initial setup process for a React Native project and explained how to configure a basic MapView component using the react-native-maps library. If you haven't read that article yet, I highly recommend you check it out.

This time, I’ll skip the project setup and basic MapView configuration and focus on adding markers, customizing their icons and callouts, implementing animations, and handling marker interactions.

Adding interactive markers

Markers are an essential component in react-native-maps that allow us to place points of interest on the map. Each marker can have various properties, such as coordinates (latitude and longitude), title, description, and even custom icons.

To add markers to the MapView, we first need to define their properties. Let's start by updating the App.tsx from the previous article.

import React from "react";
import { StyleSheet } from "react-native";
- import MapView, { PROVIDER_GOOGLE } from "react-native-maps";
+ import MapView, { Callout, Marker, PROVIDER_GOOGLE } from "react-native-maps";

export default function App() {
+ const markers = [
+   {
+     coordinate: {
+       latitude: -34.603851,
+       longitude: -58.381775,
+     },
+     title: "Obelisco",
+     description:
+       "The Obelisco is an iconic monument located in Buenos Aires, Argentina. Standing tall at the intersection of Avenida 9 de Julio and Avenida Corrientes, it serves as a symbol of the city and a tribute to its historical and cultural significance.",
+   },
+   {
+     coordinate: {
+       latitude: -34.6011,
+       longitude: -58.3835,
+     },
+     title: "Teatro Colón",
+     description:
+       "Teatro Colón, also known as the Colon Theatre, is a world-renowned opera house situated in Buenos Aires, Argentina. With its stunning architecture and rich history, it is considered one of the finest opera houses globally, hosting exceptional performances and captivating audiences with its grandeur.",
+   },
+   // Add more markers as needed
+ ];

+ const renderMarkers = () => {
+   return markers.map((marker, index) => (
+     <Marker
+       key={index}
+       coordinate={marker.coordinate}
+       title={marker.title}
+       description={marker.description}
+     />
+   ));
+ };

  return (
    <MapView
      provider={PROVIDER_GOOGLE} // Specify Google Maps as the provider
      style={styles.map}
      initialRegion={{
        latitude: -34.603738,
        longitude: -58.38157,
        latitudeDelta: 0.01,
        longitudeDelta: 0.01,
      }}
    >
+     {renderMarkers()}
    </MapView>
  );
}

const styles = StyleSheet.create({
  map: {
    flex: 1,
  },
});

A few things to mention about the code snippet above:

• We updated our App.tsx to define an array of markers, each with its own coordinate, title, and description.
• We then use the renderMarkers function to render a <Marker> component for each item in the markers array, passing in the corresponding properties.
• By including the <Marker> components within the <MapView> component, the markers will be displayed on the map at their respective coordinates.

If everything went ok, you should see something like this:

That’s fine for a basic scenario, but if you are like me, you may think that we could improve the UI for that “tooltip” bubble that appears after pressing a marker. That tooltip is called “Callout”, and react-native-maps includes a <Callout> component we can use to wrap our custom card, so let’s create a <CustomCallout> component!

Customizing the Callout component

1. Before working on our new component, we’ll need to update our array of markers to add a new property called imageUrl. We’ll use this URL to display an Image for each point of interest. We are also adding a new type called MarkerWithMetadata to get better IntelliSense later in the Callout component.

   // App.tsx
   
   + export type MarkerWithMetadata = {
   +   coordinate: MapMarkerProps["coordinate"];
   +   title?: MapMarkerProps["title"];
   +   description?: MapMarkerProps["description"];
   +   imageUrl?: string;
   + };
   
   export default function App() {
   
    const markers: MarkerWithMetadata[] = [
      {
        coordinate: {
          latitude: -34.603851,
          longitude: -58.381775,
        },
        title: "Obelisco",
   +     imageUrl: "https://upload.wikimedia.org/wikipedia/commons/f/fc/Buenos_Aires_%2820234294752%29.jpg",
        description: "The Obelisco is an iconic monument located in Buenos Aires, Argentina. Standing tall at the intersection of Avenida 9 de Julio and Avenida Corrientes, it serves as a symbol of the city and a tribute to its historical and cultural significance.",
      },
      {
        coordinate: {
          latitude: -34.6011,
          longitude: -58.3835,
        },
   +     imageUrl: "https://upload.wikimedia.org/wikipedia/commons/1/1e/Buenos_Aires_Teatro_Colon_2.jpg",
        title: "Teatro Colón",
        description: "Teatro Colón, also known as the Colon Theatre, is a world-renowned opera house situated in Buenos Aires, Argentina. With its stunning architecture and rich history, it is considered one of the finest opera houses globally, hosting exceptional performances and captivating audiences with its grandeur.",
      },
      // Add more markers as needed
    ];
   
    ...
   }
   

2. Create a new folder called components and an empty file inside for our new component by running the following command on your terminal

    mkdir components
    touch components/CustomCallout.tsx
   

3. Now, open the CustomCallout file and add the following code

    import React from "react";
    import { View, StyleSheet, Dimensions, Image, Text } from "react-native";
    import { Callout } from "react-native-maps";
    import { MarkerWithMetadata } from "../App";
   
    const screenWidth = Dimensions.get("window").width;
   
    const CustomCallout: React.FC<{
      marker: MarkerWithMetadata;
    }> = ({ marker }) => {
      return (
        <Callout tooltip>
          <View>
            <View style={styles.container}>
              <Image
                source={{
                  uri: marker.imageUrl,
                }}
                resizeMode="cover"
                style={{ width: 100, height: "100%" }}
              ></Image>
              <View style={{ paddingHorizontal: 16, paddingVertical: 8, flex: 1 }}>
                <Text
                  style={{
                    fontWeight: "bold",
                    fontSize: 18,
                  }}
                >
                  {marker.title}
                </Text>
   
                <Text>{marker.description}</Text>
              </View>
            </View>
            <View style={styles.triangle}></View>
          </View>
        </Callout>
      );
    };
   
    const styles = StyleSheet.create({
      container: {
        backgroundColor: "white",
        width: screenWidth * 0.8,
        flexDirection: "row",
        borderWidth: 2,
        borderRadius: 12,
        overflow: "hidden",
      },
      triangle: {
        left: (screenWidth * 0.8) / 2 - 10,
        width: 0,
        height: 0,
        backgroundColor: "transparent",
        borderStyle: "solid",
        borderTopWidth: 20,
        borderRightWidth: 10,
        borderBottomWidth: 0,
        borderLeftWidth: 10,
        borderTopColor: "black",
        borderRightColor: "transparent",
        borderBottomColor: "transparent",
        borderLeftColor: "transparent",
      },
    });
   
    export default CustomCallout;
   

   A few things to mention:

   • We receive the marker with our custom type. This includes all the data we need to render our new card.
   • We are wrapping our UI with the <Callout> component from react-native-maps. We also pass the tooltip prop so we can take absolute control over the UI.
   • I also wanted to add a “tooltip” triangle below, so I included the styles for the triangle. Feel free to remove it if you want.

4. Finally, we need to update the App.tsx file to render our custom callout

   // App.tsx
   
   ...
   + import CustomCallout from "./components/CustomCallout";
   
   export default function App() {
    const markers: MarkerWithMetadata[] = [
      ...
    ];
   
    const renderMarkers = () => {
      return markers.map((marker, index) => {
        return (
          <Marker 
            key={index} 
            coordinate={marker.coordinate}
   -         title={marker.title}
   -         description={marker.description}        
          >
   +         <CustomCallout marker={marker}></CustomCallout>
          </Marker>
        );
      });
    };
   
    return (
      ...
    );
   }
   

That’s it! You should now look something like this:

Using a custom marker

Another cool thing about react-native-maps is that you can customize the marker icon to suit your needs. In the library docs, you can find two props available within the <Marker> component: image and icon.

The differences between these two properties are not clear to me (except for the fact that icon only works with the google maps provider), and in both cases you can pass a local image resource like this:

// App.tsx

...
+ import MarkerIcon from "./assets/marker.png";

export default function App() {
  const markers: MarkerWithMetadata[] = [
    ...
  ];

  const renderMarkers = () => {
    return markers.map((marker, index) => {
      return (
        <Marker
+         image={MarkerIcon}
+         // You can also use icon with Google Maps
+         icon={MarkerIcon}
          key={new Date().getTime() + index}
          coordinate={marker.coordinate}
        >
          <CustomCallout marker={marker}></CustomCallout>
        </Marker>
      );
    });
  };

  return (
    ...
  );
}

But there’s a catch! Because these props expect an ImageSource, it’s a little bit limited. As example, I couldn’t find an easy way to change the size of the image.

If you want to go crazy and implement a complex marker, you can add a children component inside the <Marker>, and the rendered content will replace the marker symbol. In this example, I’m only using an Image component and customizing the background color and borders, but feel free to experiment:

+ import MarkerIcon from "./assets/marker.png";

export default function App() {
  const markers: MarkerWithMetadata[] = [
    ...
  ];

  const renderMarkers = () => {
    return markers.map((marker, index) => {
      return (
        <Marker
          key={new Date().getTime() + index}
          coordinate={marker.coordinate}
        >
+         <Image source={MarkerIcon} style={styles.marker}></Image>
          <CustomCallout marker={marker}></CustomCallout>
        </Marker>
      );
    });
  };

  return (
    ...
  );
}

const styles = StyleSheet.create({
  map: {
    flex: 1,
  },
+ marker: {
+   width: 60,
+   height: 60,
+   resizeMode: "contain",
+   backgroundColor: "yellow",
+   borderRadius: 30,
+   borderWidth: 2,
+ }
});

After these changes, your custom markers should look like this:

This is just a basic example, but the possibilities are endless. As example, if you are working on a food delivery app, you could design a custom icon to represent how expensive is each restaurant, like: "💲", "💲💲", "💲💲💲", etc. You can then use conditional rendering to display the right icon based on your marker metadata.

Adding animations to markers

Disclaimer: I’m not good at animations, but I thought it could be fun to add a little touch to the map. What if each marker would provide subtle feedback to the user when it’s tapped?

Let’s make some changes to our App.tsx file, then I’ll explain a few points.

- import { StyleSheet, Image } from "react-native";
+ import { StyleSheet, Image, Animated } from "react-native";
...

export type MarkerWithMetadata = {
+ id: number;
  coordinate: MapMarkerProps["coordinate"];
  title?: MapMarkerProps["title"];
  description?: MapMarkerProps["description"];
  imageUrl?: string;
};

export default function App() {
  const markers: MarkerWithMetadata[] = [
    {
+     id: 1,
      ...
    },
    {
+     id: 2,
      ...
    },
    // Add more markers as needed
  ];

+ const markerScales = React.useRef<{
+   [key: number]: Animated.Value;
+ }>({});

+ for (const marker of markers) {
+   markerScales.current[marker.id] = new Animated.Value(1);
+ }

+ const handleMarkerPress = (marker: MarkerWithMetadata) => {
+   const scale = markerScales.current[marker.id];
+   Animated.timing(scale, {
+     toValue: 1.25,
+     duration: 100,
+     useNativeDriver: false,
+   }).start(() => {
+     Animated.timing(scale, {
+       toValue: 1,
+       duration: 100,
+       useNativeDriver: false,
+     }).start();
+   });
+ };

  const renderMarkers = () => {
    return markers.map((marker) => {
      return (
        <Marker
+         key={marker.id}
          coordinate={marker.coordinate}
          onPress={() => handleMarkerPress(marker)}
        >
+         <Animated.View
+           style={{
+             padding: 10,
+             transform: [{ scale: markerScales.current[marker.id] }],
+           }}
          >
            <Image source={MarkerIcon} style={[styles.marker]}></Image>
+         </Animated.View>
          <CustomCallout marker={marker}></CustomCallout>
        </Marker>
      );
    });
  };

  return (
    ...
}

What’s happening here?

• We are adding the id prop on each marker:
  • The id prop is added to each marker to uniquely identify them. This id will be used later to update the scale of the tapped marker.
• We are also adding an object to track the scale of each marker:
  • The markerScales object is created using useRef to keep track of the scale value for each marker. It is initialized as an empty object.
• We then handle the marker’s onPress event:
  • The handleMarkerPress function is called when a marker is pressed. It takes the marker object as a parameter, which contains the metadata for the pressed marker. Inside the function, an animation is triggered using Animated.timing to increase the scale of the marker to 1.25 over a duration of 100 milliseconds. Once this animation completes, a second animation is started to bring the marker's scale back to 1. This creates a visual effect of the marker briefly expanding and returning to its original size.
• Finally, we are wrapping our markers with Animated.View:
  • Inside the renderMarkers function, an Animated.View is used to wrap the marker. The transform style property is applied to the Animated.View to scale the marker based on the corresponding markerScales.current[marker.id].scale value.

If everything went as expected, you should look something like this:

Handling marker interactions

As we saw in the previous example, the <Marker> component comes with an onPress event that allows you to run a custom logic every time a marker is pressed.

But react-native-maps also includes a few more things I would like to mention:

• If you set draggable in your marker, you can also use onDragStart and onDragEnd to update your marker’s position.

  // App.tsx
  
  export default function App() {
    ...
  
    const renderMarkers = () => {
      return markers.map((marker) => {
        return (
          <Marker
            key={marker.id}
  +         draggable
  +         onDragEnd={(event) => {
  +           // use the new coordinates to update marker location
  +           const newCoordinate = event.nativeEvent.coordinate;
  +           marker.coordinate = newCoordinate;
            }}
            coordinate={marker.coordinate}
            onPress={() => handleMarkerPress(marker)}
          >
            ...
          </Marker>
        );
      });
    };
  
    return (
      ...
    );
  }
  

  

• You can also handle the onPress event inside the Callout component like this

  // CustomCallout.tsx
  
  ...
  
  const CustomCallout: React.FC<{
    marker: MarkerWithMetadata;
  }> = ({ marker }) => {
    return (
      <Callout
        tooltip
  +     onPress={() => {
  +       Alert.alert(`${marker.title} pressed`);
  +     }}
      >
        ...
      </Callout>
    );
  };
  
  ...
  
  export default CustomCallout;
  

That’s it for this article. Please let me know if you find it useful. I’m planning to keep writing about Maps in React Native, so feel free to reach out if there is any specific topic you would want me to cover in the future.

To learn more about the <Marker> component, you can also visit the docs on GitHub

Happy coding!

Maps are everywhere and can be used for a wide range of purposes, allowing you to represent different types of data, and enabling powerful interactions for your users.

Whether you need to display store locations for a delivery app, show routes in a fitness app, or highlight nearby hospitals in a healthcare app, chances are you will need to deal with maps sooner or later.

In this series, we'll cover the basics of working with maps in React Native:

• Expo Project setup

• Google Cloud Console setup

  • Creating a Google project

  • Getting API keys for each platform

  • Setting up restrictions for each platform

    • Getting the required SHA-1 Certificate Fingerprint by building our app with EAS build

• Creating a basic map

• Requesting user permission to access their current location

• Displaying data within the map

• Handling user interactions.

• More!

These series are divided into two parts:

• The boring (but needed) part: Project setup, getting the API keys, building the app, and getting the SHA-1 Certificate (required for your API keys)

• The fun part: Start playing with maps and adding cool features.

By the end of this article, you’ll be done with the boring stuff, and you’ll have a basic map working in your app. The next article will cover the fun part, and will be released next week.

Creating a new project

Let’s start by creating an empty react native project with Expo. I’ll be using the expo-template-blank-typescript to avoid dealing with TypeScript configurations.

npx create-expo-app -t expo-template-blank-typescript

Adding react-native-maps

If you're working with maps in React Native, look no further than react-native-maps. It offers a lot of handy features, including markers, user location tracking, and event handling, as well as advanced functionalities like overlays and marker clustering.

Furthermore, you have the freedom to completely customize the appearance of your map to align with your brand or to support dark mode.

Run the following command in the root of your project to add react-native-maps

npx expo install react-native-maps

By using the npx expo install command, we make sure that we get the right version of react-native-maps for the Expo SDK version we are using. At the time I’m writing this article, the latest SDK version is 48.

Setting up Google Maps SDK

While working with react-native-maps. You’ll need to use the GOOGLE_PROVIDER to present a unified look and feel on both platforms. Because the Google provider relies on Google APIs for many features, we’ll need to get our API Keys and tie everything up within our Expo project so everything works as expected.

But there’s a catch. In order to properly setup your Android API key restrictions (highly recommended to protect your API key from unauthorized use), you’ll need to provide a SHA-1 Certificate Fingerprint. There are two ways you can get this certificate:

1. Build your app and upload your binary to the Google Play console.

2. Create a development build with EAS build, the Expo service that allows you to build your apps in the cloud.

You’ll eventually need to upload your binary before publishing your app to the Play Store, but it involves many additional steps that are outside of the scope of this tutorial, so we’ll proceed with option 2.

Creating a development build with EAS build

For this part of the tutorial, you’ll need to have an Expo account and install the eas-cli globally. If you don’t have an account already, please visit https://expo.dev and sign up.

If you are already using EAS and want to add maps to an existing project, you can skip the following steps

1. Once you have an Expo account, run the following command on your terminal to globally install the eas-cli package

    npm install -g eas-cli
   

2. Run the eas login command, and enter your username and password.

3. Once you are logged in, run the following command to set up your project.

    eas build:configure
   

   Select all platforms when asked, so you can build for both platforms later.

4. After this step, your project will now include a new eas.json file where you can setup your different build profiles. For the scope of this article, we’ll use the “preview” profile that is already configured. Besides, Expo will create a new project for you. You can now visit expo.dev and search for your new project.

5. Update your app.json file to provide a package name for your Android app, and a bundle identifier for your iOS app.

   {
    "expo": {
      "name": "maps-demo",
      "slug": "maps-demo",
      "version": "1.0.0",
      "orientation": "portrait",
      "icon": "./assets/icon.png",
      "userInterfaceStyle": "light",
      "splash": {
        "image": "./assets/splash.png",
        "resizeMode": "contain",
        "backgroundColor": "#ffffff"
      },
      "assetBundlePatterns": ["**/*"],
      "ios": {
        "supportsTablet": true,
   +    "bundleIdentifier": "com.example.mapsdemo"
      },
      "android": {
        "adaptiveIcon": {
          "foregroundImage": "./assets/adaptive-icon.png",
          "backgroundColor": "#ffffff"
        },
   +    "package": "com.example.mapsdemo"
      },
      "web": {
        "favicon": "./assets/favicon.png"
      },
      "extra": {
        "eas": {
          "projected": "..."
        }
      }
    }
   }
   

6. Run the following command to create your first Android build

    eas build --platform android --profile preview
   

Follow the instructions, and EAS will proceed to create a new Android Keystore for you. This Keystore is used to sign the Android app during the build process, ensuring its security and integrity.

After signing the app, Expo will automatically start building your app in the cloud.

At this point, you can visit https://expo.dev and see your new project with the first build in progress.

This build can take a few minutes, but we can already get the SHA-1 Certificate we need. 😉

Getting the SHA-1 Certificate Fingerprint

1. Go to https://expo.dev and click on your new project in the sidebar, as shown in the image above.

2. From your project dashboard, click on “Credentials” within the “Configure” section

   

3. With “Android” active in the top menu (active by default), click on your application identifier

   

4. Within the “Android Keystore” section, you’ll see your generated SHA-1 Certificate Fingerprint. Copy this, as you’ll need it below while setting up everything in Google Cloud Console.

   

Creating a project in Google Cloud Platform

Before we can use Google as a Maps provider, it is essential to create a project in Google Cloud Platform. To set up your project, follow these steps:

1. Visit cloud.google.com and sign in.

2. Click on the dropdown at the top left corner.

   

3. Click on "New Project" at the top right corner.

   

4. Fill in the form and click on "Create", and wait until the project is created. It could take a few seconds or even minutes.

   Warning: Once you confirm this form, you won’t be able to change your project id.

5. Once the project creation is finished, you receive a notification like in the image below. Click “Select project” to set your new project as active, and you’ll be redirected to your new project’s dashboard.

   

   

Enabling Google Maps SDK

With the new project created, we now need to enable Google Maps SDK. Let’s do that step-by-step:

1. Click on “APIs & Services”

   

2. Click on “Enable APIs and services”

   

3. We’ll need to enable “Maps SDK for Android” and “Maps SDK for iOS”.

   

4. Let’s start with Android first. Click on the “Maps SDK for Android” card.

5. Next, click on “Enable”. This will take a few seconds, and you’ll get your API key.

   

   Make sure to store the key. You’ll need it later.

6. Repeat the same steps for iOS to enable “Maps SDK for iOS”

   At least in my case, I didn’t get an API key for iOS after enabling it. So we’ll create an API key later in this article.

You now have both services enabled for your Google Console project. The next step is to set up a few app restrictions for each platform.

Setting up “App restrictions”

Setting up app restrictions while working with the Google Maps SDK is highly recommended for several reasons:

1. Security: By setting up app restrictions, you can ensure that only your authorized apps are able to use the Google Maps SDK with your API key.

2. Quota management: The Google Maps SDK has usage limits and quotas associated with it. By setting up app restrictions, you can effectively manage and monitor the usage of the SDK for each of your authorized apps. This helps prevent excessive usage that could lead to unexpected costs.

3. API key management: App restrictions provide an additional layer of protection for your API key. If you need to revoke access for a specific app or if you suspect unauthorized usage, you can easily update the app restrictions to disable access for that app without affecting other authorized apps.

App restrictions for Android

1. Within “APIs & Services”, click on the “Credentials” button in the sidebar, and then click on “Maps API Key”

   

2. Update the name of the API key so it’s easier to differentiate between Android and iOS. I added the “Android” prefix, but feel free to choose the name you want.

3. Within the “Set an application restriction” section, choose “Android apps”

4. A new section called “Android restrictions” will appear. Click on the “+ Add” button, and complete the form with your package name (needs to match with your app.json file) and your SHA-1 certificate fingerprint.

   

5. Click “Done” and then “Save” to confirm your new restrictions.

6. Copy your API key and add it to your app.json file:

   {
    "expo": {
      ...
      "android": {
        ...
        "package": "com.example.mapsdemo",
   +     "config": {
   +       "googleMaps": {
   +         "apiKey": "YOUR_ANDROID_API_KEY"
   +       }
   +     }
      }
    }
   }
   

App restrictions for iOS

1. Go back to the "Credentials" section and click on the "Create credentials" menu. then click on "API key"

   

2. Google will generate a new API Key. Copy it for later. Then, close the modal and click on the new API to set up the restrictions, the same as you did for Android before.

   

3. Update the name of the API key so it’s easier to differentiate between Android and iOS. I added the “iOS” prefix.

4. Within the “Set an application restriction” section, choose “iOS apps”

5. A new section called “iOS restrictions” will appear. Click on the “+ Add” button, and complete the form with your bundle identifier (it needs to match with your app.json file)

6. Click “Done” and then “Save” to confirm your new restrictions.

   

7. Copy your API key and update your app.json file like this

   {
    "expo": {
      ...
      "ios": {
        "bundleIdentifier": "com.example.mapsdemo",
   +     "config": {
   +       "googleMapsApiKey": "YOUR_IOS_API_KEY"
   +     }
      },
      ...
    }
   }
   

Adding a basic map

Update your App.tsx file to render a MapView that covers the entire screen

import React from "react";
import { StyleSheet } from "react-native";
import MapView, { PROVIDER_GOOGLE } from "react-native-maps";

export default function App() {
  return (
    <MapView
      provider={PROVIDER_GOOGLE} // Specify Google Maps as the provider
      style={styles.map}
      initialRegion={{
        latitude: -34.603738,
        longitude: -58.38157,
        latitudeDelta: 0.01,
        longitudeDelta: 0.01,
      }}
    />
  );
}

const styles = StyleSheet.create({
  map: {
    flex: 1
  },
});

Here are a few things to mention about this code:

• The provider prop is set to PROVIDER_GOOGLE, indicating the use of Google Maps as the map provider for both platforms.

• The initialRegion prop defines the initial center and zoom level of the map using the specified latitude, longitude, and delta values.

• For the map styles, we are using flex:1, so we can fill the screen with the map.

You can now run your app with npm start or yarn start. If everything went as expected, you should see your full-screen map ✨

Congrats! You are done with the boring stuff! Stay tuned for the next article, where we’ll start working with our map to add new features, track user events, and more.

Final thoughts

I saw a few articles that talked about how to use maps in React Native, but I couldn’t find an article focused on the boring but important configurations required to use maps in a secure way, so my goal for this article was to address all those aspects that are usually overlooked.

Please let me know if you find it useful, and if you want me to cover specific topics about react-native-maps or React Native in general.

Happy coding!

In today's connected world, it's crucial for mobile apps to provide proper support for users who speak different languages.

In this article, we are going to build a fully-functioning React Native app that supports multiple languages, allowing users to even switch between different languages based on their preferences.

As a bonus, we’ll also build a custom hook to deal with localized dates.

Final code

If you want to jump directly into the code, here's the Snack

What is localization?

Localization refers to the process of adapting an application to meet the specific language, cultural, and regional requirements of different target audiences. The process of implementing localization usually starts with translating the text of the UI, but it can go beyond and consider other preferences like date and time formats, currency symbols, measurement units, and more.

Benefits of implementing localization

By implementing localization, mobile apps can reach a broader audience and enhance user engagement. It allows users to interact with the app in their native language, making it more accessible, intuitive, and enjoyable for them

Creating a new React Native project

Let’s start by creating an empty react native using Expo. I’ll be using the expo-template-blank-typescript to avoid dealing with TypeScript configuration.

npx create-expo-app -t expo-template-blank-typescript

Once the project is ready, cd into your project and run the following command in the root to add the required dependencies

npx expo install expo-localization i18next react-i18next

By using the npx expo install command, we make sure that we get the right version of each package for the Expo SDK version we are using. At the time I’m writing this article, the latest SDK version is 48.

We’ll use expo-localization to get the user’s preferred locale, i18next to simplify the process of translating and displaying text in different languages, and react-i18next as an extension of the i18next library that includes a list of convenient hooks and components we can use while translating a react app.

Setting up localization

Creating the required files

To setup localization in our Expo app, let’s start by creating a i18n.ts file at the root of the project.

# Create an empty file
touch i18n.ts

Feel free to choose whatever name you want for the file.

We also need to create a translate folder where we’ll add a separate json file for each supported language. In this article, I’ll add support for English and Spanish.

mkdir translate
touch translate/es.json
touch translate/en.json

Adding localization keys for each supported language

In the new json files, make sure to initialize both json files to avoid annoying errors when setting up localizations later in the article.

translate/en.json

{
  greetings: "Hello world"
}

translate/es.json

{
  greetings: "Hola mundo"
}

Configuring the i18n instance

Next, let’s add the following code in the new i18n.ts file to initialize i18next.

//i18n.ts

import i18n from "i18next"
import { initReactI18next } from "react-i18next"
import es from "./translate/es.json"
import en from "./translate/en.json"
import * as Localization from "expo-localization";

const getLangCode = () => {
  const code = Localization.getLocales().shift();
  if (!code) return "en";
  return code.languageCode;
};

i18n.use(initReactI18next)
    .init({
        compatibilityJSON: "v3",
        lng: getLangCode(),
        defaultNS: "translation",
        interpolation: {
            // We disable this because it's not required, given that react already scapes the text
            escapeValue: false
        },
        // Here you can add all your supported languages
        resources: {
            es: es,
            en: en
        }
    })

export default i18n

Here are a few things to mention about this block of code:

• We use initReactI18next to initialize and setup i18next on our expo app.

• We retrieve the current device locales using expo-localization and extract the language code from the first locale.

• We are using the compatibilityJSON setting to make sure the default behavior is to use a JSON parser that supports advanced features such as nested objects and pluralization.

• We are disabling text escaping in the interpolation to rely on React’s built-in escaping.

• We are defining the resource files for each supported language.

• We set “translation” as the default namespace

  • If you want to learn more about namespaces in i18next, checkout this article

• Finally, we export the i18n instance to use it later.

Wrapping our app with the I18nextProvider

Thanks to react-i18next, we can wrap our entire app using the I18nextProvider. Here are a few benefits to mention:

1. Centralized Configuration: The I18nextProvider allows you to centralize the configuration of i18next in a single place. By wrapping the app with the provider, you can set up and configure i18next once and have it accessible throughout your entire application.

2. Context Propagation: The I18nextProvider utilizes React's Context API to provide the i18next instance and translations to all nested components. This eliminates the need to pass down the i18next instance manually through props to every component that requires access to translations.

3. Efficient Updates: The I18nextProvider manages the i18next instance and ensures that updates to language and translations propagate efficiently to the components that depend on them. It optimizes the rendering process by selectively re-rendering only the affected components when language changes occur.

4. Simplified Usage: Wrapping the app with the I18nextProvider simplifies the usage of i18next within components. It eliminates the need to manually import and initialize i18next in every component that requires translations, as the provider takes care of this automatically.

5. Future-Proofing: Using the I18nextProvider ensures that your application is prepared for any future updates or changes to the i18next library. It provides a standardized and recommended way to integrate i18next with React, ensuring compatibility and ease of maintenance.

Let’s update the App.tsx file to include the provider:

import { StatusBar } from 'expo-status-bar';
import { StyleSheet, Text, View } from 'react-native';
+ import i18n from "./i18n";
+ import { I18nextProvider } from "react-i18next";

export default function App() {
  return (
+   <I18nextProvider i18n={i18n}>
      <View style={styles.container}>
        <Text>Open up App.tsx to start working on your app!</Text>
        <StatusBar style="auto" />
      </View>
+   </I18nextProvider>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Using localization keys within a React component

With everything in place, it’s time to use our localization keys inside a React component.

1. First, we need to create a new folder and an empty file for the card component:

    mkdir components
    touch components/Card.tsx
   

2. Add the following code to the Card component

    // components/Card.tsx
   
    import React from "react";
    import { View, Text, StyleSheet } from "react-native";
   
    type CardProps = {
      title: string;
      content: string;
    };
   
    const Card: React.FC<CardProps> = ({ title, content }) => {
      return (
        <View style={styles.container}>
          <Text style={styles.title}>{title}</Text>
          <Text style={styles.content}>{content}</Text>
        </View>
      );
    };
   
    const styles = StyleSheet.create({
      container: {
        backgroundColor: "#fff",
        borderRadius: 8,
        padding: 16,
        marginBottom: 16,
        shadowColor: "#000",
        shadowOffset: { width: 0, height: 2 },
        shadowOpacity: 0.2,
        shadowRadius: 2,
        elevation: 2,
      },
      title: {
        fontSize: 18,
        fontWeight: "bold",
        marginBottom: 8,
      },
      content: {
        fontSize: 16,
        lineHeight: 22,
      },
    });
   
    export default Card;
   

3. Now, let’s update the App.tsx to add a few instances of the Card component:

import { StatusBar } from 'expo-status-bar';
- import { StyleSheet, Text, View } from 'react-native';
+ import { StyleSheet, SafeAreaView, View } from 'react-native';
import i18n from "./i18n";
- import { I18nextProvider } from "react-i18next";
+ import { I18nextProvider, useTranslation } from "react-i18next";

export default function App() {
  return (
    <I18nextProvider i18n={i18n}>
-     <View style={styles.container}>
-       <Text>Open up App.tsx to start working on your app!</Text>
-       <StatusBar style="auto" />
-     </View>
+     <Home />
+     <StatusBar style="auto" />
    </I18nextProvider>
  );
}

+ const Home = () => {
+   const { t } = useTranslation("cards");
+   return (
+     <SafeAreaView style={{ flex: 1 }}>
+       <View style={styles.container}>
+         <Card title={t("cardTitle")} content={t("cardDescription")} />
+         <Card
+           title={t("anotherCardTitle")}
+           content={t("anotherCardDescription")}
+         />
+       </View>
+     </SafeAreaView>
+   );
+ };

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

1. Finally, let’s update our resource files to include all the required localization keys:

   translate/en.json

    {
      "cards": {
        "cardTitle": "Card Title",
        "cardDescription": "Card Description",
        "anotherCardTitle": "Another Card Title",
        "anotherCardDescription": "Another Card Description"
      }
    }
   

   translate/es.json

    {
      "cards": {
        "cardTitle": "Titulo",
        "cardDescription": "Descripción",
        "anotherCardTitle": "Otro Titulo",
        "anotherCardDescription": "Otra Descripción"
      }
    }
   

Run npm start and you should see all the card content localized based on your preferences.

Switching between languages

To wrap up this article, let’s add a new component that will list all the supported languages, allowing the user to switch between them.

1. Create a new file for the component by executing the following command:

    touch components/LangSwitcher.tsx
   

2. Update the new empty file with the following code

    // components/LangSwitcher.tsx
   
    import { useTranslation } from "react-i18next";
    import { TouchableOpacity, Text, View, StyleSheet } from "react-native";
   
    const LangSwitcher = () => {
      const { i18n, t } = useTranslation("supportedLanguages");
      const supportedLanguages = ["en", "es"];
   
      const changeLanguage = (lng: string) => {
        i18n.changeLanguage(lng);
      };
   
      return (
        <View style={styles.container}>
          <Text style={styles.title}>Choose your language</Text>
          {supportedLanguages.map((lng) => (
            <TouchableOpacity
              onPress={() => changeLanguage(lng)}
              style={styles.item}
            >
              <Text style={styles.itemText}>{t(lng)}</Text>
            </TouchableOpacity>
          ))}
        </View>
      );
    };
   
    // improve styles
    const styles = StyleSheet.create({
      container: {
        flex: 1,
        backgroundColor: "#fff",
        alignItems: "center",
        justifyContent: "center",
        padding: 16,
      },
      title: {
        marginBottom: 16,
        fontSize: 24,
        fontWeight: "bold",
      },
      item: {
        width: "100%",
        padding: 16,
        borderBottomWidth: 1,
        borderBottomColor: "#ccc",
      },
      itemText: {
        fontSize: 16,
        textAlign: "center",
      },
    });
   
    export default LangSwitcher;
   

3. Update the resource files, so all the supported languages in the switcher are localized 😉

   translate/en.json

{
  "cards": {
    "cardTitle": "Card Title",
    "cardDescription": "Card Description",
    "anotherCardTitle": "Another Card Title",
    "anotherCardDescription": "Another Card Description"
  },
+ "supportedLanguages": {
+   "en": "English",
+   "es": "Spanish"
+ }
}

translate/es.json

{
  "cards": {
    "cardTitle": "Titulo",
    "cardDescription": "Descripción",
    "anotherCardTitle": "Otro Titulo",
    "anotherCardDescription": "Otra Descripción"
  },
+ "supportedLanguages": {
+   "en": "Inglés",
+   "es": "Español"
+ }
}

1. Finally, we need to update the App.tsx file to add the new component

...
+ import LangSwitcher from "./components/LangSwitcher";

...

const Home = () => {
  const { t } = useTranslation("cards");
  return (
    <SafeAreaView style={{ flex: 1 }}>
      <View style={styles.container}>
        ...
+       <LangSwitcher></LangSwitcher>
      </View>
    </SafeAreaView>
  );
};

Translating app metadata (iOS - Optional)

To further improve your multi-language support, you can also provide localized string for your app metadata. This includes things like:

• Your app display name

• System dialogs (every time you request permissions like location, camera, etc).

1. Update your app.json file to set CFBundleAllowMixedLocalizations to true like this:

{
  "expo": {
+   "ios": {
+     "infoPlist": {
+       "CFBundleAllowMixedLocalizations": true
+     }
+   },
  }
}

1. You also need to provide a locales object, where you’ll define the path to a json file for each supported language.

{
  "expo": {
    "ios": {
      "infoPlist": {
        "CFBundleAllowMixedLocalizations": true
      }
    },
+   "locales": {
+     "en": "./metadata/en.json",
+     "es": "./metadata/es.json",
+   }
  }
}

1. Create the new folder and required files with the following command

    mkdir metadata
    touch metadata/en.json
    touch metadata/es.json
   

2. Update each json file to include your localized metadata. Here’s an example: metadata/en.json

    {
      "CFBundleDisplayName": "My cooking app",
      "NSCameraUsageDescription": "The app need to use the camera so you can take photos of your dishes",
      "NSLocationWhenInUseUsageDescription": "The app needs access to your location to share the address of your favorite restorants"
    }
   

   metadata/es.json

    {
      "CFBundleDisplayName": "Mi aplicación de cocina",
      "NSCameraUsageDescription": "La aplicación necesita usar la cámara para que puedas tomar fotos de tus platos",
      "NSLocationWhenInUseUsageDescription": "La aplicación necesita acceso a tu ubicación para compartir la dirección de tus restaurantes favoritos"
    }
   

Bonus: Adding a localized date

Just for fun, let’s combine expo-localization with the built-in method toLocaleString() to localize our dates.

Update the Card component to include an additional prop called date

import React from "react";
import { View, Text, StyleSheet } from "react-native";
+ import * as Localization from "expo-localization";

type CardProps = {
  title: string;
  content: string;
+ date: Date;
};

const Card: React.FC<CardProps> = ({ title, content, date }) => {

+ // Get the user's preferred locale
+ const locale = Localization.getLocales().shift();
+ const languageCode = locale?.languageCode || "en";

+ const localizedDate = date.toLocaleString(languageCode, {
+   dateStyle: "long",
+   timeStyle: "long",
+ });

  return (
    <View style={styles.container}>
      <Text style={styles.title}>{title}</Text>
      <Text style={styles.content}>{content}</Text>
+     <Text style={styles.content}>{localizedDate}</Text>
    </View>
  );
};

Now, you should be able to see a localized date. You can even go a step further and add a convenient hook to encapsulate this logic, so you don’t need to add all this boilerplate every time you want to display a localized date.

Besides, the code provided above has a catch: If the user changes the language of the app in runtime, the localized string won’t update.

Let’s fix that problem with the useLocalizedDate hook

1. First, we need to create a new folder and an empty file for the new hook.

    mkdir hooks
    touch hooks/useLocalizedDate.tsx
   

2. Now, add the following code for the hook

    // hooks/useLocalizedDate.tsx
   
    import * as Localization from "expo-localization";
    import { useEffect, useState } from "react";
    import { useTranslation } from "react-i18next";
   
    const useLocalizedDate = (
      date: Date,
      options: Intl.DateTimeFormatOptions = {}
    ) => {
      const { i18n } = useTranslation();
   
      const defaultOptions: Intl.DateTimeFormatOptions = {
        dateStyle: "long",
        timeStyle: "long",
      };
   
      const [localizedDate, setLocalizedDate] = useState<string>("");
   
      // When the component mounts, set the initial value of the localized date and add a listener for language changes
      useEffect(() => {
        setInitialValue();
        i18n.on("languageChanged", (lng) => {
          setLocalizedDate(date.toLocaleString(lng, defaultOptions));
        });
   
        return () => {
          i18n.off("languageChanged");
        };
      }, []);
   
      const setInitialValue = () => {
        // Merge the user's options with the default options
        const mergedOptions = { ...defaultOptions, ...options };
   
        // Get the user's preferred locale
        const locale = Localization.getLocales().shift();
        const languageCode = locale?.languageCode || "en";
        // Localize the date
        setLocalizedDate(date.toLocaleString(languageCode, mergedOptions));
      };
   
      return localizedDate as string;
    };
   
    export default useLocalizedDate;
   

   In this improved version, we are also listening to i18next events to update the localized dates when the language of the user changes.

3. Finally, we can update the card component to use the new hook like this:

    // components/Card.tsx
   
    import React from "react";
    import { View, Text, StyleSheet } from "react-native";
    import useLocalizedDate from "../hooks/useLocalizedDate";
   
    type CardProps = {
      title: string;
      content: string;
      date: Date;
    };
   
    const Card: React.FC<CardProps> = ({ title, content, date }) => {
      const localizedDate = useLocalizedDate(date);
   
      return (
        <View style={styles.container}>
          <Text style={styles.title}>{title}</Text>
          <Text style={styles.content}>{content}</Text>
          <Text style={styles.content}>{localizedDate}</Text>
        </View>
      );
    };
   

Final thoughts

Implementing localization in mobile apps is essential for reaching a broader audience and enhancing user engagement. Thanks to libraries like expo-localization, i18next and react-i18next, it’s easier than ever to implement localization.

By providing support for multiple languages, your app will be more accessible, intuitive, and enjoyable for your users.

However, the benefits of providing these additional mechanisms can drastically improve your users’ experience with the app. You can also request permission to access certain information about your users that could allow you to further tailor the experience based on personal preferences.

Popular social providers such as Google, Facebook, Twitter, and more, follow a common open standard known as OAuth, so the steps required to integrate each provider are similar.

Supabase to the rescue

Thankfully, if you are using Supabase as your database, you can easily add social login to your app,

In this article, we’ll focus on adding Google as our first social provider.

I highly recommend reading the previous article in the series first, which provides essential instructions for setting up your Supabase and Expo projects. Once you've gone through that article, you'll be fully prepared to dive into the upcoming content.

Here’s a link to the previous post

Creating a project in Google Cloud Platform

Before we can utilize Google as a social provider in your Expo app, it is essential to create a project in Google Cloud Platform. To set up your project, follow these steps:

1. Visit cloud.google.com and sign in.

2. Click on the dropdown at the top left corner.

   

3. Click on "New Project" at the top right corner.

   

4. Fill in the form and click on "Create", and wait until the project is created. It could take a few seconds or even minutes.

   Warning: Once you confirm this form, you won’t be able to change your project id.

5. Once the project creation is finished, you receive a notification like in the image below. Click “Select project” to set your new project as active, and you’ll be redirected to your new project’s dashboard.

   

   

Creating the required OAuth Keys

1. Once you are in your project’s dashboard, use the search box at the top to search for “OAuth consent screen”, and select the first result under “Products and Pages”

   

2. In the User Type section, select “External” and hit “Create” to confirm

   

3. You’ll be redirected to the “Edit app registration” form. Make sure to review all the information and assets provided here, given that this information will be presented to your users during the login flow.

4. While following the process, make sure to define your scopes based on your specific needs. Here you can see the full list of available scopes. Besides, add a few testing users so you can complete the auth flow in your app before publishing the Consent Screen.

   You can always come back and update your consent screen later. Also, make sure to publish the consent screen once your app is about to be submitted to the stores

   

Getting your Supabase callback URL

In the next step, we’ll need to create an OAuth client ID in Google Cloud. But first, we’ll need to get our callback URL from Supabase.

1. Login into supabase, and go to your project’s dashboard.

2. In the sidebar, click on the “Authentication” button

   

3. Under the “Configuration” section, click on “Providers” and click on “Google” to expand the accordion.

4. Copy the provided Redirect URL.

Creating the OAuth client ID

1. Back into cloud.google.com, visit your project dashboard.

2. Click on the hamburger menu at the top left corner, and navigate to “APIs & Services” → “Credentials”

   

3. Click the “+ Create credentials” button, and then select “OAuth client ID”

   

4. Under “Application Type”, choose “Web application”. Fill in the name of your app, and click on “Add URI” under the “Authorized redirect URIs” section. Paste your Supabase redirect URL here.

   

5. If everything goes right, you’ll get a “Client ID” and “Client Secret”. Make sure to store this information. You’ll need it in the next step.

Updating your Google tokens in your Supabase project

1. Go back to your Supabase project, and click the “Authentication” button in the sidebar

   

2. Select “Providers” → “Google”

3. Toggle the “Google Enabled” switch to ON
4. Enter your Google tokens (Client id and Client Secret), and click on “Save”

Adding social login to our Expo app

In the previous post, we created a SupabaseContext.tsx and a SupabaseProvider.tsx file.

1. Let’s update the context by adding the getGoogleOAuthUrl and setOAuthSession methods:

   // context/SupabaseContext.tsx
   
   type SupabaseContextProps = {
     ...
   + getGoogleOAuthUrl: () => Promise<string | null>;
   + setOAuthSession: (tokens: {
   +   access_token: string;
   +   refresh_token: string;
   + }) => Promise<void>;
   };
   
   export const SupabaseContext = createContext<SupabaseContextProps>({
     ...
   + getGoogleOAuthUrl: async () => "",
   + setOAuthSession: async () => {},
   });
   

2. Now, we need to also update the provider to implement this new method.

   A few things to mention here:

   • We are setting mysupabaseapp://auth as a redirect uri while calling the getGoogleOAuthUrl method. You need to replace mysupabaseapp with your custom scheme. In the next step, I’ll show you how to setup the same redirect URL in your Supabase project so everything works as expected.
   • The signInWithOAuth method will return an object that contains the Supabase URL that we need to start the auth flow in the browser later.

   • The setOAuthSession method will allow us to persist the user session using Supabase Auth. In that way, the user won’t need to sign in again the next time.

     A few things to mention here:

   • We are setting mysupabaseapp://auth as a redirect uri while calling the getGoogleOAuthUrl method. You need to replace mysupabaseapp with your custom scheme. In the next step, I’ll show you how to setup the same redirect URL in your Supabase project so everything works as expected.
   • The signInWithOAuth method will return an object that contains the Supabase URL that we need to start the auth flow in the browser later.
   • The setOAuthSession method will allow us to persist the user session using Supabase Auth. In that way, the user won’t need to sign in again the next time.

   // context/SupabaseProvider.tsx
   
   export const SupabaseProvider = (props: SupabaseProviderProps) => {
   
    const supabase = createClient(
      ...
    );
    ...
   
   + const getGoogleOAuthUrl = async (): Promise<string | null> => {
   +   const result = await supabase.auth.signInWithOAuth({
   +     provider: "google",
   +     options: {
   +       redirectTo: "mysupabaseapp://google-auth",
   +     },
   +   });
   +   
   +   return result.data.url;
   + };
   
   + const setOAuthSession = async (tokens: {
   +   access_token: string;
   +   refresh_token: string;
   + }) => {
   +   const { data, error } = await supabase.auth.setSession({
   +     access_token: tokens.access_token,
   +     refresh_token: tokens.refresh_token,
   +   });
   +
   +   if (error) throw error;
   +
   +   setLoggedIn(data.session !== null);
   + };
   
    ...
   
    return (
      <SupabaseContext.Provider
        value={{
            ...
   +       getGoogleOAuthUrl,
   +       setOAuthSession
        }}
      >
        ...
      </SupabaseContext.Provider>
    );
   };
   

3. Install the expo-web-browser package by running the following command

    npx expo install expo-web-browser
   

4. Finally, we need to update our LoginScreen.tsx

   • We need to add a “Sign in with Google” button.
   • We are using expo-web-browser to load an in-app browser for the login flow.
   • As described in the Expo docs, we call WebBrowser.warmUpAsync() to load the browser in the background before the user taps the button to improve the user experience. You can learn more about this in this link
   • Once the user taps the button, the flow should look like this:
     • We get the Supabase OAuth URL
     • openAuthSessionAsync is called with the Supabase URL
     • The Google Consent Screen is shown.
     • Once the user completes the flow, the browser returns to the app with a URL
     • We extract the tokens from the URL.
     • Finally, we call setOAuthSession to persist the Supabase session.
     • Optional: We securely store the provider token for future use
   • For the UI, we are using SpiroKit, but feel free to use your own button.

   + import * as WebBrowser from "expo-web-browser";
   + import * as SecureStore from "expo-secure-store";
   
   const LoginScreen = () => {
   
    const { 
      login, 
   +  getGoogleOAuthUrl,
   +  setOAuthSession 
    } = useSupabase();
   
    ...
   
   + React.useEffect(() => {
   +   WebBrowser.warmUpAsync();
   +
   +   return () => {
   +     WebBrowser.coolDownAsync();
   +   };
   + }, []);
   
    ...
   
   + const onSignInWithGoogle = async () => {
   +   setLoading(true);
   +   try {
   +     const url = await getGoogleOAuthUrl();
   +     if (!url) return;
   + 
   +     const result = await WebBrowser.openAuthSessionAsync(
   +       url,
   +       "mysupabaseapp://google-auth?",
   +       {
   +         showInRecents: true,
   +       }
   +     );
   + 
   +     if (result.type === "success") {
   +       const data = extractParamsFromUrl(result.url);
   +
   +       if (!data.access_token || !data.refresh_token) return;
   +
   +       setOAuthSession({
   +         access_token: data.access_token,
   +         refresh_token: data.refresh_token,
   +       });
   +
   +       // You can optionally store Google's access token if you need it later
   +       SecureStore.setItemAsync(
   +         "google-access-token",
   +         JSON.stringify(data.provider_token)
   +       );
   +     }
   +   } catch (error) {
   +     // Handle error here
   +     console.log(error);
   +   } finally {
   +     setLoading(false);
   +   }
   + };
   
   + const extractParamsFromUrl = (url: string) => {
   +   const params = new URLSearchParams(url.split("#")[1]);
   +   const data = {
   +     access_token: params.get("access_token"),
   +     expires_in: parseInt(params.get("expires_in") || "0"),
   +     refresh_token: params.get("refresh_token"),
   +     token_type: params.get("token_type"),
   +     provider_token: params.get("provider_token"),
   +   };
   +
   +   return data;
   + };
   
    return (
      <KeyboardAvoidingView
        ...
      >
        <ScrollView contentContainerStyle={{ flexGrow: 1 }}>
          <VStack safeAreaTop padding={4} flex={1}>
            <VStack space={4} marginTop={5} width="full" flex={1}>
                ...
   +           <Button
   +             isDisabled={loading}
   +             onPress={() => onSignInWithGoogle()}
   +             marginBottom={5}
   +           >
   +             {loading ? "Loading..." : "Sign in with Google"}
   +           </Button>
            </VStack>
          </VStack>
        </ScrollView>
      </KeyboardAvoidingView>
    );
   };
   
   export default LoginScreen;
   

Redirect URL setup in Supabase

1. Go to your project dashboard in Supabase.
2. In the sidebar, click the “Authentication” button.
3. Under the “Configuration” section, click on “URL Configuration”.

4. In the “Redirect URLs” section, click the “Add URL”.

   

5. Add your custom scheme.

   1. This should match with the scheme used in the previous step.

Final thoughts

If you are still here, congrats! Now you have an app with Social login.

It's worth mentioning that Supabase offers support for numerous providers, so if you require additional options, they have you covered.

By following the steps outlined in this article, you should be able to easily add more providers to your app. While each provider may have a few specific steps to follow, Supabase's documentation serves as an excellent starting point. To delve deeper, you can find more information here

Once you get the tokens to interact with each provider, you should be able to update the Supabase provider to get the login URL. The rest of the flow should be reusable as is.

I’ll probably cover more about this in the future, so if you have any questions or require additional assistance, please do not hesitate to reach out.

In such cases, you may consider using Supabase as your backend solution. Supabase provides a seamless way to handle authentication, data storage, and more, complementing Expo's frontend capabilities to create a robust and scalable mobile app for a SaaS.

What do you get from this tutorial?

• A new Supabase project with everything configured to handle authentication.
• A working Expo app integrated with Supabase.
  • A global Supabase context with easy access to interact with the Supabase client
  • React-navigation setup for all the routes. You get IntelliSense for route names.
  • Four working screens (Login, Register, Forgot Password, Home)
  • Route security setup (only authenticated users can access the Home route).
• Login flow using Supabase auth.
  • Your session info is securely persisted locally using Expo Secure Store.
  • Automatic refresh token flow
• Register flow
• Forgot Password flow
• Setup to read environment variables from a .env file.

Expo-Supabase template is now available with SpiroKit!

For this demo app, I'll be using SpiroKit, which is a React Native UI kit I built. Given that is a paid product, feel free to follow this tutorial with your own UI.

With SpiroKit, you can use our new expo-supabase-typescript-template. It includes everything you’ll see in this tutorial.

Creating a new Supabase project

Supabase is an open-source project that offers a range of functionalities for hosting projects in the cloud. As of the time of writing, it allows users to host up to 2 projects in their free tier. If you have exceeded this quota, an alternative option is to host your own instance on a dedicated server. However, for the sake of simplicity, we will focus on utilizing the cloud project setup in this tutorial. Setting up a dedicated server falls outside the scope of this tutorial and will not be covered in detail.

1. Visit https://supabase.com and sign up if you don’t have an account

2. Once your account is ready, create your first project:

   

3. Choose a name for your project and a strong password. Make sure you are using the “Free” pricing plan if you are experimenting. You can update to a paid plan later if it’s required.

   

4. Hit the “Create new project” to confirm. If everything goes right, you’ll be redirected to the home page of your new Supabase project. You’ll need to copy the Project URL and the API key (anon) later to connect your project with your Expo app

   

Setting up authentication on Supabase

Every Supabase project comes with a full Postgres database. We’ll be using it to support our basic authentication flow with email and password.

1. From your supabase project dashboard, use the sidebar to visit the “SQL Editor” section

   

2. Under the “Quick Start” section, you’ll find the “User Management Starter” card. This will help us setup all the required tables for the auth flow.

3. You can click the “Run” button to execute the query as is, or you can make a few modifications before execution based on your needs. This script will perform the following tasks:

   1. Create Table: Defines a table called profiles with various columns to store information about public profiles, such as ID, updated timestamp, username, full name, avatar URL, and website. It also includes a constraint to ensure that the username length is at least 3 characters.
   2. Set up Row Level Security (RLS): Enables Row Level Security for the profiles table. RLS allows controlling access to individual rows based on policies. If you want lo learn more about this powerful feature, visit the following link
   3. Create Policies: Defines three policies to control access to the profiles table:
      • "Public profiles are viewable by everyone.": Grants read access to all rows in the profiles table.
      • "Users can insert their own profile.": Allows users to insert a row into the profiles table only if their authenticated user ID matches the "id" column.
      • "Users can update their own profile.": Permits users to update their own profile by matching their authenticated user ID with the "id" column.
   4. Create a function and a Trigger: Sets up a trigger function named "handle_new_user" and a trigger named "on_auth_user_created" to automatically create a profile entry when a new user signs up via Supabase Auth (we’ll use this on our Expo app later). The trigger function extracts relevant information from the newly created user and inserts it into the profiles table.
   5. Set up Storage: Inserts a row into the storage.buckets table to define a bucket named "avatars" for storing avatar images.

   6. Create Storage Policies: Defines two policies to control access to the "avatars" bucket in storage:

      • "Avatar images are publicly accessible.": Allows anyone to retrieve (select) objects from the "avatars" bucket.

      • "Anyone can upload an avatar.": Permits anyone to insert (upload) objects into the "avatars" bucket.

        For simplicity, I’ll execute the script as is.

4. We can now visit the “Table Editor” section using the sidebar and check that the profiles table was created

   

Creating an Expo app

Now that we are done with Supabase, it’s time to create our Expo app.

Because I’m using SpiroKit, I’ll be using the Expo Starter template that already comes with everything setup and ready to use. If you choose to also use SpiroKit, make sure to get your license and follow the installation instructions before running the following command:

npx create-spirokit-app --template expo-template-typescript

If you want to create a plain React Native app with Expo, run this command instead:

npx create-react-native-app -t with-typescript

# This is optional if you want to add icons to your screens. 
# It's already included with the SpiroKit template
yarn add react-native-heroicons

Setting up Supabase in your Expo app

1. You will need to run the following command to install all the required packages

    yarn add @supabase/supabase-js @react-native-async-storage/async-storage react-native-url-polyfill
   
    # Required for accessing env variables during development
    yarn add -D babel-plugin-inline-dotenv 
   
    # Required to encrypt the information in the device
    npx expo install expo-secure-store
   

2. Because we are using Expo Secure Store later to store information, we will need to update our app.json file to avoid issues with App Store Connect during app submission. We will set the usesNonExemptEncryption option to false like this: **

    {
      "expo": {
        "ios": {
          "config": {
            "usesNonExemptEncryption": false
          }
        }
      }
    }
   

   Setting this property automatically handles the compliance information prompt, as described in the Expo docs

3. Now, let’s create a SupabaseContext that will allow us to get interact with the supabase client from any screen of our app. Run the following commands to create the src folder, then the context folder inside, and finally, a few empty files to implement our context.

    mkdir src
    mkdir src/context
    touch ./src/context SupabaseContext.tsx
    touch ./src/context SupabaseProvider.tsx
    touch ./src/context useSupabase.tsx
   

4. The SupabaseContext.tsx will define the contract for the provider. We’ll add a isLoggedIn flag to easily check the session status, and a few methods to interact with Supabase auth service

    import { createContext } from "react";
   
    type SupabaseContextProps = {
      isLoggedIn: boolean;
      login: (email: string, password: string) => Promise<void>;
      register: (email: string, password: string) => Promise<void>;
      forgotPassword: (email: string) => Promise<void>;
      logout: () => Promise<void>;
    };
   
    export const SupabaseContext = createContext<SupabaseContextProps>({
      isLoggedIn: false,
      login: async () => {},
      register: async () => {},
      forgotPassword: async () => {},
      logout: async () => {},
    });
   

5. Then, add the following code to the SupabaseProvider.tsx file to initialize the Supabase client and implement all the required methods. We also need the isNavigationReady to load our navigation stack after the session info is available. That way, we can hide certain routes for anonymous users.

    import "react-native-url-polyfill/auto";
    import { createClient } from "@supabase/supabase-js";
    import React, { useState, useEffect } from "react";
    import * as SecureStore from "expo-secure-store";
    import { SupabaseContext } from "./SupabaseContext";
   
    // We are using Expo Secure Store to persist session info
    const ExpoSecureStoreAdapter = {
      getItem: (key: string) => {
        return SecureStore.getItemAsync(key);
      },
      setItem: (key: string, value: string) => {
        SecureStore.setItemAsync(key, value);
      },
      removeItem: (key: string) => {
        SecureStore.deleteItemAsync(key);
      },
    };
   
    type SupabaseProviderProps = {
      children: JSX.Element | JSX.Element[];
    };
   
    export const SupabaseProvider = (props: SupabaseProviderProps) => {
      const [isLoggedIn, setLoggedIn] = useState(false);
      const [isNavigationReady, setNavigationReady] = useState(false);
   
      const supabase = createClient(
        process.env.SUPABASE_URL,
        process.env.SUPABASE_ANON_KEY,
        {
          auth: {
            storage: ExpoSecureStoreAdapter,
            autoRefreshToken: true,
            persistSession: true,
            detectSessionInUrl: false,
          },
        }
      );
   
      const login = async (email: string, password: string) => {
        const { error } = await supabase.auth.signInWithPassword({
          email,
          password,
        });
        if (error) throw error;
        setLoggedIn(true);
      };
   
      const register = async (email: string, password: string) => {
        const { error } = await supabase.auth.signUp({
          email,
          password,
        });
        if (error) throw error;
      };
   
      const forgotPassword = async (email: string) => {
        const { error } = await supabase.auth.resetPasswordForEmail(email);
        if (error) throw error;
      };
   
      const logout = async () => {
        const { error } = await supabase.auth.signOut();
        if (error) throw error;
        setLoggedIn(false);
      };
   
      const checkIfUserIsLoggedIn = async () => {
        const result = await supabase.auth.getSession();
        setLoggedIn(result.data.session !== null);
        setNavigationReady(true);
      };
   
      useEffect(() => {
        checkIfUserIsLoggedIn();
      }, []);
   
      return (
        <SupabaseContext.Provider
          value={{ isLoggedIn, login, register, forgotPassword, logout }}
        >
          {isNavigationReady ? props.children : null}
        </SupabaseContext.Provider>
      );
    };
   

6. Finally, we’ll use the useSupabase.tsx file to create a convenient hook:

    import React from "react";
    import { SupabaseContext } from "./SupabaseContext";
   
    export const useSupabase = () => React.useContext(SupabaseContext);
   

7. Because we are using TypeScript, we’ll also need to create a app.d.ts to define the types for our environment variables

    touch app.d.ts
   

   Now let’s add our environment variables to the declaration file

    // app.d.ts
    declare namespace NodeJS {
      interface ProcessEnv {
        SUPABASE_URL: string;
        SUPABASE_ANON_KEY: string;
      }
    }
   

   If you still have typescript errors on your hook, run the “reload window” command in VSCode, or just close and open the IDE to refresh everything.

8. To properly get access to our environment variables during development, we need to update our babel.config.js file to add the “inline-dotenv” plugin. It should look like this:

    module.exports = function (api) {
      api.cache(true);
      return {
        presets: ["babel-preset-expo"],
        plugins: ["inline-dotenv"], // -> Required to read env variables
      };
    };
   

   We’ll also need to create the .env file in the root of our project and provide a value for the SUPABASE_URL and SUPABASE_ANON_KEY variables:

    touch .env
   

    SUPABASE_URL="YOUR_SUPABASE_URL"
    SUPABASE_ANON_KEY="YOUR_SUPABASE_KEY"
   

   If you already run your app before creating the .env file, please run the app with the expo r -c command to clear the expo cache. Otherwise, your environment variables won’t work. This is required every time the .env file is updated.

Setting up React Navigation

Because we are adding a few screens like Login, Register, ForgotPassword, and Home, we will need to add React Navigation to easily navigate through the screens.

1. Let’s start by installing the required dependencies

    npx expo install @react-navigation/native @react-navigation/stack react-native-gesture-handler
   

2. I’ll create a navigation folder to store all the required components here. But feel free to choose a different location for your files

    mkdir navigation
    touch navigation/GlobalNavigation.tsx
   

3. We’ll also need to create a few dummy screens

    mkdir screens
    touch screens/LoginScreen.tsx
    touch screens/RegisterScreen.tsx
    touch screens/ForgotPasswordScreen.tsx
    touch screens/HomeScreen.tsx
   

   For all the screens, let’s add a temp UI

    // screens/LoginScreen.tsx
    import { Box, LargeTitle } from "@spirokit/core";
   
    const LoginScreen = () => {
      return (
        <Box safeArea>
          <LargeTitle>Login Screen</LargeTitle>
        </Box>
      );
    };
   
    export default LoginScreen;
   
    // screens/RegisterScreen.tsx
    import { Box, LargeTitle } from "@spirokit/core";
   
    const RegisterScreen = () => {
      return (
        <Box safeArea>
          <LargeTitle>Register Screen</LargeTitle>
        </Box>
      );
    };
   
    export default RegisterScreen;
   
    // screens/ForgotPasswordScreen.tsx
    import { Box, LargeTitle } from "@spirokit/core";
   
    const ForgotPasswordScreen = () => {
      return (
        <Box safeArea>
          <LargeTitle>Forgot Password Screen</LargeTitle>
        </Box>
      );
    };
   
    export default ForgotPasswordScreen;
   
    // screens/HomeScreen.tsx
    import { Box, LargeTitle } from "@spirokit/core";
   
    const HomeScreen = () => {
      return (
        <Box safeArea>
          <LargeTitle>Home Screen</LargeTitle>
        </Box>
      );
    };
   
    export default HomeScreen;
   

4. Now that we have all our screens, we can go back to the GlobalNavigation.tsx file and add the Stack navigation with all our screens

    // navigation/GlobalNavigation.tsx
   
    import { NavigationContainer } from "@react-navigation/native";
    import { createStackNavigator } from "@react-navigation/stack";
    import React from "react";
    import ForgotPasswordScreen from "../screens/ForgotPasswordScreen";
    import HomeScreen from "../screens/HomeScreen";
    import LoginScreen from "../screens/LoginScreen";
    import RegisterScreen from "../screens/RegisterScreen";
    import { useSupabase } from "../context/useSupabase";
   
    const Stack = createStackNavigator();
   
    const GlobalNavigation = () => {
      // We check if the user is logged in
      const { isLoggedIn } = useSupabase();
   
      return (
        <NavigationContainer>
          <Stack.Navigator
            initialRouteName={isLoggedIn ? "Home" : "Login"}
            screenOptions={{ headerShown: false }}
          >
            {/* Only authenticated users can access the home */}
            {isLoggedIn ? (
              <Stack.Screen name="Home" component={HomeScreen} />
            ) : (
              <>
                <Stack.Screen name="Login" component={LoginScreen} />
                <Stack.Screen name="Register" component={RegisterScreen} />
                <Stack.Screen
                  name="ForgotPassword"
                  component={ForgotPasswordScreen}
                />
              </>
            )}
          </Stack.Navigator>
        </NavigationContainer>
      );
    };
   
    export default GlobalNavigation;
   

5. Then, we need to update our App.tsx file to add our supabase context and our new global navigation.

    import { SpiroKitProvider, usePoppins, useSpiroKitTheme } from "@spirokit/core";
    import GlobalNavigation from "./src/navigation/GlobalNavigation";
    import { SupabaseProvider } from "./src/context/SupabaseProvider";
   
    const myTheme = useSpiroKitTheme();
   
    export default function App() {
      const fontLoaded = usePoppins();
   
      if (!fontLoaded) return <></>;
   
      return (
        <SpiroKitProvider theme={myTheme}>
          <SupabaseProvider>
            <GlobalNavigation></GlobalNavigation>
          </SupabaseProvider>
        </SpiroKitProvider>
      );
    }
   

6. Finally, let’s create a GlobalParamList.tsx inside our navigation folder to add proper IntelliSense to our routes while using navigation.navigate("routeName") to move between screens

    touch navigation/GlobalParamList.tsx
   

    import { StackNavigationProp } from "@react-navigation/stack";
   
    export type GlobalParamList = {
      Home: undefined;
      Login: undefined;
      Register: undefined;
      ForgotPassword: undefined;
    };
   
    export type ScreenNavigationProp = StackNavigationProp<GlobalParamList>;
   
    declare global {
      namespace ReactNavigation {
        interface RootParamList extends GlobalParamList {}
      }
    }
   

Updating the Login screen

With the Supabase context set and our navigation stack in place, we need to update all the different screens. Let’s start with the Login with a few comments:

• We are using the useSupabase hook to call the login method
• We wrap the screen with a KeyboardAvoidingView to prevent annoying issues with the keyboard (this applies to all our screens below)

// screens/LoginScreen.tsx

import {
  Body,
  Button,
  Input,
  KeyboardAvoidingView,
  Pressable,
  TitleTwo,
  VStack,
  Image,
  Subhead,
} from "@spirokit/core";
import React from "react";
import { Platform, ScrollView } from "react-native";
import { LockClosedIcon, MailIcon } from "react-native-heroicons/outline";
import { useNavigation } from "@react-navigation/native";
import { useHeaderHeight } from "@react-navigation/elements";
import { useSupabase } from "../context/useSupabase";

const LoginScreen = () => {
  const navigation = useNavigation();
  const height = useHeaderHeight();
  const { login } = useSupabase();

  const [email, setEmail] = React.useState("");
  const [password, setPassword] = React.useState("");
  const [loading, setLoading] = React.useState(false);

  const onSignInTapped = async () => {
    try {
      setLoading(true);
      await login(email, password);
    } catch (error) {
      console.log(error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <KeyboardAvoidingView
      flex={1}
      keyboardVerticalOffset={height}
      backgroundColor={"primaryGray.100"}
      behavior={Platform.OS === "ios" ? "padding" : "height"}
    >
      <ScrollView contentContainerStyle={{ flexGrow: 1 }}>
        <VStack safeAreaTop padding={4} flex={1}>
          <VStack space={4} marginTop={5} width="full" flex={1}>
            <Image
              source={{ uri: "https://i.imgur.com/FawVClJ.png" }}
              width="full"
              height={200}
              alt="Login icon"
              resizeMode="contain"
            ></Image>
            <TitleTwo fontWeight="medium">Sign in</TitleTwo>
            <Input
              placeholder="Enter your email"
              IconLeftComponent={MailIcon}
              onChangeText={(text) => setEmail(text)}
            ></Input>
            <Input
              placeholder="Enter your password"
              secureTextEntry={true}
              IconLeftComponent={LockClosedIcon}
              onChangeText={(text) => setPassword(text)}
            ></Input>
            <Pressable onPress={() => navigation.navigate("ForgotPassword")}>
              <Subhead textAlign={"right"} paddingBottom="2">
                Forgot Password?
              </Subhead>
            </Pressable>

            <Button
              isDisabled={loading}
              onPress={() => onSignInTapped()}
              marginBottom={5}
            >
              {loading ? "Loading..." : "Sign in"}
            </Button>
          </VStack>
        </VStack>

        <VStack padding={4} backgroundColor={"white"} safeAreaBottom>
          <Body textAlign={"center"}>
            Have an account?{" "}
            <Pressable onPress={() => navigation.navigate("Register")}>
              <Body fontWeight="bold" textDecorationLine="underline">
                Sign up
              </Body>
            </Pressable>
          </Body>
        </VStack>
      </ScrollView>
    </KeyboardAvoidingView>
  );
};

export default LoginScreen;

Updating the Register screen

With the Login screen done, let’s work on the register screen:

// screens/RegisterScreen.tsx

import {
  Body,
  Button,
  Input,
  KeyboardAvoidingView,
  Pressable,
  TitleTwo,
  VStack,
  Image,
} from "@spirokit/core";
import React from "react";
import { Platform, ScrollView } from "react-native";
import { LockClosedIcon, MailIcon } from "react-native-heroicons/outline";

import { useNavigation } from "@react-navigation/native";
import { useHeaderHeight } from "@react-navigation/elements";
import { useSupabase } from "../context/useSupabase";

const RegisterScreen = () => {
  const navigation = useNavigation();
  const height = useHeaderHeight();

  const [email, setEmail] = React.useState("");
  const [password, setPassword] = React.useState("");
  const [loading, setLoading] = React.useState(false);

  const { register } = useSupabase();

  const onSignUpTapped = async () => {
    try {
      setLoading(true);
      await register(email, password);
      navigation.navigate("Login");
    } catch (error) {
      console.log(error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <KeyboardAvoidingView
      flex={1}
      keyboardVerticalOffset={height}
      backgroundColor={"primaryGray.100"}
      behavior={Platform.OS === "ios" ? "padding" : "height"}
    >
      <ScrollView contentContainerStyle={{ flexGrow: 1 }}>
        <VStack
          safeAreaTop
          padding={4}
          alignItems="flex-start"
          width="full"
          flex={1}
        >
          <VStack space={4} marginTop={5} width="full" flex={1}>
            <Image
              source={{ uri: "https://i.imgur.com/oNY0QGb.png" }}
              width="full"
              height={200}
              alt="Register icon"
              resizeMode="contain"
            ></Image>
            <TitleTwo fontWeight="medium">Sign up</TitleTwo>
            <Input
              placeholder="Enter your email"
              IconLeftComponent={MailIcon}
              onChangeText={(text) => setEmail(text)}
            ></Input>
            <Input
              placeholder="Enter your password"
              secureTextEntry={true}
              IconLeftComponent={LockClosedIcon}
              onChangeText={(text) => setPassword(text)}
            ></Input>
            <Button
              isDisabled={loading}
              marginBottom={5}
              onPress={() => onSignUpTapped()}
            >
              {loading ? "Loading..." : "Sign up"}
            </Button>
          </VStack>
        </VStack>
        <VStack padding={4} safeAreaBottom>
          <Body textAlign={"center"}>
            If you have an account,{" "}
            <Pressable onPress={() => navigation.navigate("Login")}>
              <Body fontWeight="bold" textDecorationLine="underline">
                Sign in
              </Body>
            </Pressable>
          </Body>
        </VStack>
      </ScrollView>
    </KeyboardAvoidingView>
  );
};

export default RegisterScreen;

Updating the Forgot Password screen

• We are using the useSupabase hook to call the forgotPassword method
• We are using an Alert component to show a message after the recovery email was sent.
• Feel free to improve the error handling in the onSendTapped to show a custom error if something goes wrong.

// screens/ForgotPasswordScreen.tsx

import {
  Body,
  Button,
  Input,
  KeyboardAvoidingView,
  Pressable,
  TitleTwo,
  VStack,
  Image,
  Alert,
  TitleOne,
} from "@spirokit/core";
import React from "react";
import { Platform, ScrollView } from "react-native";
import { MailIcon } from "react-native-heroicons/outline";

import { useNavigation } from "@react-navigation/native";
import { useHeaderHeight } from "@react-navigation/elements";
import { useSupabase } from "../context/useSupabase";

const ForgotPasswordScreen = () => {
  const navigation = useNavigation();
  const height = useHeaderHeight();

  const [email, setEmail] = React.useState("");
  const [loading, setLoading] = React.useState(false);
  const [showResultModal, setShowResultModal] = React.useState(false);

  const { forgotPassword } = useSupabase();

  const onFinishTapped = () => {
    setShowResultModal(false);
    navigation.navigate("Login");
  };

  const onSendTapped = async () => {
    try {
      setLoading(true);
      await forgotPassword(email);
      setShowResultModal(true);
    } catch (error) {
      console.log(error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <KeyboardAvoidingView
      flex={1}
      keyboardVerticalOffset={height}
      backgroundColor={"primaryGray.100"}
      behavior={Platform.OS === "ios" ? "padding" : "height"}
    >
      <ScrollView contentContainerStyle={{ flexGrow: 1 }}>
        <VStack
          safeAreaTop
          padding={4}
          alignItems="flex-start"
          width="full"
          flex={1}
        >
          <VStack space={4} marginTop={5} width="full" flex={1}>
            <Image
              source={{ uri: "https://i.imgur.com/sDzRjS4.png" }}
              width="full"
              alt="Forgot password icon"
              height={200}
              resizeMode="contain"
            ></Image>
            <TitleTwo fontWeight="medium">Forgot password?</TitleTwo>
            <Input
              placeholder="Enter your email"
              IconLeftComponent={MailIcon}
              onChangeText={(text) => setEmail(text)}
            ></Input>
            <Button
              isDisabled={loading}
              marginBottom={5}
              onPress={() => onSendTapped()}
            >
              {loading ? "Loading..." : "Send"}
            </Button>
          </VStack>
        </VStack>
        <VStack padding={4} safeAreaBottom>
          <Body textAlign={"center"}>
            If you have an account,{" "}
            <Pressable onPress={() => navigation.navigate("Login")}>
              <Body fontWeight="bold" textDecorationLine="underline">
                Sign in
              </Body>
            </Pressable>
          </Body>
        </VStack>
        <Alert
          isVisible={showResultModal}
          onClose={() => setShowResultModal(false)}
          TitleComponent={<TitleOne>Email sent</TitleOne>}
          ConfirmButtonComponent={
            <Button onPress={() => onFinishTapped()}>Ok</Button>
          }
        ></Alert>
      </ScrollView>
    </KeyboardAvoidingView>
  );
};

export default ForgotPasswordScreen;

Updating the Home Screen

• Primarily used to test routing security and allow users to logout
• After logout, the Supabase Context is updated, and the Global Navigation will trigger a re-render. The user is automatically redirected to the Login screen.

// screens/Home.tsx

import { Button, LargeTitle, Image, VStack } from "@spirokit/core";
import { useSupabase } from "../context/useSupabase";

const HomeScreen = () => {
  const { logout } = useSupabase();
  return (
    <VStack space={8} safeArea padding={4} flex={1} justifyContent="center">
      <LargeTitle textAlign={"center"}>Welcome!</LargeTitle>
      <Image
        source={{ uri: "https://i.imgur.com/k78EnxY.png" }}
        width="full"
        alt="Hello icon"
        height={200}
        resizeMode="contain"
      ></Image>
      <Button onPress={() => logout()}>Logout</Button>
    </VStack>
  );
};

export default HomeScreen;

Final thoughts

That was an intense article! But I wanted to cover the entire flow. There are many things we could improve or add, but I’m thinking of building a series around it. We could add a working example retrieving information from Supabase db or include additional auth mechanisms.

I would love to hear your thoughts! Your input can help me shape the upcoming articles.

Historically speaking, trying to handle navigation on a universal app (that targets web and mobile) was a pain in the ass.

Navigation on the web usually is quite simple, and Next.js did a fantastic job with its file system-based router.

In mobile land, things are not that simple. Fernando Rojo did a fantastic job with Solito, which is a wrapper around React Navigation and Next.js that lets you share navigation code across platforms. This project gained a lot of traction, and the community started to work on solving the problem of navigation for universal apps.

Introducing Expo Router

I heard about Expo Router a few weeks ago, and I instantly loved the concept: What if we could have something like Next.js file-system-based router, but for universal apps? That is Expo Router.

What's the big deal about this library?

"Expo Router brings the best routing concepts from the web to native iOS and Android apps. Every file in the app directory automatically becomes a route in your mobile navigation, making it easier than ever to build, maintain, and scale your project."

If you've had to deal with deep linking on your mobile apps in the past, you already know that this is another major pain.

Expo Router was built on top of React Navigation, and the entire deep linking system is automatically generated, meaning that you can share the same link on the web and mobile, and the deep link will automatically work 🤯.

No more weird mapping and matching routes.

There are tons of additional features like Offline support, but if you want to learn more about all these features, here's the official docs

Given that this library is still in beta, some links may change

Building a magazine app

I wanted to test features like tab and stack navigation to get a first sense of how it feels to work on a real app using Expo Router, so I decided to build a very simple magazine app that shows a list of news and allows the user to navigate to each news to read more about it.

For this demo app, I'll be using SpiroKit, which is a React Native UI kit I built. Given that is a paid product, feel free to follow this tutorial with your own UI.

Project setup

With SpiroKit

If you've decided to use SpiroKit, follow these steps to quickly generate a new expo project with SpiroKit and Expo Router:

1. Get your SpiroKit license here and follow this instructions to get access to our private npm packages.

2. Create a new project using the template

npx create-spirokit-app my-expo-router-app --template expo-router-template

With your own UI

Run the following command to create a new project with expo-router:

npx create-expo-app@latest --example with-router

First use

After creating my first project using the expo template, I just run yarn start.

By default, the starter templates don't include the app folder, so there is nothing to show. But we will get a friendly welcome message that will let us create our first route by only clicking the “touch app/index.js” button

After clicking the button, I instantly got an update on all my devices (both web and mobile)

After returning to my code, I confirmed that the new app/index.js file was created.

// app/index.js
import { Link, Stack } from "expo-router";
import { StyleSheet, Text, View } from "react-native";

export default function Page() {
  return (
    <View style={styles.container}>
      <View style={styles.main}>
        <Text style={styles.title}>Hello World</Text>
        <Text style={styles.subtitle}>This is the first page of your app.</Text>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    padding: 24,
  },
  main: {
    flex: 1,
    justifyContent: "center",
    maxWidth: 960,
    marginHorizontal: "auto",
  },
  title: {
    fontSize: 64,
    fontWeight: "bold",
  },
  subtitle: {
    fontSize: 36,
    color: "#38434D",
  },
});

Given that Expo Router is file-system based, we'll need to create new directories and files based on our needs.

My magazine app will use a bottom tab navigation with 2 main sections:

• News
• Settings

At the same time, the "News" section will use a Stack navigator to allow us to navigate to the details page. More about this below.

Let's start building our app!

1. Adding the Tab navigator

We need to add a tab navigator so we can navigate between the "news" and "settings" tabs.

Expo Router includes a feature called "Layout Routes". From the official docs:

"To render shared navigation elements like a header, tab bar, or drawer, you can use a Layout Route. If a directory contains a file named _layout.js, it will be used as the layout component for all the sibling files in the directory."

Let's create our app/_layout.js and add the Tab navigation we need:

// app/_layout.js
import { SpiroKitProvider, usePoppins, useSpiroKitTheme } from "@spirokit/core";
import { Tabs } from "expo-router";
import TabBarComponent from "../components/TabBar";

// Setting up some global preferences for theming
const theme = useSpiroKitTheme({
  config: {
    colors: {
      primaryGray: "coolGray",
      primaryDark: "coolDark",
    },
  },
});

export default function Layout() {
  const fontLoaded = usePoppins();

  if (!fontLoaded) return <></>;
  return (
    <SpiroKitProvider theme={theme}>
      <Tabs
        tabBar={(tabBarProps) => {
          console.log(tabBarProps);
          return <TabBarComponent {...tabBarProps}></TabBarComponent>;
        }}
        screenOptions={{ headerShown: false }}
      >
        <Tabs.Screen
          name="index"
          options={{
            // Using a custom title to display in the tab bar icon
            title: "Home",
          }}
        />
      </Tabs>
    </SpiroKitProvider>
  );
}

2. Updating the app/index.js file

With the tabs navigator in place, I wanted to have a welcome screen (app/index.js), with a button that redirects to the news section.

Expo Router provides many options to move between routes, but given that it's still in beta, some things may not be supported yet. In this case, I'm using the useRouter hook to move between routes.

// app/index.js
import * as React from "react";
import { useRouter } from "expo-router";
import { HomeIcon } from "react-native-heroicons/outline";

import { Button, Image, LargeTitle, VStack } from "@spirokit/core";
export default function Page() {
  // The useRouter hook allows us to navigate between routes
  const router = useRouter();
  return (
    <>
      <VStack
        space={4}
        justifyContent="center"
        alignItems={"center"}
        flex={1}
        backgroundColor={{
          linearGradient: {
            colors: ["primary.600", "emerald.800"],
            start: [0, 1],
            end: [1, 0],
          },
        }}
      >
        <Image
          width={64}
          borderWidth={8}
          borderColor="primary.500"
          height={64}
          borderRadius="full"
          source={{
            uri: "https://images.pexels.com/photos/1369476/pexels-photo-1369476.jpeg?auto=compress&cs=tinysrgb&w=1260&h=750&dpr=1",
          }}
        ></Image>
        <LargeTitle color="white" width={"1/2"} textAlign="center">
          Welcome to magazine App
        </LargeTitle>

        {/* Here I'm using the onPress event to trigger the navigation */}
        {/* This won't work until we create the news route below */}
        <Button
          variant="secondary"
          textColor="white"
          colorMode={"dark"}
          IconLeftComponent={HomeIcon}
          width="auto"
          onPress={() => router.push("news")}
        >
          Home
        </Button>
      </VStack>
    </>
  );
}

After these changes, the welcome screen should look like this:

3. Adding the "News" and "Settings" tabs

Let's start by creating the app/news and app/settings directories.

mkdir news
mkdir settings

Your project should look like this:

├── app
│   ├── index.js
│   ├── _layout.js
│   ├── news
│   │   ├── Empty directory
│   └── settings
│   │   ├── Empty directory
├── app.json
├── babel.config.js
├── index.js
├── package.json
├── README.md
└── yarn.lock

We'll also need to define which navigator to use on each tab. In this case, I decided to use stack navigators on each tab. Let's create the index.js and _layout.js files inside "news" and "settings" directories:

touch ./app/news/index.js ./app/news/_layout.js ./app/settings/index.js ./app/settings/_layout.js

Now, your project structure should look like this:

├── app
│   ├── index.js
│   ├── _layout.js
│   ├── news
│   │   ├── index.js
│   │   └── _layout.js
│   └── settings
│       ├── index.js
│       └── _layout.js
├── app.json
├── babel.config.js
├── index.js
├── package.json
├── README.md
└── yarn.lock

To add the stack navigators, add this to the app/news/_layout.js and app/settings/_layout.js files:

// app/news/_layout.js
// app/settings/_layout.js
import { Stack } from "expo-router";

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

Next, let's customize the app/news/index.js and app/settings/index.js files to include a simple message:

// app/news/index.js
import { Center, LargeTitle } from "@spirokit/core";

export default function News() {
  return (
    <Center flex={1}>
      <LargeTitle>News route</LargeTitle>
    </Center>
  )
}

// app/settings/index.js
import { Center, LargeTitle } from "@spirokit/core";

export default function News() {
  return (
    <Center flex={1}>
      <LargeTitle>Settings route</LargeTitle>
    </Center>
  )
}

You should now be able to navigate between tabs 🎉

Finally, let's update the app/_layout.js file add a custom name for the "news" and "settings" tabs. We will add a custom tab bar component in the next step that will leverage this custom title:

<Tabs.Screen
  name="index"
  options={{
    title: "Home",
  }}
/>
+<Tabs.Screen
+  name="news"
+  options={{
+    // here you can setup a custom title for the tab
+    title: "News",
+  }}
+/>
+<Tabs.Screen
+  name="settings"
+  options={{
+    title: "Settings",
+  }}
+/>

4. Adding a custom tab bar component (optional)

Something really cool about Expo Router is that it will automatically add the required information so anyone can build a custom Tab Bar component on top of it. I decided to take advantage of the TabBar component available in SpiroKit to assign a custom icon for each tab. This will iterate through all the available routes, which are dynamically generated by Expo Router, so we don't lose that benefit by implementing a custom bar.

run the following commands to create a new component for the tab bar:

mkdir components
touch ./components/TabBar.js

Then, add the following code to the new component

import React from "react";
import { TabBar, Caption, Box, useColorModeValue } from "@spirokit/core";
import {
  DotsHorizontalIcon,
  HomeIcon,
  NewspaperIcon,
} from "react-native-heroicons/outline";
import { Platform } from "react-native";

const TabBarComponent = (props) => {
  const { navigation, state, descriptors } = props;
  const isWeb = Platform.OS === "web";

  const onTabPress = (isFocused, routeKey, routeName) => {
    const event = navigation.emit({
      type: "tabPress",
      target: routeKey,
      canPreventDefault: true,
    });

    if (!isFocused && !event.defaultPrevented) {
      navigation.navigate(routeName);
    }
  };

  const getIcon = (routeName) => {
    switch (routeName) {
      case "index":
        return HomeIcon;

      case "news":
        return NewspaperIcon;

      case "settings":
        return DotsHorizontalIcon;

      default:
        return DotsHorizontalIcon;
    }
  };

  return (
    <Box
      width={"full"}
      backgroundColor={useColorModeValue("primaryGray.100", "primaryDark.1")}
    >
      <Box
        maxWidth={isWeb ? "container.lg" : "full"}
        margin="auto"
        width={"full"}
      >
        <TabBar>
          {state.routes.map((route, index) => {
            const options = descriptors[route.key].options;
            if (options.drawerItemStyle?.display === "none") return;
            return (
              <TabBar.Tab
                onPress={() =>
                  onTabPress(state.index === index, route.key, route.name)
                }
                key={route.key}
                IconComponent={getIcon(route.name)}
                LabelComponent={
                  options.title ? (
                    <Caption>{options.title}</Caption>
                  ) : (
                    <Caption>{route.name}</Caption>
                  )
                }
                isFocused={state.index === index}
              />
            );
          })}
        </TabBar>
      </Box>
    </Box>
  );
};

export default TabBarComponent;

Finally, let's update the app/_layout.js to use our new TabBar

// app/_layout.js
...
import { SpiroKitProvider, usePoppins, useSpiroKitTheme } from "@spirokit/core";
import { Tabs } from "expo-router";
+ import TabBarComponent from "../components/TabBar";

// Setting up some global preferences for theming
const theme = useSpiroKitTheme({
  config: {
    colors: {
      primaryGray: "coolGray",
      primaryDark: "coolDark",
    },
  },
});

export default function Layout() {
  const fontLoaded = usePoppins();

  if (!fontLoaded) return <></>;
  return (
    <SpiroKitProvider theme={theme}>
      <Tabs
+       tabBar={(tabBarProps) => {
+         return <TabBarComponent {...tabBarProps}></TabBarComponent>;
+       }}
        screenOptions={{ headerShown: false }}
      >
        <Tabs.Screen
          name="index"
          options={{
            title: "Home",
          }}
        />
        <Tabs.Screen
          name="news"
          options={{
            title: "News",
          }}
        />
        <Tabs.Screen
          name="settings"
          options={{
            title: "Settings",
          }}
        />
      </Tabs>
    </SpiroKitProvider>
  );
}
...

5. Adding UI to the "News" Route

Let's add some UI to our news route. Don't worry if you are not using SpiroKit. The key takeaway here is that we'll use the useRouter hook from Expo Router to navigate to the news details route.

// app/news/index.js

import {
  Button,
  VerticalCard,
  Badge,
  Avatar,
  TitleThree,
  Subhead,
  Image,
  Footnote,
  Box,
  HorizontalCard,
  VStack,
  HStack,
  LargeTitle,
  useColorModeValue,
  Pressable,
} from "@spirokit/core";
import { useRouter } from "expo-router";
import { ScrollView } from "react-native";
import { BellIcon, LightBulbIcon } from "react-native-heroicons/outline";

export default function News() {
  const router = useRouter();

  return (
    <Box
      flex={1}
      backgroundColor={useColorModeValue("white", "primaryDark.1")}
      safeArea
    >
      <ScrollView>
        <VStack space={4} flex={1} padding={4}>
          <HStack
            space={4}
            justifyContent="space-between"
            alignItems={"center"}
          >
            <LargeTitle>News</LargeTitle>
            <Button IconLeftComponent={BellIcon} size="sm" width="auto">
              Subscribe
            </Button>
          </HStack>
          {/* We are using the push method to navigate to news details */}
          <Pressable onPress={() => router.push("/news/1234")}>
            <MainTravelCard></MainTravelCard>
          </Pressable>

          <SecondaryTravelCard></SecondaryTravelCard>
          <FoodCard></FoodCard>
        </VStack>
      </ScrollView>
    </Box>
  );
}

const MainTravelCard = () => {
  return (
    <VerticalCard
      BadgeComponent={<Badge>Travel</Badge>}
      UserAvatarComponent={
        <Avatar
          alt="Siv Marko profile image"
          source={{ uri: "https://i.imgur.com/pfR8Ytj.png" }}
        ></Avatar>
      }
      userName="Siv Marko"
      TitleComponent={
        <TitleThree>Resting place of Australia's last convict ship</TitleThree>
      }
      DescriptionComponent={
        <Subhead>
          Wellington, New Zealand (CNN) - The storm that struck the Edwin Fox on
          February 1873 might sound dramatic.
        </Subhead>
      }
      DateComponent={<Footnote>15th June 2021</Footnote>}
      AssetComponent={
        <Image
          source={{ uri: "https://i.imgur.com/1lSpdz3.png" }}
          alt="Image of a ship"
        ></Image>
      }
    ></VerticalCard>
  );
};

const SecondaryTravelCard = () => {
  return (
    <HorizontalCard
      UserAvatarComponent={
        <Avatar
          alt="Kenny Grimes profile image"
          source={{ uri: "https://i.imgur.com/mwax0m0.png" }}
        ></Avatar>
      }
      userName="Kenny Grimes"
      TitleComponent={
        <TitleThree>
          Emirates introduces digital health verification for UAE passengers
        </TitleThree>
      }
      DescriptionComponent={
        <Subhead>
          Emirates and the Dubai Health Authority (DHA) have begun to implement
          full digital verification of Covid-19 medical records
        </Subhead>
      }
      DateComponent={<Footnote>15th June 2021</Footnote>}
      AssetLeftComponent={
        <Image
          source={{ uri: "https://i.imgur.com/EflHxyi.png" }}
          alt="Image of a ship"
        ></Image>
      }
    ></HorizontalCard>
  );
};

const FoodCard = () => {
  return (
    <HorizontalCard
      UserAvatarComponent={
        <Avatar
          alt="Paula Green profile image"
          source={{ uri: "https://i.imgur.com/Vbzbh6Z.png" }}
        ></Avatar>
      }
      userName="Paula Green"
      TitleComponent={
        <TitleThree>
          The Best Marinara Sauce You Can Get At The Store
        </TitleThree>
      }
      DateComponent={<Footnote>15th June 2021</Footnote>}
      AssetRightComponent={LightBulbIcon}
    ></HorizontalCard>
  );
};

Expected result:

5. Adding UI to the "Settings" Route (Optional)

I wanted to use the settings route to test that dark mode is propagated through the rest of the routes.

Let's customize the UI to add a switch that allows us to toggle dark mode:

// app/settings/index.js
import {
  Body,
  Box,
  HStack,
  LargeTitle,
  Switch,
  useColorModeValue,
  VStack,
  useColorMode,
  Button,
  Input,
  Subhead,
} from "@spirokit/core";
import { LogoutIcon, UserIcon, LinkIcon } from "react-native-heroicons/outline";

export default function Settings() {
  const { toggleColorMode, colorMode } = useColorMode();

  return (
    <Box flex={1}>
      <Box
        safeAreaTop
        justifyContent={"flex-end"}
        padding={4}
        backgroundColor={useColorModeValue("primary.500", "primary.300")}
        minHeight={32}
      >
        <LargeTitle color={useColorModeValue("white", "primaryGray.900")}>
          Settings
        </LargeTitle>
      </Box>

      <Box
        flex={1}
        backgroundColor={useColorModeValue("white", "primaryDark.1")}
        padding={4}
      >
        <VStack space={4} flex={1}>
          <HStack justifyContent={"space-between"} alignItems="center">
            <Body flex={1}>Dark mode</Body>
            <Switch onValueChange={toggleColorMode}></Switch>
          </HStack>
          <Input
            IconLeftComponent={UserIcon}
            LabelComponent={<Subhead>Name</Subhead>}
            defaultValue="Mauro"
          ></Input>
          <Input
            IconLeftComponent={UserIcon}
            LabelComponent={<Subhead>Lastname</Subhead>}
            defaultValue="Garcia"
          ></Input>
          <Input
            IconLeftComponent={LinkIcon}
            isDisabled
            LabelComponent={<Subhead>Twitter handle</Subhead>}
            defaultValue="https://www.twitter.com/mauro_codes"
          ></Input>
        </VStack>

        <Button IconLeftComponent={LogoutIcon}>Logout</Button>
      </Box>
    </Box>
  );
}

If everything goes well, we should now be able to toggle between light and dark mode

6. Adding a dynamic route for the news details screen

From the Expo docs:

"Dynamic routes match any unmatched path at a given segment level. For example, /blog/[id] is a dynamic route. The variable part ([id]) is called a "slug"."

We are going to use this pattern to navigate from the "news" route to the news details ("news"/[id]).

Remember, Expo Router is based on your file system, so let's start by creating a new file for this dynamic route:

touch ./app/news/\[id\].js

Inside our new [id].js file, let's add some UI and see how we can access the id param.

Given this is a demo, I'm using hardcoded data. In real life, we would use the id from the URL to request the information using fetch or axios.

// app/news/[id].js
import { useLocalSearchParams, useRouter, useSegments } from "expo-router";
import { Platform, ScrollView } from "react-native";
import {
  Avatar,
  Subhead,
  Image,
  Box,
  VStack,
  HStack,
  LargeTitle,
  useColorModeValue,
  ZStack,
  Body,
  Button,
} from "@spirokit/core";
import { ChevronLeftIcon } from "react-native-heroicons/outline";

export default function NewsDetails(props) {
  // Extracting the id param from the route
  const { id } = useLocalSearchParams();

  // This should be replaced by real data coming from an external API
  const content = loremIpsum;

  return (
    <Box flex={1} backgroundColor={useColorModeValue("white", "primaryDark.1")}>
      <Header></Header>
      <ScrollView>
        <VStack space={4} flex={1} padding={4}>
          <Body>{id}</Body>
          <Body>{content}</Body>
        </VStack>
      </ScrollView>
    </Box>
  );
}

const Header = () => {
  const router = useRouter();

  return (
    <>
      <ZStack minHeight={56} overflow="hidden" width="full">
        <Image
          height={56}
          width="full"
          resizeMode="cover"
          source={{ uri: "https://i.imgur.com/1lSpdz3.png" }}
          alt="Image of a ship"
        ></Image>
        <VStack
          justifyContent={"space-between"}
          backgroundColor={"black:alpha.40"}
          padding={4}
          width="full"
          height={"full"}
        >
          {Platform.OS === "web" ? (
            <Button
              size="sm"
              width="auto"
              alignSelf={"flex-start"}
              onPress={() => router.back()}
              IconLeftComponent={ChevronLeftIcon}
            ></Button>
          ) : null}
          <LargeTitle numberOfLines={3} color={"white"}>
            Resting place of Australia's last convict ship
          </LargeTitle>
        </VStack>
      </ZStack>
      <AuthorLine></AuthorLine>
    </>
  );
};

const AuthorLine = () => {
  return (
    <HStack
      padding={4}
      justifyContent={"space-between"}
      alignItems={"center"}
      space={4}
    >
      <HStack space={4} flex={1} alignItems="center">
        <Avatar
          size={"sm"}
          alt="Siv Marko profile image"
          source={{ uri: "https://i.imgur.com/pfR8Ytj.png" }}
        ></Avatar>
        <Body>Siv Marko</Body>
      </HStack>
      <Subhead flex={1} textAlign="right">
        15th June 2021
      </Subhead>
    </HStack>
  );
};

const loremIpsum = `Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus blandit faucibus justo, at eleifend sapien pellentesque ut. Curabitur ultrices eget arcu sit amet luctus. Mauris accumsan ut mauris eget pharetra. Quisque dignissim sed leo sed condimentum. Nullam ligula nisi, pellentesque sit amet lacus eget, malesuada tempus lorem. Pellentesque fringilla erat a faucibus semper. Sed posuere tristique vulputate.

Nam convallis tempor dictum. Donec maximus nisl a tempor condimentum. Fusce egestas velit id ante consectetur feugiat. Nam non ligula metus. Interdum et malesuada fames ac ante ipsum primis in faucibus. Fusce efficitur tellus leo, non vehicula lorem ornare id. Vivamus enim mauris, volutpat ut luctus semper, hendrerit eu dolor. Nunc a sapien ac ex tempus tempor. Cras odio augue, porta vitae venenatis id, sagittis at tortor. Etiam id tristique tortor, in eleifend dui. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.`;

If you reload your app, you should now be able to navigate to the news details screen.

Note that you didn't have to add any additional configuration to use this last route. Given that we already setup the stack navigator for the "news" directory, every child automatically becomes a valid route ✨✨

Conclusion

Congrats! If you are still here, you managed to build a small app that leverages a few of the available features on Expo Router. This is just the beginning. We are in the early days of this library, so everything is changing really fast. If you enjoyed this article, don't hesitate to leave a comment or reach out to me on Twitter. My DM's are always open.

I would love to hear your thoughts! Happy coding!