1 | [![Build Status](https://travis-ci.org/firebase/firebase-js-sdk.svg?branch=master)](https://travis-ci.org/firebase/firebase-js-sdk)
|
2 |
|
3 | # Firebase - App success made simple
|
4 |
|
5 | ## Overview
|
6 |
|
7 | [Firebase](https://firebase.google.com) provides the tools and infrastructure
|
8 | you need to develop, grow, and earn money from your app. This package supports
|
9 | web (browser), mobile-web, and server (Node.js) clients.
|
10 |
|
11 | For more information, visit:
|
12 |
|
13 | - [Firebase Realtime Database](https://firebase.google.com/docs/database/web/start) -
|
14 | The Firebase Realtime Database lets you store and query user data, and makes
|
15 | it available between users in realtime.
|
16 | - [Cloud Firestore](https://firebase.google.com/docs/firestore/quickstart) -
|
17 | Cloud Firestore is a flexible, scalable database for mobile, web, and server
|
18 | development from Firebase and Google Cloud Platform.
|
19 | - [Firebase Storage](https://firebase.google.com/docs/storage/web/start) -
|
20 | Firebase Storage lets you upload and store user generated content, such as
|
21 | files, and images.
|
22 | - [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/js/client) -
|
23 | Firebase Cloud Messaging is a cross-platform messaging solution that lets you
|
24 | reliably deliver messages at no cost.
|
25 | - [Firebase Authentication](https://firebase.google.com/docs/auth/web/manage-users) -
|
26 | Firebase helps you authenticate and manage users who access your application.
|
27 | - [Create and setup your account](https://firebase.google.com/docs/web/setup) -
|
28 | Get started using Firebase for free.
|
29 |
|
30 | This SDK is intended for end-user client access from environments such as the
|
31 | Web, mobile Web (e.g. React Native, Ionic), Node.js desktop (e.g. Electron), or
|
32 | IoT devices running Node.js. If you are instead interested in using a Node.js
|
33 | SDK which grants you admin access from a privileged environment (like a server),
|
34 | you should use the
|
35 | [Firebase Admin Node.js SDK](https://firebase.google.com/docs/admin/setup/).
|
36 |
|
37 | ## Get the code (browser)
|
38 |
|
39 | ### Script include
|
40 |
|
41 | Include Firebase in your web application via a `<script>` tag:
|
42 |
|
43 | ```html
|
44 | <script src="https://www.gstatic.com/firebasejs/${JSCORE_VERSION}/firebase.js"></script>
|
45 |
|
46 | <script>
|
47 | var app = firebase.initializeApp({
|
48 | apiKey: '<your-api-key>',
|
49 | authDomain: '<your-auth-domain>',
|
50 | databaseURL: '<your-database-url>',
|
51 | projectId: '<your-cloud-firestore-project>',
|
52 | storageBucket: '<your-storage-bucket>',
|
53 | messagingSenderId: '<your-sender-id>'
|
54 | });
|
55 | // ...
|
56 | </script>
|
57 | ```
|
58 |
|
59 | *Note: To get a filled in version of the above code snippet, go to the
|
60 | [Firebase console](https://console.firebase.google.com/) for your app and click on "Add
|
61 | Firebase to your web app".*
|
62 |
|
63 | ### npm bundler (Browserify, Webpack, etc.)
|
64 |
|
65 | The Firebase JavaScript npm package contains code that can be run in the browser
|
66 | after combining the modules you use with a package bundler (e.g.,
|
67 | [Browserify](http://browserify.org/), [Webpack](https://webpack.github.io/)).
|
68 |
|
69 | Install the Firebase npm module:
|
70 |
|
71 | ```
|
72 | $ npm init
|
73 | $ npm install --save firebase
|
74 | ```
|
75 |
|
76 | In your code, you can access Firebase using:
|
77 |
|
78 | ```js
|
79 | var firebase = require('firebase');
|
80 | var app = firebase.initializeApp({ ... });
|
81 | ```
|
82 |
|
83 | If you are using ES6 imports or TypeScript:
|
84 |
|
85 | ```js
|
86 | import * as firebase from 'firebase';
|
87 | var app = firebase.initializeApp({ ... });
|
88 | ```
|
89 |
|
90 | ### Include only the features you need
|
91 |
|
92 | The full Firebase JavaScript client includes support for Firebase Authentication, the
|
93 | Firebase Realtime Database, Firebase Storage, and Firebase Cloud Messaging. Including
|
94 | code via the above snippets will pull in all of these features.
|
95 |
|
96 | You can reduce the amount of code your app uses by just including the features
|
97 | you need. The individually installable services are:
|
98 |
|
99 | - `firebase-app` - The core `firebase` client (required).
|
100 | - `firebase-auth` - Firebase Authentication (optional).
|
101 | - `firebase-database` - The Firebase Realtime Database (optional).
|
102 | - `firebase-firestore` - Cloud Firestore (optional).
|
103 | - `firebase-storage` - Firebase Storage (optional).
|
104 | - `firebase-messaging` - Firebase Cloud Messaging (optional).
|
105 | - `firebase-functions` - Firebase Cloud Functions (optional).
|
106 |
|
107 | From the CDN, include the individual services you use (include `firebase-app`
|
108 | first):
|
109 |
|
110 | ```html
|
111 | <script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-app.js"></script>
|
112 | <script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-auth.js"></script>
|
113 | <script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-database.js"></script>
|
114 | <script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-firestore.js"></script>
|
115 | <script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-storage.js"></script>
|
116 | <script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-messaging.js"></script>
|
117 | <script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-functions.js"></script>
|
118 |
|
119 | <script>
|
120 | var app = firebase.initializeApp({ ... });
|
121 | // ...
|
122 | </script>
|
123 | ```
|
124 |
|
125 | When using the firebase npm package, you can `require()` just the services that
|
126 | you use:
|
127 |
|
128 | ```js
|
129 | var firebase = require('firebase/app');
|
130 | require('firebase/auth');
|
131 | require('firebase/database');
|
132 |
|
133 | var app = firebase.initializeApp({ ... });
|
134 | ```
|
135 |
|
136 | If you are using TypeScript with the npm package, you can import just the
|
137 | services you use:
|
138 |
|
139 | ```js
|
140 | // This import loads the firebase namespace along with all its type information.
|
141 | import * as firebase from 'firebase/app';
|
142 |
|
143 | // These imports load individual services into the firebase namespace.
|
144 | import 'firebase/auth';
|
145 | import 'firebase/database';
|
146 | ```
|
147 |
|
148 | _The type information from the import statement will include all of the SDKs,
|
149 | not just the ones you have `required`, so you could get a runtime error if you
|
150 | reference a non-required service._
|
151 |
|
152 | ## Get the code (Node.js - server and command line)
|
153 |
|
154 | ### NPM
|
155 |
|
156 | While you can write entire Firebase applications without any backend code, many
|
157 | developers want to write server applications or command-line utilities using the
|
158 | Node.js JavaScript runtime.
|
159 |
|
160 | You can use the same npm module to use Firebase in the Node.js runtime (on a
|
161 | server or running from the command line):
|
162 |
|
163 | ```
|
164 | $ npm init
|
165 | $ npm install --save firebase
|
166 | ```
|
167 |
|
168 | In your code, you can access Firebase using:
|
169 |
|
170 | ```js
|
171 | var firebase = require('firebase');
|
172 | var app = firebase.initializeApp({ ... });
|
173 | // ...
|
174 | ```
|
175 |
|
176 | If you are using native ES6 module with --experimental-modules flag, you should do:
|
177 |
|
178 | ```js
|
179 | // This import loads the firebase namespace.
|
180 | import firebase from 'firebase/app';
|
181 |
|
182 | // These imports load individual services into the firebase namespace.
|
183 | import 'firebase/auth';
|
184 | import 'firebase/database';
|
185 | ```
|
186 |
|
187 | _Known issue for typescript users with --experimental-modules: you have to set allowSyntheticDefaultImports to true in tsconfig.json to pass the type check. Use it with caution since it makes the assumption that all modules have a default export, which might not be the case for the other dependencies you have. And Your code will break if you try to import the default export from a module that doesn't have default export._
|
188 |
|
189 |
|
190 | Firebase Storage is not included in the server side Firebase npm module.
|
191 | Instead, you can use the
|
192 | [`google-cloud` Node.js client](https://github.com/GoogleCloudPlatform/google-cloud-node).
|
193 |
|
194 | ```
|
195 | $ npm install --save google-cloud
|
196 | ```
|
197 |
|
198 | In your code, you can access your Storage bucket using:
|
199 |
|
200 | ```js
|
201 | var gcloud = require('google-cloud')({ ... });
|
202 | var gcs = gcloud.storage();
|
203 | var bucket = gcs.bucket('<your-firebase-storage-bucket>');
|
204 | ...
|
205 | ```
|
206 |
|
207 | Firebase Cloud Messaging is not included in the server side Firebase npm module.
|
208 | Instead, you can use the
|
209 | [Firebase Cloud Messaging Rest API](https://firebase.google.com/docs/cloud-messaging/send-message).
|
210 |
|
211 | ## API definition
|
212 |
|
213 | If you use the
|
214 | [Closure Compiler](https://developers.google.com/closure/compiler/) or
|
215 | compatible IDE, you can find API definitions for all the Firebase JavaScript API
|
216 | in the included `/externs` directory in this package:
|
217 |
|
218 | ```
|
219 | externs/
|
220 | firebase-app-externs.js
|
221 | firebase-auth-externs.js
|
222 | firebase-database-externs.js
|
223 | firebase-firestore-externs.js
|
224 | firebase-storage-externs.js
|
225 | firebase-messaging-externs.js
|
226 | ```
|
227 |
|
228 | ## Changelog
|
229 |
|
230 | The Firebase changelog can be found at
|
231 | [firebase.google.com](https://firebase.google.com/support/release-notes/js).
|
232 |
|
233 | ## Browser/environment compatibility
|
234 | Please see [Environment Support](https://firebase.google.com/support/guides/environments_js-sdk).
|