DEV Community: Diego Freniche

Using Expo and Realm with expo-dev-client

Diego Freniche — Fri, 04 Mar 2022 12:10:24 +0000

In our last post on how to build an offline-first React Native mobile app with Expo and Realm, we talked about a limitation of using Realm and Expo where we stated that Realm is not compatible with Expo-managed workflows. Well, wait no more, because now Expo works with Realm and we have a nice custom development client that will have roughly the same functionality as Expo Go.

Creating a React Native app using Expo and Realm in one simple step

Yes, it sounds like clickbait, but it's true. If you want to build a full application that uses TypeScript, just type in your terminal:

npx expo-cli init ReactRealmTSTemplateApp -t @realm/expo-template-js

If you'd rather do JavaScript, just type:

npx expo-cli init ReactRealmJSTemplateApp -t @realm/expo-template-js

After either of these two, change to the directory containing the project that has just been created and start the iOS or Android app:

cd ReactRealmJSTemplateApp
yarn android

cd ReactRealmJSTemplateApp
yarn ios

This will create a prebuilt Expo app. That is, you'll see ios and android folders in your project and this won't be a managed Expo app, where all the native details are hidden and Expo takes care of everything. Having said that, you don't need to go into the ios or android folders unless you need to add some native code in Swift or Kotlin.

Once launched, the app will ask to open in ReactRealmJSTemplateApp, not in Expo Go. This means we're running this nice, custom, dev client that will bring us most of the Expo Go experience while also working with Realm.

We can install our app and use it using yarn ios/android. If we want to start the dev-client to develop, we can also use yarn start.

Adding our own code

This template is a quick way to start with Realm, so it includes all code you'll need to write your own Realm application:

It adds the versions of Expo (^44.0.6), React Native (0.64.3), and Realm (^10.13.0) that work together.
It also adds expo-dev-client and @realm/react packages, to make the custom development client part work.
Finally, in app, you'll find sample code to create your own model object, initialize a connection with Realm Sync, save and fetch data, etc.

But I want to reuse the Read it Later - Maybe app I wrote for the last post on Expo and Realm. Well, I just need to delete all JavaScript files inside app, copy over all my code from that App, and that's all. Now my old app's code will work with this custom dev client!

Putting our new custom development client to work

Showing the debug menu is explained in the React Native debug documentation, but you just need to:

Use the ⌘D keyboard shortcut when your app is running in the iOS Simulator, or ⌘M when running in an Android emulator on macOS, and Ctrl+M on Windows and Linux.

Android Debug Menu	iOS Debug Menu

As this is an Expo app, we can also show the Expo menu by just pressing m from terminal while our app is running.

Now do Hermes and react-native-reanimated

The Realm React Native SDK has a hermes branch that is indeed compatible with Hermes. So, it'll work with react-native-reanimated v2 but not with Expo, due to the React Native version the Expo SDK is pinned to.

So, right now, you have to choose:

Have Expo + Realm working out of the box.
Or start your app using Realm + Hermes (not using Expo).

Both the Expo team and the Realm JavaScript SDK teams are working hard to make everything work together, and we'll update you with a new post in the future on using React Native Reanimated + Expo + Hermes + Realm (when all required dependencies are in place).

Recap

In this post, we've shown how simple it is now to create a React Native application that uses Expo + Realm. This still won't work with Hermes, but watch this space as Realm is already compatible with it!

One more thing

Our community has also started to leverage our new capabilities here. Watch this video from Aaron Saunders explaining how to use MongoDB Realm + Expo building a React Native app.

And, as always, you can hang out in our Community Forums and ask questions (and get answers) about your React Native development with Expo, Realm and MongoDB.

Continuously Building and Hosting our Swift DocC Documentation using Github Actions and Netlify

Diego Freniche — Wed, 16 Feb 2022 08:38:45 +0000

In a past post of this series, we showed how easy it was to generate documentation for our frameworks and libraries using DocC and the benefits of doing it. We also saw the different content we can add, like articles, how-tos, and references for our functions, classes, and structs.

But once generated, you end up with an archived DocC folder that is not that easy to share. You can compress it, email it, put it somewhere in the cloud so it can be downloaded, but this is not what we want. We want:

Automatic (and continuous) generation of our DocC documentation bundle.
Automatic (and continuous) posting of that documentation to the web, so it can be read online.

What’s in a DocC bundle?

A .doccarchive archive is, like many other things in macOS, a folder. Clone the repository we created with our documentation and look inside BinaryTree.doccarchive from a terminal.

git clone https://github.com/mongodb-developer/realm-binary-tree-docc 
cd BinaryTree.doccarchive

You’ll see:

..
├── css
│   ├── …
│   └── tutorials-overview.7d1da3df.css
├── data
│   ├── documentation
│   │   ├── binarytree
│   │   │   ├── …
│   │   │   └── treetraversable-implementations.json
│   └── tutorials
│       ├── binarytree
│       │   ├── …
│       │   └── traversingtrees.json
│       └── toc.json
├── downloads
├── favicon.ico
├── favicon.svg
├── images
│   ├── …
│   └── tree.png
├── img
│   ├── …
│   └── modified-icon.5d49bcfe.svg
├── index
│   ├── availability.index
│   ├── data.mdb
│   ├── lock.mdb
│   └── navigator.index
├── index.html
├── js
│   ├── chunk-2d0d3105.459bf725.js
│   ├ …
│   └── tutorials-overview.db178ab9.js
├── metadata.json
├── theme-settings.json
└── videos

