reactSPA and the hand-built React admin template behind a gateway demo

What this repository is actually for

The repository description calls reactSPA a combination of react technology stack, and the project documentation frames it as a set of practices around the React stack and front end engineering, with the stated aim of settling on a reasonably complete solution for building a middle platform system.

That intent matters more than the code. This is not a component library and not a starter template published to a registry. It is one working example of how a particular author wired the whole thing together, with the reasoning left in the repository.

The evidence is in how the documentation is organised. There is a demo site linked for local viewing, animated demonstrations of individual modules and of a todoList built with redux, and a list of related articles that cover React performance tuning, bundle size optimisation, CSS modularisation, building an admin system with the React stack, a source level reading of redux middleware, and the webpack plugin mechanism.

So the repository is documentation by example. The primary language is JavaScript, the licence is MIT, and the homepage is a project site rather than a package. The audience is a front end developer who wants to see how a full admin shell fits together and then take it apart.

Running it locally with yarn or npm, three commands

The usage section is short and gives both package managers, so you can work with whichever is installed.

yarn install || npm install
yarn start || npm start

Those two lines cover the local development cycle. The build and publish steps follow the same pattern.

yarn build || npm run build
yarn deploy || npm run deploy

The underlying scripts are defined in package.json, and reading them tells you more than the shell aliases do. The start script runs node scripts/start.js, the build script runs node scripts/build.js, a predeploy script runs the build again, and the deploy script publishes the build directory with gh-pages -d build. That last detail explains the deploy target: this project publishes to GitHub Pages rather than to a server you control.

There are also quality scripts. The lint script is eslint src --fix, the prettier script runs prettier over the source tree with a broad file glob covering js, jsx, json, yml, yaml, css, less, scss, ts, tsx, md, graphql and mdx, and the validate script chains the two with npm run lint && npm run prettier -- --list-different.

The src/common map and where a feature actually goes

The directory layout is the most useful part of the repository, because it shows where each responsibility belongs in a Redux application.

Under src/common sits api for the request layer, actions for the redux actions, reducers for the redux reducers, components for shared functional components, container for shared style components, images, pages for page modules, utils for helpers, and routes.js for the front end routing.

The utils directory is then broken down further, with index.js at the top and three named files: config.js for general configuration, menu.js for menu configuration, and ajax.js for the ajax module.

The client directory holds the redux store and a devTools.js file for the developer tooling, and the server directory contains a controller subdirectory marked as reserved for future use. That marker is worth taking literally. The directory exists so the structure anticipates a server side, and nothing in the documentation describes a running server there.

The distinction between components and container is the older React convention, and it is what this project uses. Sharing components holds shared functional pieces, while container holds shared style components.

Two webpack configs, one for start speed and one for bundle size

The config directory splits the build into two environment specific files, and the comments in the layout say what each one optimises.

"start": "node scripts/start.js",
"build": "node scripts/build.js",
"predeploy": "node scripts/build.js",
"deploy": "gh-pages -d build",

The development config targets startup speed and the production config targets bundle size, which is the standard split, but stating it in the tree is a small courtesy that saves a newcomer an afternoon. The scripts directory holds the three entry points that pair with them, build.js for packaging, start.js for launching the project and test.js for tests, and a separate build.js at the repository root holds the files produced by a build.

The build tooling itself is Babel and Webpack at version 4.x, with webpack-dev-server providing hot updates. The dependency list includes babel-plugin-import and babel-plugin-on-demand, which are the plugins that make a component library such as Antd load only the parts you use, and react-hot-loader alongside react-loadable for hot reloading and code splitting.

The devDependencies also show analyze-webpack-plugin, autoprefixer and less with less-loader, which is how the less stylesheets are compiled and the bundle inspected.

A mock gateway stands in for the backend

The tech stack list names a gateway with a linked demo repository, and a separate project for a form solution called daForm.

This is the part of the design that most affects what you can do with the repository out of the box. The api layer in src/common/api and the ajax module in utils/ajax.js are written against a gateway rather than against live third party services, so the sample modules run without you having to stand up any backend. The frontend data flow, the loading states and the error paths are all visible, which is the point of the exercise.

