or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application.mdbase-classes.mdconfiguration.mdcontext.mdhttp-client.mdindex.mdloaders-errors.mdstartup.md
tile.json

tessl/npm-egg

A web application framework for Node.js with enterprise-grade development capabilities through a plugin-based architecture and convention-over-configuration approach

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/egg@4.0.x

To install, run

npx @tessl/cli install tessl/npm-egg@4.0.0

index.mddocs/

Egg.js

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.

Package Information

  • Package Name: egg
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install egg
  • Version: 4.0.10

Core Imports

import { 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/cluster

Basic Usage

import { 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');

Architecture

Egg.js is built around several key architectural components:

  • Multi-Process Architecture: Support for both cluster mode (via @eggjs/cluster) and single process mode
  • Application & Agent Workers: Dual worker system with app workers handling HTTP requests and agent worker handling background tasks
  • Plugin System: Extensive plugin ecosystem for extending functionality (security, session, i18n, etc.)
  • Convention over Configuration: Structured directory layout and automatic loading of components
  • Context-Based Programming: Request-scoped context providing access to services, controllers, and utilities
  • Loader System: Automatic loading and dependency injection of controllers, services, middleware, and configurations

Capabilities

Application Management

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>;
}

Application Management

Single Process Startup

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;
}

Single Process Startup

Request Context & Middleware

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;
}

Request Context

Base Classes & Components

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;
}

Base Classes

HTTP Client

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>>;
}

HTTP Client

Configuration & Types

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
}

Configuration

Loaders & Error Handling

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);
}

Loaders & Errors

Types

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;