Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EggCore
✓ import { EggCore } from 'egg-core';
const app = new EggCore({ /* ... */ });
✗ import EggCore from 'egg-core';
EggCore is a named export. Often aliased as `Application` when instantiated.
EggLoader
✓ import { EggLoader } from 'egg-core';
✗ const EggLoader = require('egg-core').Loader; // Incorrect property name
Provides utilities for loading files and directories within an Egg.js project. It's a named export.
Application (class instance)
✓ const Application = require('egg-core').EggCore; // CommonJS for egg-core@5.x
const app = new Application({ baseDir: __dirname });
✗ 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';
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.
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);
});
Debug
Known issues
breakingThe `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'`.fixUpdate `package.json` to depend on `@eggjs/core` and refactor all import statements accordingly. Consult the `@eggjs/core` migration guide for detailed steps.
affects: >=5.x (when migrating to @eggjs/core 6.x)
breakingWhen 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.fixRefactor application startup logic to use the `Boot` class and its defined lifecycle methods (e.g., `configWillLoad`, `didReady`) in `app.js` or `agent.js`.
affects: >=6.4.1 (of @eggjs/core)
gotchaNode.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.fixUpgrade your Node.js runtime to version 14.19.0 or higher. For the `egg` framework itself, Node.js `>= 14.20.0` is recommended.
affects: <14.19.0
gotchaIn `@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.fixVerify the import path for `Singleton` after upgrading. It is now exported directly from the core package.
affects: >=6.3.0 (of @eggjs/core)
Errors
Common errors & fixes
Cannot find module 'egg-core' or its corresponding type declarations.
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.
fixEnsure `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
Attempting to use the deprecated `beforeStart` lifecycle hook in an `@eggjs/core` v6.x application.
fixImplement 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'
A plugin specified in `config/plugin.js` or `package.json` dependencies is either not installed, misspelled, or its path is incorrect.
fixVerify the plugin name and installation (`npm install <plugin-name>`). Ensure it's correctly listed in `package.json` dependencies and `config/plugin.js`.
Audit
Dependencies
koarequiredegg-core is built on top of Koa; although not a direct dependency in `package.json`, it's the underlying web framework. Its successor, `@eggjs/core`, explicitly states 'based on @eggjs/koa'.