Egg.js is a comprehensive web application framework for Node.js that provides enterprise-grade development capabilities through a plugin-based architecture and convention-over-configuration approach. The framework features built-in process management with multi-process support, a powerful plugin system for extending functionality, framework customization capabilities, and comprehensive development tools.
npm install eggimport { Application, Agent, startEgg, start } from "egg";For CommonJS:
const { Application, Agent, startEgg, start } = require("egg");For cluster mode:
import { startCluster } from "egg";
// startCluster is exported from @eggjs/clusterimport { startEgg } from "egg";
// Start application in single process mode
const app = await startEgg({
baseDir: process.cwd(),
framework: 'egg'
});
// Application is now running and ready to handle requests
console.log('Egg.js application started');Egg.js is built around several key architectural components:
Core application and agent classes for managing web application lifecycle and multi-process coordination.
class Application extends EggApplicationCore {
constructor(options?: Omit<EggApplicationCoreOptions, 'type'>);
server?: http.Server;
Helper: typeof Helper;
onClientError(err: any, socket: Socket): void;
onServer(server: http.Server): void;
runInBackground(scope: (ctx: Context) => Promise<void>, req?: unknown): void;
get locals(): Record<string, any>;
set locals(val: Record<string, any>);
get keys(): string[];
}
class Agent extends EggApplicationCore {
constructor(options?: Omit<EggApplicationCoreOptions, 'type'>);
close(): Promise<void>;
}Simple startup function for single-process mode development and testing.
interface StartEggOptions {
framework?: string;
baseDir?: string;
ignoreWarning?: boolean;
mode?: 'single';
env?: string;
plugins?: EggPlugin;
}
function startEgg(options?: StartEggOptions): Promise<SingleModeApplication>;
// Alias for startEgg
const start: typeof startEgg;
interface SingleModeApplication extends Application {
agent: SingleModeAgent;
}
interface SingleModeAgent extends Agent {
app: SingleModeApplication;
}Enhanced request context with built-in utilities, HTTP client, logging, and background task execution.
class Context extends EggCoreContext {
app: Application;
request: Request;
response: Response;
starttime: number;
performanceStarttime: number;
get cookies(): Cookies;
get httpclient(): HttpClient;
get router(): Router;
get helper(): Helper;
get logger(): EggLogger;
get coreLogger(): EggLogger;
get locals(): Record<string, any>;
curl<T = any>(url: HttpClientRequestURL, options?: HttpClientRequestOptions): Promise<HttpClientResponse<T>>;
runInBackground(scope: (ctx: Context) => Promise<void>, taskName?: string): void;
getLogger(name: string): EggLogger;
}Foundation classes for building controllers, services, and other context-aware components.
class BaseContextClass extends EggCoreBaseContextClass {
ctx: Context;
app: EggApplicationCore;
service: BaseContextClass;
pathName?: string;
get logger(): BaseContextLogger;
}
class Helper extends BaseContextClass {
pathFor(name: string, params: Record<string, any>): string;
urlFor(name: string, params: Record<string, any>): string;
}Built-in HTTP client with application integration, context awareness, and request/response logging.
class HttpClient extends RawHttpClient {
constructor(app: EggApplicationCore, options?: HttpClientOptions);
request<T = any>(url: HttpClientRequestURL, options?: HttpClientRequestOptions): Promise<HttpClientResponse<T>>;
curl<T = any>(url: HttpClientRequestURL, options?: HttpClientRequestOptions): Promise<HttpClientResponse<T>>;
}
class ContextHttpClient {
constructor(ctx: Context);
curl<T = any>(url: HttpClientRequestURL, options?: HttpClientRequestOptions): Promise<HttpClientResponse<T>>;
request<T = any>(url: HttpClientRequestURL, options?: HttpClientRequestOptions): Promise<HttpClientResponse<T>>;
}Comprehensive configuration system with type-safe configuration interfaces and plugin management.
interface EggAppConfig extends EggCoreAppConfig {
workerStartTimeout: number;
baseDir: string;
middleware: string[];
coreMiddleware: string[];
bodyParser: BodyParserConfig;
logger: EggLoggerConfig;
httpclient: HttpClientConfig;
env: EggEnvType;
keys: string;
name: string;
proxy: boolean;
cookies: CookieConfig;
}
interface EggPlugin {
[key: string]: EggPluginItem | undefined;
onerror?: EggPluginItem;
session?: EggPluginItem;
i18n?: EggPluginItem;
security?: EggPluginItem;
// ... other built-in plugins
}Component loading system and error handling utilities for application bootstrapping.
class EggApplicationLoader {
// Base application loader class
}
class AppWorkerLoader extends EggApplicationLoader {
// Loader for application worker components
}
class AgentWorkerLoader extends EggApplicationLoader {
// Loader for agent worker components
}
class CookieLimitExceedError extends Error {
constructor(name: string, value: string);
}
class MessageUnhandledRejectionError extends Error {
constructor(message: string);
}type EggEnvType = 'local' | 'unittest' | 'prod' | string;
type MiddlewareFunc<T extends Context = Context> = EggCoreMiddlewareFunc<T>;
type PowerPartial<T> = {
[U in keyof T]?: T[U] extends object ? PowerPartial<T[U]> : T[U];
};
interface EggApplicationCoreOptions extends Omit<EggCoreOptions, 'baseDir'> {
mode?: 'cluster' | 'single';
clusterPort?: number;
baseDir?: string;
}
// HTTP Client Types
interface HttpClientRequestOptions extends RequestOptions {
ctx?: any;
tracer?: any;
}
interface HttpClientConfig {
timeout?: number;
request?: HttpClientRequestOptions;
allowH2?: boolean;
}
// Configuration Types
interface EggLoggerConfig extends Omit<EggLoggersOptions, 'type'> {
coreLogger?: Partial<EggLoggerOptions>;
allowDebugAtProd?: boolean;
disableConsoleAfterReady?: boolean;
enableFastContextLogger?: boolean;
}
interface EggPluginItem {
env?: EggEnvType[];
path?: string;
package?: string;
enable?: boolean;
}
// Additional exports from @eggjs/core
class Singleton {
// Singleton pattern implementation
}
class Router {
// Router class from @eggjs/core
}
type SingletonCreateMethod<T = any> = (...args: any[]) => T;
interface SingletonOptions {
name?: string;
create?: SingletonCreateMethod;
}
// Logger types from egg-logger
type LoggerLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'NONE';
interface EggLogger {
// Logger interface from egg-logger
}
// Base Hook Class
class BaseHookClass {
// Base class for boot hooks
}
// Alias for BaseHookClass
const Boot: typeof BaseHookClass;