A starter kit for new apps, based on:
- ES6 everywhere (with some bits of ES7, e.g. spread operator on objects)
- React.js, React Router, and Redux (for the frontend)
- Admin-on-rest (for the admin)
- Node.js, Koa.js and PostgreSQL (for the API server)
- Makefile, webpack and Mocha (for the build and test)
- Babel transpilation (es2015, react, stage-0) for both client and server code
- Node.js API built on top of Koa.js (successor of Express) for cleaner async code
- Automated CRUD resources based on a PostgreSQL database (using
- State-of the art robustness and security for the API (JWT, rate limiting, secure headers, based on
- Separated API for the admin, with different security settings (and login form)
- Built-in database migration handling (using
- Production-level logging (using
- CORS support (including on IE8, thanks to
- Fully automated start and stop (see
- Auto-reload of Node.js code upon modification (using
- Frontend app built with React,
react-dev-toolsand hot reload for easier development
- SASS preprocessor (using
- Including a non-trivial example with several routes, Ajax calls, and functional tests
- Fully automated build with
webpack, including development (
webpack-dev-server) and production target (minified)
- Admin app built with React.js and
- Including a full-featured admin panel with references
- Unified test build, running unit and functional tests on all apps, powered by
- AWS deployment automated by Fabric
eslintdefaults, based on Airbnb's rules
The boilerplate contains a sample app with three domains: users, products, and orders. Feel free to remove the corresponding files once you start implementing your own domain.
- Node.js V5
- openjdk-8-jre (to install selenium-standalone)
# install npm dependencies and Selenium (for tests) make install
alias make='make -s' to your bash profile (bashrc, zshrc) for a better display.
The project directory structure is as follows:
bin/ # CLI tasks build/ # compiled JS and CSS files for the admin and frontend app. The web root in production. config/ # Project configuration doc/ e2e/ # Functional tests src/ api/ # The server API code (Node.js, Koa.js) admin/ # The admin dashboard code (Angular.js, ng-admin) frontend/ # The frontend code (React.js, Redux) isomorphic/ # Code common to several apps webpack/ # Webpack configuration (for admin and frontend compilation)
The entire code (api, admin, and frontend) is written in ES6 and transpiled to ES5 by babel.
Tip: In production, the compiled JS and CSS files (under
build/) are served by the Node.js server. In development, it's done by webpack-dev-server.
The main entry point for understanding the code is probably
This projects supports various runtime environments. This means that you can switch to an entirely different configuration based on the
NODE_ENV environment variable:
# run the API server in development mode (default) $ node ./src/api/index.js # run the API server in test mode $ NODE_ENV=test node ./src/api/index.js # run the API server in production mode $ NODE_ENV=production node ./src/api/index.js
Tip: On the production servers, you should set the
NODE_ENV variable using supervisor.
It uses node-config to let you configure the project for the development, test, and production environments.
node-config supports configuration cascade, so the actual configuration for a given environment is the combination of
config/[NODE_ENV].js (the configuration settings for a given environment override the default settings).
Before running the app in development, you must copy the
config/development.js (this is done by the
make install command), and edit the server and database settings to your development environment. Same for the
test-dist.js if you intend to run unit tests.
Note: You need to remove all the demo code before to start your project. A pull request is in progress to do so, but this will take some time to finish it. Meanwhile, take a look on these folders to manually clean the code:
This project uses pm2 to manage its processes. Configuration files for pm2 can be found in the
# start servers (node and webpack via pm2) make run-dev # both servers will run in the background # the Node server uses nodemon and will restart on code change # the frontend is served by webpack dev server with hot reload # you can restart either the api or the frontend by hand make restart-api make restart-frontend
Browse the app:
- http://localhost:8081 for the admin app
- http://localhost:8080 for the frontend app
- http://localhost:3000 for the API
Tip: You can change the API port by running
NODE_PORT=3001 make run-dev. Or, for persistent change, you can add this environment variable into the PM2 configuration file.
# stop servers (node and webpack) make stop-dev
# tests run in the "test" environment and don't empty the "development" database make test # alternatively, you can run any of the individual test suites: make test-api-unit make test-api-functional make test-frontend-unit make test-frontend-functional make test-isomorphic-unit
API (and common lib) unit tests using:
API functional tests using:
Frontend unit tests using:
- expect from expect
- Redux Thunk, redux-mock-store and nock to test redux action creators (as explain in redux documentation)
- enzyme to test react components
Frontend fonctional tests using:
Managing servers with PM2
dev and tests servers are managed with PM2. So, It's possible to :
# display the 'front dev' server's logs make log-frontend-dev # display the 'api dev' server's logs make log-api-dev # display the list of all servers make servers-list # display the monitoring for all servers make servers-monitoring # stop all servers make servers-stop-all # stop all servers, delete them, and clear their logs. make servers-clear-all