This is a single-page web application. Sadly, we can’t just open index.html and expect it to render correctly. As Apple explains in the documentation, for this to work, it has to be served from a proper web server, with a few rewrite rules added:

To host a documentation archive on your website, do the following:

Copy the documentation archive to the directory that your web server uses to serve files. In this example, the documentation archive is SlothCreator.doccarchive.

Add a rule on the server to rewrite incoming URLs that begin with /documentation or /tutorial to SlothCreator.doccarchive/index.html.

Add another rule for incoming requests to support bundled resources in the documentation archive, such as CSS files and image assets.

They even add a sample configuration to use with the Apache httpd server. So, to recap:

We can manually generate our documentation and upload it to a web server.
We need to add the rewrite rules described in Apple’s documentation for the DocC bundle to work properly.

Each time we update our documentation, we need to generate it and upload it. Let’s generate our docs automatically.

Automating generation of our DocC archive using GitHub Actions

We’ll continue using our Binary Tree Package as an example to generate the documentation. We’ll add a GitHub Action to generate docs on each new push to main. This way, we can automatically refresh our documentation with the latest changes introduced in our library.

To add the action, we’ll click on the Actions button in our repo. In this case, a Swift Action is offered as a template to start. We’ll choose that one:

After clicking on Configure, we can start tweaking our action. A GitHub action is just a set of steps that GitHub runs in a container for us. There are predefined steps, or we can just write commands that will work in our local terminal. What we need to do is:

Get the latest version of our code.
Build out our documentation archive.
Find where the doccarchive has been generated.
Copy that archive to a place where it can be served online.

We’ll call our action docc.yml. GitHub actions are YAML files, as the documentation tells us. After adding them to our repository, they will be stored in .github/workflows/. So, they’re just text files we can edit locally and push to our repo.

Getting the latest version of our code

This is the easy part. Every time a Github action starts, it creates a new, empty container and clones our repo. So, our code is there, ready to be compiled, pass all tests, and does everything we need to do with it.

Our action starts with:


name: Generate DocC
on:
  push:
    branches: [ main ]

jobs:
  Build-Github-Actions:
    runs-on: macos-latest

    steps:
    - name: Git Checkout
      uses: actions/checkout@v2

So, here:

We gave the action the name “Generate DocC”.
Then we select when it’ll run, i.e., on any pushes to main.
We run this on a macOS container, as we need Xcode.
The first step is to clone our repo. We use a predefined action, checkout, that GitHub provides us with.

Building out our documentation archive

Now that our code is in place, we can use xcodebuild to build the DocC archive. We can build our projects from the command line, run our tests, or in this case, build the documentation.

xcodebuild docbuild -scheme BinaryTree -derivedDataPath ./docbuild -destination 'platform=iOS Simulator,OS=latest,name=iPhone 13 mini'

Here we’re building to generate DocC (docbuild parameter), choosing the BinaryTree scheme in our project, putting all generated binaries in a folder at hand (docbuild), and using an iPhone 13 mini as Simulator. When we build our documentation, we need to compile our library too. That’s why we need to choose the Simulator (or device) used for building.

Find where the `doccarchive` has been generated

If everything goes well, we’ll have our documentation built inside docbuild. We’ll search for it, as each build will generate a different hash to store the results of our build. And this is, on each run, a clean machine. To find the archive, we use:

find ./docbuild -type d -iname "BinaryTree.doccarchive"

Copy our documentation to a place where it can be served online

Now that we know where our DocC archive is, it’s time to put it in a different repository. The idea is we’ll have one repository for our code and one for our generated DocC bundle. Netlify will read from this second repository and host it online.

So, we clone the repository that will hold our documentation with:

git clone https://github.com/mongodb-developer/realm-binary-tree-docc

So, yes, now we have two repositories, one cloned at the start of the action and now this one that holds only the documentation. We copy over the newly generated DocC archive:

cp -R "$DOCC_DIR" realm-binary-tree-docc

And we commit all changes:

cd realm-binary-tree-docc
git add .
git commit -m "$DOC_COMMIT_MESSAGE"
git status

Here, $DOC_COMMIT_MESSAGE is just a variable we populate with the last commit message from our repo and current date. But it can be any message.

After this, we need to push the changes to the documentation repository.

git config --get remote.origin.url
git remote set-url origin https://${{ secrets.API_TOKEN_GITHUB}}@github.com/mongodb-developer/realm-binary-tree-docc

git push origin

Here we first print our origin (the repo where we’ll be pushing our changes) with

git config --get remote.origin.url

This command will show the origin of a git repository. It will print the URL of our code repository. But this is not where we want to push. We want to push to the documentation repository. So, we set the origin pointing to https://github.com/mongodb-developer/realm-binary-tree-docc. As we will need permission to push changes, we authenticate using a Personal Access Token. From Github Documentation on Personal Access Tokens:

You should create a personal access token to use in place of a password with the command line or with the API.

Luckily, Github Actions has a way to store these secrets, so they’re publicly accessible. Just go to your repository’s Settings and expand Secrets. You’ll see an “Actions” option. There you can give your secret a name to be used later in your actions.

