181 lines
7.1 KiB
Plaintext
181 lines
7.1 KiB
Plaintext
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").
|
|
|
|
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}
|
|
|
|
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}
|
|
|
|
.l-main-section#seed
|
|
:marked
|
|
## What's in the QuickStart seed?
|
|
|
|
block qs-seed
|
|
:marked
|
|
The **QuickStart seed** contains the same application as the QuickStart playground
|
|
and even has <live-example>its own _playground_</live-example>
|
|
that accomodates development of richer examples in a live coding environment.
|
|
|
|
But it's 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
|
|
: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).
|
|
|
|
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>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><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).
|