Skip to content

Home

Jump to bottom
Alexey Gurinovich edited this page Sep 24, 2022 · 1 revision

React Universal Boilerplate

react boilerplate
One more version of React Boilerplate written on TypeScript with all potentially needed development ecosystem.

Generally result Application follows Static CSR approach with ability to deploy final build to AWS S3. It is also possible to use own customizable Server and handle rendering there (SSR approach).

OpenVSCode

Boilerplate Guide

💡 Note: This boilerplate also pursues a learning goal. Follow "Note" blocks through the project for some tips. You are also free to use it as a technical specs to add some separate parts, like StoryBook/Cypress/etc. to your project.

  • all potentially customizable parts use {|TEMPLATE|}, just replace it with your values;
  • some customizable parts require additional actions:
    • Snyk usage (sca:{smth}) requires registration (https://snyk.io/) ➡ update {|ORG_NAME|} + authorize with sca:auth;
    • AWS S3 deploy (deploy:s3/storybook:deploy:s3) requires configuring AWS S3 hosting ➡ configure AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY + update {|S3_BUCKET_NAME|} (you can consider AWS alternatives, e.g. AWS Amplify);
    • CircleCI usage requires GitHub project integration + CircleCI Project env variables update (SNYK_TOKEN for Snyk, AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGION for AWS);
  • customize docs with your conventions and strategies, if needed;
  • adapt typography on your own, consider your custom fonts;
  • consider Application BPs ➡ adapt stylelint.config.js 'media-feature-name-value-allowed-list' rule;
  • adapt .vscode settings, if needed;
  • replace favicon with your perfect one;
  • if you don't need some part of application - feel free to remove it. Generally suggestion is to start either with it's run task or with according docs if any;
📖 Example Imagine you don't need UI Components Library (StoryBook). Going through run tasks there are a set of npm run storybook:{smth}.

Checking according tasks in package.json ➡ ./config/storybook configuration is unnecessary ➡ based on configuration all *.stories.@(js|jsx|ts|tsx) files should be removed ➡ remove all mentioned files/folders + clean up unnecessary NPM packages. Additionally update Webpack aliases and ts{js}config.json "paths" field.

  1. Technology Stack
  2. Run tasks
  3. Project structure
  4. Additional documentation
  5. Contribution
  6. License

Technology stack

Project Bundling

Webpack Babel SASS-LoaderPostCSS-LoaderAutoprefixer

💡 Note (TypeScript tranpiling using Babel) Transpiling TypeScript using Babel (with Webpack 'babel-loader', NOT 'ts-loader') was chosen: 1) faster compilation (no types check); 2) having single source of compilation - Babel. 
On the other hand, using Babel compilation results in <b>completely lose of type safety and TypeScript checks</b> during this phase. That's why additional test script (<a href="https://www.typescriptlang.org/docs/handbook/compiler-options.html">tsc</a>) were presented <b>to check as pre-commit(push) hook + in scope of CI/CD</b>.

Application

TypeScript React React-Router ReduxRedux-Saga SCSSCSS-Modules I18n-Next React-Helmet Mobile-Detect

Server

💡 Note: SSR approach only

Express Helmet NodeMon

Code Styling

ESLint StyleLint Prettier

Testing

Unit/Integration Testing

Jest RTL Jest-Axe

E2E Testing

Cypress Cypress-Testing-Library Cypress-Axe

Performance testing

LightHouse-CI

💡 Note (Performance Testing usage) Performance Testing is only set up on CI/CD pipeline level. For manual performance testing you can use Chrome built-in Lighthouse DevTool.

Tests Reports

CodeCov CircleCI-Test-InsightsJest-JUnit

Other

CircleCI AWS-CLI Husky Robots Snyk StoryBook

⬆️ back to top

Run tasks

💡 Note (CSR and SSR approaches) Even though Static CSR approach is used as primary, application is also able to follow SSR approach.

Default CSR approach's Client host port: 1337 (only for development stage) Default SSR approach's Server host port: 3000

CSR approach tasks:

