Egg.js — Convention-Over-Configuration Node.js Framework for Enterprise

Introduction

Egg.js is a Node.js framework developed by Alibaba's frontend infrastructure team. Built on top of Koa, it adds a convention-over-configuration layer with a robust plugin system that allows large engineering teams to share common patterns while maintaining flexibility for individual application needs.

What Egg.js Does

• Enforces a directory-based convention for controllers, services, middleware, and config
• Provides a multi-process model with automatic worker management via egg-cluster
• Ships with a plugin mechanism that allows composing reusable business logic modules
• Supports environment-specific configuration with automatic merging
• Includes a built-in security plugin for CSRF, XSS, and SSRF protection

Architecture Overview

Egg.js extends Koa with a loader system that scans conventional directories and wires up components automatically. The framework runs in a multi-process architecture: an agent process handles scheduled tasks and long-running connections, while multiple worker processes handle HTTP requests. The plugin system uses a dependency-declaration model where each plugin declares its dependencies and configuration schema. An application is itself treated as a plugin, and frameworks like egg can be further extended into company-specific base frameworks.

Self-Hosting & Configuration

• Configure environment-specific settings in config/config.{env}.js
• Enable or disable plugins in config/plugin.js with simple key-value declarations
• Use app/schedule/ to define timed tasks that run on the agent process
• Set config.cluster.listen.port to control the HTTP port
• Deploy with egg-scripts start --daemon for production process management

Key Features

• Automatic multi-process management with graceful reload and zero-downtime restarts
• Loader mechanism that eliminates manual require statements and supports file-based routing
• Framework extensibility that lets teams build a shared base framework on top of Egg
• Built-in logger with automatic log rotation and structured output
• First-class TypeScript support with egg-ts-helper for declaration generation

Comparison with Similar Tools

• NestJS — decorator-driven architecture inspired by Angular; Egg uses directory conventions and a loader system
• Express — minimal and unopinionated; Egg provides structure and enterprise patterns out of the box
• Fastify — performance-focused with a plugin system; Egg emphasizes team-scale conventions and multi-process orchestration
• Koa — Egg's foundation; Koa provides the middleware kernel while Egg adds the application layer

FAQ

Q: Is Egg.js still actively maintained? A: Yes, the core team at Alibaba continues to maintain it, with Egg 3.x bringing ES module and modern Node.js support.

Q: Can I use Egg.js with TypeScript? A: Yes, use npm init egg --type=ts to scaffold a TypeScript project with full type inference.

Q: How does the plugin system differ from npm packages? A: Egg plugins follow a specific contract (app extension, config schema, dependencies) that the loader wires up automatically, unlike generic npm packages.

Q: Is Egg.js suitable for microservices? A: Yes, many teams use Egg with gRPC or HTTP-based service communication. The framework itself is process-model agnostic.

Sources

• https://github.com/eggjs/egg
• https://www.eggjs.org/en