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.
Controller
✓ import { Controller } from 'egg'; // For TypeScript or ESM in Node environments (with transpilation or v4+)
const Controller = require('egg').Controller; // CommonJS (v3)
✗ import Controller from 'egg'; // Incorrect default import
import { Controller } from '@eggjs/core'; // Incorrect path for v3
Controller is a base class for defining application logic. For v3, CommonJS `require` is typical. v4 is moving towards `@eggjs/*` scoped packages and native ESM support.
Service
✓ import { Service } from 'egg'; // For TypeScript or ESM in Node environments (with transpilation or v4+)
const Service = require('egg').Service; // CommonJS (v3)
✗ import Service from 'egg'; // Incorrect default import
import { Service } from '@eggjs/core'; // Incorrect path for v3
Service is a base class for encapsulating business logic. Similar to Controller, CommonJS `require` is standard for v3.
Application
✓ import { Application } from 'egg'; // For TypeScript or ESM in Node environments (with transpilation or v4+)
const Application = require('egg').Application; // CommonJS (v3) - for programmatic instance
const AppBootHook = require('egg').AppBootHook; // CommonJS (v3) - for lifecycle hooks
✗ import { Application } from '@eggjs/core'; // Only for programmatic use in v4 or core package
const app = require('egg'); // App object is not the default export
The `Application` class (or `EggCore`) represents the application instance. In typical app development, `app` and `ctx` are accessed via `this.app` and `this.ctx` within Controllers and Services. For lifecycle hooks, `AppBootHook` class is recommended since v3.
Demonstrates how to set up a basic Egg.js application using the recommended scaffold, define a controller, configure routes, and create a simple service.
import { Application } from 'egg'; // Use import for TypeScript or transpiled environments
import { Controller } from 'egg';
// 1. Initialize project using scaffold (run in your terminal)
// $ npm init egg --type=simple my-egg-app
// $ cd my-egg-app
// $ npm install
// 2. Create app/controller/home.ts (or .js)
// A simple controller
class HomeController extends Controller {
async index() {
const { ctx } = this;
ctx.body = 'Hello Egg.js!';
}
}
// module.exports = HomeController; // For .js files (CommonJS)
// 3. Create app/router.ts (or .js)
// Define routing
export default (app: Application) => {
const { router, controller } = app;
router.get('/', controller.home.index);
};
// module.exports = (app) => {
// const { router, controller } = app;
// router.get('/', controller.home.index);
// }; // For .js files (CommonJS)
// 4. Run the application (in your terminal)
// $ npm run dev
// Then open http://localhost:7001 in your browser.
// Example of custom service (app/service/greeter.ts or .js)
class GreeterService extends Service {
async greet(name: string) {
return `Greetings, ${name}!`;
}
}
// Example of using the service in a controller
class UserProfileController extends Controller {
async show() {
const { ctx, service } = this;
const userName = ctx.query.name || 'World';
const greeting = await service.greeter.greet(userName);
ctx.body = greeting;
}
}
// And add to router.ts:
// router.get('/greet', controller.userProfile.show);
Errors
Common errors & fixes
Error: Cannot find module 'egg'
The `egg` package is not installed or not resolvable in the current project.
fixRun `npm install egg --save` or `pnpm install egg` in your project directory.
TypeError: Cannot read properties of undefined (reading 'Controller')
You are likely trying to access `egg.Controller` but `egg` itself was not properly imported or is undefined. This can happen with incorrect import syntax or if `egg` is not installed.
fixEnsure `const Controller = require('egg').Controller;` for CommonJS or `import { Controller } from 'egg';` for ESM/TypeScript. Verify `egg` is installed. Error: Current Node.js version is vX.Y.Z, but Egg.js requires >= v14.20.0.
The Node.js version installed on your system does not meet the minimum requirement for the installed Egg.js version.
fixUpgrade your Node.js runtime to version 14.20.0 or higher. For Egg.js v4.x, Node.js >= 18.19.0 is required. Use a version manager like `nvm` to switch Node.js versions.
TypeError: this.ctx.render is not a function
You are trying to use `ctx.render` without a configured view plugin, or the view plugin is not correctly enabled.
fixInstall a view plugin like `egg-view-nunjucks` (`npm i egg-view-nunjucks --save`) and enable it in `config/plugin.js`. Configure the view engine in `config/config.default.js`.
Audit
Dependencies
egg-corerequiredCore functionality for application loading and management.
egg-clusterrequiredProvides multi-process management and cluster capabilities.
koa-bodyparserrequiredCommon middleware for parsing request bodies.