eggjs/egg v4.1.2 on GitHub

Egg 4.1.2

Egg 4.1.2 is a stable release that brings together the Egg 4 development experience and the latest reliability fixes. We continue to adopt community tools so developers get clearer TypeScript APIs, smoother module loading, and faster feedback from tests. This release publishes 85 packages, including egg@4.1.2 and create-egg@4.1.2.

Highlights

TypeScript and ESM: typed defineConfig, defineConfigFactory, and plugin factories make configuration easier to discover and check. Applications can use ESM or CommonJS, with improved file-extension and compiled-output resolution.
Modern development tools: @eggjs/bin v8 uses Vitest 5 for tests and V8 coverage, and Oxc for development-time TypeScript loading. The repository now uses stable TypeScript 7.0.2 for its default checker, tsdown 0.23 for library builds, and oxlint/oxfmt for linting and formatting. Vitest, rolldown-vite, and VitePress bring the Vite ecosystem into testing and documentation.
Easier ecosystem maintenance: core packages, official plugins, tools, and Tegg share a monorepo with native utoo workspaces and catalogs. Maintainers can implement and validate related changes in one PR, reducing Egg's maintenance costs. Applications can keep their own package manager.
Plugins and business modules: official @eggjs plugin factories provide importable configuration. Tegg integrates module boundaries, dependency injection, and application-scoped lifecycles; HTTP and MCP controllers can reuse business services. Optional integrations remain configurable by the application.
Optional deployment tools: Manifest and compile caching reduce repeated startup work. Egg Bundler, built on @utoo/pack, adds application bundles and opt-in V8 startup snapshots for single-process and cluster deployments. These deployment capabilities are still evolving; validate plugin compatibility and ordinary bundle startup before adopting snapshots.

Recent fixes included in 4.1.2

Worker-thread shutdown: request graceful app/agent cleanup while workers are alive, then terminate workers after the configured timeout when necessary. Shutdown also handles worker errors and prevents restart; unsupported sticky-session mode is rejected. (#6043)
Scheduler cleanup: cancel pending interval, cron, long-timeout, and immediate handles on close, and prevent late startup from restarting a closed scheduler. This fixes applications lingering after app.close(). (#6058)
Windows ESM startup: pass the source-map preload to Node's --import as a file URL, avoiding drive-letter URL errors. (#6044)
Tegg diagnostics: preserve the caller's original path in module-load errors, including the Windows file-URL fallback. (#5939)
Snapshot stop and process discovery: preserve the snapshot command line so title-based stop discovery works on macOS, use PowerShell CIM instead of WMIC on Windows, and handle port output split across chunks. This fix landed after v4.1.2-rc.1. (#6065)

Upgrading

Use Node.js 22.18.0 or later. For snapshot builds and restoration, use Node.js 24 or later and align the build and deployment runtimes.
Upgrade Egg, explicitly installed plugins, and test tools together. With @eggjs/bin v8, review Mocha hooks, obsolete CLI options, and report-format assumptions; its test integration requires Vitest 5.
Oxc handles development transpilation; run type checks separately and build JavaScript explicitly for production. The CLI no longer bundles ts-node; an explicitly selected compiler must be installed by the application.
For snapshots, create connections, watchers, timers, and other runtime resources in configDidLoad or later. Snapshot builds stop after configWillLoad; initialization continues after restoration. Snapshot-backed cluster workers require process mode.

See the egg-bin migration guide for the test-tool changes.

Explore Egg 4

These articles describe the broader Egg 4 series and practical migration paths:

中文阅读：Egg 4 发布说明与系列文章。

Thank you to everyone contributing code, documentation, plugin maintenance, and feedback from real applications.

Full Changelog (rc.1 → stable): v4.1.2-rc.1...v4.1.2. Earlier recent fixes are covered by rc.0 → rc.1.

Published packages (85)