Skip to content
Get packs

Guide · Open source

How to use Egg: install, run and build apps with eggjs

Updated · written with AI from the project's own documentation and checked against our catalogue data

Egg is an open-source Node.js framework built on top of Koa, aimed at larger web applications and enterprise-style backends. This guide walks through the quickstart from the project README: installing the required tooling, creating an Egg app, running it locally and finding your way around the monorepo. By the end you will know what you need installed, how to start a dev server and where to look next.

Eggeggjs/egg · ★ 19k · MIT

Quick start

  1. 1Check Node.js version. Confirm you have Node.js 22.18.0 or newer installed before continuing.
  2. 2Install utoo globally. Run npm install --global utoo@latest to get the utoo tool used by the quickstart.
  3. 3Create a project directory. Make a folder called showcase and move into it with mkdir showcase && cd showcase.
  4. 4Create an Egg app. Run ut create egg@beta to generate the Egg application from the template.
  5. 5Install dependencies. Run ut install inside the project directory to install packages.
  6. 6Start the dev server. Run ut run dev, then open http://localhost:7001 in your browser.

What Egg is and who it is for

Egg is a framework for building Node.js web applications and backends. According to its README, it provides built-in process management, a plugin system, and the ability to customize the framework itself.

It suits teams building larger Node.js backend applications that need structure, developers who already know Koa and want a more opinionated layer on top, and TypeScript developers, since the project is written in TypeScript.

  • Built-in Process Management
  • Plugin System
  • Framework Customization
  • Lots of plugins tagged egg-plugin

Check the requirements before you install

The README requires Node.js 22.18.0 or newer. It recommends using the latest patch of an active LTS release for production.

You need npm to install utoo globally. Docker is only needed for the optional local MySQL and Redis test services, so you can skip it for a basic app.

  • Node.js 22.18.0 or newer (required)
  • npm (to install utoo globally)
  • Docker (optional, only for local MySQL/Redis test services)
node --version

Install utoo and create an Egg app

The quickstart uses utoo, a tool the README runs in place of plain npm commands. Install it globally, create a project directory, then generate an Egg app from the beta template.

The commands below are copied from the README. Run them in a terminal.

npm install --global utoo@latest mkdir showcase && cd showcase ut create egg@beta ut install

Run the app locally

Start the development server with the README's dev command, then open the address in your browser. The README gives port 7001 as the local address.

  • Open http://localhost:7001 after the dev server starts
ut run dev open http://localhost:7001

Understand the monorepo layout

The Egg repository is a utoo monorepo. It contains the main framework package, two example applications (CommonJS and TypeScript), and the documentation site. The README says it uses utoo catalog mode to keep dependency versions consistent across packages.

The repository's development commands install, build and test all packages, and you can target a single package with a filter.

  • packages/egg - Main Eggjs framework
  • examples/helloworld-commonjs - CommonJS example application
  • examples/helloworld-typescript - TypeScript example application
  • site - Documentation website
ut install ut run build ut run test ut --filter=egg run test ut --filter=@examples/helloworld-typescript run dev ut --filter=site run dev

Start optional local MySQL and Redis services

Only some database, ORM, Redis and ecosystem tests need local services. The README says the start command runs MySQL 8 and Redis 7 in Docker on the default ports 3306 and 6379, and creates several test databases. If those ports are already in use, the command stops before changing containers.

Use the status, stop and reset commands to manage these services. Run reset before switching MySQL image families, because MySQL data directories are not downgrade-compatible across major versions.

  • Start: ut run dev:services:start
  • Status: ut run dev:services:status
  • Stop: ut run dev:services:stop
  • Reset: ut run dev:services:reset
ut run dev:services:start ut run dev:services:status ut run dev:services:stop ut run dev:services:reset

What people use it for

  • Building larger Node.js backend applications that need a structured layout
  • Adding features from the plugin ecosystem tagged egg-plugin
  • Writing a backend in TypeScript, using the helloworld-typescript example as a reference
  • Studying or contributing to the framework through the monorepo's packages and examples

Frequently asked questions

Is Egg free to use?

Yes. The README states the licence is MIT, and the repository's license file is linked from the README. Check the LICENSE file in the repository for the full terms.

What version of Node.js does Egg need?

The README requires Node.js 22.18.0 or newer. It also recommends the latest patch of an active LTS release for production use.

Do I need Docker to use Egg?

No. The README says Docker is only needed for the optional local MySQL and Redis test services, which are used by some database and Redis tests.

Why does the quickstart use utoo instead of npm?

The README uses the utoo tool in its quickstart and development commands rather than plain npm commands. npm is still needed to install utoo globally.

How is Egg different from Koa?

Egg is built on top of Koa and, according to the README, adds built-in process management, a plugin system and framework customization. Koa is a lighter base layer, so Egg adds more structure on top of it.

What are the alternatives to Egg?

The README does not compare Egg with other tools. Projects commonly compared with it include Koa, Express, NestJS and Fastify, which you can evaluate against your own needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Egg suits teams building larger Node.js backends who want structure, a plugin ecosystem and TypeScript support, especially if they already know Koa. If you want a very small, minimal server library, or your environment cannot run Node.js 22.18.0 or newer, pick a lighter option such as Koa, Express or Fastify.

Install options & downloads