{"id":14989542,"url":"https://github.com/jasonboy/koa-web-kit","last_synced_at":"2025-04-07T06:05:14.801Z","repository":{"id":9762618,"uuid":"56299782","full_name":"JasonBoy/koa-web-kit","owner":"JasonBoy","description":"🚀A Modern, Production-Ready, and Full-Stack Node Web Framework with React","archived":false,"fork":false,"pushed_at":"2023-07-29T01:38:51.000Z","size":10097,"stargazers_count":213,"open_issues_count":29,"forks_count":41,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-07T06:05:05.469Z","etag":null,"topics":["babel","es6","fullstack-javascript","koa2","react","starter-kit","web-framework","webpack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JasonBoy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-15T07:19:39.000Z","updated_at":"2025-03-03T06:35:50.000Z","dependencies_parsed_at":"2024-09-20T01:15:21.473Z","dependency_job_id":null,"html_url":"https://github.com/JasonBoy/koa-web-kit","commit_stats":{"total_commits":494,"total_committers":3,"mean_commits":"164.66666666666666","dds":0.0080971659919028,"last_synced_commit":"0295a2814da55ba9ba6a94a1b4f654ad04487139"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonBoy%2Fkoa-web-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonBoy%2Fkoa-web-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonBoy%2Fkoa-web-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonBoy%2Fkoa-web-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JasonBoy","download_url":"https://codeload.github.com/JasonBoy/koa-web-kit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601447,"owners_count":20964864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","es6","fullstack-javascript","koa2","react","starter-kit","web-framework","webpack"],"created_at":"2024-09-24T14:18:32.211Z","updated_at":"2025-04-07T06:05:14.773Z","avatar_url":"https://github.com/JasonBoy.png","language":"JavaScript","readme":"# koa-web-kit\n\n[![npm](https://img.shields.io/npm/v/koa-web-kit.svg?style=flat-square)](https://www.npmjs.com/package/koa-web-kit)\n[![Building Status](https://img.shields.io/travis/JasonBoy/koa-web-kit.svg?style=flat-square)](https://travis-ci.org/JasonBoy/koa-web-kit)\n[![node](https://img.shields.io/node/v/koa-web-kit.svg?style=flat-square)](https://nodejs.org/)\n[![Dependency Status](https://img.shields.io/david/JasonBoy/koa-web-kit.svg?style=flat-square)](https://david-dm.org/JasonBoy/koa-web-kit)\n[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)\n\n🚀A Modern, Production-Ready, and Full-Stack Node Web Framework\n\n[Release Notes](https://github.com/JasonBoy/koa-web-kit/releases), \n[An Introduction for koa-web-kit](https://blog.lovemily.me/koa-web-kit-a-modern-production-ready-and-full-stack-node-web-framework/)\n\n\u003e This readme is for v3(require node \u003e= 16), if you need SASS/SCSS support, use [v2.x](https://github.com/JasonBoy/koa-web-kit/tree/v2.x)\n\n## Features\n\n- ✨Built with all modern frameworks and libs, including Koa, React(like [Vue?](https://github.com/JasonBoy/vue-web-kit))...\n- 📦Get all the Node.JS full stack development experience out of the box\n- 🔥Hot Module Replacement support, and bundle size analyzer report\n- 📉Async/Await support for writing neat async code\n- 💖Great style solutions: [Styled-Components](https://www.styled-components.com), [TailwindCSS](https://tailwindcss.com/), CSS Modules\n- 🎉Simple API Proxy bundled, no complex extra reverse proxy configuration\n- 🌈Available for generating static site, also with SSR support\n- ⚡️Just one npm command to deploy your app to production\n- 🐳Docker support(dev and prod Dockerfile)\n- 👷Continuously Maintaining🍻\n\n### Quick Start\n\nGet the [latest version](https://github.com/JasonBoy/koa-web-kit/releases), and go to your project root,\nAlso available on [npm](https://www.npmjs.com/package/koa-web-kit).\n\n\u003e Before start, copy the `config/app-config.js.sample` to `app-config.js`(to project root or `config` dir) for local dev configuration\n\n1. Install Dependencies\n\n```bash\nnpm install\n```\n\n2. Start Dev Server\n\n`npm run dev` to start koa with HMR enabled, or\n`npm run dev:ssr` to start dev server with SSR enabled(yet HMR will be disabled for now)\n\n3. Go to `http://localhost:3000` to view the default react page\n\n### Project Structure\n\n- `__tests__` dir, for your tests\n- `mocks` dir, for your mock json server and other mock data\n- `api` dir, the API Proxy utility, also put your api urls in `api-config.js` for universal import across your app\n- `config` dir, all webpack build configs are put here, besides, some application-wide env configs getter utilities\n- `services` dir, some middleware here, default logger utility also located here\n- `routes` dir, put your koa app routes here\n- `src` dir, all your front-end assets, react components, modules, etc...\n- `utils` dir, utilities for both node.js and front-end\n- `views` dir, your view templates(*NOTE: when SSR is enabled, it will use the template literal string*)\n- *`build`* dir, all built assets for your project, git ignored\n- *`logs`* dir, logs are put here by default, git ignored\n- All other files in project root, which indicate their purposes clearly😀.\n\n### Application Config and Environment Variables\n\nEvery project has some configuration or environment variables to make it run differently in different environments,\nfor koa-web-kit, it also provides different ways to configure your ENVs.\n\n#### app-config.js/app-config.js.sample\n\nThe 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:\n```javascript\nmodule.exports = {\n  //http server listen port\n  \"PORT\": 3000,\n  //most commonly used env\n  \"NODE_ENV\": \"development\",\n  //enable/disable built-in API Proxy\n  \"NODE_PROXY\": true,\n  //config the api proxy debug level, [0, 1, 2], 0 -\u003e nothing, default: 1 -\u003e simple, 2 -\u003e verbose\n  \"PROXY_DEBUG_LEVEL\": 1,\n  //static endpoint, e.g CDN for your static assets\n  \"STATIC_ENDPOINT\": \"\",\n  //add a alternative prefix for your \"STATIC_ENDPOINT\"\n  \"STATIC_PREFIX\": \"\",\n  //add \"/\" to the end of your static url, if not existed\n  \"PREFIX_TRAILING_SLASH\": true,\n  //global prefix for your routes, e.g http://a.com/prefix/...your app routes,\n  //like a github project site\n  \"APP_PREFIX\": \"\",\n  //customize build output dir, default ./build/app\n  \"OUTPUT_DIR\": \"\",\n  //if true, the \"/prefix\" below will be stripped, otherwise, the full pathname will be used for proxy\n  \"CUSTOM_API_PREFIX\": true,\n  //if enable HMR in dev mode, `npm run dev` will automatically enable this\n  \"ENABLE_HMR\": true,\n  //if need to enable Server Side Rendering, `npm run dev:ssr` will automatically enable this, HMR need to be disabled for now\n  \"ENABLE_SSR\": false,\n  //enable CSS Modules, should disable this when SSR is enabled for now\n  \"CSS_MODULES\": false,\n  //simple dynamic routes, based on file structure(like next.js)\n  \"DYNAMIC_ROUTES\": false,\n  //single endpoint string, multiple see below, type: \u003cstring|object\u003e\n  \"API_ENDPOINTS\": 'http://127.0.0.1:3001',\n  //API Proxies for multiple api endpoints with different prefix in router\n  \"API_ENDPOINTS\": {\n    //set a default prefix\n    \"defaultPrefix\": \"/prefix\",\n    //e.g http://127.0.0.1:3000/prefix/api/login --\u003eproxy to--\u003e http://127.0.0.1:3001/api/login\n    \"/prefix\": \"http://127.0.0.1:3001\",\n    \"/prefix2\": \"http://127.0.0.1:3002\",\n  }\n}\n```\n\n#### Environment Variables and Configuration\n\nAll the variables in `app-config.js` can be set with Environment Variables, which have higher priority than `app-config.js`.\ne.g:\n`\u003e NODE_ENV=production npm start`\nor\n```bash\nexport PORT=3001\nexport NODE_ENV=production\nnpm start\n```\nYou can also use `.env` file to config envs\n\n#### Default `config.default.[dev|prod].js` in `config` dir\n\nThe project comes with default config files just like `app-config.js.sample`, which will be used if `app-config.js` above is not provided.\n\n\u003e Priority: *Environment Variables* \u003e .env \u003e *app-config.js* \u003e *config.default.[dev|prod].js*\n\n### Logs\nThe builtin `services/logger.js` provides some default log functionality for your app.\nBy default, the manual log(calling like `logger.info()`) will be put into `./logs/app.log` file,\nand the http requests will be put into `./logs/requests.log`,\nboth will also be logged to console.\nFor more options, checkout the [pino](https://github.com/pinojs/pino).\n\n```javascript\n//use the default logger\nconst { logger, Logger } = require('../services/logger');\nlogger.info('message');\nlogger.error(new Error('test error'));\n//create custom logger, log into a different file\nconst pino = require('pino');\n//the 2nd params for the constructor is for only for pino options\nconst mylogger = new Logger({destination: pino.destination('./logs/my-log.log')}, {});\nmylogger.info('my log message');\n```\n\n### Production Deployment\n\nDeploy 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),\n[pm2](https://github.com/Unitech/pm2) inside is used as node process manager.\n\u003e 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\n\n\n#### Usage\n\n`npm run deploy -- [skipInstall] [skipBuild] [skipServer]`\nThe last three options are boolean values in `0`(or empty, false) and `1`(true).\n\n#### Examples:\n\n- `npm run deploy`: no options provided, defaults to do all the tasks.\n- `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.\n- `npm run deploy -- 1 0 1`: which will only build your assets\n- `npm run deploy -- 1 1 0`: which will just start node server, useful when all assets were built on a different machine.\n\n\u003e You may need to create/update the `deploy.sh` to meet your own needs.\n\n### Powered By\n\n\u003ca href=\"https://www.jetbrains.com/?from=koa-web-kit\" target=\"_blank\"\u003e![powered by jetbrains](https://raw.githubusercontent.com/JasonBoy/koa-web-kit/master/src/assets/static/jetbrains.svg)\u003c/a\u003e\n\n### LICENSE\n\nMIT @ 2016-present [jason](http://blog.lovemily.me)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonboy%2Fkoa-web-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasonboy%2Fkoa-web-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonboy%2Fkoa-web-kit/lists"}