Boilerplate - MERN

Boilerplate project for NodeJS, React based projects in TypeScript. This README documents whatever steps are necessary to get your application up and running.

Table of Contents

• Getting Started
• Configuration
• Integrations
• Deployment
• E2E Testing

Getting Started

Quickstart:

• This project supports running the application with all the required dependencies using docker compose
• Install docker
• Run docker compose -f docker-compose.dev.yml up (Add --build to force rebuild when new dependencies have been added)
• Application should open up automatically. In case it doesn't, go to - http://localhost:3000
• Make required changes for development. Both backend and frontend should hot reload and server restart is not required.

Bonus:

• On running serve, frontend server is at - http://localhost:3000
• On running serve, backend server is at - http://localhost:8080
• To connect to MongoDb server using a client, can use - mongodb://localhost:27017

Pre Requirements:

• Node (v18.17.1) - Download
• MongoDb (v4.4.24) - Download

Scripts:

• Install dependencies - npm install
• Build Project - npm build
• Start Application (without HotReload) - npm start
• Start Application (with HotReload enabled) - npm run serve
  • To disable opening up browser automatically, set WEBPACK_DEV_DISABLE_OPEN to true.
• Run Lint (JavaScript and TypeScript) - npm run lint
• Run Lint (Markdown) - npm run lint:md
• Run E2E tests - npm run e2e
• Open Cypress - npm run cy:open

Configuration

The module uses config for loading configuration entries.

In the config directory:

• Consult/update custom-environment-variables.yml for loading values via environment. This overrides any value set in files defined below.
• Create local.yml for local config.
• Consult/update development.yml for values at development. (The default env)
• Consult/update testing.yml for values at testing. NODE_CONFIG_ENV must be set to testing for this.
• Consult/update staging.yml for values at staging. NODE_CONFIG_ENV must be set to staging for this.
• Consult/update production.yml for values at production. NODE_CONFIG_ENV must be set to production for this.
• Consult/update default.yml for constant values only. Define entries here which will remain same across deployments.

INFO: default.yml config file lists the all available entries which the system uses. For creating a new config entry:

• If the config value tends to change across deployments, provide undefined for the same in default.yml and value should be provided in respective deployment file.
• If the config value is supposed to be same across deployments, provide the same in default.yml.

INFO: local* files allows you to manually provide config during development and are set to be ignored by VCS. Any environment can be overridden locally via:

• local.yml - Overrides everything.
• local-{env}.yml - Overrides only specific env environment.

INFO: Read more about in what order the config entries are loaded here.

INFO: For injecting environment variables, can add .env file in the application root directory.

UI Config:

Config module can be also used to inject configuration values into frontend build. public accepts key value pairs which will all get injected into frontend builds.

• Define the config entry in appropriate config file under public, example - public.myServiceKey. Note that deployment does not supports injecting config values using environment variables so avoid using custom-environment-variables.yml here.
• Use the config value via Config.getConfigValue('myServiceKey')
• For scripts directly using the config from window, can use the config directly via window.Config.myServiceKey. For type safety for the same, can add the entry in src/apps/frontend/types/globals.d.ts.

E2E Testing

Pre Requirements:

Get the application up and running via following steps in Getting Started

Troubleshooting:

If you're running into npm ERR! code ELIFECYCLE npm ERR! err no1 error, follow these steps to fix it:

• sudo npm cache clean -f (force) clear you npm cache
• sudo npm install -g n install n
• sudo n stable upgrade to the current stable version)

For more detailed info, check out this official guide on troubleshooting.

Running specs from the command line:

# run the entire suite
cypress run
  
# run headless chrome
cypress run --headless --browser chrome

# run an individual spec file
cypress run --spec "cypress/e2e/login.spec.cy.ts"

# run all specs within the folder matching the glob (Note: Using double quotes is strongly recommended.
cypress run --spec "cypress/e2e/**/*"

Running specs from the GUI:

1. Open the Cypress Test Runner and click on any types of testing E2E Testing & Component Testing.

cypress run

2. The Cypress Test Runner will open a new window with browser option, select respective browser.

3. The Cypress Test Runner will open a new window with specs, clicking on any spec will execute the test in browser.