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.
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:
You can head to Github's Angular On Fire repository, and download and unzip the project in the directory we created above.
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.
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 ../
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.
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.
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.
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.
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.
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.
Before you proceed here, make sure you have followed all the steps above to configure your default project, then follow the below steps:
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 tofunctions/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.
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.
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.
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 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.
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.
Follow the steps to connect your Github account and link your project to Circle Ci.
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.
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
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.
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.
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:
- Create a branch from
next
- Commit changes to this branch until you are ready to merge
- Create a pull-request to
next
(notmaster
)- 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.
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
tomaster
- 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
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 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.
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.