Repository files navigation

Firestack makes using the latestFirebase straight-forward.

Firestack is alight-weight layer sitting atop the native Firebase libraries for iOS and Android and mirrors the React Native JS api as closely as possible.

For a detailed discussion of how Firestack works as well as how to contribute, check out ourcontribution guide.

• Nearly automatic, rapid setup on Firebase
• Covers lots of awesome features of Firebase:
  • authentication
    • username and password
    • social auth (implemented in conjunction withreact-native-oauth)
      • Facebook
      • Github
      • Google
      • Twitter
  • storage handling
    • upload files
    • download urls
    • download files
  • real-time database
  • presence out-of-the-box
  • analytics
  • Remote configuration
  • FCM (in-progress)
• Redux support built-in (but not required)
• Android and iOS support
• Community supported and professionally backed
• Intended on being as drop-dead simple as possible
• And so much more

We have a working application example available in atfullstackreact/FirestackApp. Check it out for more details about how to use Firestack.

Firebase is awesome and it's combination with the Google Cloud Platform makes it super awesome. Sadly, the latest version of Firebase requires thewindow object. That's where Firestack comes in! Firestack provides a really thin layer that sits on top of the native Firebase SDKs and attempts to use the JavaScript library as much as possible rather than reinventing the wheel.

Gettingreact-native-firestack up and running in your app should be a 2 step process + 1 for each platform.

1. Install thenpm package
2. Link the project withreact-native link react-native-firestack
3. To ensure Android is setup, check yourMainApplication.java for theFirestackPackage() line.

Those steps in more detail:

Install thenpm package with:

npm install react-native-firestack --save

To use Firestack, we'll need to have a development environment that includes the same prerequisites of Firebase.

Unfortunately, due to AppStore restrictions, we currently donot package Firebase libraries in with Firestack. However, the good news is we've automated the process (with many thanks to the Auth0 team for inspiration) of setting up with cocoapods. This will happen automatically upon linking the package withreact-native-cli.

Remember to use theios/[YOUR APP NAME].xcworkspace instead of theios/[YOUR APP NAME].xcproj file from now on.

We need to link the package with our development packaging. We have two options to handle linking:

React native ships with alink command that can be used to link the projects together, which can help automate the process of linking our package environments.

react-native link react-native-firestack

Update the newly installed pods once the linking is done:

cd ios&& pod update --verbose

If you prefer not to usernpm, we can manually link the package together with the following steps, afternpm install:

1. In XCode, right click onLibraries and find theAdd Files to [project name].

2. Add thenode_modules/react-native-firestack/ios/Firestack.xcodeproj

3. Ensure that theBuild Settings of theFirestack.xcodeproj project is ticked toAll and it'sHeader Search Paths include both of the following pathsand are set torecursive:

4. $(SRCROOT)/../../react-native/React

5. $(SRCROOT)/../node_modules/react-native/React

6. ${PROJECT_DIR}/../../../ios/Pods

4. Setting up cocoapods

Since we're dependent upon cocoapods (or at least the Firebase libraries being available at the root project -- i.e. your application), we have to make them available for Firestack to find them.

Using cocoapods is the easiest way to get started with this linking. Add or update aPodfile atios/Podfile in your app with the following:

source'https://github.com/CocoaPods/Specs.git'['Firebase/Core','Firebase/Auth','Firebase/Storage','Firebase/Database','Firebase/RemoteConfig','Firebase/Messaging'].eachdo |lib|podlibendtarget'[project name]'doend# target '[project test name]' do# end

Then you can run(cd ios && pod install) to get the pods opened. If you do use this route, remember to use the.xcworkspace file.

If you don't want to use cocoapods, you don't need to use it! Just make sure you link the Firebase libraries in your project manually. For more information, check out the relevant Firebase docs athttps://firebase.google.com/docs/ios/setup#frameworks.

Full Android support is coming soon, as it currently supports a smaller feature-set than the iOS version. Just as we do with iOS, we'll need to install the library usingnpm and calllink on the library:

