W3cubDocs

/Angular

Setup for upgrading from AngularJS

Audience: Use this guide only in the context of Upgrading from AngularJS or Upgrading for Performance. Those Upgrade guides refer to this Setup guide for information about using the deprecated QuickStart GitHub repository, which was created prior to the current Angular CLI.

For all other scenarios, see the current instructions in Setting up the Local Environment and Workspace.

This guide describes how to develop locally on your own machine. Setting up a new project on your machine is quick and easy with the QuickStart seed on github.

Prerequisite: Make sure you have Node.js® and npm installed.

Clone

Perform the clone-to-launch steps with these terminal commands.

git clone https://github.com/angular/quickstart.git quickstart
  cd quickstart
  npm install

Download

Download the QuickStart seed and unzip it into your project folder. Then perform the remaining steps with these terminal commands.

cd quickstart
  npm install

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!).

Do this only in the beginning to avoid accidentally deleting your own tests and git setup!

Open a terminal window in the project folder and enter the following commands for your environment:

OS/X (bash)

xargs rm -rf < non-essential-files.osx.txt
  rm src/app/*.spec*.ts
  rm non-essential-files.osx.txt

Windows

for /f %i in (non-essential-files.txt) do del %i /F /S /Q
  rd .git /s /q
  rd e2e /s /q

Update dependency versions

Since the quickstart repository is deprecated, it is no longer updated and you need some additional steps to use the latest Angular.

  1. Remove the obsolete @angular/http package (both from package.json > dependencies and src/systemjs.config.js > SystemJS.config() > map).

  2. Install the latest versions of the Angular framework packages by running:

    npm install --save @angular/[email protected] @angular/[email protected] @angular/[email protected] @angular/[email protected] @angular/[email protected] @angular/[email protected] @angular/[email protected]
  3. Install the latest versions of other packages used by Angular (RxJS, TypeScript, Zone.js) by running:

    npm install --save [email protected] [email protected]
    npm install --save-dev [email protected]
  4. Install the systemjs-plugin-babel package. This will later be used to load the Angular framework files, which are in ES2015 format, using SystemJS.

    npm install --save [email protected]
  5. In order to be able to load the latest Angular framework packages (in ES2015 format) correctly, replace the relevant entries in src/systemjs.config.js:

    System.config({
      /* . . . */
      map: {
        /* . . . */
        '@angular/core': 'npm:@angular/core/fesm2015/core.mjs',
        '@angular/common': 'npm:@angular/common/fesm2015/common.mjs',
        '@angular/common/http': 'npm:@angular/common/fesm2015/http.mjs',
        '@angular/compiler': 'npm:@angular/compiler/fesm2015/compiler.mjs',
        '@angular/platform-browser': 'npm:@angular/platform-browser/fesm2015/platform-browser.mjs',
        '@angular/platform-browser-dynamic': 'npm:@angular/platform-browser-dynamic/fesm2015/platform-browser-dynamic.mjs',
        '@angular/router': 'npm:@angular/router/fesm2015/router.mjs',
        '@angular/router/upgrade': 'npm:@angular/router/fesm2015/upgrade.mjs',
        '@angular/forms': 'npm:@angular/forms/fesm2015/forms.mjs',
        /* . . . */
      },
      /* . . . */
    });
  6. In order to be able to load the latest RxJS package correctly, replace the relevant entries in src/systemjs.config.js:

    System.config({
      /* . . . */
      map: {
        /* . . . */
        'rxjs': 'npm:rxjs/dist/cjs',
        'rxjs/operators': 'npm:rxjs/dist/cjs/operators',
        /* . . . */
      },
      /* . . . */
      packages: {
        /* . . . */
        'rxjs': {
          defaultExtension: 'js',
          format: 'cjs',
          main: 'index.js'
        },
        'rxjs/operators': {
          defaultExtension: 'js',
          format: 'cjs',
          main: 'index.js'
        },
        /* . . . */
      }
    });
  7. In order to be able to load the tslib package (which is required for files transpiled by TypeScript), add the following entry to src/systemjs.config.js:

    System.config({
      /* . . . */
      map: {
        /* . . . */
        'tslib': 'npm:tslib/tslib.js',
        /* . . . */
      },
      /* . . . */
    });
  8. In order for SystemJS to be able to load the ES2015 Angular files correctly, add the following entries to src/systemjs.config.js:

    System.config({
      /* . . . */
      map: {
        /* . . . */
        'plugin-babel': 'npm:systemjs-plugin-babel/plugin-babel.js',
        'systemjs-babel-build': 'npm:systemjs-plugin-babel/systemjs-babel-browser.js'
      },
    
      transpiler: 'plugin-babel',
      /* . . . */
      packages: {
        /* . . . */
        'meta': {
          '*.mjs': {
            babelOptions: {
              es2015: false
            }
          }
        }
      }
    });
  9. Finally, in order to prevent TypeScript typecheck errors for dependencies, add the following entry to src/tsconfig.json:

    {
      "compilerOptions": {
        "skipLibCheck": true,
        // ...
      }
    }

