πŸš€A Modern, Production-Ready, and Full-Stack Node Web Framework
Branch: master
Clone or download
JasonBoy Merge pull request #26 from JasonBoy/issue#25
Fix non-js files error in SSR mode
Latest commit 07955b2 Feb 22, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
__tests__ πŸš₯Add simple http client tests Jan 30, 2019
api πŸš₯Add simple http client tests Jan 30, 2019
config πŸ›Fix non-js files error in SSR mode Feb 22, 2019
mocks 🎲Use random port for testing Jan 11, 2019
routes πŸš₯Add simple http client tests Jan 30, 2019
services βœ‚οΈRemove INLINE_STYLES logic Feb 15, 2019
src βœ‚οΈRemove INLINE_STYLES logic Feb 15, 2019
utils 🚰Add koa router and request proxying tests Jan 10, 2019
views πŸ‘·Update SSR scripts Jun 20, 2018
.dockerignore 🐳Docker config update, Dockerfile now only for production Jan 8, 2019
.gitignore 🐳Docker config update, Dockerfile now only for production Jan 8, 2019
.npmrc ✨Add got package & .npmrc file Jan 4, 2019
.prettierignore ⬇️Add download proxying test Jan 11, 2019
.prettierrc πŸ’…add prettier stuff Feb 11, 2018
.travis.yml βœ…Use "npm test" for CI Nov 30, 2018
Dockerfile 🐳Docker config update, Dockerfile now only for production Jan 8, 2019
LICENSE ©️Update license year Jan 8, 2019
README.md ✏️Update file structure with __tests__ dir Jan 11, 2019
app.js βœ‚οΈRemove INLINE_STYLES logic Feb 15, 2019
babel.config.js βœ‚οΈDo not use babel "loose" mode Feb 15, 2019
deploy.sh πŸ”§Moving change registry into "install phase" Dec 11, 2018
jest.config.client.js πŸ›Fix dynamic import failed in jest tests Feb 14, 2019
jest.config.node.js πŸƒStart add server and client side tests Jan 9, 2019
package-lock.json βœ‚οΈCleanup react-loadable related code Feb 15, 2019
package.json βœ‚οΈCleanup react-loadable related code Feb 15, 2019
pm2.config.js πŸƒStart add server and client side tests Jan 9, 2019
postcss.config.js πŸ’…reformat code with prettier Feb 11, 2018
server.js 🏊Add upload proxying test Jan 10, 2019

README.md

koa-web-kit

npm Building Status node Dependency Status code style: prettier

πŸš€A Modern, Production-Ready, and Full-Stack Node Web Framework

Release Notes An Introduction for koa-web-kit

Features

  • ✨Built with all modern frameworks and libs, including Koa2, React(like Vue?), Bootstrap-v4(css only)...
  • πŸ“¦Get all the Node.JS full stack development experience out of the box
  • πŸ”₯Hot Module Replacement support, and bundle size analyzer report
  • πŸ“‰Async/Await support for writing neat async code
  • πŸ’–CSS Modules, SASS preprocessor, PostCSS, autoprefixer
  • πŸŽ‰Simple API Proxy bundled, no complex extra nginx configuration
  • 🌈Available for generating static react site, also with SSR support
  • ⚑️Just one npm command to deploy your app to production
  • πŸ‘·Continuously Maintaining🍻

Quick Start

Get the latest version, and go to your project root, Also available on npm.

Before start, copy the config/app-config.js.sample to app-config.js(to project root or config dir) for local dev configuration

  1. Install Dependencies
npm install
  1. Start Dev Server

npm run dev to start koa with HMR enabled, or npm run dev:ssr to start dev server with SSR enabled(yet HMR will be disabled for now)

  1. Go to http://localhost:3000 to view the default react page

Project Structure

  • __tests__ dir, for your tests
  • mocks dir, for your mock json server and other mock data
  • api dir, the API Proxy utility, also put your api urls in api-config.js for universal import across your app
  • config dir, all webpack build configs are put here, besides, some application-wide env configs getter utilities
  • services dir, some middleware here, default logger utility also located here
  • routes dir, put your koa app routes here
  • src dir, all your front-end assets, react components, modules, etc...
  • utils dir, utilities for both node.js and front-end
  • views dir, your view templates(NOTE: when SSR is enabled, it will use the template literal string)
  • build dir, all built assets for your project, git ignored
  • logs dir, logs are put here by default, git ignored
  • All other files in project root, which indicate their purposes clearlyπŸ˜€.