For reference, this is the complete action I’ve used.

Hosting our DocC archives in Netlify

As shown in this excellent post by Joseph Duffy, we'll be hosting our documentation in Netlify. Creating a free account is super easy. In this case, I advise you to use your Github credentials to log in Netlify. This way, adding a new site that reads from a Github repo will be super easy. Just add a new site and select Import an existing project. You can then choose Github, and once authorized, you’ll be able to select one of your repositories.

Now I set it to deploy with “Any pull request against your production branch / branch deploy branches.” So, every time your repo changes, Netlify will pick up the change and host it online (if it’s a web app, that is).

But we’re missing just one detail. Remember I mentioned before that we need to add some rewrite rules to our hosted documentation? We’ll add those in a file called netlify.toml. This file looks like:

[build]
publish = "BinaryTree.doccarchive/"

[[redirects]]
from = "/documentation/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/tutorials/*"
status = 200
to = "/index.html"

[[redirects]]
from = "/data/documentation.json"
status = 200
to = "/data/documentation/binarytree.json"

[[redirects]]
force = true
from = "/"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/documentation"
status = 302
to = "/documentation/"

[[redirects]]
force = true
from = "/tutorials"
status = 302
to = "/tutorials/"

To use it in your projects, just review the lines:

publish = "BinaryTree.doccarchive/"
…
to = "/data/documentation/binarytree.json"

And change them accordingly.

Recap

In this post, we’ve seen how to:

Add a Github Action to a code repository that continuously builds a DocC documentation bundle every time we push a change to the code.
That action will in turn push that newly built documentation to a documentation repository for our library.
That documentation repository will be set up in Netlify and add some rewrite rules so we'll be able to host it online.

Don’t wait and add continuous generation of your library’s documentation to your CI pipeline!

Build an Offline-First React Native Mobile App with Expo and Realm

Diego Freniche — Thu, 23 Dec 2021 16:00:21 +0000

Introduction

Building Mobile Apps that work offline and sync between different devices is not an easy task. You have to write code to detect when you’re offline, save data locally, detect when you’re back online, compare your local copy of data with that in the server, send and receive data, parse JSON, etc.

It’s a time consuming process that’s needed, but that appears over and over in every single mobile app. You end up solving the same problem for each new project you write. And it’s worse if you want to run your app in iOS and Android. This means redoing everything twice, with two completely different code bases, different threading libraries, frameworks, databases, etc.

To help with offline data management and syncing between different devices, running different OSes, we can use MongoDB’s Realm. To create a single code base that works well in both platforms we can use React Native. And the simplest way to create React Native Apps is using Expo.

React Native Apps

The React Native Project, allows you to create iOS and Android apps using React “a best-in-class JavaScript library for building user interfaces”. So if you’re an experienced Web developer who already knows React, using React Native will be the natural next step to create native Mobile Apps.

But even if you’re a native mobile developer with some experience using SwiftUI in iOS or Compose in Android, you’ll find lots of similarities here.

Expo and React Native

Expo is a set of tools built around React Native. Using Expo you can create React Native Apps quickly and easily. For that, we need to install Expo using Node.js package manager npm:

npm install --global expo-cli

This will install expo-cli globally so we can call it from anywhere in our system. In case we need to update Expo we’ll use that very same command. For this tutorial we’ll need the latest version of Expo, that’s been updated to support Realm. You can find all the new features and changes in the Expo SDK 44 announcement blog post.

To ensure you have the latest Expo version run:

expo --version

Should return at least 5.0.1. If not, run again npm install --global expo-cli

Prerequisites

Now that we have the latest Expo installed, let’s check out that we have everything we need to develop our application:

Xcode 13, including Command Line Tools, if we want to develop an iOS version. We’ll also need a macOS computer running at least macOS 11/Big Sur in order to run Xcode.
Android Studio, to develop for Android and at least one Android Emulator ready to test our apps.
Any code editor. I’ll be using Visual Studio Code as it has plugins to help with React Native Development, but you can use any other editor.
Check that you have the latest version of yarn running npm install -g yarn
Make sure you are NOT on the latest version of node, however, or you will see errors about unsupported digital envelope routines. You need the LTS version instead. Get the latest LTS version number from https://nodejs.org/ and then run:

nvm install 16.13.1 # swap for latest LTS version

If you don’t have Xcode or Android Studio, and need to build without installing anything locally you can also try Expo Application Services, a cloud-based building service that allows you to build your Expo Apps remotely.

MongoDB Atlas and Realm App

Our App will store data in a cloud-backed MongoDB Atlas cluster. So we need to create a free MongoDB account and set up a cluster. For this tutorial, a Free-forever, M0 cluster will be enough.

Once we have our cluster created we can go ahead and create a Realm App. The Realm App will sync our data from mobile into a MongoDB Atlas database, although it has many other uses: manages authentication, can run serverless functions, host static sites, etc. Just follow this quick tutorial (select the React Native template) but don’t download any code, as we’re going to use Expo to create our app from scratch. That will configure our Realm App correctly to use Sync and set it into Development Mode.

Read It Later - Maybe

Now we can go ahead and create our app, a small “read it later” kind of app to store web links we save for later reading. As sometimes we never get back to those links I’ll call it Read It Later - Maybe.

You can always clone the repo and follow along.

