@angular/fire 16.0.0-canary.e04cd7f → 16.0.0

package/docs/install-firebase-tools.md

@@ -0,0 +1,78 @@
+# Firebase Tools Install and Setup
+
+### 1. Install package
+
+```bash
+npm install -g firebase-tools
+```
+
+or with `yarn`
+
+```bash
+yarn global add firebase-tools
+```
+
+You can also choose to install it as a dependency for your project rather than globally
+
+```bash
+npm install --save-dev firebase-tools
+```
+
+or with `yarn`
+
+```bash
+yarn add -D firebase-tools
+```
+
+### 2. Configure Firebase Tools
+
+In your projects root directory run:
+
+```bash
+firebase init
+```
+
+or if your installed it within your project rather than globally
+
+```bash
+npx firebase init
+```
+
+or with `yarn`
+
+```bash
+yarn firebase init
+```
+
+This will ask you to login if you are not logged in already, the process will take you through a browser
+redirect to log you into Firebase.
+
+### 3. Choose what Firebase features
+
+`firebase-tools` displays Firebase features you want to configure.
+
+```bash
+? Which Firebase features do you want to set up for this directory? Press Space 
+to select features, then Enter to confirm your choices. (Press <space> to select
+, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
+ ◯ Realtime Database: Configure a security rules file for Realtime Database and 
+(optionally) provision default instance
+ ◯ Firestore: Configure security rules and indexes files for Firestore
+ ◯ Functions: Configure a Cloud Functions directory and its files
+ ◯ Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub 
+Action deploys
+ ◯ Hosting: Set up GitHub Action deploys
+(Move up and down to reveal more choices)
+```
+
+### 4. Connect your repo to a Firebase project
+
+The CLI will then walk you through making sure your repo is configured with a Firebase project.
+
+```bash
+? Please select an option: 
+  ◯ Use an existing project 
+  ◯ Create a new project 
+  ◯ Add Firebase to an existing Google Cloud Platform project 
+  ◯ Don't set up a default project
+  ```

package/docs/messaging.md