Application Config and Environment Variables

Every project has some configuration or environment variables to make it run differently in different environments, for koa-web-kit, it also provides different ways to configure your ENVs.

app-config.js/app-config.js.sample

The pre bundled file config/app-config.js.sample lists some common variables to use in the project, you should copy and rename it to app-config.js for your local config, both put it in ${project_root} or the same config dir are supported:

module.exports = {
  //http server listen port
  "PORT": 3000,
  //most commonly used env
  "NODE_ENV": "development",
  //enable/disable built-in API Proxy
  "NODE_PROXY": true,
  //config the api proxy debug level, [0, 1, 2], 0 -> nothing, default: 1 -> simple, 2 -> verbose
  "PROXY_DEBUG_LEVEL": 1,
  //static endpoint, e.g CDN for your static assets
  "STATIC_ENDPOINT": "",
  //add a alternative prefix for your "STATIC_ENDPOINT"
  "STATIC_PREFIX": "",
  //add "/" to the end of your static url, if not existed
  "PREFIX_TRAILING_SLASH": true,
  //global prefix for your routes, e.g http://a.com/prefix/...your app routes,
  //like a github project site
  "APP_PREFIX": "",
  //if true, the "/prefix" below will be stripped, otherwise, the full pathname will be used for proxy
  "CUSTOM_API_PREFIX": true,
  //if enable HMR in dev mode, `npm run dev` will automatically enable this
  "ENABLE_HMR": true,
  //if need to enable Server Side Rendering, `npm run dev:ssr` will automatically enable this, HMR need to be disabled for now
  "ENABLE_SSR": false,
  //enable CSS Modules, should disable this when SSR is enabled for now
  "CSS_MODULES": false,
  //API Proxies for multiple api endpoints with different prefix in router
  "API_ENDPOINTS": {
    //set a default prefix
    "defaultPrefix": "/prefix",
    //e.g http://127.0.0.1:3000/prefix/api/login -->proxy to--> http://127.0.0.1:3001/api/login
    "/prefix": "http://127.0.0.1:3001",
    "/prefix2": "http://127.0.0.1:3002",
  }
}

Environment Variables

All the variables in app-config.js can be set with Environment Variables(except for API_ENDPOINTS for now, since it has nested json structure), which have higher priority than app-config.js. e.g: > NODE_ENV=production npm start or

export PORT=3001
export NODE_ENV=production
npm start

BTW you can do Everything you can within cli to set your env.

Default config.default.[dev|prod].js in config dir

The project comes with default config files just like app-config.js.sample, which will be used if app-config.js above is not provided.

Priority: Environment Variables > app-config.js > config.default.[dev|prod].js

Logs

The builtin services/logger.js provides some default log functionality for your app. By default, the manual log(calling like logger.info()) will be put into ./logs/app.log file, and the http requests will be put into ./logs/requests.log, both will also be logged to console. For more options, checkout the pino.

//use the default logger
const { logger, Logger } = require('../services/logger');
logger.info('message');
logger.error(new Error('test error'));
//create custom logger, log into a different file
const pino = require('pino');
//the 2nd params for the constructor is for only for pino options
const mylogger = new Logger({destination: pino.destination('./logs/my-log.log')}, {});
mylogger.info('my log message');

Production Deployment

Deploy your app to production is extremely simple with only one npm script command, you can provide couple of options for different deployment phases(e.g: install, build, start server), pm2 inside is used as node process manager.

Global installation of PM2 is not required now, we will use the locally installed pm2, but if you want to use pm2 cmd everywhere, you may still want to install it globally

Usage

npm run deploy -- [skipInstall] [skipBuild] [skipServer] The last three options are boolean values in 0(or empty, false) and 1(true).

Examples:

  • npm run deploy: no options provided, defaults to do all the tasks.
  • npm run deploy -- 1: same as npm run deploy:noinstall as an alias, this will skip the npm install --no-shrinkwrap, and just go to build and start server.
  • npm run deploy -- 1 0 1: which will only build your assets
  • npm run deploy -- 1 1 0: which will just start node server, useful when all assets were built on a different machine.

You may need to create/update the deploy.sh to meet your own needs.

LICENSE

MIT @ 2016-present jason