Login	Adding a Link

All Links	Deleting a Link

Install Expo and create the App

We’ll use Expo to create our app using expo init read-later-maybe. This will ask us which template we want to use for our app. Using up and down cursors we can select the desired template, in this case, from the Managed Workflows we will choose the blank one, that uses JavaScript. This will create a read-later-maybe directory for us containing all the files we need to get started.

To start our app, just enter that directory and start the React Native Metro Server using yarn start. This will tell Expo to install any dependencies and start the Metro Server.

cd read-later-maybe
yarn start

This will open our default browser, with the Expo Developer Tools at http://localhost:19002/. If your browser doesn't automatically open, press d to open Developer Tools in the browser. From this web page we can:

Start our app in the iOS Simulator
Start our app in the Android Emulator
Run it in a Web browser (if our app is designed to do that)
Change the connection method to the Developer Tools Server
Get a link to our app. (More on this later when we talk about Expo Go)

We can also do the same using the developer menu that’s opened in the console, so it’s up to you to use the browser and your mouse or your Terminal and the keyboard.

Running our iOS App

To start the iOS App in the Simulator, we can either click “Start our app in the iOS Simulator” on Expo Developer Tools or type i in the console, as starting expo leaves us with the same interface we have in the browser, replicated in the console. We can also directly run the iOS app in Simulator by typing yarn ios if we don’t want to open the development server.

Expo Go

The first time we run our app Expo will install Expo Go. This is a native application (both for iOS and Android) that will take our JavaScript and other resources bundled by Metro and run it in our devices (real or simulated/emulated). Once run in Expo Go, we can make changes to our JavaScript code and Expo will take care of updating our app on the fly, no reload needed.

Open Expo Go	1st time Expo Go greeting	Debug menu

Expo Go apps have a nice debugging menu that can be opened pressing “m” in the Expo Developer console.

Structure of our App

Now our app is working, but it only shows a simple message: “Open up App.js to start working on your app!”. So we’ll open the app using our code editor. These are the main files and folders we have so far:

.
├── .expo-shared
│   └── assets.json
├── assets
│   ├── adaptive-icon.png
│   ├── favicon.png
│   ├── icon.png
│   └── splash.png
├── .gitignore
├── App.js
├── app.json
├── babel.config.js
├── package.json
└── yarn.lock

The main three files here are:

package.json, where we can check / add / delete our app’s dependencies
app.json: configuration file for our app
App.js: the starting point for our JavaScript code

These changes can be found in tag step-0 of the repo.

Let’s add some navigation

Our App will have a Login / Register Screen and then will show the list of Links for that particular User. We’ll navigate from the Login Screen to the list of Links and when we decide to Log Out our app we’ll navigate back to the Login / Register Screen. So first we need to add the React Native Navigation Libraries, and the gesture handler (for swipe & touch detection, etc). Enter the following commands in the Terminal:

expo install @react-navigation/native
expo install @react-navigation/stack
expo install  react-native-gesture-handler
expo install  react-native-safe-area-context
expo install react-native-elements

These changes can be found in tag step-1 of the repo.

Now, we’ll create a mostly empty LoginView in views/LoginView.js (the views directory does not exist yet, we need to create it first) containing:

import React from "react";
import { View, Text, TextInput, Button, Alert } from "react-native";

export function LoginView({ navigation }) {
  return (
    <View>
      <Text>Sign Up or Sign In:</Text>
      <View>
        <TextInput          
          placeholder="email"
          autoCapitalize="none"
        />
      </View>
      <View>
        <TextInput
          placeholder="password"
          secureTextEntry
        />
      </View>
      <Button title="Sign In" />
      <Button title="Sign Up" />
    </View>
  );
}

This is just the placeholder for our Login screen. We open it from App.js. Change the App function to:

export default function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen
            name="Login View"
            component={LoginView}
            options={{ title: "Read it Later - Maybe" }}
          />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

And add required imports to the top of the file, below the existing import lines.

import { NavigationContainer } from "@react-navigation/native";
import { createStackNavigator } from "@react-navigation/stack";
import { LoginView } from './views/LoginView';
const Stack = createStackNavigator();

All these changes can be found in tag step-2 of the repo.

Adding the Realm Library

Installing Realm

To add our Realm library to the project we’ll type in the Terminal:

expo install realm

This will add Realm as a dependency in our React Native Project. Now we can also create a file that will hold the Realm initialization code, we’ll call it RealmApp.js and place it in the root of the directory, alongside App.js.

import Realm from "realm";
const app = new Realm.App({id: "your-realm-app-id-here"});
export default app;

We need to add a Realm App ID to our code. Here are instructions on how to do so. In short, a Mobile Realm-powered App will use a local database to save changes and will connect to a MongoDB Atlas Database using a Realm App that we create in the cloud. We have Realm as a library in our Mobile App, doing all the heavy lifting (sync, offline, etc.) for our React Native app, and a Realm App in the cloud that connects to MongoDB Atlas, acting as our backend. This way, if we go offline we’ll be using our local database on device and when online, all changes will propagate in both directions.

All these changes can be found in tag step-3 of the repo.

Update 24 January 2022

A simpler way to create a React Native App that uses Expo & Realm is just to create it using a template.
For JavaScript based apps:
npx expo-cli init ReactRealmJsTemplateApp -t @realm/expo-template-js

