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).
💡 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 withsca:auth; - AWS S3 deploy (
deploy:s3/storybook:deploy:s3) requires configuring AWS S3 hosting ➡ configureAWS_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_TOKENfor Snyk,AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_REGIONfor AWS);
- Snyk usage (
- 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 ofnpm 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.
- if you don't need SSR:
- remove all it's templates (
SSR_) fromindex.html; - remove /src/server folder (you can just remove render middleware there in case you still need Server without SSR);
- remove SSR docs;
- remove/update SSR approach's tasks;
- remove/update Webpack Server bundling config;
- remove all it's templates (
- if you don't need PWA support - watch PWA docs and remove unnecessary tech stack + all the code under
WITH_PWAflag; - double-check all unnecessary NPM packages removed;
- after all steps complete - update READMEs files;
- remove that Boilerplate Guide;
💡 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 completely lose of type safety and TypeScript checks during this phase. That's why additional test script (tsc) were presented to check as pre-commit(push) hook + in scope of CI/CD.
💡 Note: SSR approach only
CSS_static_code_analyzer-00c8e6?labelColor=grey&logo=stylelint){kind=icon}
💡 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.
💡 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
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)
npm run build:client- Client general build task (development is default)npm run build:client:dev- Client development build tasknpm run build:client:prod- Client production build tasknpm run build:client:prod:pwa- Client production build task (with PWA support)
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)
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)
npm run build:client:wssr- SSR Client general build task (development is default)npm run build:client:wssr:dev- SSR Client development build tasknpm run build:client:wssr:prod- SSR Client production build tasknpm run build:server- Server general build task (development build used as default)npm run build:server:dev- Server development build tasknpm run build:server:prod- Server production build tasknpm run build:app:wssr:dev- Application (Client + Server) development build tasknpm run build:app:wssr:prod- Application (Client + Server) production build task
npm run build:clean- Clean build ("dist") folder
- Unit/Integration Testing
npm test(npm run test) - run Application Unit/Integration Tests (Common + A11y)npm run test:with:reports- 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)
npm run lint:scripts- lint JS/TS filesnpm run lint:scripts:fix- lint JS/TS files with autofixnpm run lint:styles- lint Styles filesnpm run lint:styles:fix- lint Styles files with autofixnpm run lint- lint all (JS/TS+Styles) filesnpm run lint:fix- lint all (JS/TS+Styles) files with autofix
npm run sca:test- scan for vulnerabilities for known issues (with disrupting processes) - CI/CD integrationnpm run sca:test:dev- scan for vulnerabilities for known issues (with disrupting processes), include dev dependenciesnpm 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)
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 buildnpm 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)
./
│
├───.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
│ │ │ │
│ │ │ ├───mocks // Jest setup mocks (e.g. no-JS pattern files mock)
│ │ │ │
│ │ │ ├───test-utils // Testing utils enhancement (e.g. RTL custom "render" util)
│ │ │ │ │
│ │ │ │ ├───custom
│ │ │ │ │
│ │ │ │ │ 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 (Button, Icon, etc.)
│ │ │ │
│ │ │ ├───common // base components (Header, Footer, 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.types.ts // Store types models file
│ │ │ │ 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
│ │ │ │ font-declarations.scss // fonts declarations main file
│ │ │ │ reset-normalize.scss // reset & normalize basic styles
│ │ │ └───
│ │ │
│ │ │ 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)
│ │ │ application.types.ts // application types models file
│ │ │ declarations.d.ts // non-TS files declarations and globals
│ │ │ 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
│ │ │ │
│ │ │ ├───fonts
│ │ │ │
│ │ │ ├───images
│ │ │ │
│ │ │ └───favicons // favicons collection folder (generated by Webpack Favicon plugin)
│ │ │
│ │ ├───css
│ │ │ │
│ │ │ ├───chunks
│ │ │ │
│ │ │ │ styles.css // main dist CSS entry file
│ │ │ └───
│ │ │
│ │ ├───js
│ │ │ │
│ │ │ ├───chunks
│ │ │ │
│ │ │ │ index.js // main dist JS entry file
│ │ │ └───
│ │ │
│ │ │ robots.txt
│ │ │ 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
└───
| 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 |
| 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 |
Find a bug or enhancement and want provide help? Please submit an issue.