@@ -0,0 +1,25 @@
+<img align="right" width="30%" src="images/cloud-messaging-illo_1x.png">
+
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Realtime Cloud Messaging
+</small>
+
+# Cloud Messaging
+
+The FCM JavaScript API lets you receive notification messages in web apps running in browsers that support the Push API.
+
+[Learn More](https://firebase.google.com/docs/cloud-messaging/)
+
+## Dependency Injection
+
+YADA YADA YADA
+
+## Firebase API
+
+Something something look at the offical docs
+
+## Convenience observables
+
+### Foo
+
+bar baz

package/docs/performance.md

@@ -0,0 +1,57 @@
+<img align="right" width="30%" src="images/performance-illo_1x.png">
+
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Realtime Performance Monitoring
+</small>
+
+# Performance Monitoring
+
+Firebase Performance Monitoring is a service that helps you to gain insight into the performance characteristics of your Apple, Android, and web apps.
+
+[Learn More](https://firebase.google.com/docs/perf-mon)
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide a Performance instance and configuration in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getPerformance, providePerformance} from '@angular/fire/performance';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    providePerformance(() => getPerformance()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject} from '@angular/core';
+import { Performance } from '@angular/fire/performance';
+
+@Component({ ... })
+export class PerformanceComponent {
+  private performance: Performance = inject(Performance);
+  ...
+}
+```
+
+## Firebase API
+
+The [Performance documentation](https://firebase.google.com/docs/reference/js/performance.md#performance_package) is available on the Firebase website.
+
+## Services
+
+Coming soon.
+
+## Convenience observables
+
+Coming soon.

package/docs/remote-config.md

@@ -0,0 +1,53 @@
+<img align="right" width="30%" src="images/remote-config-illo_1x.png">
+
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Realtime Remote Config
+</small>
+
+# Remote Config
+
+Firebase Remote Config is a cloud service that lets you change the behavior and appearance of your app without requiring users to download an app update.
+
+[Learn More](https://firebase.google.com/docs/remote-config/)
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide a Performance instance and configuration in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getRemoteConfig, provideRemoteConfig} from '@angular/fire/remote-config';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideRemoteConfig(() => getRemoteConfig()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject} from '@angular/core';
+import { RemoteConfig } from '@angular/fire/remote-config';
+
+@Component({ ... })
+export class RemoteConfigComponent {
+  private remoteConfig: RemoteConfig = inject(RemoteConfig);
+  ...
+}
+```
+
+## Firebase API
+
+The [Remote Config documentation](https://firebase.google.com/docs/reference/js/remote-config) is available on the Firebase website.
+
+## Convenience observables
+
+Coming soon.

package/docs/storage.md

@@ -0,0 +1,90 @@
+<img align="right" width="30%" src="images/storage-illo_1x.png">
+
+<small>
+<a href="https://github.com/angular/angularfire">AngularFire</a> &#10097; <a href="../README.md#developer-guide">Developer Guide</a> &#10097; Realtime Cloud Storage
+</small>
+
+# Cloud Storage
+
+Cloud Storage allows developers to upload and share user generated content such as images, video and more. Data is stored in Google Cloud Storage. 
+
+[Learn more](https://firebase.google.com/docs/storage)
+
+## Dependency Injection
+
+AngularFire allows you to work with Firebase Storage via Angular's Dependency Injection.
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide a Firebase Storage instance in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getStorage, provideStorage } from '@angular/fire/storage';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideStorage(() => getStorage()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject} from '@angular/core';
+import { Storage } from '@angular/fire/storage';
+
+@Component({ ... })
+export class StorageComponent {
+  private storage: Storage = inject(Storage);
+  ...
+}
+```
+
+
+## Firebase API
+
+AngularFire wraps the Firebase JS SDK to ensure proper functionality in Angular, while providing the same API.
+
+Update the imports from `import { ... } from 'firebase/storage'` to `import { ... } from '@angular/fire/storage'` and follow the offical documentation.
+
+[Getting Started](https://firebase.google.com/docs/storage/web/start) | [API Reference](https://firebase.google.com/docs/reference/js/storage)
+
+## File Upload Example
+
+```ts
+import { Component, inject } from '@angular/core';
+import { Storage, ref, uploadBytesResumable } from '@angular/fire/storage';
+
+@Component({
+    selector: 'app-storage',
+    template: `
+        <h1>Storage</h1>
+        <label for="fileUpload">Choose a File</label>
+        <input id="fileUpload" type="file" #upload>
+        <button (click)="uploadFile(upload)">Upload</button>
+    `,
+})
+export class StorageComponent {
+    private readonly storage: Storage = inject(Storage);
+
+    uploadFile(input: HTMLInputElement) {
+        if (!input.files) return
+
+        const files: FileList = input.files;
+
+        for (let i = 0; i < files.length; i++) {
+            const file = files.item(i);
+            if (file) {
+                const storageRef = ref(this.storage, file.name);
+                uploadBytesResumable(storageRef, file);
+            }
+        }
+    }
+}
+```

package/docs/universal/cloud-functions.md

@@ -0,0 +1,96 @@
+# Deploying your Universal application on Cloud Functions for Firebase
+
+After [setting up your application with Angular Universal as outlined in Getting Started](getting-started.md), you're now ready to build your application for Firebase Hosting & Cloud Functions.
+
+> Cloud Functions for Firebase lets you automatically run backend code in response to events triggered by Firebase features and HTTPS requests. Your code is stored in Google's cloud and runs in a managed environment. There's no need to manage and scale your own servers. [Learn more about Cloud Functions for Firebase](https://firebase.google.com/docs/functions/).
+
+If you don't already have the Firebase CLI installed, do so:
+
+```bash
+npm i -g firebase-tools
+firebase login
+```
+
+Then inside your project root, setup your Firebase CLI project:
+
+```bash
+firebase init
+```
+
+Configure whichever features you'd want to manage but make sure to select at least `functions` and `hosting`. Choose Typescript for Cloud Functions and use the default `public` directory for Hosting.
+
+After you're configured, you should now see a `firebase.json` file in your project root. Let's add the following `rewrites` directive to it:
+
+```js
+{
+  // ...
+  "hosting": {
+    // ...
+    "rewrites": [
+      { "source": "**", "function": "universal" }
+    ]
+  }
+}
+```
+
+This will inform Firebase Hosting that it should proxy all requests to Cloud Functions, if a file isn't already present in the hosting directory.
+
+Let's go ahead and modify your `package.json` to build for Cloud Functions:
+
+```js
+"scripts": {
+  // ... omitted
+  "build": "ng build && npm run build:ssr && npm run copy:hosting && npm run build:functions",
+  "copy:hosting": "cp -r ./dist/YOUR_PROJECT_NAME/* ./public && rm -f ./public/index.html",
+  "build:functions": "npm run --prefix functions build"
+},
+```
+
+Change the build script in your `functions/package.json` to the following:
+
+```js
+"scripts": {
+    // ... omitted
+    "build": "rm -rf ./dist && cp -r ../dist . && tsc",
+}
+```
+
+You will either need to install the dependencies from the `functions/package.json` or add them to your root `package.json`.
+
+Finally, add the following to your `functions/src/index.ts`:
+
+```ts
+export const universal = functions.https.onRequest((request, response) => {
+  require(`${process.cwd()}/dist/YOUR_PROJECT_NAME/server/main`).app()(request, response);
+});
+```
+
+In the `server.ts` file generated by the Angular CLI ensure that the `index.html` is being read from the correct place.
+
+As of writing the Angular CLI generates:
+
+```typescript
+const indexHtml = existsSync(join(distFolder, 'index.original.html')) ? 'index.original.html' : 'index.html';
+```
+
+this needs to be changed to:
+
+```typescript
+const indexHtml = existsSync(join(distFolder, 'index.original.html')) ? 'index.original.html' : join(distFolder, 'index.html');
+```
+
+So that the `index.html` is read from the correct `dist` folder.
+
+You should now be able to run `npm run build` to build your project for Firebase Hosting and Cloud Functions.
+
+To test, spin up the emulator with `firebase serve`. Once you've confirmed its working go ahead and `firebase deploy`.
+
+_Note: Universal will now SSR your application and serve it, depending on how you have your deployment setup some assets may fail to 
+serve because the Cloud Function is at a different route than the `APP_BASE_REF` configured._
+
+### [Next Step: Prerendering your Universal application](prerendering.md)
+
+## Additional Resources
+
+- [Universal Starter Template](https://github.com/angular/universal-starter)
+- [FireShip: Angular Universal SSR with Firebase](https://fireship.io/lessons/angular-universal-firebase/)

package/docs/universal/getting-started.md

@@ -0,0 +1,28 @@
+# Getting started with AngularFire and Universal
+
+Server-side rendering (SSR) is the process of converting a JavaScript app to plain HTML at request-time, allowing search engine crawlers and linkbots to understand page content reliably. 
+
+## 0. Prerequisites
+
+- @angular/cli >= v6.0
+- @angular/fire >= v5.0.0
+
+## 1. Add Angular Universal to your project
+
+Follow the steps from the [Angular Universal Tutorial](https://angular.io/guide/universal) to add Universal to your
+project.
+
+```
+ng add @nguniversal/express-engine
+```
+
+This will create all the files you need and setup all the configurations for Universal rendering for your application.
+
+## 2. Next Steps
+
+Test your app locally by running `npm run dev:ssr`.
+
+_Note: `dev:ssr` is a command that was added to your `package.json` by the `ng add` command that will run the dev server
+for your Angular with Universal._ 
+
+### [Next Step: Deploying your Universal application on Cloud Functions for Firebase](cloud-functions.md)

package/docs/universal/prerendering.md

@@ -0,0 +1,72 @@
+# Prerendering your Universal application
+
+Prerendering a Universal application allows us to generate the HTML before the user requests it; increasing performance and decreasing cost. Let's configure your application to prerender and staticly serve it's most commonly accessed routes on Firebase Hosting.
+
+First create a `static.paths.js` in your project root, which lists the URLs you'd want to prerender:
+
+```js
+export default [
+    '/',
+    '/another_path',
+    '/yet_another_path'
+];
+```
+
+Let's install `mkdir-recursive` to make the next step a little easier:
+
+```bash
+npm i --save-dev mkdir-recursive
+```
+
+Now replace the listener in your `server.ts` with the following:
+
+```ts
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { renderModuleFactory } from '@angular/platform-server';
+import { mkdirSync } from 'mkdir-recursive';
+
+if (process.env.PRERENDER) {
+
+    const routes = require('./static.paths').default;
+    Promise.all(
+        routes.map(route =>
+            renderModuleFactory(AppServerModuleNgFactory, {
+                document: template,
+                url: route,
+                extraProviders: [
+                    provideModuleMap(LAZY_MODULE_MAP)
+                ]
+            }).then(html => [route, html])
+        )
+    ).then(results => {
+        results.forEach(([route, html]) => {
+            const fullPath = join('./public', route);
+            if (!existsSync(fullPath)) { mkdirSync(fullPath); }
+            writeFileSync(join(fullPath, 'index.html'), html);
+        });
+        process.exit();
+    });
+
+} else if (!process.env.FUNCTION_NAME) {
+
+    // If we're not in the Cloud Functions environment, spin up a Node server
+    const PORT = process.env.PORT || 4000;
+    app.listen(PORT, () => {
+        console.log(`Node server listening on http://localhost:${PORT}`);
+    });
+}
+```
+
+Now if the `PRERENDER` environment variable is passed any value, instead of serving your application it will iterate over the paths in `static.paths.js`, render them, and write them to your `public` directory.  *You could always make this a seperate script.*
+
+Finally make some modifications to your `package.json`, to prerender your content when you build:
+
+```js
+"scripts": {
+  // ... omitted
+  "build": "ng build && npm run copy:hosting && npm run build:functions && npm run prerender:ssr",
+  "prerender:ssr": "PRERENDER=1 node dist/YOUR_PROJECT_NAME-webpack/server.js",
+},
+```
+
+Now when you run `npm run build` the prerendered content should be available in your `/public` directory, ready for deployment on Firebase Hosting.

package/docs/version-4-upgrade.md

@@ -0,0 +1,119 @@
+# Upgrading to AngularFire2 4.0
+
+AngularFire2 4.0 is a refactor of the AngularFire2 package which implements
+@NgModule, simplifies authentication, and better supports Angular 4.
+
+### Removing `AngularFire` for Modularity
+
+Prior to 4.0, AngularFire2 did not take advantage of the Firebase SDK's modularity for tree shaking. The `AngularFire` service has now been removed and the library is broken up into smaller `@NgModule`s:
+
+* `AngularFireModule`
+* `AngularFireDatabaseModule`
+* `AngularFireAuthModule`
+
+When upgrading, replace calls to `AngularFire.database` and `AngularFire.auth` with `AngularFireDatabase` and `AngularFireAuth` respectively.
+
+```typescript
+constructor(af: AngularFire) {
+  af.database.list('foo');
+  af.auth;
+}
+```
+Should now be:
+
+```typescript
+constructor(db: AngularFireDatabase, afAuth: AngularFireAuth) {
+  db.list('foo');
+  afAuth.authState;
+}
+```
+
+### Simplified Authentication API
+
+In 4.0 we've reduced the complexity of the auth module by providing only [`firebase.User`](https://firebase.google.com/docs/reference/js/firebase.User) observers (`AngularFireAuth.authState`, `AngularFireAuth.idToken`) and cutting the methods that were wrapping the Firebase SDK.
+
+
+```typescript
+import { AngularFireAuth } from 'angularfire2/auth';
+// Do not import from 'firebase' as you'd lose the tree shaking benefits
+import firebase from 'firebase/app';
+...
+
+user: Observable<firebase.User>;
+constructor(afAuth: AngularFireAuth) {
+  this.user = afAuth.authState; // only triggered on sign-in/out (for old behavior use .idToken)
+}
+```
+
+AngularFire2 exposes the raw Firebase Auth object via `AngularFireAuth.auth`. For actions like login, logout, user creation, etc. you should use the [methods available to `firebase.auth.Auth`](https://firebase.google.com/docs/reference/js/firebase.auth.Auth).
+
+While convenient, the pre-configured login feature added unneeded complexity. `AngularFireModule.initializeApp` no longer takes a default sign in method. Sign in should be done with the Firebase SDK via `firebase.auth.Auth`:
+
+```typescript
+login() {
+  this.afAuth.auth.signInWithPopup(new firebase.auth.GoogleAuthProvider());
+}
+logout() {
+  this.afAuth.auth.signOut();
+}
+```
+
+### FirebaseListFactory and FirebaseObjectFactory API Changes
+
+If you directly use `FirebaseListFactory` or `FirebaseObjectFactory` you will no longer be able to pass in a string, it will instead expect a Firebase database reference.
+
+## Putting this all together
+
+Here's an example of what AngularFire2 4.0 looks like:
+
+```typescript
+import { NgModule, Component } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+import { AngularFireModule } from 'angularfire2';
+import { AngularFireDatabaseModule, AngularFireDatabase, FirebaseListObservable } from 'angularfire2/database';
+import { AngularFireAuthModule, AngularFireAuth } from 'angularfire2/auth';
+import { environment } from '../environments/environment';
+
+// Do not import from 'firebase' as you'd lose the tree shaking benefits
+import firebase from 'firebase/app';
+
+
+@NgModule({
+  declarations: [ App ],
+  exports: [ App ],
+  imports: [ 
+    AngularFireModule.initializeApp(environment.firebase, 'my-app'),
+    AngularFireDatabaseModule,
+    AngularFireAuthModule
+  ],
+  bootstrap: [ App ]
+})
+export class MyModule { }
+
+```
+
+```typescript
+@Component({
+  selector: 'my-app',
+  template: `
+    <div> {{ (items | async)? | json }} </div>
+    <div> {{ (user | async)? | json }} </div>
+    <button (click)="login()">Login</button>
+    <button (click)="logout()">Logout</button>
+  `
+})
+export class App {
+  user: Observable<firebase.User>;
+  items: FirebaseListObservable<any[]>;
+  constructor(afAuth: AngularFireAuth, db: AngularFireDatabase) {
+    this.user = afAuth.authState;
+    this.items = db.list('items');
+  }
+  login() {
+    this.afAuth.auth.signInWithPopup(new firebase.auth.GoogleAuthProvider());
+  }
+  logout() {
+     this.afAuth.auth.signOut();
+  }
+}
+```