{"id":13109,"library":"egg","title":"Egg.js Web Framework","description":"Egg.js is a robust web framework for Node.js, designed to streamline enterprise-level application development by enforcing conventions and providing a powerful plugin system. Built upon Koa.js, it abstracts away complex middleware logic and offers a multi-process architecture for enhanced stability and scalability. The current stable version is 3.34.0, which regularly receives minor updates, and a major version 4.x is in active beta development, expected around April 2026. Egg.js differentiates itself through its \"convention over configuration\" approach, extensive plugin ecosystem, and comprehensive built-in features for areas like security, logging, and application lifecycle management, making it particularly suitable for large teams and complex business scenarios requiring high quality and reliability.","status":"active","version":"3.34.0","language":"javascript","source_language":"en","source_url":"https://github.com/eggjs/egg","tags":["javascript","web","app","http","application","framework","middleware","koa","egg","typescript"],"install":[{"cmd":"npm install egg","lang":"bash","label":"npm"},{"cmd":"yarn add egg","lang":"bash","label":"yarn"},{"cmd":"pnpm add egg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core functionality for application loading and management.","package":"egg-core","optional":false},{"reason":"Provides multi-process management and cluster capabilities.","package":"egg-cluster","optional":false},{"reason":"Common middleware for parsing request bodies.","package":"koa-bodyparser","optional":false}],"imports":[{"note":"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.","wrong":"import Controller from 'egg'; // Incorrect default import\nimport { Controller } from '@eggjs/core'; // Incorrect path for v3","symbol":"Controller","correct":"import { Controller } from 'egg'; // For TypeScript or ESM in Node environments (with transpilation or v4+)\nconst Controller = require('egg').Controller; // CommonJS (v3)"},{"note":"Service is a base class for encapsulating business logic. Similar to Controller, CommonJS `require` is standard for v3.","wrong":"import Service from 'egg'; // Incorrect default import\nimport { Service } from '@eggjs/core'; // Incorrect path for v3","symbol":"Service","correct":"import { Service } from 'egg'; // For TypeScript or ESM in Node environments (with transpilation or v4+)\nconst Service = require('egg').Service; // CommonJS (v3)"},{"note":"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.","wrong":"import { Application } from '@eggjs/core'; // Only for programmatic use in v4 or core package\nconst app = require('egg'); // App object is not the default export","symbol":"Application","correct":"import { Application } from 'egg'; // For TypeScript or ESM in Node environments (with transpilation or v4+)\nconst Application = require('egg').Application; // CommonJS (v3) - for programmatic instance\nconst AppBootHook = require('egg').AppBootHook; // CommonJS (v3) - for lifecycle hooks"}],"quickstart":{"code":"import { Application } from 'egg'; // Use import for TypeScript or transpiled environments\nimport { Controller } from 'egg';\n\n// 1. Initialize project using scaffold (run in your terminal)\n// $ npm init egg --type=simple my-egg-app\n// $ cd my-egg-app\n// $ npm install\n\n// 2. Create app/controller/home.ts (or .js)\n// A simple controller\nclass HomeController extends Controller {\n  async index() {\n    const { ctx } = this;\n    ctx.body = 'Hello Egg.js!';\n  }\n}\n\n// module.exports = HomeController; // For .js files (CommonJS)\n\n// 3. Create app/router.ts (or .js)\n// Define routing\nexport default (app: Application) => {\n  const { router, controller } = app;\n  router.get('/', controller.home.index);\n};\n\n// module.exports = (app) => {\n//   const { router, controller } = app;\n//   router.get('/', controller.home.index);\n// }; // For .js files (CommonJS)\n\n// 4. Run the application (in your terminal)\n// $ npm run dev\n// Then open http://localhost:7001 in your browser.\n\n// Example of custom service (app/service/greeter.ts or .js)\nclass GreeterService extends Service {\n  async greet(name: string) {\n    return `Greetings, ${name}!`;\n  }\n}\n\n// Example of using the service in a controller\nclass UserProfileController extends Controller {\n  async show() {\n    const { ctx, service } = this;\n    const userName = ctx.query.name || 'World';\n    const greeting = await service.greeter.greet(userName);\n    ctx.body = greeting;\n  }\n}\n\n// And add to router.ts:\n// router.get('/greet', controller.userProfile.show);","lang":"typescript","description":"Demonstrates how to set up a basic Egg.js application using the recommended scaffold, define a controller, configure routes, and create a simple service."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18.19.0 or higher. For v3, ensure Node.js >= 14.20.0.","message":"Egg.js v4.x will require Node.js >= 18.19.0. If you are using an older Node.js version, you must upgrade before migrating to Egg.js v4.x.","severity":"breaking","affected_versions":">=4.0.0-beta"},{"fix":"Refactor your application's lifecycle hooks to use the `AppBootHook` class methods as per the documentation for better control and maintainability.","message":"The lifecycle event functions (e.g., `app.beforeStart`, `app.ready`, `app.beforeClose`) have been deprecated. Developers should now use class methods within an `AppBootHook` class defined in `app.js` or `agent.js` (e.g., `async willReady()`, `async didReady()`, `async beforeClose()`).","severity":"breaking","affected_versions":">=3.x"},{"fix":"During v4 migration, update dependencies in `package.json` and adjust import statements to use the new `@eggjs/` scoped package names.","message":"Starting with Egg.js v4.x, many core packages have been renamed from `egg-something` to `@eggjs/something` (e.g., `egg-security` to `@eggjs/security`, `egg-jsonp` to `@eggjs/jsonp`). This requires updating package names in `package.json` and potentially import paths.","severity":"breaking","affected_versions":">=4.0.0-beta"},{"fix":"Adhere to the file naming conventions (e.g., use snake_case for filenames that represent multi-word properties) to ensure correct auto-loading and access.","message":"Egg.js heavily relies on 'convention over configuration'. File names within `app/controller`, `app/service`, etc., are automatically mapped to camelCase properties on `app.controller` or `ctx.service`. For example, `app/service/user_info.js` maps to `ctx.service.userInfo`.","severity":"gotcha","affected_versions":"All"},{"fix":"Set `exports.keys = ['your_secret_key_1', 'your_secret_key_2'];` with unique, random strings. Do not hardcode secrets in production configurations.","message":"Always configure `exports.keys` with a strong, secret array of strings in your `config/config.default.js` or environment variables. This is crucial for security-related features like cookie signing and CSRF protection.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install egg --save` or `pnpm install egg` in your project directory.","cause":"The `egg` package is not installed or not resolvable in the current project.","error":"Error: Cannot find module 'egg'"},{"fix":"Ensure `const Controller = require('egg').Controller;` for CommonJS or `import { Controller } from 'egg';` for ESM/TypeScript. Verify `egg` is installed.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'Controller')"},{"fix":"Upgrade 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.","cause":"The Node.js version installed on your system does not meet the minimum requirement for the installed Egg.js version.","error":"Error: Current Node.js version is vX.Y.Z, but Egg.js requires >= v14.20.0."},{"fix":"Install 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`.","cause":"You are trying to use `ctx.render` without a configured view plugin, or the view plugin is not correctly enabled.","error":"TypeError: this.ctx.render is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}