@angular/fire 16.0.0-canary.e04cd7f → 16.0.0

package/docs/deploy/getting-started.md

@@ -0,0 +1,204 @@
+# Deploy your application on Firebase Hosting & Functions
+
+In this guide, we'll look at how to use `@angular/fire` to automatically deploy an Angular application to Firebase hosting or functions by using the Angular CLI.
+
+`@angular/fire` uses Firebase functions to deploy your Angular universal projects, with server-side rendering enabled.
+
+**Angular Universal deployments work with `@nguniversal/*` version 9.0.0 and above**.
+
+## Step 1: add `@angular/fire` to your project
+
+First, you need to add the `@angular/fire` package to your project. In your Angular CLI project run:
+
+```shell
+ng add @angular/fire
+```
+
+*Note that the command above assumes you have global Angular CLI installed. To install Angular CLI globally run `npm i -g @angular/cli`.*
+
+First, the command above will check if you have an Angular universal project. It'll do so by looking at your `angular.json` project, looking for a `server` target for the specified project. If it finds one, it'll ask you if you want to deploy the project in a firebase function.
+
+After that it will trigger the `@angular/fire` `ng-add` schematics. The schematics will open a web browser and guide you through the Firebase authentication flow (if you're not signed in already). After you authenticate, you'll see a prompt to select a Firebase hosting project.
+
+The schematics will do the following:
+
+- Add `@angular/fire` to your list of dependencies
+- Create `firebase.json`, `.firebaserc` files in the root of your workspace. You can use them to configure your firebase hosting deployment. Find more about them [here](https://firebase.google.com/docs/hosting/full-config)
+- Update your workspace file (`angular.json`) by inserting the `deploy` builder
+
+In the end, your `angular.json` project will look like below:
+
+```json5
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "sample-app": {
+      // ...
+      "deploy": {
+        "builder": "@angular/fire:deploy",
+        "options": {} // Here you may find an "ssr": true option if you've
+                      // selected that you want to deploy your Angular universal project
+                      // as a firebase function.
+        }
+      }
+  },
+    // ...
+  "defaultProject": "sample-app"
+  
+}
+```
+
+If you want to add deployment capabilities to a different project in your workspace, you can run:
+
+```
+ng add @angular/fire --project=[PROJECT_NAME]
+```
+
+## Step 2: deploying the project
+
+As the second step, to deploy your project run:
+
+```
+ng deploy --project=[PROJECT_NAME]
+```
+
+*The `--project` option is optional. Learn more [here](https://angular.io/cli/deploy).*
+
+The command above will trigger:
+
+1. Production build of your application
+2. Deployment of the produced assets to the firebase hosting project you selected during `ng add`
+
+If you've specified that you want a server-side rendering enabled deployment in a firebase function, the command will also:
+
+1. Create a firebase function in `dist`, which directly consumes `main.js` from your server output directory.
+2. Create `package.json` for the firebase function with the required dependencies.
+3. Deploy the static assets to firebase hosting and your universal server as a Firebase function.
+
+If you want to preview your Angular Universal project before we deploy it as a Firebase Function you can run:
+
+```
+ng deploy --preview
+```
+
+We'll create the function and a `package.json` in your project output directory. This way, you can later run `firebase serve` in your project root so you can test everything before deploying.
+
+## Step 3: customization
+
+To customize the deployment flow, you can use the configuration files you're already familiar with from `firebase-tools`. You can find more in the [firebase documentation](https://firebase.google.com/docs/hosting/full-config).
+
+### Configuring Cloud Functions
+
+Setting `functionsNodeVersion` and `functionsRuntimeOptions` in your `angular.json` allow you to customize the version of Node.js Cloud Functions is running and run-time settings like timeout, VPC connectors, and memory.
+
+```json
+"deploy": {
+    "builder": "@angular/fire:deploy",
+    "options": {
+        "functionsNodeVersion": 12,
+        "functionsRuntimeOptions": {
+          "memory": "2GB",
+          "timeoutSeconds": 10,
+          "vpcConnector": "my-vpc-connector",
+          "vpcConnectorEgressSettings": "PRIVATE_RANGES_ONLY"
+        }
+    }
+}
+```
+
+### Working with multiple Firebase Projects
+
+If you have multiple build targets and deploy targets, it is possible to specify them in your `angular.json` or `workspace.json`.
+
+It is possible to use either your project name or project alias in `firebaseProject`. The setting provided here is equivalent to passing a project name or alias to `firebase deploy --project projectNameOrAlias`.
+
+The `buildTarget` simply points to an existing build configuration for your project. Most projects have a default configuration and a production configuration (commonly activated by using the `--prod` flag) but it is possible to specify as many build configurations as needed.
+
+You may specify a `buildTarget` and `firebaseProject` in your `options` as follows:
+
+```json
+"deploy": {
+    "builder": "@angular/fire:deploy",
+    "options": {
+        "buildTarget": "projectName:build",
+        "firebaseProject": "developmentProject"
+    },
+    "configurations": {
+        "production": {
+            "buildTarget": "projectName:build:production",
+            "firebaseProject": "productionProject"
+        }
+    }
+}
+```
+
+The above configuration specifies the following:
+
+1. `ng deploy` will deploy the default project with default configuration.
+2. `ng deploy projectName` will deploy the specified project with default configuration.
+3. `ng deploy projectName --prod` or `ng deploy projectName --configuration='production'` will deploy `projectName` with production build settings to your production environment.
+
+All of the options are optional. If you do not specify a `buildTarget`, it defaults to a production build (`projectName:build:production`). If you do not specify a `firebaseProject`, it defaults to the first matching deploy target found in your `.firebaserc` (where your projectName is the same as your Firebase deploy target name). The `configurations` section is also optional.
+
+### Working with multiple project sites
+
+For example, if you have muti sites config in firebase.json like this:
+```
+{
+  "hosting": [
+    {
+      "target": "custom-site",
+      "public": "public/my-custom-site",
+      "ignore": [
+        "firebase.json",
+        "**/.*",
+        "**/node_modules/**"
+      ],
+      "rewrites": [
+        {
+          "source": "**",
+          "destination": "/index.html"
+        }
+      ]
+    }
+  ],
+```
+
+If you have multiple build targets and deploy targets, it is possible to specify them in your `angular.json` or `workspace.json`.
+
+It is possible to use either your project name or project alias in `siteTarget`.
+
+You may specify a `siteTarget` in your `options` as follows:
+
+```json
+"deploy": {
+    "builder": "@angular/fire:deploy",
+    "options": {
+        "buildTarget": "projectName:build",
+        "firebaseProject": "developmentProject",
+        "siteTarget": "yourDefaultSiteTarget"
+    },
+    "configurations": {
+        "production": {
+            "buildTarget": "projectName:build:production",
+            "firebaseProject": "productionProject",
+            "siteTarget": "yourProdSiteTarget"
+        },
+        "storybook": {
+            "buildTarget": "projectName:build-storybook",
+            "firebaseProject": "developmentProject",
+            "siteTarget": "yourStorybookSiteTarget"
+        }
+    }
+}
+```
+
+The above configuration specifies the following:
+
+1. `ng deploy` will deploy the default project with default configuration.
+2. `ng deploy projectName` will deploy the specified project with default configuration.
+3. `ng deploy projectName --configuration=storybook --siteTarget=mySiteTarget` will deploy `projectName` to `mySiteTarget` with configuration`storybook`.
+
+All of the options are optional

package/docs/firebase.json

@@ -0,0 +1,16 @@
+{
+  "firebase": "angular-fire-2",
+  "public": ".",
+  "redirects": [
+    {
+      "source": "/",
+      "destination": "/api",
+      "type": 302
+    }
+  ],
+  "ignore": [
+    "firebase.json",
+    "**/.*",
+    "**/node_modules/**"
+  ]
+}

package/docs/firestore.md

@@ -0,0 +1,148 @@
+<img align="right" width="30%" src="images/firestore-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 Firestore
+</small>
+
+# Cloud Firestore
+
+Cloud Firestore is a flexible, scalable NoSQL database for mobile, web, and server development from Firebase and Google Cloud. It keeps your data in sync across client apps through realtime listeners and offers offline support for mobile and web so you can build responsive apps that work regardless of network latency or Internet connectivity. 
+
+[Learn more](https://firebase.google.com/docs/firestore)
+
+Cloud Firestore is the API that gives your application access to your database in the cloud or locally in your [emulator](https://firebase.google.com/docs/emulator-suite).
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+Provide a Firestore instance in the application's `NgModule` (`app.module.ts`):
+
+```typescript
+@NgModule({
+  declarations: [
+    ...
+  ],
+  imports: [
+    ...
+    // App initialization
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideFirestore(() => getFirestore())
+  ],
+  providers: [],
+  bootstrap: [AppComponent]
+})
+export class AppModule { }
+```
+
+
+In your component class, for example `user-profile.component.ts` import and inject `Firestore`:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { Firestore } from '@angular/fire/firestore';
+
+@Component({
+    standalone: true,
+    selector: 'app-user-profile',
+    ...
+})
+export class UserProfileComponent {
+    private firestore: Firestore = inject(Firestore);
+    ...
+}
+```
+
+## Firebase API
+With the reference to Cloud Firestore available in a component it is now possible to connect read from and write to the database.
+
+### Reading data
+In Cloud Firestore data is stored in `documents` and `documents` are stored in `collections`. The path to data follows `<collection_name>/<document_id>` and continues if there are subcollections. For example, `"users/ABC12345/posts/XYZ6789"` represents:
+* `users` collection
+* document id `ABC12345`
+* `posts` collection
+* document id `XYZ6789`
+
+
+Let's explore reading data in Angular using the `collection` and `collectionData` functions.
+
+In `user-profile.component.ts`:
+
+```typescript
+import { Firestore, collection, collectionData} from '@angular/fire/firestore';
+import { Component, inject } from '@angular/core';
+
+@Component ({
+    selector: 'app-user-profile',
+    standalone: true,
+    ...
+})
+export class UserProfileComponent {
+    private firestore: Firestore = inject(Firestore); // inject Cloud Firestore
+    users$: Observable<UserProfile[]>;
+
+    constructor() {
+        // get a reference to the user-profile collection
+        const userProfileCollection = collection(this.firestore, 'users');
+
+        // get documents (data) from the collection using collectionData
+        this.users$ = collectionData(userProfileCollection) as Observable<UserProfile[]>;
+    }
+}
+export Interface UserProfile {
+    username: string;
+}
+```
+`collectionData` returns an `observable` that can we can use to display the data in the template. In `user-profile.component.html`:
+
+```html
+    <section>
+        <h1>User Profiles</h1>
+        <ul>
+            <li *ngFor="let user of users$ | async">
+                {{user.username}}
+            </li>
+        </ul>
+    </section>
+```
+
+The `async` pipe handles unsubscribing from observables.
+
+### Writing data
+To write to Cloud Firestore use the `addDoc` function. It will create a new document at the path specified by the collection. In `user-profile.component.ts`, we'll update the code to add a new document on a `<button>` click.
+
+
+```typescript
+import { Firestore, collection, collectionData, addDoc} from '@angular/fire/firestore';
+import { Component, inject } from '@angular/core';
+
+@Component ({
+    selector: 'app-user-profile',
+    standalone: true,
+    ...
+})
+export class UserProfileComponent {
+    private firestore: Firestore = inject(Firestore); // inject Cloud Firestore
+    users$: Observable<UserProfile[]>;
+    usersCollection: CollectionReference;
+    
+    constructor() {...}
+
+    addUserProfile(username: string) {
+        if (!username) return;
+
+        addDoc(this.usersCollection, <UserProfile> { username }).then((documentReference: DocumentReference) => {
+            // the documentReference provides access to the newly created document
+        });
+    }
+}
+export Interface UserProfile {
+    username: string;
+}
+```
+In the `addUserProfile` method we use a reference to the `this.usersCollection` and provide `UserProfile` data to the the `addDoc` function. `addDoc` returns a promise that can be used to respond to the successful addition of the data. Errors can also be caught here.
+
+## Learn More
+More information on API methods and other functions can be found on the [Firebase Official Docs](https://firebase.google.com/docs/reference/js/firestore_)

package/docs/functions.md

@@ -0,0 +1,52 @@
+<img align="right" width="30%" src="images/functions-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 Functions
+</small>
+
+# Cloud Functions
+
+The Cloud Functions for Firebase client SDKs let you call functions directly from a Firebase app. To call a function from your app in this way, write and deploy an HTTPS Callable function in Cloud Functions, and then add client logic to call the function from your app.
+
+[Learn More](https://firebase.google.com/docs/functions/get-started)
+
+## Dependency Injection
+
+As a prerequisite, ensure that `AngularFire` has been added to your project via
+```bash
+ng add @angular/fire
+```
+
+Provide a Cloud Functions instance in the application's `NgModule` (`app.module.ts`):
+
+```ts
+import { provideFirebaseApp, initializeApp } from '@angular/fire/app';
+import { getFunctions, provideFunctions } from '@angular/fire/functions';
+
+@NgModule({
+  imports: [
+    provideFirebaseApp(() => initializeApp(environment.firebase)),
+    provideFunctions(() => getFunctions()),
+  ]
+})
+```
+
+Next inject it into your component:
+
+```ts
+import { Component, inject} from '@angular/core';
+import { Functions } from '@angular/fire/functions';
+
+@Component({ ... })
+export class AppComponent {
+  private functions: Functions = inject(Functions);
+  ...
+}
+```
+
+## Firebase API
+The [Firebase API for Cloud Functions documentation](https://firebase.google.com/docs/reference/js/functions) is available on the Firebase website.
+
+## Convenience observables
+
+More details coming soon.

package/docs/install-and-setup.md

@@ -0,0 +1,114 @@
+# AngularFire Quickstart
+
+### 1. Create a new project
+
+```bash
+# Using yarn create
+yarn create @angular <project-name>
+cd <project-name>
+```
+or 
+
+```bash
+# Using npm create
+npm create @angular <project-name>
+cd <project-name>
+```
+
+optionally installing the tooling directly:
+```bash
+# Installing the tooling directly
+npm install -g @angular/cli
+ng new <project-name>
+cd <project-name>
+```
+
+The Angular CLI's `new` command will set up the latest Angular build in a new project structure.
+
+### 2. Install AngularFire and Firebase
+
+```bash
+ng add @angular/fire
+```
+
+Now that you have a new project setup, install AngularFire and Firebase from npm. This will complete the following tasks:
+
+1. Add Firebase config to environments variables
+2. Configure `@NgModule` for the `AngularFireModule`
+
+### 3. Inject `Firestore`
+
+Open `/src/app/app.component.ts`, and make the following changes to :
+
+```ts
+import { Component, inject } from '@angular/core';
+import { Firestore } from '@angular/fire/firestore';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: 'app.component.html',
+  styleUrls: ['app.component.css']
+})
+export class AppComponent {
+  firestore: Firestore = inject(Firestore);
+
+  constructor() {
+
+  }
+}
+```
+
+### 4. Bind a Firestore collection to a list
+
+In `/src/app/app.component.ts`:
+
+```ts
+import { Component, inject } from '@angular/core';
+import { Firestore, collection, collectionData } from '@angular/fire/firestore';
+import { Observable } from 'rxjs';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: 'app.component.html',
+  styleUrls: ['app.component.css']
+})
+export class AppComponent {
+  firestore: Firestore = inject(Firestore)
+  items$: Observable<any[]>;
+
+  constructor() {
+    const aCollection = collection(this.firestore, 'items')
+    this.items$ = collectionData(aCollection);
+  }
+}
+```
+
+Open `/src/app/app.component.html`:
+
+```html
+<ul>
+  <li class="text" *ngFor="let item of items$ | async">
+    {{item.name}}
+  </li>
+</ul>
+```
+
+### 5. Run your app locally
+
+```bash
+ng serve
+```
+
+Your Angular app will compile and serve locally, visit it we should find an empty list.
+
+In another tab [start adding data to an `items` collection in Firestore](https://firebase.google.com/docs/firestore/manage-data/add-data). *As we're not authenticating users yet, be sure to start Firestore in **test mode** or allow reading from the `items` collection in Security Rules (`allow read: if true`).*
+
+Once you've created a `items` collection and are inserting documents, you should find data streaming into your Angular application and being rendered in your browser.
+
+### 6. Deploy your app
+
+Finally, we can deploy the application to Firebase hosting:
+
+```bash
+ng deploy
+```

package/docs/install-angular-cli-windows10.md

@@ -0,0 +1,82 @@
+# Installing Angular CLI on Windows 10
+
+> There had been installation issues of `@angular/cli` on Windows 10 system. Most of the time these errors are related to Python dependencies and node-gyp.
+
+Something as below :
+
+```bash
+execSync@1.0.2 install C:\Users\User\AppData\Roaming\npm\node_modules\angu
+lar-cli\node_modules\angular2-template-loader\node_modules\codecov\node_modules\
+execSync
+ node install.js
+
+[execsync v1.0.2] Attempting to compile native extensions.
+{ [Error: spawn node-gyp ENOENT]
+  code: 'ENOENT',
+  errno: 'ENOENT',
+  syscall: 'spawn node-gyp',
+  path: 'node-gyp',
+  spawnargs: [ 'rebuild' ] }
+[execSync v1.0.2]
+    Native code compile failed!!
+    Will try to use win32 extension.
+npm WARN deprecated tough-cookie@2.2.2: ReDoS vulnerability parsing Set-Cookie h
+ttps://nodesecurity.io/advisories/130
+npm WARN deprecated minimatch@0.3.0: Please update to minimatch 3.0.2 or higher
+to avoid a RegExp DoS issue
+npm WARN deprecated minimatch@2.0.10: Please update to minimatch 3.0.2 or higher
+ to avoid a RegExp DoS issue
+
+ node-zopfli@2.0.1 install C:\Users\User\AppData\Roaming\npm\node_modules\a
+ngular-cli\node_modules\compression-webpack-plugin\node_modules\node-zopfli
+ node-pre-gyp install --fallback-to-build
+.......................
+```
+
+To resolve this issue, make sure you've upgraded to the latest version of **NPM** and try installing `@angular/cli` again. This seems to have worked on certain scenarios.
+
+If the above doesn't work then the below steps should help. Please ensure all the commands are executed as an **Administrator**.
+
+## Steps:
+
+### 1) Install `node-gyp` from [here](https://github.com/nodejs/node-gyp) using NPM
+
+```bash
+npm install -g node-gyp
+```
+
+### 2) Install Windows build tools from [here](https://github.com/felixrieseberg/windows-build-tools) using NPM
+
+```bash
+npm install --global windows-build-tools
+```
+
+*This will also install Python
+
+### 3) Install Angular CLI
+
+```bash
+npm install -g @angular/cli
+```
+
+This should install `@angular/cli` without errors.
+
+#### Post this installation, follow the installation [guide](https://github.com/angular/angularfire2/blob/master/docs/install-and-setup.md) to install AngularFire and everything should work as expected.
+
+
+### Note:
+
+When you start your app using `ng serve` in the console, you might still see the below errors. Despite these errors, the application should work as expected and should be able to talk to Firebase.
+
+```bash
+ERROR in [default] C:\angularFire2Test\node_modules\angularfire2\interfaces.d.ts:12:34
+Cannot find namespace 'firebase'.
+
+ERROR in [default] C:\angularFire2Test\src\typings.d.ts:6:12
+Subsequent variable declarations must have the same type.  Variable 'require' must be of type 'NodeRequire',
+but here has type 'any'.
+
+ERROR in [default] C:\angularFire2Test\src\typings.d.ts:7:12
+Subsequent variable declarations must have the same type.  Variable 'module' must be of type 'NodeModule',
+but here has type 'any'.
+```