# @eggjs/core

> A core plugin framework based on @eggjs/koa

Latest version **7.1.0** (published 2026-10-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @eggjs/core
pnpm add @eggjs/core
yarn add @eggjs/core
bun add @eggjs/core
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.1.0 |
| Published | 2026-10-07 |
| First published | 2024-06-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=22.18.0 |
| Dependencies | 16 |
| Unpacked size | 162.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Author | fengmk2 |
| Maintainers | gxkl, eggjs-admin, fengmk2, atian25, hyj1991, killagu, coolme200, akitasummer, elrrrrrrr, niania |
| Keywords | egg, loader |

## Links

- npm: https://www.npmjs.com/package/@eggjs/core
- Repository: https://github.com/eggjs/egg
- Homepage: https://github.com/eggjs/egg/tree/next/packages/core
- Issues: https://github.com/eggjs/egg/issues
- npm.io page: https://npm.io/package/@eggjs/core

## Dependencies (16)

- [globby](https://npm.io/package/globby.md) ^11.0.2
- [utility](https://npm.io/package/utility.md) ^2.5.0
- [get-ready](https://npm.io/package/get-ready.md) ^3.1.0
- [@eggjs/koa](https://npm.io/package/@eggjs/koa.md) 3.2.0
- [egg-logger](https://npm.io/package/egg-logger.md) ^3.5.0
- [is-type-of](https://npm.io/package/is-type-of.md) ^2.2.0
- [@eggjs/utils](https://npm.io/package/@eggjs/utils.md) 5.1.0
- [node-homedir](https://npm.io/package/node-homedir.md) ^2.0.0
- [@eggjs/router](https://npm.io/package/@eggjs/router.md) 4.1.0
- [@eggjs/extend2](https://npm.io/package/@eggjs/extend2.md) 5.1.0
- [@eggjs/typings](https://npm.io/package/@eggjs/typings.md) 4.2.0
- [performance-ms](https://npm.io/package/performance-ms.md) ^1.1.0
- [ready-callback](https://npm.io/package/ready-callback.md) ^4.0.0
- [tsconfig-paths](https://npm.io/package/tsconfig-paths.md) ^4.2.0
- [@eggjs/loader-fs](https://npm.io/package/@eggjs/loader-fs.md) 1.1.0
- [@eggjs/path-matching](https://npm.io/package/@eggjs/path-matching.md) 3.1.0

## Recent versions

- 7.1.0 (latest) — 2026-10-07
- 7.0.2-rc.1 (rc) — 2026-10-06
- 7.0.2-beta.27 (beta) — 2026-09-20
- 7.0.2 — 2026-10-06
- 7.0.2-rc.0 — 2026-09-23
- 7.0.2-beta.26 — 2026-08-07
- 7.0.2-beta.25 — 2026-07-13
- 7.0.2-beta.24 — 2026-07-12
- 7.0.2-beta.23 — 2026-07-11
- 7.0.2-beta.22 — 2026-07-11
- 7.0.2-beta.20 — 2026-07-09
- 7.0.2-beta.19 — 2026-06-29
- 7.0.2-beta.17 — 2026-06-28
- 7.0.2-beta.16 — 2026-06-26
- 7.0.2-beta.15 — 2026-06-26
- … 80 more at https://npm.io/package/@eggjs/core/versions

## README

# @eggjs/core

[![NPM version][npm-image]][npm-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]
[![npm download][download-image]][download-url]
[![Node.js Version](https://img.shields.io/node/v/@eggjs/core.svg?style=flat)](https://nodejs.org/en/download/)

[npm-image]: https://img.shields.io/npm/v/@eggjs/core.svg?style=flat-square
[npm-url]: https://npmjs.org/package/@eggjs/core
[snyk-image]: https://snyk.io/test/npm/@eggjs/core/badge.svg?style=flat-square
[snyk-url]: https://snyk.io/test/npm/@eggjs/core
[download-image]: https://img.shields.io/npm/dm/@eggjs/core.svg?style=flat-square
[download-url]: https://npmjs.org/package/@eggjs/core

A core plugin framework based on [@eggjs/koa](https://github.com/eggjs/koa).
Support Commonjs and ESM both by [tshy](https://github.com/isaacs/tshy).

**Don't use it directly, see [egg].**

## Usage

Directory structure

```bash
├── package.json
├── app.ts (optional)
├── agent.ts (optional)
├── app
|   ├── router.ts
│   ├── controller
│   │   └── home.ts
|   ├── extend (optional)
│   |   ├── helper.ts (optional)
│   |   ├── filter.ts (optional)
│   |   ├── request.ts (optional)
│   |   ├── response.ts (optional)
│   |   ├── context.ts (optional)
│   |   ├── application.ts (optional)
│   |   └── agent.ts (optional)
│   ├── service (optional)
│   ├── middleware (optional)
│   │   └── response_time.ts
│   └── view (optional)
|       ├── layout.html
│       └── home.html
├── config
|   ├── config.default.ts
│   ├── config.prod.ts
|   ├── config.test.ts (optional)
|   ├── config.local.ts (optional)
|   ├── config.unittest.ts (optional)
│   └── plugin.ts
```

Then you can start with code below

```ts
import { EggCore as Application } from '@eggjs/core';

const app = new Application({
  baseDir: '/path/to/app',
});
app.ready(() => {
  app.listen(3000);
});
```

## EggLoader

EggLoader can easily load files or directories in your [egg] project.
In addition, you can customize the loader with low level APIs.

### constructor

- {String} baseDir - current directory of application
- {Object} app - instance of egg application
- {Object} plugins - merge plugins for test
- {Logger} logger - logger instance，default is console

### High Level APIs

#### async loadPlugin

Load config/plugin.ts

#### async loadConfig

Load config/config.ts and config/{serverEnv}.ts

If `process.env.EGG_APP_CONFIG` is exists, then it will be parse and override config.

#### async loadController

Load app/controller

#### async loadMiddleware

Load app/middleware

#### async loadApplicationExtend

Load app/extend/application.ts

#### async loadContextExtend

Load app/extend/context.ts

#### async loadRequestExtend

Load app/extend/request.ts

#### async loadResponseExtend

Load app/extend/response.ts

#### async loadHelperExtend

Load app/extend/helper.ts

#### async loadCustomApp

Load app.ts, if app.ts export boot class, then trigger configDidLoad

#### async loadCustomAgent

Load agent.ts, if agent.ts export boot class, then trigger configDidLoad

#### async loadService

Load app/service

### Low Level APIs

#### getServerEnv()

Retrieve application environment variable values via `serverEnv`.
You can access directly by calling `this.serverEnv` after instantiation.

| serverEnv | description                            |
| --------- | -------------------------------------- |
| default   | default environment                    |
| test      | system integration testing environment |
| prod      | production environment                 |
| local     | local environment on your own computer |
| unittest  | unit test environment                  |

#### getEggPaths()

To get directories of the frameworks. A new framework is created by extending egg,
then you can use this function to get all frameworks.

#### getLoadUnits()

A loadUnit is a directory that can be loaded by EggLoader, cause it has the same structure.

This function will get add loadUnits follow the order:

1. plugin
2. framework
3. app

loadUnit has a path and a type. Type must be one of those values: _app_, _framework_, _plugin_.

```js
{
  path: 'path/to/application',
  type: 'app'
}
```

#### getAppname()

To get application name from _package.json_

#### appInfo

Get the infomation of the application

- pkg: `package.json`
- name: the application name from `package.json`
- baseDir: current directory of application
- env: equals to serverEnv
- HOME: home directory of the OS
- root: baseDir when local and unittest, HOME when other environment

#### async loadFile(filepath)

To load a single file. **Note:** The file must export as a function.

#### async loadToApp(directory, property, LoaderOptions)

To load files from directory in the application.

Invoke `this.loadToApp('$baseDir/app/controller', 'controller')`, then you can use it by `app.controller`.

#### async loadToContext(directory, property, LoaderOptions)

To load files from directory, and it will be bound the context.

```ts
// define service in app/service/query.ts
export default class Query {
  constructor(ctx: Context) {
    super(ctx);
    // get the ctx
  }

  async get() {}
}

// use the service in app/controller/home.ts
export default async (ctx: Context) => {
  ctx.body = await ctx.service.query.get();
};
```

#### async loadExtend(name, target)

Loader app/extend/xx.ts to target, For example,

```ts
await this.loadExtend('application', app);
```

### LoaderOptions

| Param | Type | Description |
| ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
| directory | `String/Array` | directories to be loaded |
| target | `Object` | attach the target object from loaded files |
| match | `String/Array` | match the files when load, default to `**/*.js`(if process.env.EGG\*TYPESCRIPT was true, default to `[ '\*\*/\_.(js                                                | ts)', '!\*_/_.d.ts' ]`) |
| ignore | `String/Array` | ignore the files when load |
| 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` |
| caseStyle | `String/Function` | set property's case when converting a filepath to property list. |
| override | `Boolean` | determine whether override the property when get the same name |
| call | `Boolean` | determine whether invoke when exports is function |
| inject | `Object` | an object that be the argument when invoke the function |
| filter | `Function` | a function that filter the exports which can be loaded |

## Timing

EggCore record boot progress with `Timing`, include:

- Process start time
- 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`)
- `application start` or `agent start` time
- Load duration
- `require` duration

### start

Start record a item. If the item exits, end the old one and start a new one.

- {String} name - record item name
- {Number} [start] - record item start time, default is Date.now()

### end

End a item.

- {String} name - end item name

### toJSON

Generate all record items to json

- {String} name - record item name
- {Number} start - item start time
- {Number} end - item end time
- {Number} duration - item duration
- {Number} pid - pid
- {Number} index - item index

## Questions & Suggestions

Please open an issue [here](https://github.com/eggjs/egg/issues).

## License

[MIT](LICENSE)

## Contributors

[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)

Made with [contributors-img](https://contrib.rocks).

[egg]: https://github.com/eggjs/egg

---
_Source: https://npm.io/package/@eggjs/core · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._