Getting Started

Web applications require a lot of boilerplate. It's also hard to know how to get started without examples. We offer both server side rendered (SSR) and client side rendered (CSR) solutions that can be bootstrapped and tailored to your current project with just one command.

Oh, and they come complete with infrastructure as code so you can deploy on your cloud of choice.

Brilliant.

Bootstrap your framework

The best way to get started, is bootstrap the framework using the scaffolding-cli from Amido Stacks. By using it in interactive mode, you can simply answered 5 questions to get a bespoke framework, ready to go with an example test.

Run to start configuring your solution
npx @amidostacks/scaffolding-cli run -i

Get developing in just a few questions

Environment Variables

Before you can start developing you will need to replace your environment variables with the appropriated values. This values will be automatically picked up and used by the underlying server and web client.

NODE_ENV=development
PORT=3000
APP_BASE_URL=http://localhost
APP_BASE_PATH=""
export NODE_ENV=development
export PORT=3000
export APP_BASE_URL=http://localhost
export APP_BASE_PATH=""

Configure Optional Features

Auth0
Contentful
API

Get developing

Install dependencies (this may take a while, please be patient):

npm install

Compile the app:

npm run build

At the end of bootstrapping your example framework, you will have an output that will contain all the:

  • dependencies
  • scripts
  • example tests
  • pipelines
  • and information to start testing

Development

If you like to view the github repository , the source code can be found here https://github.com/amido/stacks-webapp-template/tree/master/packages/scaffolding-cli/templates/src/ssr

Move to the <PROJECT-NAME>/src folder and run the next commands

npm install
npm run dev
To run locally
npm run start

This offers live reload of both server side - when using ssr - and client side code.

Production

Move to the <PROJECT-NAME>/src folder and run the next commands

npm install
npm run build
npm run start

This will start the app in production mode, so you can see how it would behave deployed!

Implementation details

The template is a Server Side Rendered (SSR) implementation using:

To build and run using Docker

In order to be able to build and run the webapp template, across environments and as part of CI, we need to use Docker.

Build from the webapp directory
docker build ../ -f ./Dockerfile -t stacks-app

Run it:

docker run --rm -it -p 3000:3000 stacks-app
docker run --rm -it -v $(pwd):/app/deployed/src stacks-app:latest /bin/sh
docker run --rm -it -v $(pwd):/usr/src sonarsource/sonar-scanner-cli
docker run --rm -it -p 3000:3000 stacks-app:latest /bin/sh

Alternatives to running in a container

CMD ["pm2-runtime", "--json", "./ecosystem.yml", "--exp-backoff-restart-delay=500", "-a", "--update-env"]

Dockerfile Notes

Best practice guidelines:

  • Do not run app under root
    • To maximise cache layer capacity we should copy over package.json into /tmp and build there

Testing

Unit, Component and Snapshot Testing

We are using Jest for running all unit, component, integration and snapshot tests. Jest supports TypeScript via Babel. Because TypeScript support in Babel is transpilation, to ensure that Jest will type-check the tests as they are run we use ts-jest.

To help that encourage good testing practices for React DOM testing, we are leveraging a helper library react-testing-library.

npm run test: To run all unit tests. This will also run any snapshot tests. Snapshots are to be checked in and are found under the source code. __tests__/__snapshots__

For more information using Cypress, see: [Testing and Quality]https://stacks.amido.com/docs/testing/cypress_functional_testing).

Visual Testing

For more information using Applitools with Cypress, see: Testing and Quality.

Accessibility Testing

For more information using Axe with Jest and Cypress, see: Testing and Quality.

Static Testing

For more information about the running using amidostacks/ci-sonarscanner, please refer to: amidostacks/ci-sonarscanner

For general information about setting up and using SonarQube for static analysis, please refer to the docs/test_static_code

Consumer driven contract testing with Pact

Please refer to the very verbose documentation in /__tests__/pact/README.md

Customizing

Since the frameworks provide real examples on deployed applications, we recommend using these as examples and then replacing them with your own applications under test.

Feedback

As always, we only improve from the incredible feedback and contributions from people like you. To help us improve, see our contribution guide for more information.