Skip to content

Commit 9e21e19

Browse files
geekdadageekdada
committed
docs: quickstart/egg.md
1 parent a8ace9a commit 9e21e19

File tree

2 files changed

+160
-5
lines changed

2 files changed

+160
-5
lines changed

‎docs/quickstart/README.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

‎docs/quickstart/egg.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: Your first Egg application
3+
---
4+
5+
It's time to get your hands dirty. In this guide, we'll walk you through every step of building a (really) simple Egg application.
6+
7+
:::tip Tips
8+
- This guide is for beginners who want to get started with an Egg application from scratch.
9+
- Most of the plugins are included in Egg by default. You can switch them on/off in the configurations.
10+
- More information can be found in [Guide](../guide/README.md).
11+
:::
12+
13+
## TodoMVC
14+
15+
We'll build a [TodoMVC](http://todomvc.com/) application from scratch, using Egg.
16+
17+
The complete version can be found at [eggjs/examples/todomvc](https://github.com/eggjs/examples/tree/master/todomvc).
18+
19+
<!-- ![](./images/todomvc.png) -->
20+
21+
## Creating an Egg aplication
22+
23+
### Preparation
24+
25+
- **OS**: All operating systems are supported, but `macOS` is recommended.
26+
- **Node.js**: If you are new to Node.js, there's an [installation guide here](./prepare.md).
27+
28+
### Scaffolding
29+
30+
There's a [tool](../workflow/development/init.md) for scaffolding Egg applications.
31+
32+
:::tip Tips
33+
The examples below use $ to represent the terminal prompt in a UNIX-like OS, it might be different in some occasions.
34+
:::
35+
36+
```bash
37+
$ mkdir demo && cd demo
38+
$ npm init egg --type=simple
39+
$ npm install
40+
```
41+
42+
### Directory
43+
44+
The `demo` directory will be looking like this. They are generated by following [the directory rules](../guide/directory.md) of an Egg application. We strongly recommend you to follow it when creating new folders.
45+
46+
```bash
47+
demo
48+
├── app
49+
│   ├── controller # Controllers
50+
│   │   └── home.js
51+
│   └── router.js # Routers
52+
├── config # Configurations
53+
│   ├── config.default.js
54+
│   └── plugin.js
55+
├── test # Testing files
56+
├── README.md
57+
└── package.json
58+
```
59+
60+
### `Controller`
61+
62+
[Controller](../guide/controller.md) is responsible for **parsing user requests**, **handling them** and **response back**.
63+
64+
```js
65+
// app/controller/home.js
66+
const { Controller } = require('egg');
67+
68+
class HomeController extends Controller {
69+
async index() {
70+
const { ctx } = this;
71+
ctx.body = 'hi, egg';
72+
}
73+
}
74+
75+
module.exports = HomeController;
76+
```
77+
78+
Every controller needs to be set to a certain `URL` which tells Egg when to handle incoming requests. In the case below, `/` would be handled with the controller you just wrote.
79+
80+
```js
81+
// app/router.js
82+
/**
83+
* @param {Egg.Application} app - egg application
84+
*/
85+
module.exports = app => {
86+
const { router, controller } = app;
87+
router.get('/', controller.home.index);
88+
};
89+
```
90+
91+
### Local Development
92+
93+
Egg comes with a [tool](../workflow/development/development.md) for local development.
94+
95+
- Getting your application up;
96+
- Watching file changes;
97+
- Generating `d.ts` files if you're using TypeScript;
98+
99+
To start your application:
100+
101+
```bash
102+
$ npm run dev
103+
```
104+
105+
Next, go to `http://127.0.0.1:7001` in your browser.
106+
107+
### Template Rendering
108+
109+
In most cases, we want to present web pages to users, using template rendering. But Egg doesn't come with this feature enabled by default. You have to choose a *template engine plugin* and enable it by yourself.
110+
111+
:::tip What is *Plugins*?
112+
The plugin system is a special feature of Egg. It makes the core simple enough, yet stable and highly efficient. You can also use plugins for business logic reusing and building an eco-system.
113+
114+
Go to [Development - Plugins](../guide/plugin.md) to see more.
115+
:::
116+
117+
In this guide, we'll be using [Nunjucks](https://mozilla.github.io/nunjucks/) to render our pages.
118+
119+
To start, you need to install [egg-view-nunjucks] first.
120+
121+
```bash
122+
$ npm i egg-view-nunjucks --save
123+
```
124+
125+
Then, enable it.
126+
127+
```js
128+
// config/plugin.js
129+
exports.nunjucks = {
130+
enable: true,
131+
package: 'egg-view-nunjucks'
132+
};
133+
```
134+
135+
Every template file should be located in `app/view` and its enclosing folders.
136+
137+
```html
138+
<!-- app/view/home.tpl -->
139+
<html>
140+
...
141+
<script src="/public/main.js"></script>
142+
</html>
143+
```
144+
145+
Lastly, change your `Controller` into this.
146+
147+
```js
148+
class HomeController extends Controller {
149+
async index() {
150+
const { ctx } = this;
151+
// 渲染模板 `app/view/home.tpl`
152+
await ctx.render('home.tpl');
153+
}
154+
}
155+
```
156+
157+
[Node.js]: http://nodejs.org
158+
[egg-static]: https://github.com/eggjs/egg-static
159+
[egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks
160+
[Nunjucks]: https://mozilla.github.io/nunjucks/

0 commit comments

Comments
 (0)