Dsch-donedeal-frontend NPM

DoneDeal

Very Important

When running this project, you should never be accessing it via localhost:3000. You should always be accessing it via your local DoneDeal domain. Usually yournamedev.com. Please reach out to a member of the frontend team for clarification if you are not sure.

DoneDeal

Overview

This is the main repo for the DoneDeal shared platform frontend.

Tech Stack

This template is built using React and NextJS with Typescript. Units tests are run using Jest and @testing-library/react, while integration tests use Cypress with mock APIs using Mountebank. Component templates and directory structures are generated using Hygen and can be viewed and developed through Storybook and are styled using styled-components. ES Lint is used for linting and prettier will format code automatically.

Scripts

npm run dev — Spins up the app in dev mode @ http://localhost:3000

npm run storybook — Spins up storybook @ http://localhost:6006

npm run build — Builds a production version of the project

npm run start — Start the app in production mode @ http://localhost:3000. Note: This will not work unless you run npm run build first

npm run start:local — Start the app in production mode @ http://localhost:3000. Note: This will not work unless you run npm run build first. This is needed locally as we do not have a valid cert for https

npm run build-storybook — Builds a static version of Storybook. Generates a folder named storybook-static and builds an index.html in that directory

npm run test — Runs all unit tests once and give an overview of coverage

npm run test:watch — Runs all unit tests in watch mode. Tests wil rerun when the spec file is edited

npm run test:integration Opens Cypress UI where tests can be selected to run, or all integration tests can be run

npm run test:integration:run Runs all integration tests headless, quicker than npm run test:integration but without the UI for debugging

npm run lint-all — Lints the entire project

npm run view-cypress-coverage It will open HTML report for coverage generated by Cypress

npm run view-jest-coverage It will open HTML report for coverage generated by Jest

npm run hygen:toolkit It will run the Hygen toolkit component generator

npm run majestic Runs a nice UI version of Jest

Environment Variables

New Routes

Local Dev

As you will always be working under https://www.yournamedev.com you will need to add a route to Nginx on DoneDeal-Website. To set up a new route you need to:

Create route on Next.js

This can be done via pages directory or if a more complex route is needed you may need to add it to server.ts. Checkout the /*-for-sale/:title/:id route as an example.

Define Route on DoneDeal-Website

Open /docker/services/nginx/src/main/docker/nginx.conf and add your route here.

Search for $new_fe_proxy_pass to see a few examples.

Next once you have saved this you will need to rebuild Nginx.

In the /docker/services/nginx directory run mvn clean install -DskipTests=true

Then test your change:

docker exec -it localdev_nginx_1 nginx -t

Following that restart:

docker exec -it localdev_nginx_1 nginx -s reload

Test and commit

Once you are happy with your change you need to open a pull request with your change on DoneDeal-Website repo. Be sure that your single platform route is also going back to master around the same time to ensure everyone does not loose access to this route locally.

Ninja

Not currently supported.

Staging

For staging you need to define the route in this file and open a pull request. This should be identical to the one you have already tested locally.

Once this has been approved and merged it will updating on staging automatically.

Production

For production you need to define the route in this file and open a pull request. This should be identical to the one you have already tested locally.

Once this has been approved and merged it will updating on staging automatically.

IMPORTANT

Make sure that the single platform app route is live first.
Co-ordinate with SRE/Solutions Architect

Config files

The project has a number of config files which are outlined below:

.babelrc Babel will automatically search for this file in the root directory. This file contains environment presets and plugins for NextJS, TypeScript and styled-components.
jest.config.js This file tells Jest what files to run, in this case, any ts or tsx files with .specin the name. It also indicates which folders should be ignore (e.g. node_modules) and where to collect coverage data from. It also reads the jest.setup.js file which setups up some env variables and imports required packages.
next.config.js Imports required packages, such as next-offline, and sets up environment variables. Webpack custom configuration and middleware setup occurs in this file.
tsconfig.json This file specifies the root files and the TypeScript compiler options required to compile the project.
tsconfig.server.json This file extends tsconfig.json and configures the project for production build.
.eslintrc.js This file extends Unity's @dsch/eslint-rules, which is the lint config that all DSCH projects under Unity should be using. No custom ES Lint configuration should be necessary.

Unit Tests

Important

To ensure that our components inherit the theme correctly you need to wrap every component in a test in the TestWrapper component.

This project usesJest and react testing library (@testing-library/react) for unit testing.

The script npm run test will run all unit tests. You can run npm run test:coverage to run tests and output test coverage.

The script npm run test:watch will run the tests and then watch for changes to tests which it will then run as the changes occur.

Snapshots are generated automatically in the __test__ folder and can be updated by running npm run test -u.

Mocks should be contained in a folder within the component folder called __mocks__. An example of a test and of a mock data can be found in the project.

npm run majestic opens tests in a better UI. Please note sometime this can be a little sluggish but is handy to use all the same.

Integration Tests

Integration tests are run through Cypress, using Mountebank for API responses. The script npm run test:integration will open the Cypress application. The Cypress application UI displays a list of tests, which can be run individually or together. When a test is selected, a Chrome browser if opened and the tests are ran in the browser. The script npm run test:integration:run will run all tests in headless and output the results. Running the tests headless tends to be much faster, especially if there are no failing tests. Check out the cypress folder for tests and themocks directory for mocks.

Storybook

Storybook is use to develop components in isolation before introducing it into the application. The script npm run storybook will open Storybook in the browser at http://localhost:6006 where all the available components should be visible for inspection. Each component should have a __stories__ folder in which all related stories are kept.

Hygen

Hygen is a code generator to create boilerplate and skeleton files to speed up development. We can add new generators for our different types components or modify generators as our components grow and become more complex. Hygen Documentation

To use Hygen:

To use one of our existing generators run npm run hygen:toolkit
- This will run the script from package.json and ask you for a name of the component. Type it in and press enter. This will create a component for you in the toolbox folder with a template for all of the accompanying tests in the following directories:

── components
...
│   └── Toolkit
│       └── HygenTestComponent
│           ├── HygenTestComponent.tsx
│           ├── __stories__
│           │   └── HygenTestComponent.stories.mdx
│           ├── __tests__
│           │   ├── __screenshots__
│           │   │   └── HygenTestComponent
│           │   └── hygenTestComponent.screenshot.tsx
│           └── index.tsx
...

Hygen Demo

Hygen in our code base

_templates/generator is what Hygen uses as base templates to allow us to create generators
_templates/generate-toolkit-component is where our code templates live. We can modify these and add new generators for different types of files, pages, components, etc

── _templates
│   └── generate-toolkit-component
│       └── with-prompt
│           ├── prompt.js
│           ├── toolkitComponent.ejs.t
│           ├── toolkitComponentIndex.ejs.t
│           ├── toolkitComponentScreenshots.ejs.t
│           └── toolkitComponentStories.ejs.t