The dependencies support that arrangement. fetch-jsonp is present for cross origin calls, and the stack list names CORS under the cross origin heading with Fetch as the ajax mechanism, so the browser calls go through Fetch rather than through an XMLHttpRequest wrapper.

The form story is separate and external. daForm appears both as a dependency at version 0.1.1 and as the answer to a question about a one for all form approach, so the form handling pattern in this project comes from that library rather than from a bespoke implementation inside this repository.

The demo modules and what they exercise

The module list is a catalogue of small applications, and it doubles as a feature test of the stack.

There is a music module with a music list. There is a tools module holding intelligent calculators for salary, rent, body mass index and age, along with a rich text editor and a todo list. There is a gallery module with an image waterfall layout, built on a plugin the author wrote and published separately as jswaterfall. There is a search module that integrates Baidu, 360 and Sogou search engines. And there is the one for all form solution, daForm, listed as its own entry.

The rich text editor is worth a note because its dependency list explains what it is made of. The editor is react-draft-wysiwyg, and two conversion packages sit alongside it, draftjs-to-html and draftjs-to-markdown, which is how the same editor content is turned into HTML or into Markdown depending on where it goes. The gallery depends on photoswipe for the lightbox and screenfull for a full screen toggle.

The todoList gets its own section in the documentation and a separate animation, and the todo list in the project notes shows two things left undone: replacing react-loadable with suspense, and migrating the state management library to GraphQL. Those two lines are the honest summary of where the project stopped.

Where this codebase stops being a good starting point

The dependency versions are the clearest limitation, and they are worth confronting before you copy anything.

The pinned versions are React and React-Dom at 16.13.0, redux at 3.6.0, react-redux at 5.0.5, react-router at 4.1.1, Antd at 3.x, and the bundler is Webpack 4. The routing and Redux integration is react-router-redux at 5.0.0-alpha.9, which is an alpha of a major version, a signal that the wiring was still settling.

The topics attached to the repository confirm it, listing webpack4 and react-router-v4 alongside redux, redux-thunk and antd. A project on React 16 and Webpack 4 works, but you are adopting a stack whose successor versions have been current for years, and the browser tooling, the loader ecosystem and the type definitions you would pair with it all reflect that age.

The second limitation is that there are no GitHub releases at all. There is no version to pin, no changelog to read and no migration path documented between revisions. You track the master branch, which is what you would do with a reference implementation anyway, but it does mean there is no stability guarantee for the code you copy out of it.

Finally, the project is written in Chinese, from the project documentation through the code comments in the directory map to the commit conventions. That is fine if you read Chinese and mildly awkward if you do not, because the comments explaining what each directory is for are part of the documentation.

Commit hooks, linting rules and the tooling around the code

The repository carries more engineering plumbing than a demo project usually has, and it is a reasonable part to steal.

The package.json configures husky with a pre-commit hook running lint-staged and a commit-msg hook running commitlint, so commit messages are validated and staged files are formatted before they land. The lint-staged configuration matches a broad set of file types and runs prettier --write on them before staging. A .commitlintrc.js file at the root holds the commit message rules, and the topics and layout show the project commits to a conventional style.

Style is enforced from two directions. The .eslintrc file applies the Airbnb ruleset, and .prettierrc and .prettierignore handle formatting, with .editorconfig in place for editors that read it.

The interesting piece of configuration is .npmrc together with the presence of both yarn.lock and package.json. The project documentation shows every command with a yarn alternative and an npm alternative, so the project supports both package managers, and the lock file that ships is the yarn one, which tells you which path the author actually used.

Editorial conclusion

Adopt reactSPA if you want a working Chinese-language React and Redux admin backend to read, copy or fork, and if you are comfortable running a Webpack 4 era toolchain. Skip it if you need a current React and TypeScript foundation, since the pinned dependency versions date from the React 16 and Webpack 4 era and the repository publishes no tagged releases. Before building on it, read the src/common directory map and the two webpack config files, then decide whether to keep the mock gateway in the src/server directory or replace it, because that directory is marked as reserved for future use and is not a working server.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. MuYunyun/reactSPA on GitHub
4. Project website
5. README