Node.js+Koa.js+PostgreSQL+React.js+Webpack+Mocha+Makefile, a starter kit for new apps
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
config
doc
src
.babelrc
.fabricrc-production
.fabricrc-staging
.gitignore
.travis.yml
README.md
fabfile.py
makefile
package.json
yarn.lock

README.md

marmelab-boilerplate Build Status

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)

Features:

  • 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 pg and co-postgres-queries)
  • State-of the art robustness and security for the API (JWT, rate limiting, secure headers, based on helmet)
  • Separated API for the admin, with different security settings (and login form)
  • Built-in database migration handling (using db-migrate)
  • Production-level logging (using winston)
  • CORS support (including on IE8, thanks to xDomain)
  • Fully automated start and stop (see Makefile)
  • Auto-reload of Node.js code upon modification (using pm2)
  • Frontend app built with React, redux, redux-saga, react-router, and redux-form
  • Using react-dev-tools and hot reload for easier development
  • SASS preprocessor (using node-sass)
  • 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 admin-on-rest
  • Including a full-featured admin panel with references
  • Unified test build, running unit and functional tests on all apps, powered by mocha and selenium
  • AWS deployment automated by Fabric
  • Sensible eslint defaults, 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.

Install

Requirements:

  • Node.js V5
  • PostgreSQL
  • openjdk-8-jre (to install selenium-standalone)
# install npm dependencies and Selenium (for tests)
make install

Tip: Add alias make='make -s' to your bash profile (bashrc, zshrc) for a better display.

Understand

The project directory structure is as follows:

architecture

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 src/api/index.js.

Project Configuration

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/default.js and 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-dist.js into 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:

Develop

This project uses pm2 to manage its processes. Configuration files for pm2 can be found in the ./config/pm2_servers/ directory.

# 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:

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

Test

# 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:

Frontend fonctional tests using:

Deployment

See deployment instructions.

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