Start:

  • npm start (npm run build:client:and:start:dev) - Client development build task -> start with Webpack Watcher (port 1337)
  • npm run build:client:and:start:prod - Client production build task -> start hosting (using http-server)

Build:

  • npm run build:client - Client general build task (development is default)
  • npm run build:client:dev - Client development build task
  • npm run build:client:prod - Client production build task
  • npm run build:client:prod:pwa - Client production build task (with PWA support)

Deploy:

  • npm run deploy:s3 - Application deploy to AWS S3 task (used for Static Site Hosting)
  • npm run build:and:deploy:s3 - Application production build -> deploy to AWS S3 task (used for Static Site Hosting)

SSR approach tasks:

Start:

  • npm run start:wssr - Server start (Nodemon used to handle restart on change, port 3000)
  • npm run start:wssr:debug - Server start with Debug (Nodemon used to handle restart on change + debug ability, port 3000)

Build:

  • npm run build:client:wssr - SSR Client general build task (development is default)
  • npm run build:client:wssr:dev - SSR Client development build task
  • npm run build:client:wssr:prod - SSR Client production build task
  • npm run build:server - Server general build task (development build used as default)
  • npm run build:server:dev - Server development build task
  • npm run build:server:prod - Server production build task
  • npm run build:app:wssr:dev - Application (Client + Server) development build task
  • npm run build:app:wssr:prod - Application (Client + Server) production build task

General tasks:

  • npm run build:clean - Clean build ("dist") folder

Test:

  • Unit/Integration Testing
    • npm test (npm run test) - run Application Unit/Integration Tests (Common + A11y)
    • npm test:with:reports (npm run test) - run Application Unit/Integration Tests (Common + A11y). Reports (results and coverage) enabled.
    • npm run test:ci - run Application Unit/Integration Tests in CI mode (used for CI/CD pipeline level testing)
    • npm run test:ci:with:reports - run Application Unit/Integration Tests in CI mode (used for CI/CD pipeline level testing). Reports (results and coverage) enabled.
  • E2E Testing
    • npm run test:e2e (npm run test:e2e:dev) - run All (Common + A11y) E2E Tests (development build used)
    • npm run test:e2e:dev:open - open launcher of All (Common + A11y) E2E Tests (development build used)
    • npm run test:e2e:common:prod - run Common E2E Tests (production build used)
    • npm run test:e2e:a11y:prod - run A11y E2E Tests (production build used)
  • Performance Testing
    • npm run test:perf:ci - run Application Performance + Insights testing (Lighthouse CI, user for CI/CD pipeline level testing)
  • TypeScript Types checking
    • npm run test:tsc - run Application Typescript's types checking (no Libraries level checking)

Lint:

  • npm run lint:scripts - lint JS/TS files
  • npm run lint:scripts:fix - lint JS/TS files with autofix
  • npm run lint:styles - lint Styles files
  • npm run lint:styles:fix - lint Styles files with autofix
  • npm run lint - lint all (JS/TS+Styles) files
  • npm run lint:fix - lint all (JS/TS+Styles) files with autofix

Code vulnerabilities scan:

  • npm run sca:test - scan for vulnerabilities for known issues (with disrupting processes) - CI/CD integration
  • npm run sca:test:dev - scan for vulnerabilities for known issues (with disrupting processes), include dev dependencies
  • npm run sca:monitor - scan for vulnerabilities with exposing and storing results snapshot (without disrupting processes)
  • npm run sca:auth - SCA tool (Snyk) authenticate (auth token required)

Components Library maintaining:

  • npm run storybook:start - start Components Library application (localy)
  • npm run storybook:build - build Components Library (dist folder: 'storybook-static')
  • npm run storybook:build:clean - clean Components Library build
  • npm run storybook:deploy:s3 - Components Library deploy to AWS S3 task for (used for Static Site Hosting)
  • npm run storybook:build:and:deploy:s3 - Components Library build -> deploy to AWS S3 task (used for Static Site Hosting)

⬆️ back to top

Project structure

