This package has been deprecated

Author message:

Please use the realm package instead

MongoDB Stitch React Native SDK

The official MongoDB Stitch React Native SDK for JavaScript/TypeScript.

Index

• Documentation
• Discussion
• Installation
• Getting Started

Documentation

• MongoDB Stitch Documentation
• API Reference Manual

Discussion

• MongoDB Stitch Users - Google Group
• MongoDB Stitch Announcements - Google Group

Installation

NPM

Run the following in the root directory of your NPM project.

npm install mongodb-stitch-react-native-sdk

This will start you off with the core SDK functionality as well as the remote MongoDB service.

See Customized Dependencies (Advanced) below for customizing dependencies.

Getting Started

Creating a new app with the SDK (React Native)

Set up an application on Stitch

First, you need to create the server-side Stitch app, and (for the purpose of this quick start) enable anonymous authentication:

1. Go to https://stitch.mongodb.com/ and log in to MongoDB Atlas.
2. Create a new app in your project with your desired name.
3. Go to your app in Stitch via Atlas by clicking Stitch Apps in the left side pane and clicking your app.
4. Copy your app's client app id by going to Clients on the left side pane and clicking copy on the App ID section.
5. Go to Providers from Users in the left side pane and edit and enable "Allow users to log in anonymously".

For detailed instructions, see Create a Stitch App.

Set up a React Native project

Next, you create the source for your client app.

1. Ensure that you have npm installed. See npmjs.com.
2. Follow the instructions in React Native's Getting Started guide to create a basic React Native project.
3. Once in the directory for your new project, add the MongoDB Stitch React Native SDK by running npm install mongodb-stitch-react-native-sdk.
4. Run npm install again to ensure that the SDK's dependencies are properly fetched.
5. In App.js, replace the existing code with the following, replacing <your-client-app-id> with the id you retrieved when setting up the application in MongoDB Stitch:

import React from 'react'
import { Button, StyleSheet, Text, View } from 'react-native';
import { Stitch, AnonymousCredential } from 'mongodb-stitch-react-native-sdk';
 
export default class App extends React.Component {
  constructor(props) {
    super(props);
    this.state={
      currentUserId: undefined,
      client: undefined
    };
    this._loadClient = this._loadClient.bind(this);
    this._onPressLogin = this._onPressLogin.bind(this);
    this._onPressLogout = this._onPressLogout.bind(this);
  }
 
  componentDidMount() {
    this._loadClient();
  }
 
  render() {
    let loginStatus = "Currently logged out."
 
    if(this.state.currentUserId) {
      loginStatus = `Currently logged in as ${this.state.currentUserId}!`
    }
 
    loginButton = <Button
                    onPress={this._onPressLogin}
                    title="Login"/>
 
    logoutButton = <Button
                    onPress={this._onPressLogout}
                    title="Logout"/>
 
    return (
      <View style={styles.container}>
        <Text> {loginStatus} </Text>
        {this.state.currentUserId !== undefined ? logoutButton : loginButton}
      </View>
    );
  }
 
  _loadClient() {
    Stitch.initializeDefaultAppClient('<your-client-app-id>').then(client => {
      this.setState({ client });
 
      if(client.auth.isLoggedIn) {
        this.setState({ currentUserId: client.auth.user.id })
      }
    });
  }
 
  _onPressLogin() {
    this.state.client.auth.loginWithCredential(new AnonymousCredential()).then(user => {
        console.log(`Successfully logged in as user ${user.id}`);
        this.setState({ currentUserId: user.id })
    }).catch(err => {
        console.log(`Failed to log in anonymously: ${err}`);
        this.setState({ currentUserId: undefined })
    });
  }
 
  _onPressLogout() {
    this.state.client.auth.logout().then(user => {
        console.log(`Successfully logged out`);
        this.setState({ currentUserId: undefined })
    }).catch(err => {
        console.log(`Failed to log out: ${err}`);
        this.setState({ currentUserId: undefined })
    });
  }
}
 
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});
 

1. Run the app by running npm start and following the instructions in the terminal.

Using the SDK

Initialize the SDK

When your app has started, use Stitch.initializeDefaultAppClient to initialize the Stitch SDK. Replace <your-client-app-id> with your Stitch application's client app ID:

import { Stitch, AnonymousCredential } from 'mongodb-stitch-react-native-sdk';
 
Stitch.initializeDefaultAppClient('<your-client-app-id>').then(client => {
    // use the client
});

Note: Unlike the other Stitch SDKs, this client initialization method is asynchronous. This is due to the fact that the client stores persisted authentication information using React Native's AsyncStorage system.

Logging In

We enabled anonymous authentication in the steps above, so let's log in with it! Add the following anywhere in your code:

const client = Stitch.defaultAppClient;
 
console.log("logging in anonymously");
client.auth.loginWithCredential(new AnonymousCredential()).then(user => {
  console.log(`logged in anonymously as user ${user.id}`)
});

When running this code, you should see the following in your standard out:

logging in anonymously                                                    	
logged in anonymously as user 58c5d6ebb9ede022a3d75050

See StitchAuth for more information.

Executing a Stitch Function

One of Stitch's powerful features is serverless Functions. Once logged in, the Stitch client can execute remote Stitch Functions using the StitchAppClient.callFunction method:

client.callFunction("echoArg", ["Hello world!"]).then(echoedResult => {
  console.log(`Echoed result: ${echoedResult}`);
})

Assuming you've configured your Stitch application to have a function named "echoArg" that returns its argument, you should see a message like:

Echoed result: Hello world!

The echoArg Function in Stitch would look something like:

// echoArg Function in the Stitch UI
exports = function(arg) {
  return {arg: arg};
};

Using BSON and Extended JSON

As a convenience, the SDK includes the bson library. You can import it as you would import other classes and values from the SDK.

Here is an example of importing BSON to generate a BSON ObjectID:

import { BSON } from 'mongodb-stitch-react-native-sdk';
 
let myObjectId = new BSON.ObjectId();
console.log(`Generated ObjectId: ${myObjectId}`);

Advanced Topics

Customized Dependencies

For customized dependencies, use the following:

 npm install mongodb-stitch-react-native-core
 npm install mongodb-stitch-react-native-services-aws
 npm install mongodb-stitch-react-native-services-http
 npm install mongodb-stitch-react-native-services-mongodb-remote
 npm install mongodb-stitch-react-native-services-twilio

Getting a StitchAppClient without Stitch.getDefaultAppClient (Advanced)

In the case that you don't want a single default initialized StitchAppClient, you can use the following with as many client app IDs as you'd like to initialize clients for multiple app IDs:

const client = Stitch.initializeAppClient("<your-client-app-id>");

You can use the client returned there or anywhere else in your app by using the following:

const client = Stitch.getAppClient("<your-client-app-id>");

Closing the StitchAppClient

The client maintains some background processes in the event loop that must be shutdown when the client is no longer needed. Simply call close on the client when you are done with the client:

client.close();