marmelab / Javascript Boilerplate
Programming Languages
Projects that are alternatives of or similar to Javascript Boilerplate
Archived Repository This code is no longer maintained. Feel free to fork it, but use it at your own risks. |
marmelab-boilerplate
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
andco-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
, andredux-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
andselenium
- 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:
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:
- 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
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:
- Mocha
- 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:
Deployment
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