react-native link react-native-firestack

Firestack includes the Firebase libraries and will link those directly into our project automatically.

To installreact-native-firestack manually in our project, we'll need to import the package fromio.fullstack.firestack in our project'sandroid/app/src/main/java/com/[app name]/MainApplication.java and list it as a package for ReactNative in thegetPackages() function:

packagecom.appName;// ...importio.fullstack.firestack.FirestackPackage;// ...publicclassMainApplicationextendsApplicationimplementsReactApplication {// ...@OverrideprotectedList<ReactPackage>getPackages() {returnArrays.<ReactPackage>asList(newMainReactPackage(),newFirestackPackage()      );    }  };// ...}

We'll also need to list it in ourandroid/app/build.gradle file as a dependency that we want React Native to compile. In thedependencies listing, add thecompile line:

dependencies {compileproject(':react-native-firestack')}

Add toAndroidManifest.xml file

  <activity android:name="com.facebook.react.devsupport.DevSettingsActivity" />+   <service android:name="io.fullstack.firestack.FirestackMessagingService">+     <intent-filter>+       <action android:name="com.google.firebase.MESSAGING_EVENT"/>+     </intent-filter>+   </service>+   <service android:name="io.fullstack.firestack.FirestackInstanceIdService" android:exported="false">+     <intent-filter>+       <action android:name="com.google.firebase.INSTANCE_ID_EVENT"/>+     </intent-filter>+   </service>

The Firestack library is intended on making it easy to work withFirebase and provides a small native shim to the Firebase native code.

To add Firebase to your project, make sure to create a project in theFirebase console

Each platform uses a different setup method after creating the project.

After creating a Firebase project, click on theAdd Firebase to your iOS app and follow the steps from there to add the configuration file. You donot need to set up a cocoapods project (this is already done through firestack). Make sure not to forget theCopy Files phase in iOS.

Download the Firebase config file and place it in your app directory next to your app source code:

Once you download the configuration file, make sure you place it in the root of your Xcode project. Every different Bundle ID (aka, even different project variants needs their own configuration file).

Lastly, due to some dependencies requirements, Firestack supports iOS versions 8.0 and up. Make sure to update the minimum version of your iOS app to8.0.

There are several ways to setup Firebase on Android. Theeasiest way is to pass the configuration settings in JavaScript. In that way, there is no setup for the native platform.

If you prefer to include the default settings in the source of your app, download thegoogle-services.json file provided by Firebase in theAdd Firebase to Android platform menu in your Firebase configuration console.

Next you'll have to add the google-services gradle plugin in order to parse it.

Add the google-services gradle plugin as a dependency in theproject level build.gradleandroid/build.gradle

