Template React project with full TypeScript and SSR support.
This project is a compilation of different approaches in React development that allows not only to start a new project quickly, but to learn how it works under the hood.
You can also check a React Proto Lite - Template React project for fast SPA prototyping. It contains only everything necessary for Single Page Application projects without any server side parts.
Starting from version 2.0.0, this project uses Rspack as the primary bundler.
Rspack is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, allowing for seamless replacement of webpack, and provides lightning fast build speeds.
Webpack is still available as an option (rspack vs webpack and switching back to webpack).
- Issue
- What's Inside
- The App
- How to Use
- Basic Project Configuration
- General Notices
- Documentation
- Changes
- Feedback
Every new React developer knows that React is a library, not a complete framework. Thus, it provides maximum flexibility. However, a lot of knowledge is required to create a fully functional web application powered with React.
That is why there exist such a famous framework as Next.js as well as a tool Create React App (CRA) or Rsbuild for React.
Despite the advantages that such tools have, there are some cons that their user may face:
- Lack of understanding how exactly certain solutions work and why they are applied;
- Lack of flexibility: applied solutions are difficult to fine-tune to your needs;
- The complexity of the codebase of these tools.
As a result, novice React developers have two options for action:
- Simply apply these tools and frameworks to get the product without going into the nuances of their implementation;
- Independently collect bit by bit information on how to implement certain functions in React ecosystem.
Thus, the goal of this project is to collect in one place all the most common methods of working with the React ecosystem without being tied to a specific framework or tool like CRA.
Core:
- React 18+ (Preact 10+ as an option, see comparison below)
- Rspack 1 (webpack 5+ as an option) with SWC support and SSR or static build (why not Vite?, rspack vs webpack and switching back to webpack)
- TypeScript (with strict rules, including webpack configuration)
SSR:
- Express (with render to stream option including helmet data and initial state pushing)
State:
- Redux 5 (with custom state persisting middleware; why not redux-persist package?)
Router:
- React Router
Code Splitting:
- Loadable Components (SSR compatible)
API:
- RTK Query
i18n (Internationalization):
- Lightweight custom solution based on Redux (with async loading and SSR support; why not any common i18n package?)
Styles:
- (S)CSS modules (with TypeScript support; important note for VSCode)
Linters:
- Biome (modern replace for ESLinter and Prettier; configuration Biome for VSCode)
- Stylelint (including rules order)
Tests:
- Jest 29+
- React Testing Library
- Utility for Redux Testing
- One example of integration test of a component with user event and Redux
Other:
- API request caching (powered by RTK Query)
- Data prefetching on server side
- State persisting to Local Storage
- Hot reload (including state, style and server code hot reloading)
- HOC for preventing component rendering on the server
- VSCode support with error highlight and on save fixes
- Script for fast component creation
- Optional Service worker and offline status detector
- Webpack Bundle Analyzer
This boilerplate includes a simple application with:
- Several screen/pages with their own routes
- Local counter
- Global counter
- One of the components is dynamically loaded
- API requests
- Loading spinner
- Theme switcher (light and dark)
- Offline detector
Live preview: https://react-proto.onrender.com/
(due to free hosting, a cold start could be slow)
-
Clone this repo:
git clone https://github.com/StopNGo/react-proto -
Delete the
_webpackfolder if you are not going to use webpack bundler or switch to it before installing the packages. -
Install all packages:
npm i -
Run project in a development mode:
npm start -
Open your browser with the next address:
http://localhost:8080/
-
Build the project (production bundle will be in the
"dist"folder):npm run buildor with Webpack Bundle Analyzer report server:
npm run build:report -
Run a server:
npm run run -
You can test the server locally:
http://localhost:3000/
-
Just run the next command and browser will open automatically:
npm run start:static
-
Run the next command and get a production bundle in the
"dist"folder:npm run build:staticor with Webpack Bundle Analyzer report server:
npm run build:static:report
-
Copy the contents of
_webpackfolder (exceptREADME.md) to the root of the project. -
Delete the
rspack.config.tsfile. -
Delete the
rspackand_webpackfolders. -
If you have a previous installation, clean the
node_modulesfolder. -
Then install the packages:
npm i
All packages in this project are pinned to latest versions at the time of publishing to exclude version-based conflicts and errors and to guarantee proper work of the code in this repository.
If you want to update packages, do next:
npm install -g npm-check-updates
ncu -u
npm i
All configuration is available in files with constants:
webpack\constants.ts- contains working directories, SWC option and other related to bundling staffsrc\constants- a directory with app files with configuration constantssrc\server\constants.ts- contains a server port and render to stream options
Vite is an excellent new generation bundler that could speed up your development process. However, you can face with some lack of flexibility and compatibility especially in big projects that need a lot of specific configurations. Also, webpack has many good plugins that are not compatible with Vite.
As for the speed: you can check this article - Storybook Performance: Vite vs Webpack. As you can see - Webpack could still be fast enough. React Proto has such configurations. In webpack\constants.ts you can switch on SWC and Lazy Compilation.
Starting from version 2.0.0, this project uses Rspack as the primary bundler. This bundler written in Rust and offers strong compatibility with the webpack ecosystem, so, performance should be much better (rspack vs webpack).
I'm also looking forward to Turbopack — another Rust-powered successor to Webpack. Currently, it's available only in Next.js, but it might be released as a standalone CLI tool in the future.
Rspack is a high performance JavaScript bundler written in Rust. It offers strong compatibility with the webpack ecosystem, allowing for seamless replacement of webpack, and provides lightning fast build speeds.
Here is a comparison between Rspack 1 with the built-in SWC loader and Webpack 5+ with the external SWC loader, while building the SSR version of the sample application on the same hardware configuration:
| Rspack | webpack | |
|---|---|---|
| Server | 4.82 s | 6.14 s |
| Client | 4.81 s | 6.56 s |
Of course, the larger the project, the greater the performance advantage. However, if you need more webpack compatibility or hot module reloading while developing with Preact, you can always switch back to the webpack bundler.
Also, the optimization process of Rspack is currently slightly worse. Check the bundle size comparison for the non-SSR version of the sample application in this repository:
| Rspack | webpack | |
|---|---|---|
| Parsed | 285.42 KB | 263.92 KB |
| Gzipped | 90.55 KB | 87.16 KB |
In webpack\constants.ts you can choose to use Preact library instead React itself (IS_PREACT boolean constant).
Preact is a fast and compact React-compatible Virtual DOM library. But because its community is much smaller, you can face with some incompatibility with React API and functionality, especially with new ones. Also some tests show some frame drops during moving a lot of elements. Below you can see a bundle size comparison of no-SSR version of the sample application of this repository that was built with Rspack (according to Webpack Bundle Analyzer):
| React | Preact | |
|---|---|---|
| Parsed | 285.42 KB | 173.3 KB |
| Gzipped | 90.55 KB | 56.05 KB |
Important Note At the moment, the Rspack version of the project does not support hot module reloading during development with Preact. Compared to Webpack, it requires some additional tricky configuration, which I will probably add in the near future. However, if you need HMR (and you definitely do!), you can develop your project using React and then build it with Preact. Or just switch your project back to the webpack.
You can freely integrate any React compatible i18n solution. But if React Proto already uses Redux and RTK, why just not use them for this task? Therefore, I have created a custom internationalization solution with a minimum additional code. It supports translations dynamic loading, server side rendering based on user acceptable languages, strict typing, etc. At the moment it just does not support string processing like pluralization, but it could easily be added later.
As for me this solution is overcomplicated in most of cases. It definitely has a lot of "storage engines", state version control and etc., but smart using of Redux Middlewares and Listeners can cover all this functionality in a more precise way.
Please check this official documentation.
For proper CSS class hinting, please check this note.
Coming soon.
One of the goals of this project is to provide some common solutions in React development and to clarify why they were chosen and how they work. So, such information will be present in this documentation in an orderly fashion.
Detailed release notes for a given version can be found on releases page.
I welcome any feedbacks, suggestions and questions related to this project.
You can leave them on issues or discussions pages.
Thank you!