{"id":10780,"library":"egg-core","title":"Egg Core Framework","description":"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.","status":"deprecated","version":"5.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/eggjs/core","tags":["javascript","egg","loader","typescript"],"install":[{"cmd":"npm install egg-core","lang":"bash","label":"npm"},{"cmd":"yarn add egg-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add egg-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"egg-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'.","package":"koa","optional":false}],"imports":[{"note":"EggCore is a named export. Often aliased as `Application` when instantiated.","wrong":"import EggCore from 'egg-core';","symbol":"EggCore","correct":"import { EggCore } from 'egg-core';\nconst app = new EggCore({ /* ... */ });"},{"note":"Provides utilities for loading files and directories within an Egg.js project. It's a named export.","wrong":"const EggLoader = require('egg-core').Loader; // Incorrect property name","symbol":"EggLoader","correct":"import { EggLoader } from 'egg-core';"},{"note":"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.","wrong":"import { Application } from 'egg-core'; // `Application` is often an alias for `EggCore` and not a direct named export like this for v5.x\nimport Application from 'egg-core';","symbol":"Application (class instance)","correct":"const Application = require('egg-core').EggCore; // CommonJS for egg-core@5.x\nconst app = new Application({ baseDir: __dirname });"}],"quickstart":{"code":"import { EggCore } from 'egg-core';\nimport { join } from 'path';\n\nasync function startApp() {\n  const app = new EggCore({\n    baseDir: join(__dirname, 'my-egg-app'),\n    // Other options like 'env', 'plugins'\n  });\n\n  // Application ready event, often used to start listening for requests\n  app.ready(() => {\n    console.log(`Egg application is ready.`);\n    app.listen(3000, () => {\n      console.log('Server listening on http://localhost:3000');\n    });\n  });\n\n  // You might also need to initialize the app loader, typically done internally by the framework\n  // For advanced usage, direct loader API can be used:\n  // const loader = new EggLoader({ baseDir: app.baseDir, app });\n  // loader.loadConfig();\n  // loader.loadController();\n  // ...\n}\n\nstartApp().catch(err => {\n  console.error('Application startup failed:', err);\n  process.exit(1);\n});","lang":"typescript","description":"This quickstart demonstrates how to instantiate and start a minimal EggCore application, including listening for HTTP requests."},"warnings":[{"fix":"Update `package.json` to depend on `@eggjs/core` and refactor all import statements accordingly. Consult the `@eggjs/core` migration guide for detailed steps.","message":"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'`.","severity":"breaking","affected_versions":">=5.x (when migrating to @eggjs/core 6.x)"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=6.4.1 (of @eggjs/core)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<14.19.0"},{"fix":"Verify the import path for `Singleton` after upgrading. It is now exported directly from the core package.","message":"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.","severity":"gotcha","affected_versions":">=6.3.0 (of @eggjs/core)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `egg-core` is listed in `package.json` and installed, or update import statements to `@eggjs/core` if migrating to the newer version.","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.","error":"Cannot find module 'egg-core' or its corresponding type declarations."},{"fix":"Implement lifecycle methods within a `Boot` class in `app.js` (e.g., `async didReady() { ... }`) instead of `app.beforeStart`.","cause":"Attempting to use the deprecated `beforeStart` lifecycle hook in an `@eggjs/core` v6.x application.","error":"TypeError: app.beforeStart is not a function"},{"fix":"Verify the plugin name and installation (`npm install <plugin-name>`). Ensure it's correctly listed in `package.json` dependencies and `config/plugin.js`.","cause":"A plugin specified in `config/plugin.js` or `package.json` dependencies is either not installed, misspelled, or its path is incorrect.","error":"Error: Can't load plugin, egg-xx not found in 'path/to/node_modules'"}],"ecosystem":"npm"}