Skip to content

Update README #5214

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Aug 2, 2021
Merged

Update README #5214

Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2615fcf
Update README
hsubox76 Jul 29, 2021
df4078c
Add alternatives
hsubox76 Jul 29, 2021
f330845
Update packages/firebase/README.md
hsubox76 Jul 30, 2021
a587498
Address PR comments, tinker with script includes
hsubox76 Jul 30, 2021
f2869dd
Merge branch 'ch-readme' of https://github.com/firebase/firebase-js-s…
hsubox76 Jul 30, 2021
caef9d5
Update var to const
hsubox76 Jul 30, 2021
ef4e0c9
Add TODO
hsubox76 Aug 2, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 70 additions & 93 deletions packages/firebase/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[![Build Status](https://travis-ci.org/firebase/firebase-js-sdk.svg?branch=master)](https://travis-ci.org/firebase/firebase-js-sdk)
<!-- [![Build Status](https://travis-ci.org/firebase/firebase-js-sdk.svg?branch=master)](https://travis-ci.org/firebase/firebase-js-sdk) -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be deleted?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought that leaving the comment would be a good reminder to put a new badge there if we go through the README in the future and we have a new service by then. I guess it's better to explicitly put a TODO instead.


# Firebase - App success made simple

Expand Down Expand Up @@ -36,16 +36,31 @@ you should use the

## Get the code (browser)

### Script include
>This brings in all Firebase features. See
>["Include only the features you need"](#include-only-the-features-you-need)
>below for
>how to minimize download size by only including the scripts you need.
We recommend only installing the features you need. The individually installable services are:

Include Firebase in your web application via a `<script>` tag:
- `firebase-app` - The core `firebase` client (required).
- `firebase-analytics` - Firebase Analytics (optional).
- `firebase-auth` - Firebase Authentication (optional).
- `firebase-database` - The Firebase Realtime Database (optional).
- `firebase-firestore` - Cloud Firestore (optional).
- `firebase-storage` - Firebase Storage (optional).
- `firebase-messaging` - Firebase Cloud Messaging (optional).
- `firebase-functions` - Firebase Cloud Functions (optional).
- `firebase-remote-config` - Firebase Remote Config (optional).
- `firebase-performance` - Firebase Performance (optional).

### Script include
Include Firebase in your web application via `<script>` tags. Create a script tag for each of the individual services you use (include `firebase-app`
first):

```html
<script src="https://www.gstatic.com/firebasejs/${JSCORE_VERSION}/firebase.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-app.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-auth.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-database.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-firestore.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-storage.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-messaging.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-functions.js"></script>

<script>
var app = firebase.initializeApp({
Expand All @@ -54,7 +69,8 @@ Include Firebase in your web application via a `<script>` tag:
databaseURL: '<your-database-url>',
projectId: '<your-cloud-firestore-project>',
storageBucket: '<your-storage-bucket>',
messagingSenderId: '<your-sender-id>'
messagingSenderId: '<your-sender-id>',
appId: '<your-app-id>'
});
// ...
</script>
Expand All @@ -64,86 +80,31 @@ _Note: To get a filled in version of the above code snippet, go to the
[Firebase console](https://console.firebase.google.com/) for your app and click on "Add
Firebase to your web app"._

### npm bundler (Browserify, Webpack, etc.)

>This brings in all Firebase features. See
>["Include only the features you need"](#include-only-the-features-you-need)
>below for
>how to minimize bundle size by only importing the features you need.

The Firebase JavaScript npm package contains code that can be run in the browser
after combining the modules you use with a package bundler (e.g.,
[Browserify](http://browserify.org/), [Webpack](https://webpack.github.io/)).
#### Alternative - all-in-one import

Install the Firebase npm module:

```
$ npm init
$ npm install --save firebase
```

In your code, you can access Firebase using:

```js
var firebase = require('firebase');
var app = firebase.initializeApp({ ... });
```

If you are using ES6 imports or TypeScript:

```js
import firebase from 'firebase';
var app = firebase.initializeApp({ ... });
```

### Include only the features you need

The full Firebase JavaScript client includes support for Firebase Authentication, the
Firebase Realtime Database, Firebase Storage, and Firebase Cloud Messaging. Including
code via the above snippets will pull in all of these features.

You can reduce the amount of code your app uses by just including the features
you need. The individually installable services are:

- `firebase-app` - The core `firebase` client (required).
- `firebase-auth` - Firebase Authentication (optional).
- `firebase-database` - The Firebase Realtime Database (optional).
- `firebase-firestore` - Cloud Firestore (optional).
- `firebase-storage` - Firebase Storage (optional).
- `firebase-messaging` - Firebase Cloud Messaging (optional).
- `firebase-functions` - Firebase Cloud Functions (optional).
>This brings in all Firebase features. We recommend the method above to
>minimize download size by only including the scripts you need.

From the CDN, include the individual services you use (include `firebase-app`
first):
Include Firebase in your web application via a `<script>` tag:

```html
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-app.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-auth.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-database.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-firestore.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-storage.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-messaging.js"></script>
<script src="https://www.gstatic.com/firebasejs/${FIREBASE_VERSION}/firebase-functions.js"></script>
<script src="https://www.gstatic.com/firebasejs/${JSCORE_VERSION}/firebase.js"></script>

<script>
var app = firebase.initializeApp({ ... });
// ...
</script>
```

When using the firebase npm package, you can `require()` just the services that
you use:
### NPM Bundler (Browserify, Webpack, Rollup, etc.)

```js
var firebase = require('firebase/app');
require('firebase/auth');
require('firebase/database');

var app = firebase.initializeApp({ ... });
Install the Firebase NPM module:
```
$ npm init
$ npm install --save firebase
```

If you are using TypeScript with the npm package, you can import just the
services you use:
In your code, you can import the services you use:

```js
// This import loads the firebase namespace along with all its type information.
Expand All @@ -154,10 +115,41 @@ import 'firebase/auth';
import 'firebase/database';
```

Or if using `require()`:

_We recommend the `.default` import from `firebase/app` in order for
typings to work correctly.
See [release notes for 8.0.0](https://firebase.google.com/support/release-notes/js#version_800_-_october_26_2020)._

```js
var firebase = require('firebase/app').default;
require('firebase/auth');
require('firebase/database');

var app = firebase.initializeApp({ ... });
```

_The type information from the import statement will include all of the SDKs,
not just the ones you have `required`, so you could get a runtime error if you
reference a non-required service._

#### Alternative - all-in-one import

>This brings in all Firebase features. We recommend the method above to
>minimize download size by only including the scripts you need.

```js
// This import loads all Firebase services, whether used in your code or not.
import firebase from 'firebase';
```

Or with `require()`:

```js
// This import loads all Firebase services, whether used in your code or not.
var firebase = require('firebase').default;
```

## Get the code (Node.js - server and command line)

### NPM
Expand All @@ -177,7 +169,9 @@ $ npm install --save firebase
In your code, you can access Firebase using:

```js
var firebase = require('firebase');
var firebase = require('firebase/app').default;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to double check that Node needs the .default too? I vaguely remember maybe not?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, if you want to get typings. Can you also update vars to consts?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated.

require('firebase/auth');
require('firebase/database');
var app = firebase.initializeApp({ ... });
// ...
```
Expand All @@ -196,23 +190,6 @@ import 'firebase/database';

_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._

Firebase Storage is not included in the server side Firebase npm module.
Instead, you can use the
[`google-cloud` Node.js client](https://github.com/GoogleCloudPlatform/google-cloud-node).

```
$ npm install --save google-cloud
```

In your code, you can access your Storage bucket using:

```js
var gcloud = require('google-cloud')({ ... });
var gcs = gcloud.storage();
var bucket = gcs.bucket('<your-firebase-storage-bucket>');
...
```

Firebase Cloud Messaging is not included in the server side Firebase npm module.
Instead, you can use the
[Firebase Cloud Messaging Rest API](https://firebase.google.com/docs/cloud-messaging/send-message).
Expand Down