./
│
├───.circleci   // application CI/CD configuration (using CircleCI)
│
├───.github   // GitHub templates for Projects
│
├───.husky   // Git Hooks configuration
│
├───.vscode   // VSCode Workspace configuration (additionally for .editorconfig)
│
├───config   // configurations folder
│   │
│   ├───application
│   │
│   ├───environment
│   │
│   ├───test
│   │   │
│   │   ├───jest   // Unit/Integration Tests configuration folder
│   │   │   │
│   │   │   ├───test-utils   // Testing utils enhancement (e.g. RTL custom "render" util)
│   │   │   │   │
│   │   │   │   ├───custom-utils
│   │   │   │   │
│   │   │   │   │   test-utils.js
│   │   │   │   │   index.js
│   │   │   │   └───
│   │   │   │
│   │   │   │   jest.setupAfterEnv.js   // Jest pre-setup execution (after installed to environment)
│   │   │   │   jest.setup.js   // Jest pre-setup execution (before installed to environment)
│   │   │   └───
│   │   ├───cypress   // E2E Tests configuration folder
│   │   │   │
│   │   │   ├───downloads
│   │   │   │
│   │   │   ├───e2e
│   │   │   │
│   │   │   ├───fixtures
│   │   │   │
│   │   │   ├───support
│   │   │   │
│   │   │   │   cypress.config.a11y.json   // E2E A11y Tests override configuration
│   │   │   │   cypress.config.e2e.json   // E2E General Tests override configuration
│   │   │   └───
│   │   │
│   │   │   cypress.config.js   // E2E Tests (Cypress) main config file
│   │   │   jest.config.js   // Unit/Integration Tests (Jest) main config file
│   │   │   lighthouse.config.js   // Performance Tests main config file (used for CI/CD pipeline)
│   │   └───
│   │
│   ├───lint
│   │   │
│   │   ├───eslint
│   │   │
│   │   └───stylelint
│   │
│   ├───prettier
│   │
│   ├───webpack
│   │   │
│   │   ├───client   // Webpack Client configuration
│   │   │
│   │   ├───helpers
│   │   │   │
│   │   │   ├───loaders   // Webpack loaders (babel-loader, sass-loader, etc.)
│   │   │   │
│   │   │   ├───plugins   // Webpack plugins (Favicon plugin, HTML plugin, etc.)
│   │   │   │
│   │   │   └───resolve   // Webpack resolves (aliases, etc.)
│   │   │
│   │   ├───server   // Webpack Server configuration
│   │   │
│   │   └───storybook   // Webpack Components Library (StoryBook) configuration
│   │
│   ├───storybook   // UI Components Library configuration
│   │   │
│   │   ├───docs
│   │   │
│   │   ├───helpers
│   │   │   │
│   │   │   ├───argTypes   // StoryBook global argTypes and args (e.g. device type)
│   │   │   │
│   │   │   └───decorators   // StoryBook global decorators (e.g. Providers wrapper)
│   │   │
│   │   │   constants.js   // StoryBook sharable constants
│   │   │   main.js   // StoryBook main config file
│   │   │   preview.js   // StoryBook global stories setup (decorators, parameters, args, etc.)
│   │   │   webpack.config.storybook.es5.js   // StoryBook Webpack config loader (use Babel transpiler to provide ES6 Webpack config usage)
│   │   └───
│   │
│   ├───
│   │
│   ├───robots
│   │   │
│   │   │   robots.txt   // Robots configuration to enhance Web crawlers search
│   │   └───
│   │
│   │   README.md   // Config folder info
│   └───
│
├───src
│   │
│   ├───client   // Client source folder (Static CSR or SSR approaches)
│   │   │
│   │   ├───api
│   │   │
│   │   ├───assets
│   │   │   │
│   │   │   ├───fonts
│   │   │   │
│   │   │   └───images
│   │   │
│   │   ├───components   // React components folder
│   │   │   │
│   │   │   ├───base   // base components (Header, Button, Icon, etc.)
│   │   │   │
│   │   │   ├───pages   // general pages components (MainPage, etc.)
│   │   │   │
│   │   │   └───routes   // application routes setup
│   │   │
│   │   ├───reusables
│   │   │   │
│   │   │   ├───custom-hooks
│   │   │   │
│   │   │   ├───hocs
│   │   │   │
│   │   │   │   services-context.tsx   // Services context for components injection using specific Custom Hook/HOC
│   │   │   └───
│   │   │
│   │   ├───store   // Redux's Store
│   │   │   │
│   │   │   ├───middlewares
│   │   │   │
│   │   │   ├───slices
│   │   │   │
│   │   │   │   store.ts   // main Store setup file (used for both CSR and SSR approaches)
│   │   │   │   store.reducer.ts   // main reducer setup file
│   │   │   │   store.saga.ts   // root saga setup file (main init + watch sagas)
│   │   │   └───
│   │   │
│   │   ├───styles   // main styles folder
│   │   │   │
│   │   │   ├───base   // base styles (mixins, functions, variables, etc.)
│   │   │   │
│   │   │   │   main.scss   // main styles file
│   │   │   │   reset-normalize.scss
│   │   │   └───
│   │   │
│   │   │   Application.component.tsx   // main application Component
│   │   │   Application.module.scss   // entry styles file
│   │   │   application.tsx   // main Create App file (used for both CSR and SSR approaches)
│   │   │   index.ts   // Client entry file
│   │   │   README.md   // Client folder info
│   │   └───
│   │
│   ├───common    // common staff which could be potentially used both for Client and Server side
│   │   │
│   │   ├───services    // device detection, i18n, etc.
│   │   │
│   │   ├───utils   // reusable utils
│   │   │
│   │   │   README.md   // Common folder info
│   │   └───
│   │
│   ├───server   // Server source folder (SSR approach)
│   │   │
│   │   ├───api   // Server API router entry folder
│   │   │
│   │   ├───middlewares   // Server custom middlewares (services, app-render for SSR, etc.)
│   │   │
│   │   │   server.ts   // main Server file
│   │   │   index.ts   // Server entry file
│   │   │   README.md   // Server folder info
│   │   └───
│   │
│   │   index.html   // unified HTML template used as index file for Static CSR approach and rendering template for SSR approach
│   └───
│
├───dist
│   │
│   ├───client   // Client dist folder
│   │   │
│   │   ├───assets
│   │   │   │
│   │   │   └───favicons   // favicons collection folder (generated by Webpack Favicon plugin)
│   │   │
│   │   │   index.js   // result Client main js file
│   │   │   [chunk_hash].index.js   // js chunk file
│   │   │   styles.css   // result Client main styles file
│   │   │   index.html   // result HTML file (used as entry for CSR approach OR as template for SSR approach)
│   │   └───
│   │
│   ├───server   // Server dist folder (only for SSR approach)
│   │   │
│   │   │   index.js   // result Server main js file
│   │   │   [chunk_hash].index.js   // js chunk file
│   │   └───
│   └───
│
│   .editorconfig   // editor basic setup for IDE
│   babel.config.js   // Babel configuration
│   jsconfig.json   // JS configuration file for indicating directory root, aliases setup, etc.
│   tsconfig.json   // TS configuration file for indicating basic setup, including directory root, aliases setup, etc.
│   package.json
│   package-lock.json
│   .gitignore
│   LICENSE
│   README.md
└───

⬆️ back to top

Additional documentation

Folders README

Name Description
Config README general configuration setup
Client README major source of truth for Static CSR approach, also used for SSR approach
Common README application common staff (services, utils) which could be used both on Client and Server
Server README server main folder, used only for SSR approach

Project Docs

Name Description
Branching Strategy & CI/CD Project's branching strategy info and CI/CD approach description
TypeScript Project's TypeScript usage details and general Code Convention
SSR Project's SSR approach explanation (workflow, HTML Template processing, etc.)
PWA Project's PWA support information (tech stack, build process, etc.)
Testing Project's testing approaches (Unit+Integration, E2E) + according CI/CD quality gates description
Typography Project's typography configuration and conventions

Contribution

Find a bug or enhancement and want provide help? Please submit an issue.

License

MIT React Universal Boilerplate

⬆️ back to top

Clone this wiki locally