search

Shift3 / boilerplate-client-angular

The Bitwise standard starting point for new Angular projects
2 stars 0 forks source link
angular boilerplate

readme

Warning! This boilerplate is unmaintained/community maintained at the moment. It lacks other feature supported by our React Boilerplate such as pagination, an updated design, image uploader and others, and may or may not work out the box with our Node Boilerplate backend. The angular boilerplate also has some architectural choices that may be difficult for beginners to grasp.

BoilerplateClientAngular

Our current recommendation is to use the React Boilerplate as your frontend boilerplate instead, as it is actively maintained.

Branch Status
development Shift3
main Shift3

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.

Staging URL

https://boilerplate-client-angular.shift3sandbox.com/

Deployment

Terraform

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 and with actual values:

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:

  1. terraform init
    • This command is used to initialize a working directory containing Terraform configuration files. This is the first command that should be run after writing a new Terraform configuration or cloning an existing one from version control. It is safe to run this command multiple times.
  2. terraform plan
    • The plan command will give you information on what will be built through Terraform, as well as any feedback if there will be forseen issues (missing variables etc.)
    • This also gives you the chance to make adjustments if need be to ensure the output is correct for what you need. (domain name, configurations values for cloud-front etc.)
  3. terraform apply
    • The apply command will actually setup all of the required AWS services to deploy this project. Terraform will save a state file for you, and can continue from where it left off if something goes wrong.

Local Environment

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.

AWS

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.

Development

Template Repository

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.

Initializing the Project

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.

Yarn

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.

How to Use npm Instead of yarn

In order to use npm instead of yarn, the project needs to be updated in a few areas.

Prettier

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.

Docker

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.

CI

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.

Local Development

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.

Webpack Bundle Analyzer

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.

Development server

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.

Development server in IE11

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.

Code scaffolding

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.

Build

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.

Staging Build

Run npm run build-staging to build the project. The build artifacts will be stored in the dist/ directory.

Running unit tests

Run ng test to execute the unit tests via Karma.

Running end-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.