Egg.js in the 4.x beta: what the monorepo, utoo tooling and tegg layer actually give you

The problem Egg.js solves for teams running many Node services

Plain Koa gives you a middleware chain and almost nothing else. Every team then invents its own answer for where controllers live, how configuration is layered per environment, how a background process starts, and how a feature is packaged so another service can reuse it. Egg.js is the answer to that second problem: it is a Koa-based framework whose selling points are a plugin system, framework customization, and built-in process management. The intended audience is not a solo developer writing a small API. It is a platform or infrastructure group that wants many applications to share one shape, so that a developer moving between two services already knows where to look.

The repository reflects that ambition. It is not a single package. The root package.json is named @eggjs/monorepo and marked private, and the README describes packages/egg as the main framework, examples/helloworld-commonjs and examples/helloworld-typescript as sample applications, and site as the documentation website. Alongside those sit plugins/ and tegg/, which the README's service notes tie to DAL, ORM, Redis and session fixtures. The scope is closer to a platform than to a library.

How the plugin system and the layered config actually work

The README lists four features without expanding on them: built-in process management, a plugin system, framework customization, and a plugin index on GitHub under the egg-plugin topic. The mechanism those four describe is a fixed application layout that the framework loads, with plugins contributing middleware, services and config into that layout. Framework customization is the layer above plugins: a framework is itself an Egg.js application that bundles a chosen set of plugins, which is how an organisation ships an internal standard rather than asking each team to assemble one.

Built-in process management is what makes this an application framework rather than a middleware collection. Instead of running a single node process under an external supervisor, the framework owns the process model, so a service can have worker processes for request handling and a separate process for scheduled or long-running work. The README does not document the process model in detail, and it does not document rollback behaviour either, so treat those as things to read in the documentation site rather than infer from the repository.

The tegg directory is the piece worth understanding before you commit. The README's hard-coded service assumptions list DAL runtime tests under tegg/core/dal-runtime, DAL module fixtures under tegg/plugin/dal, and ORM fixtures under tegg/plugin/orm, all expecting a local MySQL on port 3306. That tells you tegg is the layer that brings dependency injection and data-access conventions to Egg.js applications, and that its tests are integration tests against real services rather than mocks.

Installing Egg.js and running a first app with utoo

The README's quickstart does not use npm or yarn. It uses utoo, and it requires Node.js 22.18.0 or newer, which is stated as a hard requirement below the command block. The first line enables the utoo corepack shim, the next two create a directory and scaffold an application from the beta line, and the last three install, start the dev server, and open the default port.

$ corepack enable utoo
$ mkdir showcase && cd showcase
$ ut create egg@beta
$ ut install
$ ut run dev
$ open http://localhost:7001

If the scaffold succeeds, the dev server listens on port 7001 and the browser shows the default page. Note that the quickstart pins egg@beta. The newest published tag in the repository is v4.1.2-beta.27 from 2026-09-20, while v3.34.0 from 2026-01-18 is the stable line, so the quickstart as written puts you on the beta. If you want the stable line, that is a deliberate change to the create command rather than the default path.

Working inside the monorepo itself is a different flow. The README gives these development commands, using utoo catalog mode for centralised dependency management so that versions stay consistent across packages.

# Install dependencies for all packages
ut install --from pnpm

# Build all packages
ut run build

# Test all packages
ut run test

# Run specific package commands
ut --filter=egg run test
ut --filter=@examples/helloworld-typescript run dev

The filter form is the one you will use most: it runs a workspace command against a single package instead of the whole monorepo. The root package.json also exposes example:dev:commonjs, example:dev:typescript and example:dev:tegg scripts, which map onto the examples directory if you want to see a running application without scaffolding a new one.

MySQL, Redis and the local services the test suite expects

Several test paths are not self-contained. The README states that DAL, ORM, Redis and ecosystem benchmark paths need local MySQL and Redis services, and provides a command that starts them from the repository-aligned Docker Compose file.

ut run dev:services:start

That command starts MySQL 8 and Redis 7, matching the main CI service versions, and creates the databases used by the local fixtures: test, apple, banana, test_runtime_datasource, test_runtime_dao, test_dal_plugin, test_dal_standalone, cnpmcore and cnpmcore_unittest. The default host ports are 127.0.0.1:3306 and 127.0.0.1:6379. There are companion commands for status, stop and reset.