For TypeScript based apps:
npx create-react-native-app ReactRealmTsTemplateApp -t with-realm

Auth Provider

All Realm related code to register a new user, log in and log out is inside a Provider. This way we can provide all descendants of this Provider with a context that will hold a logged in user. All this code is in providers/AuthProvider.js. You’ll need to create the providers folder and then add AuthProvider.js to it.

Realm not only stores data offline, syncs across multiple devices and stores all your data in a MongoDB Atlas Database, but can also run Serverless Functions, host static html sites or authenticate using multiple providers. In this case we’ll use the simpler email/password authentication.

We create the context with:

const AuthContext = React.createContext(null);

The SignIn code is asynchronous:

const signIn = async (email, password) => {
    const creds = Realm.Credentials.emailPassword(email, password);
    const newUser = await app.logIn(creds);
    setUser(newUser);
  };

As is the code to register a new user:

  const signUp = async (email, password) => {
    await app.emailPasswordAuth.registerUser({ email, password });
  };

To log out we simply check if we’re already logged in, in that case call logOut

const signOut = () => {
    if (user == null) {
      console.warn("Not logged in, can't log out!");
      return;
    }
    user.logOut();
    setUser(null);
  };

All these changes can be found in tag step-4 of the repo.

Login / Register code

Take a moment to have a look at the styles we have for the app in the stylesheet.js file, then modify the styles to your heart’s content.

Now, for Login and Logout we’ll add a couple states to our LoginView in views/LoginView.js. We’ll use these to read both email and password from our interface.

