-
Notifications
You must be signed in to change notification settings - Fork 0
Home
![react boilerplate](https://github.com/Shagon1k/React-Universal-Boilerplate/raw/main/_docs/assets/project-logo.jpg)
π‘ 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_TOKEN
for Snyk,AWS_ACCESS_KEY_ID
/AWS_SECRET_ACCESS_KEY
/AWS_REGION
for 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_PWA
flag; - 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 <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>.
π‘ Note: SSR approach only
π‘ 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 task -
npm run build:client:prod
- Client production build task -
npm 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 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
-
npm run build:clean
- Clean build ("dist") folder
-
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)
-
-
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
-
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)
-
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)
./
β
ββββ.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
ββββ
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.