marmelab / javascript-boilerplate Goto Github PK

View Code? Open in Web Editor NEW

251.0 26.0 53.0 1.01 MB

Node.js+Koa.js+PostgreSQL+React.js+Webpack+Mocha+Makefile, a starter kit for new apps

JavaScript 95.33% HTML 0.29% Makefile 4.32% CSS 0.06%

boilerplate react koa redux postgresql

javascript-boilerplate's Introduction

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

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:

Mocha
expect from expect

API functional tests using:

Mocha
expect from expect
request

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:

selenium-webdriver

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

javascript-boilerplate's People

Contributors

Stargazers

Watchers

javascript-boilerplate's Issues

Cannot create an Order in the Admin app

[email protected] cannot create an order in the Admin app. orders/Create.js should probably create a for order and also an ability to search and add multiple products to an order. This looks more like an enhancement.

Consider introducing repositories with models

As discussed with @alexisjanvier, we currently have storage related code in our models. We should consider introducing repositories.

Add default limit and offset for `selectPage` method

In selectPage, there is a dangerous behavior: API may return all records if neither limit nor offset is specified. This issue, coupled with #51 makes the API to return all available records. It doesn't scale well. :)

We should add a default value for these two parameters. This way, even if we want to retrieve all records, we would need to specify it by hand, setting a limit = 0 for instance.

Run the project with few commands

Add a command to create database and migrate to allow everyone to run the project quickly.

Consider using koa2, async_to_gen et reify

This would allow us to remove babel at least for the API part

Use Webpack templating to include CSS and JS

See: http://www.jonathan-petitcolas.com/slides/2015-12-17-zombo-reloaded-webpack-sass.html#/10/2

Fields on the Frontend and Admin sign in pages lose focus

Password field on the Admin Sign in page loses focus after the first character is entered. You have to click it again to continue to enter the password. This was observed in Chrome for Windows and in Chrome for Linux.

Upgrade to bootstrap alpha 3

Wanted: Server-side rendering

Like this issue.

api server not streaming logs to console