Place the following code inside export function LoginView({ navigation }) {:

  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

Then, we’ll add the UI code for Login and Sign up. Here we use signIn and signUp from our AuthProvider.

  const onPressSignIn = async () => {
    console.log("Trying sign in with user: " + email);
    try {
      await signIn(email, password);
    } catch (error) {
      const errorMessage = `Failed to sign in: ${error.message}`;
      console.error(errorMessage);
      Alert.alert(errorMessage);
    }
  };

  const onPressSignUp = async () => {
    console.log("Trying signup with user: " + email);
    try {
      await signUp(email, password);
      signIn(email, password);
    } catch (error) {
      const errorMessage = `Failed to sign up: ${error.message}`;
      console.error(errorMessage);
      Alert.alert(errorMessage);
    }
  };

All changes can be found in step-5.

Prebuilding our Expo App

On save we’ll find this error:

Error: Missing Realm constructor. Did you run "pod install"? Please see https://realm.io/docs/react-native/latest/#missing-realm-constructor for troubleshooting

Right now, Realm is not compatible with Expo Managed Workflows. In a managed Workflow Expo hides all iOS and Android native details from the JavaScript/React developer so they can concentrate on writing React code. Here, we need to prebuild our App, which will mean that we lose the nice Expo Go App that allows us to load our app using a QR code.

The Expo Team is working hard on improving the compatibility with Realm, as is our React Native SDK team, who are currently working on improving the compatibility with Expo, supporting the Hermes JavaScript Engine and expo-dev-client. Watch this space for all these exciting announcements!

So to run our app in iOS we’ll do:

expo run:ios

We need to provide a Bundle Identifier to our iOS app. In this case we’ll use com.realm.read-later-maybe

This will install all needed JavaScript libraries using yarn, then install all native libraries using CocoaPods, and finally will compile and run our app. To run on Android we’ll do:

expo run:android

Navigation completed

Now we can register and login in our App. Our App.js file now looks like:

export default function App() {
  return (
    <AuthProvider>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen
              name="Welcome View"
              component={LoginView}
              options={{ title: "Read it Later - Maybe" }}
            />
        </Stack.Navigator>
      </NavigationContainer>
    </AuthProvider>
  );
}

We have an AuthProvider that will provide the user logged in to all descendants. Inside is a Navigation Container with one Screen: Login View. But we need to have two Screens: our “Login View” with the UI to log in/register and “Links Screen”, which will show all our links.

So let’s create our LinksView screen:

import React, { useState, useEffect } from "react";
import { Text } from "react-native";

export function LinksView() {
    return (
        <Text>Links go here</Text>
    );
}

Right now only shows a simple message “Links go here”, as you can check in step-6

Log out

We can register and log in, but we also need to log out of our app. To do so, we’ll add a Nav Bar item to our Links Screen, so instead of having “Back” we’ll have a logout button that closes our Realm, calls logout and pops out our Screen from the navigation, so we go back to the Welcome Screen.

In our LinksView Screen in we’ll add:

React.useLayoutEffect(() => {
    navigation.setOptions({
        headerBackTitle: "Log out",
        headerLeft: () => <Logout closeRealm={closeRealm} />
    });
  }, [navigation]);

Here we use a components/Logout component that has a button. This button will call signOut from our AuthProvider. You’ll need to add the components folder.

   return (
    <Button
      title="Log Out"
      onPress={() => {
        Alert.alert("Log Out", null, [
          {
            text: "Yes, Log Out",
            style: "destructive",
            onPress: () => {
              navigation.popToTop();
              closeRealm();
              signOut();
            },
          },
          { text: "Cancel", style: "cancel" },
        ]);
      }}
    />
  );

Nice! Now we have Login, Logout and Register! You can follow along in step-7.

Links

CRUD

We want to store Links to read later. So we’ll start by defining how our Link class will look like. We’ll store a Name and a URL for each link. Also, we need an id and a partition field to avoid pulling all Links for all users. Instead we’ll just sync Links for the logged in user. These changes are in schemas.js

class Link {
  constructor({
    name,
    url,
    partition,
    id = new ObjectId(),
  }) {

    this._partition = partition;
    this._id = id;
    this.name = name;
    this.url = url;
  }

  static schema = {
    name: 'Link',
    properties: {
      _id: 'objectId',
      _partition: 'string',
      name: 'string',
      url: 'string',
    },

    primaryKey: '_id',
  };
}

You can get these changes in step-8 of the repo.

And now, we need to code all the CRUD methods. For that, we’ll go ahead and create a LinksProvider that will fetch Links and delete them. But first, we need to open a Realm to read the Links for this particular user:

  realm.open(config).then((realm) => {
      realmRef.current = realm;
      const syncLinks = realm.objects("Link");
      let sortedLinks = syncLinks.sorted("name");
      setLinks([...sortedLinks]);

      // we observe changes on the Links, in case Sync informs us of changes
      // started in other devices (or the cloud)
      sortedLinks.addListener(() => {
        console.log("Got new data!");
        setLinks([...sortedLinks]);
      });
    });

To add a new Link we’ll have this function that uses [realm.write](https://docs.mongodb.com/realm-sdks/js/latest/Realm.html#write) to add a new Link. This will also be observed by the above listener, triggering a UI refresh.

const createLink = (newLinkName, newLinkURL) => {

    const realm = realmRef.current;

    realm.write(() => {
      // Create a new link in the same partition -- that is, using the same user id.
      realm.create(
        "Link",
        new Link({
          name: newLinkName || "New Link",
          url: newLinkURL || "http://",
          partition: user.id,
        })
      );
    });
  };

Finally to delete Links we’ll use [realm.delete](https://docs.mongodb.com/realm-sdks/js/latest/Realm.html#delete).

  const deleteLink = (link) => {

    const realm = realmRef.current;

    realm.write(() => {
      realm.delete(link);
      // after deleting, we get the Links again and update them
      setLinks([...realm.objects("Link").sorted("name")]);
    });
  };

Showing Links

Our LinksView will map the contents of the links array of Link objects we get from LinkProvider and show a simple List of Views to show name and URL of each Link. We do that using:

{links.map((link, index) =>
    <ScrollView>
        <ListItem.Content>
            <ListItem.Title>
                {link.name}
            </ListItem.Title>
            <ListItem.Subtitle>
                {link.url}
            </ListItem.Subtitle>
        </ListItem.Content>
        <ListItem.Chevron />
    </ScrollView>

UI for deleting Links

As we want to delete links we’ll use a swipe right-to-left gesture to show a button to delete that Link

<ListItem.Swipeable
    onPress={() => onClickLink(link)}
    bottomDivider
    key={index} 
    rightContent={
        <Button
            title="Delete"
            onPress={() => deleteLink(link)}
        />
    }
>

We get deleteLink from the useLinks hook in LinksProvider:

  const { links, createLink, deleteLink } = useLinks();

UI for adding Links

We’ll have a TextInput for entering name and URL, and a button to add a new Link directly at the top of the List of Links. We’ll use an accordion to show/hide this part of the UI:

<ListItem.Accordion
        content={
          <ListItem.Content>
            <ListItem.Title>Create new Link</ListItem.Title>
          </ListItem.Content>
        }
        isExpanded={expanded}
        onPress={() => {
          setExpanded(!expanded);
        }}
      >
      {
        <>
          <TextInput
            style={styles.input}
            onChangeText={setLinkDescription}
            placeholder="Description"
            value={linkDescription}
          />
          <TextInput
            style={styles.input}
            onChangeText={setlinkURL}
            placeholder="URL"
            value={linkURL}
          />
          <Button
                title='Click!'
                color='red'
                onPress={ () => { createLink(linkDescription, linkURL); }}
                />
        </>
      }
      </ListItem.Accordion>

Adding Links in the main App

Finally, we’ll integrate the new LinksView inside our LinksProvider in App.js

<Stack.Screen name="Links">
    {() => {
        return (
            <LinksProvider>
                <LinksView />
            </LinksProvider>
        );
    }} 
</Stack.Screen>

The final App

Wow! That was a lot, but now we have a React Native App, that works with the same code base in both iOS and Android, storing data in a MongoDB Atlas Database in the cloud thanks to Realm Sync. And what’s more, any changes in one device syncs in all other devices with the same user logged-in. But the best part is that Realm Sync works even when offline!

Syncing iOS and Android	Offline Syncing!

Recap

In this tutorial we’ve seen how to build a simple React Native application using Expo that takes advantage of Realm Sync for their offline and syncing capabilities. This App is a prebuilt app as right now Managed Expo Workflows won’t work with Realm (yet, read more below). But you still get all the simplicity of use that Expo gives you, all the Expo libraries and the EAS: build your app in the cloud without having to install Xcode or Android Studio.

The Realm SDK team is working hard to make Realm fully compatible with Hermes. Once we release an update to the Realm React Native SDK compatible with Hermes, we’ll publish a new post updating this app. Also, we’re working to finish an Expo Custom Development Client. This will be our own Realm Expo Development Client that will substitute Expo Go while developing with Realm. Expect also a piece of news when that is approved!

All the code for this tutorial can be found in this repo.

Let’s Give Your Realm-Powered Ionic Web App the Native Treatment on iOS and Android!

Diego Freniche — Wed, 22 Dec 2021 16:40:34 +0000

Realm is an open-source, easy-to-use local database that helps mobile developers to build better apps, faster. It offers a data synchronization service—MongoDB Realm Sync—that makes it simple to move data between the client and MongoDB Atlas on the back end. Using Realm can save you from writing thousands of lines of code, and offers an intuitive way to work with your data.

The Ionic team posted a fantastic article on how you can use Ionic with Realm to build a React Web app quickly, taking advantage of Realm to easily persist your data in a MongoDB Atlas Database.

After cloning the repo and running ionic serve, you'll have a really simple task management web application. You can register (using any user/password combination, Realm takes care of your onboarding needs). You can log in, have a look at your tasks, and add new tasks.

Login in the Web App	Browsing Tasks

Let’s build on what the Ionic team created for the web, and expand it by building a mobile app for iOS and Android using one of the best features Ionic has: the “Write Once, Run Anywhere” approach to coding. I’ll start with an iOS app.

Prerequisites

To follow along this post, you’ll need five things:

A macOS-powered computer running Xcode (to develop for iOS). I’m using Xcode 13 Beta. You don’t have to risk your sanity.
Ionic installed. You can follow the instructions here, but TL;DR it’s npm install -g @ionic/cli
Clone the repo with the Ionic React Web App that we’ll turn into mobile.
As we need an Atlas Database to store our data in the cloud, and a Realm app to make it easy to work with Atlas from mobile, set up a Free Forever MongoDB cluster and create and import a Realm app schema so everything is ready server-side.
Once you have your Realm app created, copy the Realm app ID from the MongoDB admin interface for Realm, and paste it into src/App.tsx, in the line:

export const APP_ID = '<Put your Realm App Id here>';

Once your APP_ID is set, run:

$ npm run build

The iOS app

To add iOS capabilities to our existing app, we need to open a terminal and run:

$ ionic cap add ios

This will create the iOS Xcode Project native developers know and love, with the code from our Ionic app. I ran into a problem doing that and it was that the version of Capacitor used in the repo was 3.1.2, but for iOS, I needed at least 3.2.0. So, I just changed package.json and ran npm install to update Capacitor.

package.json fragment:

...
"dependencies": {

    "@apollo/client": "^3.4.5",
    "@capacitor/android": "3.2.2",
    "@capacitor/app": "1.0.2",
    "@capacitor/core": "3.2.0",
    "@capacitor/haptics": "1.0.2",
    "@capacitor/ios": "3.2.2",
...

Now we have a new ios directory. If we enter that folder, we’ll see an App directory that has a CocoaPods-powered iOS app. To run this iOS app, we need to:

Change to that directory with cd ios. You’ll find an App directory. cd App
Install all CocoaPods with pod repo update && pod install, as usual in a native iOS project. This updates all libraries’ caches for CocoaPods and then installs the required libraries and dependencies in your project.
Open the generated App.xcworkspace file with Xcode. From Terminal, you can just type open App.xcworkspace.
Run the app from Xcode.

Login in the iOS App	Browsing Tasks

That’s it. Apart from updating Capacitor, we only needed to run one command to get our Ionic web project running on iOS!

The Android App

How hard can it be to build our Ionic app for Android now that we have done it for iOS? Well, it turns out to be super-simple. Just cd back to the root of the project and type in a terminal:

 ionic cap android

This will create the Android project. Once has finished, launch your app using:

ionic capacitor run android -l --host=10.0.1.81

In this case, 10.0.1.81 is my own IP address. As you can see, if you have more than one Emulator or even a plugged-in Android phone, you can select where you want to run the Ionic app.

Once running, you can register, log in, and add tasks in Android, just like you can do in the web and iOS apps.

Adding a task in Android	Browsing Tasks in Android

The best part is that thanks to the synchronization happening in the MongoDB Realm app, every time we add a new task locally, it gets uploaded to the cloud to a MongoDB Atlas database behind the scenes. And all other apps accessing the same MongoDB Realm app can show that data!

Automatically refreshing tasks

Realm SDKs are well known for their syncing capabilities. You change something in the server, or in one app, and other users with access to the same data will see the changes almost immediately. You don’t have to worry about invalidating caches, writing complex networking/multithreading code that runs in the background, listening to silent push notifications, etc. MongoDB Realm takes care of all that for you.

But in this example, we access data using the Apollo GraphQL Client for React. Using this client, we can log into our Realm app and run GraphQL Queries—although as designed for the web, we don’t have access to the hard drive to store a .realm file. It’s just a simpler way to use the otherwise awesome Apollo GraphQL Client with Realm, so we don’t have synchronization implemented. But luckily, Apollo GraphQL queries can automatically refresh themselves just passing a pollInterval argument. I told you it was awesome. You set the time interval in milliseconds to refresh the data.

So, in useTasks.ts, our function to get all tasks will look like this, auto-refreshing our data every half second.

function useAllTasksInProject(project: any) {
 const { data, loading, error } = useQuery(
   gql`
     query GetAllTasksForProject($partition: String!) {
       tasks(query: { _partition: $partition }) {
         _id
         name
         status
       }
     }
   `,
   { variables: { partition: project.partition }, pollInterval: 500 }
 );
 if (error) {
   throw new Error(`Failed to fetch tasks: ${error.message}`);
 }

 // If the query has finished, return the tasks from the result data
 // Otherwise, return an empty list
 const tasks = data?.tasks ?? [];
 return { tasks, loading };
}

Pull to refresh

Adding automatic refresh is nice, but in mobile apps, we’re used to also refreshing lists of data just by pulling them. To get this, we’ll need to add the Ionic component IonRefresher to our Home component:

<IonPage>
     <IonHeader>
       <IonToolbar>
         <IonTitle>Tasks</IonTitle>
         <IonButtons slot="end">
           <IonButton onClick={addNewTask}>
             <IonIcon slot="icon-only" icon={add}></IonIcon>
           </IonButton>
         </IonButtons>
       </IonToolbar>
     </IonHeader>
     <IonContent fullscreen>
       <IonRefresher slot="fixed" onIonRefresh={doRefresh}>
         <IonRefresherContent></IonRefresherContent>
       </IonRefresher>
       <IonHeader collapse="condense">
         <IonToolbar>
           <IonTitle size="large">Tasks</IonTitle>
         </IonToolbar>
       </IonHeader>
       <IonList>
         {loading ? <IonLoading isOpen={loading} /> : null}
         {tasks.map((task: any) => (
           <TaskItem key={parseInt(task._id)} {...task}></TaskItem>
         ))}
       </IonList>
     </IonContent>
   </IonPage>

As we can see, an IonRefresher component will add the pull-to-refresh functionality with an included loading indicator tailored for each platform.

<IonRefresher slot="fixed" onIonRefresh={doRefresh}>
   <IonRefresherContent></IonRefresherContent>
</IonRefresher>

To refresh, we call doRefresh and there, we just reload the whole page.

 const doRefresh = (event: CustomEvent<RefresherEventDetail>) => {
   window.location.reload(); // reload the whole page
   event.detail.complete();  // we signal the loading indicator to hide
 };

Deleting tasks

Right now, we can swipe tasks from right to left to change the status of our tasks. But I wanted to also add a left to right swipe so we can delete tasks. We just need to add the swiping control to the already existing IonItemSliding control. In this case, we want a swipe from the start of the control. This way, we avoid any ambiguities with right-to-left vs. left-to-right languages. When the user taps on the new “Delete” button (which will appear red as we’re using the danger color), deleteTaskSelected is called.

<IonItemSliding ref={slidingRef} className={'status-' + task.status}>
     <IonItem>
       <IonLabel>{task.name}</IonLabel>
     </IonItem>
     <IonItemOptions side="end">
       <IonItemOption onClick={toggleStatus}>Status</IonItemOption>
     </IonItemOptions>
     <IonItemOptions side="start">
       <IonItemOption onClick={deleteTaskSelected} color="danger">Delete</IonItemOption>
     </IonItemOptions>
   </IonItemSliding>

To delete the task, we use a GraphQL mutation defined in useTaskMutations.ts:

const deleteTaskSelected = () => {
   slidingRef.current?.close();  // close sliding menu
   deleteTask(task);             // delete task
 };

Recap

In this post, we’ve seen how easy it is to start with an Ionic React web application and, with only a few lines of code, turn it into a mobile app running on iOS and Android. Then, we easily added some functionality to the three apps at the same time. Ionic makes it super simple to run your Realm-powered apps everywhere!

You can check out the code from this post in this branch of the repo, just by typing:

$ git clone https://github.com/mongodb-developer/ionic-realm-demo
$ git checkout observe-changes

But this is not the only way to integrate Realm in your Ionic apps. Using Capacitor and our native SDKs, we’ll show you how to use Realm from Ionic in a future follow-up post.

DEV Community: Diego Freniche

Using Expo and Realm with expo-dev-client

Creating a React Native app using Expo and Realm in one simple step

Adding our own code

Putting our new custom development client to work

Now do Hermes and react-native-reanimated

Recap

One more thing

Continuously Building and Hosting our Swift DocC Documentation using Github Actions and Netlify

What’s in a DocC bundle?

Automating generation of our DocC archive using GitHub Actions

Getting the latest version of our code

Building out our documentation archive

Find where the doccarchive has been generated

Copy our documentation to a place where it can be served online

Hosting our DocC archives in Netlify

Recap

Build an Offline-First React Native Mobile App with Expo and Realm

Introduction

React Native Apps

Expo and React Native

Prerequisites

MongoDB Atlas and Realm App

Read It Later - Maybe

Install Expo and create the App

Running our iOS App

Expo Go

Structure of our App

Let’s add some navigation

Adding the Realm Library

Installing Realm

Auth Provider

Login / Register code

Prebuilding our Expo App

Navigation completed

Log out

Links

CRUD

Showing Links

UI for deleting Links

UI for adding Links

Adding Links in the main App

The final App

Recap

Let’s Give Your Realm-Powered Ionic Web App the Native Treatment on iOS and Android!

Prerequisites

The iOS app

The Android App

Automatically refreshing tasks

Pull to refresh

Deleting tasks

Recap

Find where the `doccarchive` has been generated