React Starter

What’s Inside?

• TypeScript - typed superset of JavaScript
• Vite - next generation frontend tooling
• Ant.Design - UI library
• JWT Authentication - including all the common features such as Sign-up, Login, Logout, Forgotten password, Email verification
• SWR - hooks for data fetching with stale-while-revalidate strategy
• i18next - internationalization framework
  • i18next-parser - parses the code, extracts translation keys and produces i18n resource file
• LESS - dynamic stylesheet language
• Recoil - state management library
  • recoil-persist - persist and rehydrate Recoil store
  • recoil-nexus - allows accessing Recoil store from outside components
• React Router - declarative routing
  • oaf-react-router - accessible wrapper for React Router to set proper scroll position & focus
• react-error-boundary - simple reusable React error boundary component
• Vitest - blazing fast Vite-native unit test framework
  • Testing Library - simple and complete testing utilities that encourage good testing practices
  • MSW - API mocking library for browser and Node.js
  • @mswjs/data - data modeling and relation library for testing
  • cross-fetch - polyfill Fetch API for testing
  • mock-match-media - mock window.matchMedia for testing
• Prettier - opinionated code formatter
• ESLint - pluggable linting utility
• Husky & lint-staged - run ESLint & Prettier before commiting new code
• CI/CD - Github Actions to run integration tests on each PR & Main branch
• source-map-explorer - analyze and debug space usage through source maps

You can read more about what's included and why here DOCS.md.

Getting Started

Just clone the repo with git clone https://github.com/Kamahl19/react-starter.git or click on "Use this template" button above.

Prerequisites

1. Install nvm (Node version manager)
2. Install Node v16 nvm install 16
3. Use Node v16 nvm use 16
4. Upgrade NPM CLI npm upgrade -g npm
5. Install dependencies npm install
6. Edit the .env file according to your needs

Start app

To run the app locally, run npm run start in app root directory. Vite will start web server in the development mode at http://localhost:3000 (or the first next free port).

This project includes Mock Service Worker to mock API. It starts automatically and provides API for authentication and user functionality.

Build app

To build the app for production, run npm run build in app root directory. Your app is then ready to be deployed from the /dist folder. See the Building for Production and Deploying a Static Site for more information.

Test app

Run npm run test to launch the test runner in the interactive watch mode. See Vitest docs for more information.

Prettier

This project uses Prettier, an opinionated code formatter. In order to format code manually, run npm run format in app root directory. All the code is also formatted automatically on pre-commit hook. There is also npm run format-check for CI purposes to check if code is formatted properly.

ESLint

Project comes with ESLint configured. It helps you prevent common errors.

There are multiple ways how to run ESLint.

• CLI: npm run lint
• in terminal while developing (after running npm run start)
• it runs automatically on pre-commit hook
• in IDE if supported

i18n

Running npm run extract-translations will first parse the whole codebase to find all used i18n keys. Then it inserts missing keys into the JSON file and removes deprecated keys which are not used in the codebase anymore. The result will be an alphabetically sorted JSON containing all the currently used i18n keys in the codebase.

Analysing production JS bundle

Project comes with the source-map-explorer which analyzes the production JS bundle. To use it just run npm run analyze.

Updating dependencies

Project comes with the default Renovate config renovate.json. It takes care of automated dependency updates and it's free for open-source projects. More about how to configure here.

CI/CD

This project is using GitHub's Actions to run integration tests on each PR and Main branch. It includes running eslint, prettier, tests and building the app. PR becomes mergable only if it passes. We also show badge on top of README.md to show Main branch status. If you don't use GitHub you can remove the .github folder, otherwise follow these steps to configure your GitHub repository:

1. Go to Settings -> Branches -> Add rule
   • Apply to your main branch
   • Require status checks to pass before merging
   • Select build checks being run in CI.yml
2. Update path to your repository (eg. Kamahl19/react-starter) and name of the branch for CI badge in README.md

More Docs & Guides

Please read DOCS.md for more useful guides and documentation.

Keeping up with updates

Once you start building your own app on top of React Starter you will probably want to keep up-to-date with the new updates of React Starter. This can be easily achieved using GitHub's compare feature. We suggest this process:

1. When you clone the React Starter repo, don't forget to write down the hash of latest main's commit
2. Every once in a while, compare the version of React Starter you used with the current version of React Starter like this https://github.com/Kamahl19/react-starter/compare/{YOUR_LATEST_REACT_STARTER_COMMIT_HASH}...main
3. Go through the diff and apply the changes in your own app
4. Commit these changes into your own repo with this commit message: Updating to React Starter hash: {LATEST_REACT_STARTER_COMMIT_HASH}. This way you always keep the hash of the React Starter's version you currently use in your app

License

This is open source software licensed as MIT.