🚀A Modern, Production-Ready, and Full-Stack Node Web Framework
Release Notes, An Introduction for koa-web-kit
This readme is for v3(require node >= 16), if you need SASS/SCSS support, use v2.x
- ✨Built with all modern frameworks and libs, including Koa, React(like Vue?)...
- 📦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
- 💖Great style solutions: Styled-Components, TailwindCSS, CSS Modules
- 🎉Simple API Proxy bundled, no complex extra reverse proxy configuration
- 🌈Available for generating static site, also with SSR support
- ⚡️Just one npm command to deploy your app to production
- 🐳Docker support(dev and prod Dockerfile)
- 👷Continuously Maintaining🍻
Get the latest version, and go to your project root, Also available on npm.
Before start, copy the
config/app-config.js.sampletoapp-config.js(to project root orconfigdir) for local dev configuration
- Install Dependencies
npm install- 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)
- Go to
http://localhost:3000to view the default react page
__tests__dir, for your testsmocksdir, for your mock json server and other mock dataapidir, the API Proxy utility, also put your api urls inapi-config.jsfor universal import across your appconfigdir, all webpack build configs are put here, besides, some application-wide env configs getter utilitiesservicesdir, some middleware here, default logger utility also located hereroutesdir, put your koa app routes heresrcdir, all your front-end assets, react components, modules, etc...utilsdir, utilities for both node.js and front-endviewsdir, your view templates(NOTE: when SSR is enabled, it will use the template literal string)builddir, all built assets for your project, git ignoredlogsdir, logs are put here by default, git ignored- All other files in project root, which indicate their purposes clearly😀.
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.
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": "",
//customize build output dir, default ./build/app
"OUTPUT_DIR": "",
//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,
//simple dynamic routes, based on file structure(like next.js)
"DYNAMIC_ROUTES": false,
//single endpoint string, multiple see below, type: <string|object>
"API_ENDPOINTS": 'http://127.0.0.1:3001',
//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",
}
}All the variables in app-config.js can be set with Environment Variables, which have higher priority than app-config.js.
e.g:
> NODE_ENV=production npm start
or
export PORT=3001
export NODE_ENV=production
npm startYou can also use .env file to config envs
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 > .env > app-config.js > config.default.[dev|prod].js
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');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
pm2cmd everywhere, you may still want to install it globally
npm run deploy -- [skipInstall] [skipBuild] [skipServer]
The last three options are boolean values in 0(or empty, false) and 1(true).
npm run deploy: no options provided, defaults to do all the tasks.npm run deploy -- 1: same asnpm run deploy:noinstallas an alias, this will skip thenpm install --no-shrinkwrap, and just go to build and start server.npm run deploy -- 1 0 1: which will only build your assetsnpm 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.shto meet your own needs.
MIT @ 2016-present jason
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent