From c771f8ff7da86a34b7b84acf6f8be662d88f374f Mon Sep 17 00:00:00 2001 From: Simon M Date: Fri, 5 Apr 2024 22:34:07 +0100 Subject: [PATCH] Readme updated --- README.md | 140 ++++++++++++++++++++++----------- docs/quick-start.md | 64 --------------- docs/user-guide.md | 40 ++++++++++ packages/nx-firebase/README.md | 127 +++++++++++++++++++++++++----- 4 files changed, 239 insertions(+), 132 deletions(-) delete mode 100644 docs/quick-start.md create mode 100644 docs/user-guide.md diff --git a/README.md b/README.md index 19dd839..e459081 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,116 @@ -# @simondotm/nx-firebase +# @simondotm/nx-firebase ![Status](https://github.com/simondotm/nx-firebase/actions/workflows/ci.yml/badge.svg) ![Status](https://img.shields.io/badge/Nx-v16.8.1-blue) ![Status](https://img.shields.io/npm/v/@simondotm/nx-firebase) ![npm](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..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..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. \ No newline at end of file diff --git a/docs/quick-start.md b/docs/quick-start.md deleted file mode 100644 index 308305c..0000000 --- a/docs/quick-start.md +++ /dev/null @@ -1,64 +0,0 @@ -# Quick Start - -- [Quick Start](#quick-start) - - [Install Plugin](#install-plugin) - - [Generate Firebase Application Project](#generate-firebase-application-project) - - [Generate Firebase Function Application Project](#generate-firebase-function-application-project) - - [Build Firebase Application](#build-firebase-application) - - [Deploy Firebase Application](#deploy-firebase-application) - - [Serve Firebase Project](#serve-firebase-project) - -## Install Plugin - -**`npm install @simondotm/nx-firebase --save-dev`** - -- Installs this plugin into your Nx workspace. -- This will also install some Nx and firebase dependencies (both for backend and frontend) to your root workspace `package.json` if they are not already installed. -- The plugin is compatible with Nx versions 16.1.1 or above - -## Generate Firebase Application Project - -**`nx g @simondotm/nx-firebase:app [--directory=dir] [--project=proj]`** - -- 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..json`. - -## Generate Firebase Function Application Project - -**`nx g @simondotm/nx-firebase:function --app= [--directory=dir]`** - -- 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 - -## Build Firebase Application - -**`nx build `** - -- Compiles & builds all Firebase function applications linked to the Nx Firebase - -## Deploy Firebase Application - -**`nx deploy [--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 inital 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..json --only functions`** - -## Serve Firebase Project - -**`nx serve `** - -- Builds & Watches all Firebase functions apps linked to the Firebase application -- Starts the Firebase emulators diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 0000000..0b0ab2a --- /dev/null +++ b/docs/user-guide.md @@ -0,0 +1,40 @@ +# User Guide + + +- [Migrating to new plugin versions](./nx-firebase-migrations.md) + +**Nx Firebase Generators** + +- [Firebase Applications](./nx-firebase-applications.md) +- [Firebase Functions](./nx-firebase-functions.md) +- [Firebase Functions - Environment Variables](./nx-firebase-functions-environment.md) + +**Nx Firebase** + +- [Firebase Hosting](./nx-firebase-hosting.md) +- [Firebase Emulators](./nx-firebase-emulators.md) +- [Firebase Databases](./nx-firebase-databases.md) +- [Firebase Projects](./nx-firebase-projects.md) + +**Nx Firebase Workspace Management** + +- [Nx-Firebase Sync](./nx-firebase-sync.md) +- [Nx-Firebase Project Schemas](./nx-firebase-project-structure.md) + +**Nx Workspace** + +- [Nx Workspace Layout Ideas](./nx-workspace-layout.md) +- [Using Nx Libraries with Firebase Functions](./nx-libraries.md) +- [Migrating an existing Firebase project to Nx](./nx-migration.md) + +**Version information** + +- [Firebase Versions](./firebase-versions.md) +- [Nx Versions](./nx-versions.md) + +_Note: Some of these may not always be upto date - it's hard work keeping track of external releases and compatibilities!_ + +**Notes** + +- [Plugin Development Notes](./nx-plugin-commands.md) +- [Nx Development Setup for Mac](./nx-setup-mac.md) \ No newline at end of file diff --git a/packages/nx-firebase/README.md b/packages/nx-firebase/README.md index d98c893..e459081 100644 --- a/packages/nx-firebase/README.md +++ b/packages/nx-firebase/README.md @@ -1,31 +1,116 @@ -# @simondotm/nx-firebase +# @simondotm/nx-firebase ![Status](https://github.com/simondotm/nx-firebase/actions/workflows/ci.yml/badge.svg) ![Status](https://img.shields.io/badge/Nx-v16.8.1-blue) ![Status](https://img.shields.io/npm/v/@simondotm/nx-firebase) ![npm](https://img.shields.io/npm/dw/@simondotm/nx-firebase.svg) -A plugin for [Nx](https://nx.dev) v16.8.1+ that provides support for Firebase projects in an Nx monorepo workspace. +A plugin for [Nx](https://nx.dev) v16.8.1+ that integrates Firebase workflows 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 + +**`npm install @simondotm/nx-firebase --save-dev`** + +- 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 + +## Generate Firebase Application + +**`nx g @simondotm/nx-firebase:app my-new-firebase-app [--directory=dir] [--project=proj]`** + +- 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..json` +- Use `--project` to link your Firebase App to a Firebase project name in your `.firebaserc` file + +## Generate Firebase Function + +**`nx g @simondotm/nx-firebase:function my-new-firebase-function --app=my-new-firebase-app [--directory=dir]`** + +- 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 + +## Build + +**`nx build my-new-firebase-app`** + +- Compiles & builds all Firebase function applications linked to the Nx Firebase application or an individual function + +**`nx build my-new-firebase-function`** + +- Compiles & builds an individual function + + +## Serve + +**`nx serve my-new-firebase-app`** + +- Builds & Watches all Firebase functions apps linked to the Firebase application +- Starts the Firebase emulators + +## 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..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 -Nx provides a great way to manage monorepo workflows and this plugin helps make it easy to integrate Firebase projects with Nx. +## Sync Workspace -### Features +**`nx g @simondotm/nx-firebase:sync`** -- **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 +- 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 [README](https://github.com/simondotm/nx-firebase/blob/main/README.md) for more details. +See the full plugin [User Guide](https://github.com/simondotm/nx-firebase/blob/main/docs/user-guide.md) for more details. \ No newline at end of file