This guide covers getting up and running a real example using Egg. By following along with this guide step by step, you can quickly get started with Egg development.
- Operating System: Linux, OS X or Windows.
- Node.js Runtime: 8.x or newer; it is recommended that you use LTS Releases.
# The Quick Way
To begin with, let's quickly initialize the project by using a scaffold,
which will quickly generate some of the major pieces of the application (
$ mkdir egg-example && cd egg-example
Then get up and run by using the following commands.
$ npm run dev
# Step by Step
Usually you can just use
npm init egg of the previous section,
choose a scaffold that best fits your business model and quickly generate a project,
then get started with the development.
However, in this section, instead of using scaffolds we will build a project called Egg HackerNews step by step, for a better understanding of how it works.
First let's create the project directory and initialize its structure.
$ mkdir egg-example
npm scripts to
# Create a Controller
Then edit the router file and add a mapping.
Then add a configuration file:
The project directory looks like this:
For more information about directory structure, see Directory Structure.
Now you can start up the Web Server and see your application in action.
$ npm run dev
# Adding Static Assets
Egg has a built-in plugin called static. In production, it is recommended that you deploy static assets to CDN instead of using this plugin.
/public/* to the directory
app/public/* by default.
In this case, we just need to put our static assets into the directory
# Adding Templates for Rendering
In most cases, data are usually read, processed and rendered by the templates before being presented to the user. Thus we need to introduce corresponding template engines to handle it.
Egg does not force to use any particular template engines, but specifies the View Plugins Specification to allow the developers to use different plugins for their individual needs instead.
For more information, cf. View.
In this example, we will use Nunjucks.
First install the corresponding plugin egg-view-nunjucks.
$ npm i egg-view-nunjucks --save
And enable it.
config dir, not
Then create a template for the index page. This usually goes to the app/view directory.
<!-- app/view/news/list.tpl -->
Then add a controller and router.
Open a browser window and navigate to http://localhost:7001/news. You should be able to see the rendered page.
Tip：In development, Egg enables the development plugin by default, which reloads your worker process when changes are made to your back-end code.
# Create a Service
In practice, controllers usually won't generate data on their own, neither will they contain complicated business logic. Complicated business logic should be abstracted as a busineess logic layer instead, i.e., service.
Let's create a service to fetch data from the HackerNews.
Egg has HttpClient built in in order to help you make HTTP requests.
Then slightly modify our previous controller.
And also add config.
# Adding Extensions
We might encounter a small problem here. The time that we fetched are Unix Time format, whereas we want to present them in a more friendly way to read.
Egg provides us with a quick way to extend its functionalities.
We just need to add extension scripts to the
For more information, cf. Extensions.
In the case of view, we can just write a helper as an extension.
$ npm i moment --save
Then use it in the templates.
<!-- app/view/news/list.tpl -->
# Adding Middlewares
Suppose that we wanted to prohibit accesses from Baidu crawlers.
Smart developers might quickly guess that we can achieve it by adding a middleware that checks the User-Agent.
Now try it using
curl localhost:7001/news -A "Baiduspider".
See Middleware for more details.
# Adding Configurations
When writing business logic, it is inevitable that we need to manage configurations. Egg provides a powerful way to manage them in a merged configuration file.
- Environment-specific configuration files are well supported, e.g. config.local.js, config.prod.js, etc.
- Configurations could be set wherever convenient for Applications/Plugins/Frameworks, and Egg will be careful to merge and load them.
- For more information on merging, see Configurations.
# Adding Unit Testing
Unit Testing is very important, and Egg also provides egg-bin to help you write tests painless.
All the test files should be placed at
Also install dependencies.
$ npm i egg-mock --save-dev
$ npm test
That is all of it, for more detail, see Unit Testing.
We can only touch the tip of the iceberg of Egg with the above short sections. Where to go from here? read our documentation to better understand the framework.
- About Egg boilerplate type, See Boilerplate Type Description.
- Egg provides a powerful mechanism for extending features. See Plugin.
- Egg framework allows small or large teams to work together as fast as possible under the well-documented conventions and coding best practices. In addition, the teams can build up logics on top of the framework to better suit their special needs. See more on [Frameworks].(../advanced/framework.md).
- Egg framework provides code reusabilities and modularities. See details at Progressive.
- Egg framework enables developers to write painless unit testing with many plugins and community-powered toolings. The team should give it a try by using Egg unit testing without worrying about setting up the testing tooling but writing the testing logics. See Unit Testing.