Our current recommendation is to use the React Boilerplate as your frontend boilerplate instead, as it is actively maintained.
Branch | Status |
---|---|
development | |
main |
This project was generated with Angular CLI version 13.0.2
This boilerplate has a wiki which explains the project and its implementation in much greater detail than the code comments.
https://boilerplate-client-angular.shift3sandbox.com/
The AWS configuration for the sandbox is handled by Terraform. Terraform needs the AWS credentials which developers should already have or can access through Zoho Vault. The Terraform configuration is separated into modules for each cloud service it sets up.
Terraform also needs the project secrets saved in project/terraform/terraform.tfvars
with the following structure:
aws_profile = "shift3"
aws_region = "us-west-2"
web_domain_name = ""
Secret | Note |
---|---|
aws_profile | This must match the AWS credentials name on the development machine |
aws_region | This is usually us-west-2 |
web_domain_name | This will be the web domain name for the project, an example may be: example.shift3sandbox.com |
Terraform also needs to update the following key value within main.tf
by replacing
terraform {
backend "s3" {
key = "<project-name>/<environment>/terraform.tfstate"
}
}
Once this is completed, navigate to the terraform folder in your terminal and run the following commands:
terraform init
terraform plan
terraform apply
After provisioning the AWS instance through Terraform, the project environment variables need to be updated with the new server values.
The apiRoute
property in environment.staging.ts
will now need to be filled out with the provisioned sandbox instance.
The package.json
file needs to be updated with the project name and sandbox S3 bucket: "deploy:staging": "ng build --prod --configuration=staging && aws s3 sync ./dist/<PROJECT_DIRECTORY_PATH> s3://<AWS_SANDBOX_URL> --profile shift3 --delete"
Replace the brackets and placeholder values with the project values.
Deploying to AWS requires having AWS credentials on the machine. The script is set to look for a default AWS profile named shift3
. Once the AWS sandbox setup has been taken care of by Terraform, the deployment is done via npm run deploy:staging
.
This project is configured as a template repository. It creates one commit in the new project based on the template instead of the entire original boilerplate history.
If this project is being cloned to start a new project, there are a few things that need to be updated to make it work.
The project name will need to be updated in the README.md
, package.json
, angular.json
, karma.conf.js
, CircleCI config.yml
, app.e2e.spec.ts
, index.html
, app.component.ts
, and app.component.spec.ts
files with the new project name. The README also refers to the boilerplate, both in the text and in the CircleCI badges.
The CODEOWNERS file should be updated to reflect the developers responsible for the project.
The project environment
files will need to be updated with the path to the APIs. The development environment.ts
assumes a local development server of http://localhost:3000
, which might need to be updated.
After provisioning and before deploying, the deploy:staging
script in package.json
needs to be updated, as mentioned above.
This project is configured to use yarn
instead of npm
. yarn
can be installed here and its commands are here. It is significantly faster than npm
. yarn
uses yarn.lock
as its lockfile instead of the package-lock.json
from npm
. yarn.lock
should be committed and kept current in the project just like package-lock.json
would be for a project using npm
.
npm
Instead of yarn
In order to use npm
instead of yarn
, the project needs to be updated in a few areas.
angular.json
specifies yarn
as the package manager on line 5.config.yml
uses yarn
instead of npm
to execute scripts.yarn-lock
file should be deleted and the package-lock.json
file should be committed in its place.This project uses Prettier to enforce code style. It is highly opinionated by design with relatively scant options for customization. The thought process behind it is to ignore personal styling preferences and instead embrace consistency. There are .prettierrc
and .prettierignore
configuration files to adjust some options. Prettier is also wired up to a pre-commit hook. This DOES slightly slow down git, as it runs the hook on staged files every time git commit
is executed.
Prettier can be configured within editors so that it formats files on save, which helps minimize any changes the pre-commit hook would need to make.
This project can be run through Docker (it is not recommended for involved development because it makes it harder to debug the codebase). Running docker-compose up
will configure and serve the project locally. It supports hot reloading. (On Windows, docker-compose
needs access to the drive where the project is located. It should see C:\
by default but other drives need to be added manually: see here, here and here).
To run the unit test or e2e test servers, run docker-compose exec client ng test --watch=false --browsers=ChromeHeadlessDocker
or docker-compose exec client ng e2e --port 4202
respectively while running the above development server.
If you still have more docker questions or are having issues with docker there's a Docker FAQ in the wiki.
This project is configured to work with CircleCI. The CI builds the application, runs tests, and runs the linter. All of these jobs need to pass for the CI build to succeed. The config file is found here. The project name needs to match the new project name for the builds to succeed.
To work with the project directly, the development machine needs Angular CLI installed (which requires node
and npm
). The project has been configured to use yarn
in addition for package dependency management.
The project includes webpack-bundle-analyzer, which helps developers figure out the size of the project and its webpack dependencies. To use it, type npm run build:stats
or yarn run build:stats
in the project's directory in a terminal to create the webpack bundle. Run npm run analyze
or yarn run analyze
, and webpack-bundle-analyzer will launch a server and browser window with a visualization of the project bundle size.
Run ng serve
for a dev server. Navigate to http://localhost:4200/
. The app will automatically reload if you change any of the source files.
Run ng serve --configuration es5
for a dev server that is compatible with IE11. Navigate to http://localhost:4200/
. The app will automatically reload if you change any of the source files.
Run ng generate component component-name
to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module
.
Run ng build
to build the project. The build artifacts will be stored in the dist/
directory. Use the --prod
flag for a production build.
Run npm run build-staging
to build the project. The build artifacts will be stored in the dist/
directory.
Run ng test
to execute the unit tests via Karma.
Run ng e2e
to execute the end-to-end tests via Protractor.
To get more help on the Angular CLI use ng help
or go check out the Angular CLI README.