{"id":23275492,"url":"https://github.com/eggjs/core","last_synced_at":"2026-01-16T02:21:36.170Z","repository":{"id":37285141,"uuid":"61421577","full_name":"eggjs/core","owner":"eggjs","description":"A core plugin framework based on koa.","archived":false,"fork":false,"pushed_at":"2025-03-28T14:24:21.000Z","size":1138,"stargazers_count":222,"open_issues_count":2,"forks_count":92,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-05-01T01:25:57.758Z","etag":null,"topics":["egg","egg-core","framework","koa","koa2","nodejs-framework","pluggable"],"latest_commit_sha":null,"homepage":"https://eggjs.org","language":"TypeScript","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/eggjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2016-06-18T07:02:57.000Z","updated_at":"2025-04-27T14:20:51.000Z","dependencies_parsed_at":"2023-02-09T16:15:45.450Z","dependency_job_id":"37037bff-27b4-41c9-9342-f6c49ed46011","html_url":"https://github.com/eggjs/core","commit_stats":{"total_commits":337,"total_committers":43,"mean_commits":7.837209302325581,"dds":0.685459940652819,"last_synced_commit":"9ff7f767255b6e4109aac9a1aac36463ae6554e0"},"previous_names":["eggjs/egg-loader","eggjs/core"],"tags_count":170,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eggjs%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eggjs","download_url":"https://codeload.github.com/eggjs/core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252200414,"owners_count":21710435,"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":["egg","egg-core","framework","koa","koa2","nodejs-framework","pluggable"],"created_at":"2024-12-19T21:14:24.661Z","updated_at":"2026-01-16T02:21:36.127Z","avatar_url":"https://github.com/eggjs.png","language":"TypeScript","readme":"# @eggjs/core\n\n[![NPM version][npm-image]][npm-url]\n[![Node.js CI](https://github.com/eggjs/core/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/core/actions/workflows/nodejs.yml)\n[![Test coverage][codecov-image]][codecov-url]\n[![Known Vulnerabilities][snyk-image]][snyk-url]\n[![npm download][download-image]][download-url]\n[![Node.js Version](https://img.shields.io/node/v/@eggjs/core.svg?style=flat)](https://nodejs.org/en/download/)\n\n[npm-image]: https://img.shields.io/npm/v/@eggjs/core.svg?style=flat-square\n[npm-url]: https://npmjs.org/package/@eggjs/core\n[codecov-image]: https://codecov.io/github/eggjs/core/coverage.svg?branch=master\n[codecov-url]: https://codecov.io/github/eggjs/core?branch=master\n[snyk-image]: https://snyk.io/test/npm/@eggjs/core/badge.svg?style=flat-square\n[snyk-url]: https://snyk.io/test/npm/@eggjs/core\n[download-image]: https://img.shields.io/npm/dm/@eggjs/core.svg?style=flat-square\n[download-url]: https://npmjs.org/package/@eggjs/core\n\nA core plugin framework based on [@eggjs/koa](https://github.com/eggjs/koa).\nSupport Commonjs and ESM both by [tshy](https://github.com/isaacs/tshy).\n\n**Don't use it directly, see [egg].**\n\n## Usage\n\nDirectory structure\n\n```bash\n├── package.json\n├── app.ts (optional)\n├── agent.ts (optional)\n├── app\n|   ├── router.ts\n│   ├── controller\n│   │   └── home.ts\n|   ├── extend (optional)\n│   |   ├── helper.ts (optional)\n│   |   ├── filter.ts (optional)\n│   |   ├── request.ts (optional)\n│   |   ├── response.ts (optional)\n│   |   ├── context.ts (optional)\n│   |   ├── application.ts (optional)\n│   |   └── agent.ts (optional)\n│   ├── service (optional)\n│   ├── middleware (optional)\n│   │   └── response_time.ts\n│   └── view (optional)\n|       ├── layout.html\n│       └── home.html\n├── config\n|   ├── config.default.ts\n│   ├── config.prod.ts\n|   ├── config.test.ts (optional)\n|   ├── config.local.ts (optional)\n|   ├── config.unittest.ts (optional)\n│   └── plugin.ts\n```\n\nThen you can start with code below\n\n```ts\nimport { EggCore as Application } from '@eggjs/core';\n\nconst app = new Application({\n  baseDir: '/path/to/app',\n});\napp.ready(() =\u003e {\n  app.listen(3000);\n});\n```\n\n## EggLoader\n\nEggLoader can easily load files or directories in your [egg] project.\nIn addition, you can customize the loader with low level APIs.\n\n### constructor\n\n- {String} baseDir - current directory of application\n- {Object} app - instance of egg application\n- {Object} plugins - merge plugins for test\n- {Logger} logger - logger instance，default is console\n\n### High Level APIs\n\n#### async loadPlugin\n\nLoad config/plugin.ts\n\n#### async loadConfig\n\nLoad config/config.ts and config/{serverEnv}.ts\n\nIf `process.env.EGG_APP_CONFIG` is exists, then it will be parse and override config.\n\n#### async loadController\n\nLoad app/controller\n\n#### async loadMiddleware\n\nLoad app/middleware\n\n#### async loadApplicationExtend\n\nLoad app/extend/application.ts\n\n#### async loadContextExtend\n\nLoad app/extend/context.ts\n\n#### async loadRequestExtend\n\nLoad app/extend/request.ts\n\n#### async loadResponseExtend\n\nLoad app/extend/response.ts\n\n#### async loadHelperExtend\n\nLoad app/extend/helper.ts\n\n#### async loadCustomApp\n\nLoad app.ts, if app.ts export boot class, then trigger configDidLoad\n\n#### async loadCustomAgent\n\nLoad agent.ts, if agent.ts export boot class, then trigger configDidLoad\n\n#### async loadService\n\nLoad app/service\n\n### Low Level APIs\n\n#### getServerEnv()\n\nRetrieve application environment variable values via `serverEnv`.\nYou can access directly by calling `this.serverEnv` after instantiation.\n\n| serverEnv | description                            |\n| --------- | -------------------------------------- |\n| default   | default environment                    |\n| test      | system integration testing environment |\n| prod      | production environment                 |\n| local     | local environment on your own computer |\n| unittest  | unit test environment                  |\n\n#### getEggPaths()\n\nTo get directories of the frameworks. A new framework is created by extending egg,\nthen you can use this function to get all frameworks.\n\n#### getLoadUnits()\n\nA loadUnit is a directory that can be loaded by EggLoader, cause it has the same structure.\n\nThis function will get add loadUnits follow the order:\n\n1. plugin\n2. framework\n3. app\n\nloadUnit has a path and a type. Type must be one of those values: _app_, _framework_, _plugin_.\n\n```js\n{\n  path: 'path/to/application',\n  type: 'app'\n}\n```\n\n#### getAppname()\n\nTo get application name from _package.json_\n\n#### appInfo\n\nGet the infomation of the application\n\n- pkg: `package.json`\n- name: the application name from `package.json`\n- baseDir: current directory of application\n- env: equals to serverEnv\n- HOME: home directory of the OS\n- root: baseDir when local and unittest, HOME when other environment\n\n#### async loadFile(filepath)\n\nTo load a single file. **Note:** The file must export as a function.\n\n#### async loadToApp(directory, property, LoaderOptions)\n\nTo load files from directory in the application.\n\nInvoke `this.loadToApp('$baseDir/app/controller', 'controller')`, then you can use it by `app.controller`.\n\n#### async loadToContext(directory, property, LoaderOptions)\n\nTo load files from directory, and it will be bound the context.\n\n```ts\n// define service in app/service/query.ts\nexport default class Query {\n  constructor(ctx: Context) {\n    super(ctx);\n    // get the ctx\n  }\n\n  async get() {}\n}\n\n// use the service in app/controller/home.ts\nexport default async (ctx: Context) =\u003e {\n  ctx.body = await ctx.service.query.get();\n};\n```\n\n#### async loadExtend(name, target)\n\nLoader app/extend/xx.ts to target, For example,\n\n```ts\nawait this.loadExtend('application', app);\n```\n\n### LoaderOptions\n\n| Param       | Type              | Description                                                                                                                                                        |\n| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |\n| directory   | `String/Array`    | directories to be loaded                                                                                                                                           |\n| target      | `Object`          | attach the target object from loaded files                                                                                                                         |\n| match       | `String/Array`    | match the files when load, default to `**/*.js`(if process.env.EGG\\*TYPESCRIPT was true, default to `[ '\\*\\*/\\_.(js                                                | ts)', '!\\*_/_.d.ts' ]`) |\n| ignore      | `String/Array`    | ignore the files when load                                                                                                                                         |\n| initializer | `Function`        | custom file exports, receive two parameters, first is the inject object(if not js file, will be content buffer), second is an `options` object that contain `path` |\n| caseStyle   | `String/Function` | set property's case when converting a filepath to property list.                                                                                                   |\n| override    | `Boolean`         | determine whether override the property when get the same name                                                                                                     |\n| call        | `Boolean`         | determine whether invoke when exports is function                                                                                                                  |\n| inject      | `Object`          | an object that be the argument when invoke the function                                                                                                            |\n| filter      | `Function`        | a function that filter the exports which can be loaded                                                                                                             |\n\n## Timing\n\nEggCore record boot progress with `Timing`, include:\n\n- Process start time\n- Script start time(node don't implement an interface like `process.uptime` to record the script start running time, framework can implement a prestart file used with node `--require` options to set `process.scriptTime`)\n- `application start` or `agent start` time\n- Load duration\n- `require` duration\n\n### start\n\nStart record a item. If the item exits, end the old one and start a new one.\n\n- {String} name - record item name\n- {Number} [start] - record item start time, default is Date.now()\n\n### end\n\nEnd a item.\n\n- {String} name - end item name\n\n### toJSON\n\nGenerate all record items to json\n\n- {String} name - record item name\n- {Number} start - item start time\n- {Number} end - item end time\n- {Number} duration - item duration\n- {Number} pid - pid\n- {Number} index - item index\n\n## Questions \u0026 Suggestions\n\nPlease open an issue [here](https://github.com/eggjs/egg/issues).\n\n## License\n\n[MIT](LICENSE)\n\n## Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=eggjs/core)](https://github.com/eggjs/core/graphs/contributors)\n\nMade with [contributors-img](https://contrib.rocks).\n\n[egg]: https://github.com/eggjs/egg\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feggjs%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feggjs%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feggjs%2Fcore/lists"}