With that, you can now run npm start and have the application built and served. Once built, the application will be automatically opened in a new browser tab and it will be automatically reloaded when you make changes to the source code.

What's in the QuickStart seed?

The QuickStart seed provides a basic QuickStart playground application and other files necessary for local development. Consequently, there are many files in the project folder on your machine, most of which you can learn about later.

Reminder: The "QuickStart seed" example was created prior to the Angular CLI, so there are some differences between what is described here and an Angular CLI application.

Focus on the following three TypeScript (.ts) files in the /src folder.

src
  app
    app.component.ts
    app.module.ts
  main.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `<h1>Hello {{name}}</h1>`
})
export class AppComponent { name = 'Angular'; }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

@NgModule({
  imports:      [ BrowserModule ],
  declarations: [ AppComponent ],
  bootstrap:    [ AppComponent ]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { AppModule } from './app/app.module';

platformBrowserDynamic().bootstrapModule(AppModule);

All guides and cookbooks have at least these core files. Each file has a distinct purpose and evolves independently as the application grows.

Files outside src/ concern building, deploying, and testing your application. They include configuration files and external dependencies.

Files inside src/ "belong" to your application. Add new Typescript, HTML and CSS files inside the src/ directory, most of them inside src/app, unless told to do otherwise.

The following are all in src/

File Purpose
app/app.component.ts

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.

app/app.module.ts

Defines AppModule, the root module that tells Angular how to assemble the application. When initially created, it declares only the AppComponent. Over time, you add more components to declare.

main.ts

Compiles the application with the JIT compiler and bootstraps the application's main module (AppModule) to run in the browser. The JIT compiler is a reasonable choice during the development of most projects and it's the only viable choice for a sample running in a live-coding environment such as Stackblitz. Alternative compilation, build, and deployment options are available.

Appendix: Test using fakeAsync()/waitForAsync()

If you use the fakeAsync()/waitForAsync() helper functions to run unit tests (for details, read the Testing guide), you need to import zone.js/testing in your test setup file.

If you create project with `Angular/CLI`, it is already imported in `src/test.ts`.

And in the earlier versions of Angular, the following files were imported or added in your html file:

import 'zone.js/plugins/long-stack-trace-zone';
import 'zone.js/plugins/proxy';
import 'zone.js/plugins/sync-test';
import 'zone.js/plugins/jasmine-patch';
import 'zone.js/plugins/async-test';
import 'zone.js/plugins/fake-async-test';

You can still load those files separately, but the order is important, you must import proxy before sync-test, async-test, fake-async-test and jasmine-patch. And you also need to import sync-test before jasmine-patch, so it is recommended to just import zone-testing instead of loading those separated files.

© 2010–2021 Google, Inc.
Licensed under the Creative Commons Attribution License 4.0.
https://angular.io/guide/upgrade-setup