docs: Updated for next release

CHANGELOG.md

@@ -1,46 +1,29 @@
 # @simondotm/nx-firebase Changelog
 
-All notable changes to this project will be documented in this file.
+* **Nx badges** for each release indicate the Nx version the plugin was built against, and the minimum required version of Nx to use the plugin. Each plugin release may be with earlier or future versions of Nx, but this is not always guaranteed.
 
-This plugin was completely rewritten since V2.x to use esbuild for bundling cloud functions. For documentation of the legacy v1.x plugin version see [here](https://github.com/simondotm/nx-firebase/tree/release/v1.1.0).
+* **Node badges** for each release indicate the Node version the plugin was built against, and the default engine set for Firebase functions generated by the plugin, not the node version required to use the plugin.
+
+## v2.3.0 ![nx](https://img.shields.io/badge/Nx-v16.8.1-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
+
+- TODO
 
-- [@simondotm/nx-firebase Changelog](#simondotmnx-firebase-changelog)
-  - [v2.2.0](#v220)
-  - [v2.1.2](#v212)
-  - [v2.1.1](#v211)
-  - [v2.1.0](#v210)
-  - [v2.0.0](#v200)
-  - [v2.0.0-beta.1](#v200-beta1)
-  - [v2.0.0-beta.0](#v200-beta0)
-  - [v1.1.0](#v110)
-  - [v1.1.0-beta.0](#v110-beta0)
-  - [v1.0.0](#v100)
-  - [v0.13.0-beta.1](#v0130-beta1)
-  - [v0.13.0-beta.0](#v0130-beta0)
-  - [v0.3.4](#v034)
-  - [v0.3.3](#v033)
-  - [v0.3.2](#v032)
-  - [v0.3.1](#v031)
-  - [v0.3.0](#v030)
-  - [v0.2.3](#v023)
-  - [v0.2.2 - Initial Release](#v022---initial-release)
-
-## v2.2.0
+## v2.2.0 ![nx](https://img.shields.io/badge/Nx-v16.6.0-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 - Fix package dependencies for `@nx/node`, plugin init generator now adds this if/when needed
 - This prevents scenarios where incorrect Nx plugin versions could be added to the user workspace
 - It may also fix an issue with `@nx/esbuild` plugin version being out of sync and bundling external dependencies incorrectly
 
-## v2.1.2
+## v2.1.2 ![nx](https://img.shields.io/badge/Nx-v16.6.0-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 - Include `@nx/devkit` as a peer dependency for the package
 - Listing in the [Nx plugin registry](https://nx.dev/plugin-registry)
 
-## v2.1.1
+## v2.1.1 ![nx](https://img.shields.io/badge/Nx-v16.6.0-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 - Fix issues in the v2.1.0 release
 
-## v2.1.0
+## v2.1.0 ![nx](https://img.shields.io/badge/Nx-v16.6.0-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 - Added support for [environment variables](docs/nx-firebase-functions-environment.md)
 - Added support for [secrets](docs/nx-firebase-functions-environment.md#environment-file-types)
@@ -49,26 +32,24 @@ This plugin was completely rewritten since V2.x to use esbuild for bundling clou
 - Added a custom `migrate` generator to ensure workspace configurations match the latest plugin version schemas
 - Updated plugin to be built against Nx 16.6.0
 
-## v2.0.0
+Read [here for plugin v2.0.0 -> v2.1.0+ migration instructions](docs/nx-firebase-migrations.md#migrating-from-plugin-v200-to-v210)
+
+## v2.0.0 ![nx](https://img.shields.io/badge/Nx-v16.1.1-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 Official v2 release
 
 - Updated default function template to match firebase CLI
 
-## v2.0.0-beta.1
+## v2.0.0-beta.1 ![nx](https://img.shields.io/badge/Nx-v16.1.1-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 - Fixed issue with dependencies
 - Sort codebases
 - Updated documents
 
-## v2.0.0-beta.0
+## v2.0.0-beta.0 ![nx](https://img.shields.io/badge/Nx-v16.1.1-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 Initial beta of plugin version 2.0.
 
-Users of earlier plugin versions must read [here for plugin v1 -> v2 migration instructions](docs/nx-firebase-migrations.md)
-
-> **Please note that legacy v1 versions of the plugin are no longer supported from this point on, so only take this update if you are prepared to migrate your workspace and Firebase projects**
-
 **Changes**
 
 - Plugin is completely rewritten
@@ -80,23 +61,33 @@ Users of earlier plugin versions must read [here for plugin v1 -> v2 migration i
 - Minimum Nx version is now 16.1.1
 - Watch mode build of function code & libraries is now fully supported when running Firebase emulator
 
-## v1.1.0
+# Version 2
+
+This plugin was completely rewritten since V2.x to use esbuild for bundling cloud functions. For documentation of the legacy v1.x plugin version see [here](https://github.com/simondotm/nx-firebase/tree/release/v1.1.0).
+
+Users of earlier plugin versions must read [here for plugin v1 -> v2 migration instructions](docs/nx-firebase-migrations.md#migration-from-plugin-v1x-to-v200)
+
+> **Please note that legacy v1 versions of the plugin are no longer supported from this point on, so only take this update if you are prepared to migrate your workspace and Firebase projects**
+
+# Version 1
+
+## v1.1.0 ![nx](https://img.shields.io/badge/Nx-v16.1.1-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 No changes from beta.
 
-## v1.1.0-beta.0
+## v1.1.0-beta.0 ![nx](https://img.shields.io/badge/Nx-v16.1.1-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 Updated for Nx 16.1.1+
 
 - You will need to migrate your workspace to Nx 16.1.1 before updating the plugin
 
-## v1.0.0
+## v1.0.0 ![nx](https://img.shields.io/badge/Nx-v13.10.6-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 First Major release. No change since `0.13.0-beta.1`.
 
 Compatible with Nx 13.10.6+
 
-## v0.13.0-beta.1
+## v0.13.0-beta.1 ![nx](https://img.shields.io/badge/Nx-v13.10.6-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 **Changes**
 
@@ -110,7 +101,7 @@ Compatible with Nx 13.10.6+
 - Check the [targets documentation](docs/nx-firebase-targets.md) if you already have a workspace that is using nx-firebase
 - Remove `main` from `package.json` files in any nx-firebase apps in your workspace
 
-## v0.13.0-beta.0
+## v0.13.0-beta.0 ![nx](https://img.shields.io/badge/Nx-v13.10.6-blue) ![nx](https://img.shields.io/badge/Node-v16-orange)
 
 Due to the large number of API changes in Nx from version 12 to version 13.10, this plugin has been rewritten from scratch:
 
@@ -133,7 +124,11 @@ Due to the large number of API changes in Nx from version 12 to version 13.10, t
 
 Recommended minimum version of Nx is now 13.10.6. See [Nx Migration](docs/nx-migration.md) documentation for more information.
 
-## v0.3.4
+## v0.3.13 ![nx](https://img.shields.io/badge/Nx-v13.2.3-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
+
+
+
+## v0.3.4 ![nx](https://img.shields.io/badge/Nx-v13.2.3-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
 
 Interim release fixes for issues introduced in nx version 13.0.2+ where `createProjectGraph` was deprecated.
 
@@ -170,7 +165,7 @@ Nx version migrations below may handle this transition for you, but if not, you
 
 See [Nx Migration](docs/nx-migration.md) documentation for more information.
 
-## v0.3.3
+## v0.3.3 ![nx](https://img.shields.io/badge/Nx-v12.3.4-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
 
 **General changes**
 
@@ -283,7 +278,8 @@ And in your `firebase.<appname>.json` config settings for `"emulators"` add `"au
     }
 ```
 
-## v0.3.2
+## v0.3.2 ![nx](https://img.shields.io/badge/Nx-v12.3.4-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
+
 
 - Plugin now detects incompatible Nx library dependencies and aborts compilation when found
 
@@ -295,14 +291,14 @@ Incompatible dependencies are as follows:
 If either of these two types of libraries are imported by Firebase functions, the compilation will be halted, since a functional app cannot be created with these types of dependencies.
 
 See the [README](README.md#using-nx-libraries-within-nested-sub-directories) for more information.
-
-## v0.3.1
+ 
+## v0.3.1 ![nx](https://img.shields.io/badge/Nx-v12.3.4-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
 
 - Removed undocumented/unusued `firebase` target in app generator. No longer needed.
 
 - `serve` target now builds `--with-deps` before watching to ensure all dependent local libraries are built. Note that `serve` only detects incremental changes to the main application, and not dependent libraries as well at this time.
 
-## v0.3.0
+## v0.3.0 ![nx](https://img.shields.io/badge/Nx-v12.3.4-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
 
 Project has been renamed from `@simondotm/nxfirebase` to `@simondotm/nx-firebase` to better match Nx plugin naming conventions. Took a deep breath and did it early before many installs occurred. Apologies to any users who this may have inconvenienced - I didn't realise I could deprecate packages until after I'd deleted & renamed the pnm project. Rest assured, I won't be making any further major modifications like this!
 
@@ -312,7 +308,7 @@ If you have already generated NxFirebase applications using `@simondotm/nxfireba
 2. `npm install @simondotm/nx-firebase --save-dev`
 3. Update the `builder` targets in any NxFirebase applications you already have in your `workspace.json` or `angular.json` config from `@simondotm/nxfirebase:build` to `@simondotm/nx-firebase:build`
 
-## v0.2.3
+## v0.2.3 ![nx](https://img.shields.io/badge/Nx-v12.3.4-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
 
 Built against Nx 12.3.4
 
@@ -367,6 +363,6 @@ v0.2.3 adds these targets to your `workspace.json` or `angular.json`, so for use
                 },
 ```
 
-## v0.2.2 - Initial Release
+## v0.2.2 - Initial Release ![nx](https://img.shields.io/badge/Nx-v12.1.1-blue) ![nx](https://img.shields.io/badge/Node-v12-orange)
 
 Built against Nx 12.1.1

README.md

@@ -1,70 +1,116 @@
-# @simondotm/nx-firebase
+# @simondotm/nx-firebase ![actions](https://github.com/simondotm/nx-firebase/actions/workflows/ci.yml/badge.svg) ![nx](https://img.shields.io/badge/Nx-v16.8.1-blue) ![npm](https://img.shields.io/npm/v/@simondotm/nx-firebase) ![downloads](https://img.shields.io/npm/dw/@simondotm/nx-firebase.svg)
 
-![npm](https://img.shields.io/npm/dw/@simondotm/nx-firebase.svg)
+A plugin for [Nx](https://nx.dev) v16.8.1+ that integrates Firebase workflows in an Nx monorepo workspace.
 
-A plugin for [Nx](https://nx.dev) v16.8.1+ that provides support for Firebase projects in an Nx monorepo workspace.
+* Easily generate Firebase applications and functions
+* Uses `esbuild` for fast Firebase function builds so you can easily create & import shared Nx libraries with the benefits of tree-shaking
+* Supports function environment variables and secrets
+* Supports single or multiple firebase projects/apps within an Nx workspace
+* Full support for the Firebase Emulator suite for local development, with watch mode for functions
+* Keeps your `firebase.json` configurations in sync when renaming or deleting Firebase apps & functions
+* Only very lightly opinionated about your Firebase configurations and workspace layouts; you can use Nx or the Firebase CLI
 
 See [CHANGELOG](https://github.com/simondotm/nx-firebase/blob/main/CHANGELOG.md) for release notes.
 
-## Overview
+## Install Plugin
 
-Nx provides a great way to manage monorepo workflows and this plugin helps make it easy to integrate Firebase projects with Nx.
+**`npm install @simondotm/nx-firebase --save-dev`**
 
-### Features
+- Installs this plugin into your Nx workspace
+- This will also install `@nx/node` and firebase SDK's to your root workspace `package.json` if they are not already installed
 
-- **Firebase Apps**
-  - Generates Firebase application projects, with default `firebase.json` configurations, rules and indexes for each Firebase app
-- **Firebase Functions**
-  - Generates Firebase function apps based on Typescript Nx node applications
-  - Bundling of Firebase functions using `esbuild` for extremely fast compilation & tree-shaking for optimal function cold starts
-  - Easily import Typescript Nx libraries from your Nx workspace into your Firebase functions for code sharing across projects
-  - Supports function environment variables and secrets
-- **Firebase Features**
-  - Use the Firebase Emulator suite whilst developing locally - all functions are watched and updated live while you work
-  - Use Firebase hosting with Nx to easily build & deploy web apps
-- **Workspace Management**
-  - Nx's automatic dependency checking for no-fuss builds, and per-project or per-function deployments
-  - Supports single or multiple firebase projects/apps within an Nx workspace
-  - Nx workspace management with the `sync` generator keeps your project & `firebase.json` configs automatically updated when renaming or deleting Firebase apps & functions
-  - Only very lightly opinionated about your Firebase configurations and workspace layouts; you can use Nx or the Firebase CLI
+## Generate Firebase Application
 
-# User Guide
+**`nx g @simondotm/nx-firebase:app my-new-firebase-app [--directory=dir] [--project=proj]`**
 
-- **[Quick Start](docs/quick-start.md)**
-- [Migrating to new plugin versions](docs/nx-firebase-migrations.md)
+- Generates a new Nx Firebase application project in the workspace
+- The app generator will also create a Firebase configuration file in the root of your workspace (along with a default `.firebaserc` and `firebase.json` if they don't already exist)
+- For the first firebase application you create, the project firebase configuration will be `firebase.json`
+- If you create additional firebase applications, the project firebase configuration will be `firebase.<app-project-name>.json`
+- Use `--project` to link your Firebase App to a Firebase project name in your `.firebaserc` file
 
-**Nx Firebase Generators**
+## Generate Firebase Function
 
-- [Firebase Applications](docs/nx-firebase-applications.md)
-- [Firebase Functions](docs/nx-firebase-functions.md)
-- [Firebase Functions - Environment Variables](docs/nx-firebase-functions-environment.md)
+**`nx g @simondotm/nx-firebase:function my-new-firebase-function --app=my-new-firebase-app [--directory=dir]`**
 
-**Nx Firebase**
+- Generates a new Nx Firebase function application project in the workspace
+- Firebase Function projects must be linked to a Firebase application project with the `--app` option
+- Firebase Function projects can contain one or more firebase functions
+- You can generate as many Firebase Function projects as you need for your application
 
-- [Firebase Hosting](docs/nx-firebase-hosting.md)
-- [Firebase Emulators](docs/nx-firebase-emulators.md)
-- [Firebase Databases](docs/nx-firebase-databases.md)
-- [Firebase Projects](docs/nx-firebase-projects.md)
+## Build 
 
-**Nx Firebase Workspace Management**
+**`nx build my-new-firebase-app`**
 
-- [Nx-Firebase Sync](docs/nx-firebase-sync.md)
-- [Nx-Firebase Project Schemas](docs/nx-firebase-project-structure.md)
+- Compiles & builds all Firebase function applications linked to the Nx Firebase application or an individual function
 
-**Nx Workspace**
+**`nx build my-new-firebase-function`**
 
-- [Nx Workspace Layout Ideas](docs/nx-workspace-layout.md)
-- [Using Nx Libraries with Firebase Functions](docs/nx-libraries.md)
-- [Migrating an existing Firebase project to Nx](docs/nx-migration.md)
+- Compiles & builds an individual function
 
-**Version information**
 
-- [Firebase Versions](docs/firebase-versions.md)
-- [Nx Versions](docs/nx-versions.md)
+## Serve
 
-_Note: Some of these may not always be upto date - it's hard work keeping track of external releases and compatibilities!_
+**`nx serve my-new-firebase-app`**
 
-**Notes**
+- Builds & Watches all Firebase functions apps linked to the Firebase application
+- Starts the Firebase emulators
 
-- [Plugin Development Notes](docs/nx-plugin-commands.md)
-- [Nx Development Setup for Mac](docs/nx-setup-mac.md)
+## Deploy
+
+### Firebase Application
+
+**`nx deploy my-new-firebase-app [--only ...]`**
+
+- By default, deploys ALL of your cloud resources associated with your Firebase application (eg. sites, functions, database rules etc.)
+- Use the `--only` option to selectively deploy (same as Firebase CLI)
+
+For initial deployment:
+
+- **`firebase login`** if not already authenticated
+- **`firebase use --add`** to add your Firebase Project(s) to the `.firebaserc` file in your workspace. This step must be completed before you can deploy anything to Firebase.
+
+Note that you can also use the firebase CLI directly if you prefer:
+
+- **`firebase deploy --config=firebase.<appname>.json --only functions`**
+
+### Firebase Function
+
+**`nx deploy my-new-firebase-function`**
+
+- Deploys only a specific Firebase function
+
+
+
+## Test
+
+**`nx test my-new-firebase-app`**
+
+- Runs unit tests for all Firebase functions apps linked to the Firebase application
+
+**`nx test my-new-firebase-function`**
+
+- Runs unit tests for an individual function
+
+
+## Lint
+
+**`nx lint my-new-firebase-app`**
+
+- Runs linter for all Firebase functions apps linked to the Firebase application or an individual function
+
+**`nx lint my-new-firebase-function`**
+
+- Runs linter for an individual function
+
+## Sync Workspace
+
+**`nx g @simondotm/nx-firebase:sync`**
+
+- Ensures that your `firebase.json` configurations are kept up to date with your workspace
+  - If you rename or move firebase application or firebase function projects
+  - If you delete firebase function projects
+
+## Further Information
+
+See the full plugin [User Guide](https://github.com/simondotm/nx-firebase/blob/main/docs/user-guide.md) for more details.

docs/nx-firebase-applications.md

@@ -17,6 +17,7 @@ OR
 | `name`            | required | the project name for your firebase app                             |
 | `--directory=dir` | optional | the directory this app will be located in                          |
 | `--project=proj`  | optional | the `--project` option that will be used for firebase CLI commands |
+| `--projectNameAndRootFormat` | optional | `derived` or `as-provided` see [projectNameAndRootFormat](https://nx.dev/nx-api/node/generators/application#projectnameandrootformat) |
 
 ## About Firebase Apps
 
@@ -31,6 +32,7 @@ When a new Nx Firebase application project is generated in the workspace it will
 - Default `database.rules.json` for Firebase realtime database
 - Default `storage.rules` for Firebase storage rules
 - Default `public/index.html` for Firebase hosting - _you can delete this if your firebase configuration for hosting points elsewhere_.
+- Default `public/404.html` for Firebase hosting - _you can delete this if your firebase configuration for hosting points elsewhere_.
 - Default [environment variables](./nx-firebase-functions-environment.md) for your firebase functions
 
 **And in the workspace root:**