forked from angular/angular.io
-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathsetup.jade
221 lines (182 loc) · 8.55 KB
/
setup.jade
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
block includes
include ../_util-fns
- var _prereq = 'node and npm';
- var _playground = 'playground';
- var _Install = 'Install';
//- npm commands
- var _install = 'install';
- var _start = 'start';
a#develop-locally
:marked
## Setup a local development environment
<span if-docs="ts">
The <live-example name=quickstart>QuickStart live-coding</live-example> example is an Angular _playground_.
It's not where you'd develop a real application.
You [should develop locally](#why-locally "Why develop locally") on your own machine ... and that's also how we think you should learn Angular.
</span>
Setting up a new project on your machine is quick and easy with the **QuickStart seed**,
maintained [on github](!{_qsRepo} "Install the github QuickStart repo").
.l-sub-section
:marked
The <live-example title="QuickStart Seed in Plunker">QuickStart seed live-example</live-example> is QuickStart
_plus_ the `app.module.ts` and `main.ts` application files ([described below](#app-files "QuickStart application files")) that facilitate richer application examples.
:marked
Make sure you have [!{_prereq} installed](#install-prerequisites "What if you don't have !{_prereq}?").
Then ...
1. Create a project folder (you can call it `quickstart` and rename it later).
1. [Clone](#clone "Clone it from github") or [download](#download "download it from github") the **QuickStart seed** into your project folder.
1. !{_Install} [!{_npm}](#install-prerequisites "What if you don't have !{_prereq}?") packages.
1. Run `!{_npm} !{_start}` to launch the sample application.
a#clone
:marked
### Clone
Perform the _clone-to-launch_ steps with these terminal commands.
code-example(language="sh" class="code-shell").
git clone !{_qsRepo}.git quickstart
cd quickstart
!{_npm} !{_install}
!{_npm} !{_start}
.alert.is-important
:marked
`npm start` fails in _Bash for Windows_ which does not support networking to servers as of January, 2017.
a#download
:marked
### Download
<a href="!{_qsRepoZip}" title="Download the QuickStart seed repository">Download the QuickStart seed</a>
and unzip it into your project folder. Then perform the remaining steps with these terminal commands.
code-example(language="sh" class="code-shell").
cd quickstart
!{_npm} !{_install}
!{_npm} !{_start}
.alert.is-important
:marked
`npm start` fails in _Bash for Windows_ which does not support networking to servers as of January, 2017.
a#non-essential
.l-main-section
:marked
## Delete _non-essential_ files (optional)
You can quickly delete the _non-essential_ files that concern testing and QuickStart repository maintenance
(***including all git-related artifacts*** such as the `.git` folder and `.gitignore`!).
.alert.is-important
:marked
Do this only in the beginning to avoid accidentally deleting your own tests and git setup!
:marked
Open a terminal window in the project folder and enter the following commands for your environment:
### OS/X (bash)
code-example(language="sh" class="code-shell").
xargs -a non-essential-files.txt rm -rf
rm app/*.spec*.ts
rm non-essential-files.txt
:marked
### Windows
code-example(language="sh" class="code-shell").
for /f %i in (non-essential-files.txt) do del %i /F /S /Q
rd .git /s /q
rd e2e /s /q
a#seed
.l-main-section
:marked
## What's in the QuickStart seed?
block qs-seed
:marked
The **QuickStart seed** contains the same application as the QuickStart playground.
But its true purpose is to provide a solid foundation for _local_ development.
Consequently, there are _many more files_ in the project folder on your machine,
most of which you can [learn about later](setup-systemjs-anatomy.html "Setup Anatomy").
block core-files
a#app-files
:marked
Focus on the following three TypeScript (`.ts`) files in the **`/app`** folder.
.filetree
.file app
.children
.file app.component.ts
.file app.module.ts
.file main.ts
+makeTabs(`
setup/ts/app/app.component.ts,
setup/ts/app/app.module.ts,
setup/ts/app/main.ts
`, '', `
app/app.component.ts,
app/app.module.ts,
app/main.ts
`)(format='.')
:marked
All guides and cookbooks have _at least these core files_. Each file has a distinct purpose and evolves independently as the application grows.
style td, th {vertical-align: top}
table(width="100%")
col(width="20%")
col(width="80%")
tr
th File
th Purpose
tr
td <ngio-ex>app.component.ts</ngio-ex>
td
:marked
Defines the same `AppComponent` as the one in the QuickStart !{_playground}.
It is the **root** component of what will become a tree of nested components
as the application evolves.
tr(if-docs="ts")
td <code>app.module.ts</code>
td
:marked
Defines `AppModule`, the [root module](appmodule.html "AppModule: the root module") that tells Angular how to assemble the application.
Right now it declares only the `AppComponent`.
Soon there will be more components to declare.
tr
td <ngio-ex>main.ts</ngio-ex>
td
:marked
Compiles the application with the [JIT compiler](../glossary.html#jit)
and [bootstraps](appmodule.html#main "bootstrap the application") the application to run in the browser.
That's a reasonable choice for the development of most projects and
it's the only viable choice for a sample running in a _live-coding_ environment like Plunker.
You'll learn about alternative compiling and deployment options later in the documentation.
.l-sub-section
:marked
### Next Step
If you're new to Angular, we recommend staying on the [learning path](learning-angular.html "Angular learning path").
br
br
a#install-prerequisites
.l-main-section
:marked
## Appendix: !{_prereq}
block install-tooling
:marked
Node.js and npm are essential to modern web development with Angular and other platforms.
Node powers client development and build tools.
The _npm_ package manager, itself a _node_ application, installs JavaScript libraries.
<a href="https://docs.npmjs.com/getting-started/installing-node" target="_blank" title="Installing Node.js and updating npm">
Get them now</a> if they're not already installed on your machine.
**Verify that you are running node `v4.x.x` or higher and npm `3.x.x` or higher**
by running the commands `node -v` and `npm -v` in a terminal/console window.
Older versions produce errors.
We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of node and npm.
You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that
use other versions of node and npm.
+ifDocsFor('ts')
a#why-locally
.l-main-section
:marked
## Appendix: Why develop locally
<live-example title="QuickStart Seed in Plunker">Live coding</live-example> in the browser is a great way to explore Angular.
Links on almost every documentation page open completed samples in the browser.
You can play with the sample code, share your changes with friends, and download and run the code on your own machine.
The [QuickStart](../quickstart.html "Angular QuickStart Playground") shows just the `AppComponent` file.
It creates the equivalent of `app.module.ts` and `main.ts` internally _for the playground only_.
so the reader can discover Angular without distraction.
The other samples are based on the QuickStart seed.
As much fun as this is ...
* you can't ship your app in plunker
* you aren't always online when writing code
* transpiling TypeScript in the browser is slow
* the type support, refactoring, and code completion only work in your local IDE
Use the <live-example title="QuickStart Seed in Plunker"><i>live coding</i></live-example> environment as a _playground_,
a place to try the documentation samples and experiment on your own.
It's the perfect place to reproduce a bug when you want to
<a href="https://github.com/angular/angular.io/issues/new" target="_blank" title="File a documentation issue">file a documentation issue</a> or
<a href="https://github.com/angular/angular/issues/new" target="_blank" title="File an Angular issue">file an issue with Angular itself</a>.
For real development, we strongly recommend [developing locally](#develop-locally).