Angular On Fire is more than your average starter project, Angular On Fire gives you a whole development environment with everything you need and minimal configuration.

Angular On Fire puts the best tools on the market into one package, Angular 8 Universal (SSR), RXJS, Firebase, Circle CI, Cypress and Jest, all pre-configured and fully compatible with Angular CLI, so you can get your projects running in no time.

Getting Started

Start by creating a new directory to host your files:

mkdir aof-project
cd aof-project

Now you got a couple of options to choose from:

Download

You can head to Github's Angular On Fire repository, and download and unzip the project in the directory we created above.

Clone

Clone Angular On Fire:

git clone https://github.com/layoutzweb/angular-on-fire.git .

Remember to change your remote url to your own repository url before pushing your code.

Install dependencies

To install all dependencies you must first run from the root:

npm install

and also from the functions directory:

cd functions
npm install

Make sure to navigate back to root for next steps:

cd ../

Run a dev server

While developing locally, no server side rendering is needed, so run a development server using:

npm start

or alternatively ng serve. Navigate to http://localhost:4200/ to see your app running.

Firebase Integration

Angular On Fire is by default built to work with Firebase services, out of the box it uses:

• Hosting: This is where the client application will be served from
• Cloud Functions: Hosts our server application, allowing for server side rendered pages. You can extend this integration with any Firebase service that meet your needs as you build your project.

Creating a Firebase Project

If you haven't done so, start by creating a Firebase account here, and follow by creating a new Firebase project, here's a nice video tutorial on how to do that to help you get started.

With your project created, login to Firebase in your console so you can have access to your cloud projects from your local machine:

firebase login

Follow the prompts to complete the authentication of your account. If you plan on integrating with Circle Ci using the default configuration, you will need an extra Firebase project to host your staging application, if so, go ahead and repeat the steps above to create your staging project.

Configure your active project

To deploy or perform any action on your Firebase, you first must select a project, so you don't have to pass --project [MyProjecName] to every command, if you haven't done so, use the Firebase cli command to set it:

firebase use --add

A list with your existing projects will be available on your console, select the name of your project in the list and press enter.

It will then ask you too give your project an alias, since this is the first project you are associating, enter default as the alias.

This will add your project to the .firebaserc file under the default alias and will set it as the active project in the console, this is done so you don't have to pass --project parameter to Firebase commands.

Multiple Environments

The Angular On Fire CI integration comes configured to work with 2 environments, on for production and one for staging, so if you plan on working with the CI workflow, go ahead and repeat the steps to create a new Firebase project to hold your staging environment.

Fore more info on the use command, checkout the Firebase cli reference page here.

Running the Firebase Emulator

Firebase cli provides a great way to test your builds locally before deployments in an environment that emulates the Firebase cloud environment. To do so run the following command from the root of the project:

npm run emulator

This will serve your application in the Firebase dev emulator environment, which is the same as production but with source maps enabled.

Deploying To Firebase

Before you proceed here, make sure you have followed all the steps above to configure your default project, then follow the below steps:

Build for production

npm run build:ssr:prod

This will perform a few steps:

• Build the Angular client application and place in dist/browser
• Build the Angular server application and place it in dist/server
• Build our SSR Express server and place in dist/index.js
• Copy the dist folder to functions/dist to be deployed in our SSR cloud function context

You can also build with the build:ssr:staging command, which will build your project using the staging environment configuration.

Manual Deployment

firebase deploy

This will deploy to Firebase Hosting and Cloud Functions, making your application available at your Firebase project url, which looks something like https://[YOUR PROJECT ID].web.app or your custom domain if you have already configured one.

Automated Deployment

Angular On Fire comes with a default CI pipeline configuration that takes care of deploying to production or staging depending on the tag or branch being merge in. Learn more on how to get your project setup with Circle CI for automated builds and deployment.

Release Automation

Angular On Fire provides a Gulp task to help you automate your release process, it uses Conventional Changelog and Conventional Github Releaser along with other gulp helpers to:

• Bump your project version based on the release type (patch, minor, major, etc..)
• Update your change log with a new release
• Create a release tag based on the updated version
• Push the new release to Github

To perform a release make sure:

• your current branch is set to master
• commit and push any pending changes
• have a Github Personal Access Token in hand, you can create one here.

With the token in hands, run one of the available npm scripts:

npm run release:pre -- --token [YOUR GITHUB TOKEN]

For a pre-release version and tag (0.0.1-1).

npm run release:patch -- --token [YOUR GITHUB TOKEN]

For a patch version and tag (0.0.1).

npm run release:minor -- --token [YOUR GITHUB TOKEN]

For a minor version and tag (0.1.0).

npm run release:major -- --token [YOUR GITHUB TOKEN]