The port behaviour is the part that will bite you. If either port is already in use, the start command stops before changing containers rather than picking another port. You can override the host ports with EGG_DEV_SERVICES_MYSQL_PORT and EGG_DEV_SERVICES_REDIS_PORT, but the README is explicit that the full DAL, ORM and Redis local test path still expects the default ports. So the override is useful for a partial run, not for the full suite.

Image overrides exist for compatibility checks, for example EGG_DEV_SERVICES_MYSQL_IMAGE=mysql:5.7 or EGG_DEV_SERVICES_REDIS_IMAGE=redis:7. The README warns that you must run the reset command before switching MySQL image families, because MySQL data directories are not downgrade-compatible across major versions. That is a real operational constraint, not a footnote: switching from MySQL 8 to 5.7 without resetting leaves you with a data directory the older server will not open.

Where Egg.js is the wrong choice

The first limitation is the toolchain. The quickstart depends on utoo and on Node.js 22.18.0 or newer. If your deployment base image, your CI runners or your corporate registry policy pin an older Node release, the quickstart path is closed to you, and the monorepo's own install command assumes utoo's catalog mode. That is a heavier starting position than a framework you add with a single npm install.

The second is the beta default. The quickstart scaffolds egg@beta, and the most recent published tag is a beta release. A team that wants the stable line has to know to ask for it, and the README does not spend a paragraph explaining the trade-off, which is a documentation gap rather than a design flaw.

The third is scope. Egg.js is a convention-heavy framework. If your service is a thin proxy, a webhook receiver, or a single Lambda handler, the plugin system and the directory conventions are overhead you will pay for and never use. The same applies if you already have a strong internal platform: adopting Egg.js means adopting its plugin contract as your extension point, and a team that has already standardised on a different one will be fighting the framework rather than using it.

Finally, the documentation is thin in specific places. The README does not document rollback, does not describe the process model in detail, and does not list which plugins are compatible with the 4.x beta line. Those are the questions to answer from the documentation site and the plugin repositories before you plan a migration.

Egg.js versus plain Koa

The obvious alternative is Koa itself, which is the layer Egg.js is built on. The difference is not performance, it is what is decided for you. Koa gives you a middleware composition model and a context object, and leaves routing, configuration, process management, and code organisation to you or to whatever you assemble. Egg.js takes those decisions and encodes them: a fixed application layout, a plugin contract for extending it, a framework layer for bundling a chosen plugin set, and process management built in.

That trade is legible in the repository. Koa would be a dependency and a handful of files. Egg.js is a monorepo with a main framework package, a plugin directory, a tegg layer for dependency injection and data access, and a test suite that expects MySQL and Redis to be running. You are buying a platform contract, and the price is that the contract is not yours to redefine. For a team of one or two shipping a focused API, Koa plus a router is the smaller and more honest choice. For a platform group that wants twenty services to look alike, the contract is the product.

Licence and the cost of staying current

The repository is MIT licensed, and the root package.json carries the same MIT identifier. MIT is permissive: it allows commercial use, modification and redistribution provided the copyright notice and licence text are preserved. That is a statement about the licence text, not legal advice, and organisations with strict open-source review processes should run it through their own channel.

The upgrade cost is the more practical question. The repository has two lines in flight: a 3.x stable line, with v3.34.0 published on 2026-01-18, and a 4.x beta line, with v4.1.2-beta.27 published on 2026-09-20. The default branch is next, which is where the 4.x work lands, and the last push to the repository was on 2026-09-20. A team on 3.x is therefore not on the branch that receives the newest work, and a team on the 4.x beta is tracking a line that has not yet produced a stable tag. Either way, the plugin ecosystem is the variable to check: the framework's value comes from its plugins, so the practical upgrade question is whether each plugin you depend on has a release for the line you are moving to. The README does not answer that, and the plugin index is a separate search rather than a compatibility table.

Editorial conclusion

Adopt Egg.js when you want Koa middleware plus an enforced directory convention and a plugin system that a platform team can standardise on. Do not adopt it when you want a minimal HTTP layer you fully control, or when you cannot move to Node.js 22.18.0 and the utoo toolchain. Before committing, verify which release line you are pinning: the default branch is next and the newest published tag is a beta, while v3.34.0 is the stable line from 2026-01-18. Check that every plugin you depend on publishes a compatible version for that line, because the plugin system is where the framework's value and its upgrade cost both sit.

Frequently asked questions

Official sources

1. eggjs/egg on GitHub
2. License: MIT
3. Project website
4. README
5. Releases