buildscript {// ...dependencies {// ...classpath'com.google.gms:google-services:3.0.0'  }}

In your app build.gradle file, add the gradle plugin at the VERY BOTTOM of the file (below all dependencies)android/app/build.gradle

applyplugin:'com.google.gms.google-services'

After creating a Firebase project and installing the library, we can use it in our project by importing the library in our #"auto" data-snippet-clipboard-copy-content="import Firestack from 'react-native-firestack'">

importFirestackfrom'react-native-firestack'

constfirestack=newFirestack();

constconfigurationOptions={debug:true};constfirestack=newFirestack(configurationOptions);firestack.on('debug',msg=>console.log('Received debug message',msg))

API documentation

Authentication

listenForAuth()

firestack.auth.listenForAuth(function(evt){// evt is the authentication event// it contains an `error` key for carrying the// error message in case of an error// and a `user` key upon successful authenticationif(!evt.authenticated){// There was an error or there is no userconsole.error(evt.error)}else{// evt.user contains the user detailsconsole.log('User details',evt.user);}}).then(()=>console.log('Listening for authentication changes'))

unlistenForAuth()

firestack.auth.unlistenForAuth()

createUserWithEmail()

firestack.auth.createUserWithEmail('ari@fullstack.io','123456').then((user)=>{console.log('user created',user)}).catch((err)=>{console.error('An error occurred',err);})

signInWithEmail()

firestack.auth.signInWithEmail('ari@fullstack.io','123456').then((user)=>{console.log('User successfully logged in',user)}).catch((err)=>{console.error('User signin error',err);})

signInWithCustomToken()

firestack.auth.signInWithCustomToken(TOKEN).then((user)=>{console.log('User successfully logged in',user)}).catch((err)=>{console.error('User signin error',err);})

signInWithProvider()

OAuth setup with library

socialLogin with custom Library

var{FBLogin, FBLoginManager}=require('react-native-facebook-login');varLogin=React.createClass({render:function(){return(<FBLoginonLogin={function(data){console.log("Logged in!");console.log(data);lettoken=data.credentials.tokenfirestack.auth.signInWithProvider('facebook',token,'')// facebook need only access token..then((user)=>{console.log(user)})}}/>);}});

reauthenticateWithCredentialForProvider()

updateUserEmail()

firestack.auth.updateUserEmail('ari+rocks@fullstack.io').then((res)=>console.log('Updated user email')).catch(err=>console.error('There was an error updating user email'))

updateUserPassword()

firestack.auth.updateUserPassword('somethingReallyS3cr3t733t').then(res=>console.log('Updated user password')).catch(err=>console.error('There was an error updating your password'))

sendPasswordResetWithEmail()

firestack.auth.sendPasswordResetWithEmail('ari+rocks@fullstack.io').then(res=>console.log('Check your inbox for further instructions')).catch(err=>console.error('There was an error :('))

updateUserProfile()

firestack.auth.updateUserProfile({displayName:'Ari Lerner'}).then(res=>console.log('Your profile has been updated')).catch(err=>console.error('There was an error :('))

deleteUser()

firestack.auth.deleteUser().then(res=>console.log('Sad to see you go')).catch(err=>console.error('There was an error - Now you are trapped!'))

getToken()

firestack.auth.getToken().then(res=>console.log(res.token)).catch(err=>console.error('error'))

signOut()

firestack.auth.signOut().then(res=>console.log('You have been signed out')).catch(err=>console.error('Uh oh... something weird happened'))

getCurrentUser()

firestack.auth.getCurrentUser().then(user=>console.log('The currently logged in user',user)).catch(err=>console.error('An error occurred'))

Analytics

logEventWithName()

firestack.analytics.logEventWithName("launch",{'screen':'Main screen'}).then(res=>console.log('Sent event named launch')).catch(err=>console.error('You should never end up here'));

Storage

setStorageUrl()

firestack.storage.setStorageUrl(`${config.firebase.storageBucket}`)

uploadFile()

firestack.storage.uploadFile(`photos/${auth.user.uid}/${filename}`,path,{contentType:'image/jpeg',contentEncoding:'base64',}).then((res)=>console.log('The file has been uploaded')).catch(err=>console.error('There was an error uploading the file',err))

this.camera.capture().then(({path})=>{firestack.storage.uploadFile(`photos/${auth.user.uid}/${filename}`,path,{contentType:'image/jpeg',contentEncoding:'base64',})}).catch(err=>console.error(err));

<Cameraref={(cam)=>{this.camera=cam;}}captureTarget={Camera.constants.CaptureTarget.temp}style={styles.preview}aspect={Camera.constants.Aspect.fill}><Textstyle={styles.capture}onPress={this.takePicture.bind(this)}>[CAPTURE]</Text></Camera>

takePicture(){this.camera.capture().then(({path})=>{constfilename='photo.jpg'firestack.storage.uploadFile(`photos/${filename}`,path,{contentType:'image/jpeg',contentEncoding:'base64',},(evt)=>{console.log('Got an event in JS',evt);}).then((res)=>{console.log('result from upload file: ',res);}).catch((err)=>{console.log('error happened with uploadFile',err);})}).catch(err=>console.error(err));}

downloadUrl()

conststorageRef=data.firestack.storage.ref('photos/photo.jpg');storageRef.downloadUrl().then(res=>{// res is an object that contains// the `url` as well as the path to the file in `path`})

download()

conststorageRef=data.firestack.storage.ref('photos/photo.jpg');constlocalPath=`downloadedFile.jpg`;storageRef.download(localPath,(msg)=>{// downloading state callback}).then(res=>{// res contains details about the downloaded file}).catch(err=>{// error contains any errors in downloading});

Realtime Database

firebaseApp.database.ref('posts').push().then((res)=>{letnewPostKey=res.key;firebaseApp.ServerValue.then(map=>{constpostData={name:name,timestamp:map.TIMESTAMP,text:this.state.postText,title:this.state.postTitle,puid:newPostKey}letupdates={}updates['/posts/'+newPostKey]=postDatafirebaseApp.database.ref().update(updates).then(()=>{this.setState({postStatus:'Posted! Thank You.',postText:'',});}).catch(()=>{this.setState({postStatus:'Something went wrong!!!'});})})})

firebaseApp.database.ref('posts').orderByChild('timestamp').limitToLast(30).once('value').then((snapshot)=>{this.props.savePosts(snapshot.val())constval=snapshot.val();console.log(val);})

DatabaseRef

Example

functionhandleValueChange(snapshot){if(snapshot.val()){console.log('The list was updated');}}constLIST_KEY='path/to/data';firestack.database.ref(LIST_KEY).on('value',handleValueChange);// Calling `.off` with a reference to the callback function will only remove that specific listener.// This is useful if multiple components are listening and unlistening to the same ref path.firestack.database.ref(LIST_KEY).off('value',handleValueChange);// Calling `.off` without passing the callback function will remove *all* 'value' listeners for that reffirestack.database.ref(LIST_KEY).off('value');

Offline data persistence

firestack.database.setPersistence(true);

constref=firestack.database.ref('chat-messages').child('roomId');ref.keepSynced(true);

Presence

firestack.presence// the presence api.on('users/connections')// set the users/connections as the// root for presence handling.setOnline('auser')// Set the child of auser as online

{online:true,lastOnline:TIMESTAMP}

{online:false,lastOnline:TIMESTAMP}

constpresence=firestack.presence.on('users/connections');presence.onConnect((ref)=>{ref.onDisconnect().remove();// Remove the entry// orref.set({location:someLocation});// or whatever you want as it's called with the database// reference. All methods on the DatabaseRef object are// available here on the `ref`})

ServerValue

consttimestamp=firestack.ServerValue.TIMESTAMP

Cloud Messaging

firestack.cloudMessaging.getToken().then(function(token){console.log('device token',token);});

// add listenerfirestack.cloudMessaging.listenForTokenRefresh(function(token){console.log('refresh device token',token);});// remove listenerfirestack.cloudMessaging.unlistenForTokenRefresh();

firestack.cloudMessaging.subscribeToTopic("topic_name").then(function(topic){console.log('Subscribe:'+topic);}).catch(function(err){console.error(err);});

firestack.cloudMessaging.unsubscribeFromTopic("topic_name").then(function(topic){console.log('unsubscribe:'+topic);}).catch(function(err){console.error(err);});

firestack.cloudMessaging.listenForReceiveNotification((msg)=>{console.log('Receive Messages:'+msg.data);console.log('Receive Messages:'+msg.notification);});

Events

on()

firestack.on('listenForAuth',(evt)=>console.log('Got an event'));

off()

firestack.off('listenForAuth');

FirestackModule

Running with themaster branch

npm install --save react-native-firestack

git clone https://github.com/fullstackreact/react-native-firestack.git ./node_modules/react-native-firestack

git clone https://github.com/fullstackreact/react-native-firestack.git \~/Development/react-native/mine/react-native-firestack/## And rsyncrsync -avhW --delete \      --exclude='node_modules' \      --exclude='.git' \~/Development/react-native/mine/react-native-firestack/ \      ./node_modules/react-native-firestack/

Contributing

TODO

Fullstack React Book