For a major version and tag (1.0.0).

Circle CI Integration

Circle CI is a widely used job runner, it's easy to manage, integrate and they offer a free account so you can get started right away. This will require your project to be hosted on Github, the default Circle CI configuration can be found at .circleci/config.yml.

Follow the below steps to get started with automated deployments.

Create a Circle CI account

If you haven't done so, go ahead and get a Circle CI free account here, you can log in with your github account to make it even easier to configure.

Link your Github Project

Follow the steps to connect your Github account and link your project to Circle Ci.

Configure your CI Firebase Token

In order to build or deploy from a CI environment, you must obtain a Firebase CI token, to do so run the following command in your console:

firebase login:ci

A browser window will pop-up so you can authenticate your Firebase account, once that is done, look in the command line to find your newly generated CI token, keep it open for the next step or save it locally, just don't commit it to your repo.

Head to your Circle CI dashboard, and create the following environment variables:

• FIREBASE_PROD_PROJECT_ID: Your production app id
• FIREBASE_STAGING_PROJECT_ID: Your staging app id
• FIREBASE_CI_TOKEN: The token generated in the previous step

Learn more on setting environment variables in Circle CI.

Branch Strategy

Angular On Fire assumes that 2 branches should exist from the start:

• master: This will be your production, it's where everything that been tested and is ready to be shipped end's up
• next: This is where all your new features will build up to a new release

Commitizen Firendly

To help you keep your repository and commit history looking good, Angular On Fire comes with Commitizen, it is a great tool to standardize commit messages across contributors. To use it, simply change your commit command from:

git commit

to:

git cz

And you will be prompt to choose a few options to construct your commit message, this also contributes to the generation of the changelog, which will breakdown your latest changes into a readable release description. For more information on Commitizen head over to their website.

Branch Protection Rules

Another important step specially when working in teams, is branch protection, you can set rules for branches so pull requests can only be merged if they satisfy your rules.

To get started, head over to your Github repository then click Settings/Branches.

Create a rule for each of your main branches like the image above, and for each of them consider the following options: Require pull request reviews before merging This is only needed if you are working in teams. Require status checks to pass before merging This is needed to make sure code being merged to one of this branches, is only allowed if the status checks passes, you can read more about it here. To start set your required status checks for both branches as following:

• ci/circleci: preload
• ci/circleci: lint
• ci/circleci: build
• ci/circleci: test

There are 3 Circle CI jobs configured:

• test: Job that runs for any PR being merged anywhere
• deploy_staging: Job that runs for any branch being merged to next, includes lint, build & test
• deploy_prod: Job that runs and a release tag is created (should be done from master)

This will make sure that any branch being merged to either master or next pass tests before they are allowed to be merged.

Workflow

Angular On Fire comes with a general workflow in mind, the following steps assumes the following:

• You have already cloned/downloaded the project, install dependencies and you are ready to start coding:
• You have configured your branches as suggested in the Branch Protection Rules step.
• You added your Github repo in Circle CI.

With the above completed, think of your development cycle in 2 phases:

The development phase

• Create a branch from next
• Commit changes to this branch until you are ready to merge
• Create a pull-request to next (not master)
  • If you have configured Circle CI, this should trigger a build/test workflow
  • Do PR reviews here
• Merge PR into next
  • This will trigger a deploy to your Firebase staging project
  • QA team members can validate new features here and approve or deny a deploy

Repeat the above for every change you want to include in the next release.

The deployment phase

Once all changes are merged into next it's time to create a release and push the new code to production:

• Create a pull request from next to master
  • This will also trigger lint/build/test workflow but no deploys
• Merge the PR into master
• Create a new release:
  • This will trigger the production deployment workflow
  • Visit your production url to see your updated application

Unit Tests

Angular On Fire uses Jest to run unit tests, you can start your tests by running:

npm run test

You can writes your tests for any Angular Component/Service/Directive/Pipe just as you would write for a regular Angular project, Jest only runs your tests.

Visit Jest documentation to learn more on how to create and run tests with Jets. Visit the Angular Testing Guide to lerna more about Angular tests.
You can extend your testing tools by using a library like Spectator which provides a simplified way to create Angular tests.

E2E Tests

E2e tests are created and managed with Cypress, to open the cypress console run:

npm run e2e:open

Or if you want to run your tests in headless environment, use:

npm run e2e:run

The latter is much faster as you don't need to wait for the UI to open.

Visit Cypress documentation site for more info on how to create e2e tests with Cypress.

LICENSE

All assets and code are under the The Unlicense and in the public domain unless specified otherwise.

This project is in no way associated with Angular. The assets in src/assets/ are trademarks of their respective companies and are under their terms and license.