Whether a request to the api server is successful or not, nothing is being streamed to the console (using the command "make log-api-dev" after starting the apps with pm2 using "make run-dev". I am able to stream logs to the console from the frontend server, but not the api server. I am a novice developer so perhaps there is something I am missing so I apologize for that. I spent hours trying to stream logs from the api server to the console with no success.

Running on Cloud9, change API port

Great stuff again!
I am trying to run this on the Cloud9 infrastructure.
Is there any simple way for making :3000 -> :8080/api ?

Should we use babel-transformer, or the babel-node command?

Resource querying/filtering not intuitive or not working

I'm able to limit how many resources are returned by using the following query: 'http://localhost:3000/api/products?limit=2'. This was simple to do, but I've been unable to use any of the other query parameters.

For example, given how RESTful query filtering is usually designed, I tried filtering with 'http://localhost:3000/api/products?id=2' (and a few other variations), but this did not affect the resources queried. Does resource filtering require the keyword 'filter' in the query string? I also tried using sort. I created a table of vehicles(id, year, make, models) and implemented the api routes for vehicles. I'm able to perform CRUD actions successfully with vehicles, but none of the query parameters are successful except for 'limit'. I tried sorting with 'http://localhost:3000/api/vehicles?sort=year', but the resources were not sorted.

I've tried reading the code inside src/api/lib/middlewarespgCrud.js and co-postgres-queries/lib/queries/selectPage.js and co-postgres-queries/lib/queries/whereQuery.js. The code in the co-postgres-queries library is pretty dense. I don't know what the problem is.

Webpack hot reloader not working (reload page)

Hello, just pulled your repository.
I tried to test webpack hot reloading but without success.
The HotModule reloads all the page when I change a character in source files.

Here is a screen:

Review e2e testing without nightwatch, protractor and selenium-standalone

Follow:
https://github.com/jeromemacias/mocha-node-webdriver

Consider extracting core functionalities into an open-source project (see sww folder)

Extract db code into its own package

Extract the postgres code into its own package.

This will allow us to provide a mongoose package too.

Remove javascript-boilerplate/api/test/unit

Unit tests should be where the file is

Add unit test un react components

I don't see any unit test for components

Make server.js more secure

include:

koaCors
koaHelmet
xdomain

(see with @brikou and @RobinBressan for code)

ng-admin filters doesn't work

Not working on Windows environment

After setting up everything as instructed it didn't work (node instances seems to be working but URLs are not working - blank) on Windows 8+

make build-admin ERROR in ./~/admin-on-rest/lib/mui/input/RichTextInput.css

$ node --version
v6.9.1

$ npm --version
3.10.8

$ make build-admin
Building frontend application
Hash: aa014ab78b65d19d7bc2                                                                
Version: webpack 2.1.0-beta.25
Time: 10042ms
     Asset       Size  Chunks             Chunk Names
  index.js    9.33 MB       0  [emitted]  index
index.html  398 bytes          [emitted]  
[1131] multi index 28 bytes {0} [built]
    + 1131 hidden modules

ERROR in ./~/admin-on-rest/lib/mui/input/RichTextInput.js
Module not found: Error: Can't resolve 'quill' in '.../javascript-boilerplate/node_modules/admin-on-rest/lib/mui/input'
 @ ./~/admin-on-rest/lib/mui/input/RichTextInput.js 31:13-29
 @ ./~/admin-on-rest/lib/mui/input/index.js
 @ ./~/admin-on-rest/lib/mui/index.js
 @ ./src/admin/js/Admin.js
 @ ./src/admin/js/main.js
 @ multi index

ERROR in ./~/admin-on-rest/lib/mui/input/RichTextInput.css
Module parse failed: .../javascript-boilerplate/node_modules/admin-on-rest/lib/mui/input/RichTextInput.css Unexpected character '@' (1:0)
You may need an appropriate loader to handle this file type.
| @import "~quill/dist/quill.snow.css";
| 
| .ql-editor {
 @ ./~/admin-on-rest/lib/mui/input/RichTextInput.js 37:0-30
 @ ./~/admin-on-rest/lib/mui/input/index.js
 @ ./~/admin-on-rest/lib/mui/index.js
 @ ./src/admin/js/Admin.js
 @ ./src/admin/js/main.js
 @ multi index
Child html-webpack-plugin for "index.html":
        + 1 hidden modules
make: *** [build-admin] Error 2

Track unhandled rejected promises

http://www.2ality.com/2016/04/unhandled-rejections.html

Add functional tests on the frontend

Using Selenium and Nightwatch

No `this.request.query` available

We use sometimes this.request.query, especially on the CRUD. Yet, when I console.log content of this.request, I don't have the query parameter:

{ method: 'GET',
  url: '/?range=%5B0,29%5D&sort=%5Bname,DESC%5D',
  header: { host: 'localhost:3000',
      connection: 'keep-alive',
      accept: 'application/json, text/plain, */*',
      origin: 'http://localhost:8080',
      'user-agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.93 Safari/537.36',
      authorization: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6MSwiZW1haWwiOiJwZXRpdGNvbGFzLmpvbmF0aGFuQGdtYWlsLmNvbSIsImlhdCI6MTQ1NjgyMDkyMH0.8_GjamNsdfns54sTh0D0fPQ15PBQ4vWSI-feSySQKZY',
      referer: 'http://localhost:8080/admin',
      'accept-encoding': 'gzip, deflate, sdch',
      'accept-language': 'fr-FR,fr;q=0.8,en-US;q=0.6,en;q=0.4',
      cookie: '_ga=GA1.1.1982579996.1454323573; token=e97d26d8e784569d2690d4b06321ef2e3be8d4a1e8b9fd727c28729e913922c3'
   }
}