Egg Core Framework

5.5.1 · deprecated · verified Sun Apr 19

egg-core, at version 5.5.1, is the foundational module of the Egg.js framework, a highly extensible web framework for Node.js built upon Koa. It provides the core loading mechanisms, plugin system, and application context management essential for enterprise-grade web applications. While the unscoped `egg-core` package saw its last update to 5.5.1 in January 2025, active development has since transitioned to its successor, `@eggjs/core`. The `@eggjs/core` package, with `v6.5.0` as its current stable release, continues to evolve the framework with features like enhanced TypeScript support, Vitest integration, and refined lifecycle management. Both `egg-core` and `@eggjs/core` adhere to a convention-over-configuration philosophy, offering a powerful plugin system and environment-aware configurations for extensible and maintainable server-side applications. This package is typically consumed as a dependency by the main `egg` framework, rather than being directly integrated into end-user applications.

Common errors

```
Cannot find module 'egg-core' or its corresponding type declarations.
```
cause The package `egg-core` is either not installed, or the project has migrated to `@eggjs/core` but old import paths remain, or `tsconfig.json` paths are misconfigured.

fix Ensure `egg-core` is listed in `package.json` and installed, or update import statements to `@eggjs/core` if migrating to the newer version.
```
TypeError: app.beforeStart is not a function
```
cause Attempting to use the deprecated `beforeStart` lifecycle hook in an `@eggjs/core` v6.x application.

fix Implement lifecycle methods within a `Boot` class in `app.js` (e.g., `async didReady() { ... }`) instead of `app.beforeStart`.
```
Error: Can't load plugin, egg-xx not found in 'path/to/node_modules'
```
cause A plugin specified in `config/plugin.js` or `package.json` dependencies is either not installed, misspelled, or its path is incorrect.

fix Verify the plugin name and installation (`npm install <plugin-name>`). Ensure it's correctly listed in `package.json` dependencies and `config/plugin.js`.

Warnings

breaking The `egg-core` package has been superseded by `@eggjs/core` in its 6.x series. All import paths must be updated, e.g., `from 'egg-core'` to `from '@eggjs/core'`.
Fix: Update `package.json` to depend on `@eggjs/core` and refactor all import statements accordingly. Consult the `@eggjs/core` migration guide for detailed steps.
breaking When migrating to `@eggjs/core` v6.4.1+, the `beforeStart` lifecycle hook has been replaced by `lifecycle` methods within the Boot class. Direct usage of `app.beforeStart` will lead to errors.
Fix: Refactor application startup logic to use the `Boot` class and its defined lifecycle methods (e.g., `configWillLoad`, `didReady`) in `app.js` or `agent.js`.
gotcha Node.js version requirement for `egg-core` is `>= 14.19.0`. Ensure your environment meets this minimum, otherwise, the package may not function correctly or install properly.
Fix: Upgrade your Node.js runtime to version 14.19.0 or higher. For the `egg` framework itself, Node.js `>= 14.20.0` is recommended.
gotcha In `@eggjs/core` v6.3.0, the `Singleton` utility class was relocated. If your application directly imported or relied on `Singleton` from an older `egg` package, its path would change when migrating to the new core.
Fix: Verify the import path for `Singleton` after upgrading. It is now exported directly from the core package.

Install

npm install egg-core npm
yarn add egg-core yarn
pnpm add egg-core pnpm

Imports

EggCore

wrong:

import EggCore from 'egg-core';

correct:

import { EggCore } from 'egg-core';
const app = new EggCore({ /* ... */ });

EggCore is a named export. Often aliased as `Application` when instantiated.

EggLoader
wrong:
```
const EggLoader = require('egg-core').Loader; // Incorrect property name
```
correct:
```
import { EggLoader } from 'egg-core';
```
Provides utilities for loading files and directories within an Egg.js project. It's a named export.

Application (class instance)

wrong:

import { Application } from 'egg-core'; // `Application` is often an alias for `EggCore` and not a direct named export like this for v5.x
import Application from 'egg-core';

correct:

const Application = require('egg-core').EggCore; // CommonJS for egg-core@5.x
const app = new Application({ baseDir: __dirname });

In CommonJS, `EggCore` is imported and then instantiated, typically aliased as `Application`. For `@eggjs/core` v6.x, `import { EggCore as Application } from '@eggjs/core';` is the modern approach.

Quickstart

This quickstart demonstrates how to instantiate and start a minimal EggCore application, including listening for HTTP requests.

import { EggCore } from 'egg-core';
import { join } from 'path';

async function startApp() {
  const app = new EggCore({
    baseDir: join(__dirname, 'my-egg-app'),
    // Other options like 'env', 'plugins'
  });

  // Application ready event, often used to start listening for requests
  app.ready(() => {
    console.log(`Egg application is ready.`);
    app.listen(3000, () => {
      console.log('Server listening on http://localhost:3000');
    });
  });

  // You might also need to initialize the app loader, typically done internally by the framework
  // For advanced usage, direct loader API can be used:
  // const loader = new EggLoader({ baseDir: app.baseDir, app });
  // loader.loadConfig();
  // loader.loadController();
  // ...
}

startApp().catch(err => {
  console.error('Application startup failed:', err);
  process.exit(1);
});

view raw JSON →