Skip to content

chore(docs): add webpack update instructions #1456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 3, 2016
Merged

chore(docs): add webpack update instructions #1456

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,12 @@ This project is very much still a work in progress.
The CLI is now in beta.
If you wish to collaborate while the project is still young, check out [our issue list](https://github.com/angular/angular-cli/issues).

## Webpack preview release update

We're updating the build system in Angular-CLI to use webpack instead of Broccoli.

You can install and update your projects using [these instructions](https://github.com/angular/angular-cli/blob/master/WEBPACK_UPDATE.md).

## Prerequisites

The generated project has dependencies that require **Node 4 or greater**.
Expand Down
60 changes: 60 additions & 0 deletions WEBPACK_UPDATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Upgrading from [email protected] to the angular-cli@webpack

To update `angular-cli` to the webpack preview, you must update both the global package, project's local package and your project files.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically the global package shouldn't care about it. Only the local package needs to be installed.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the official update procedure for ember-cli itself actually. I don't think it's a good idea to have de-synced versions of global and local... plus without the global version your ng new will generate old projects.


## Global package:
```
npm uninstall -g angular-cli
npm cache clean
npm install -g angular-cli@webpack
```

## Local project package:
```
# commit any changes you have to git first
rm -rf node_modules dist tmp typings
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should tell them to git commit everything before doing the upgrade.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

npm install --save-dev angular-cli@webpack
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the release to npm w/ webpack the @webpack is not needed

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hans said that the release would not be made as 1.0.0-beta.11 but rather as webpack, so we need to install that particular version for now.

```

IMPORTANT NOTE:
Currently project generated with `ng new` will use a wrong local CLI version (see https://github.com/angular/angular-cli/issues/1528). After initializing your project, run `npm install --save-dev angular-cli@webpack` to set the correct version.

## Project files

You will need to run `ng init` to check for changes in all the auto-generated files created by `ng new` and allow you to update yours. You are offered four choices for each changed file: `y` (overwrite), `n` (don't overwrite), `d` (show diff between your file and the updated file) and `h` (help).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remove ng init. It's dangerous that people are relying on it; it will not touch files that have been deleted, or files added by the user. We need to list a higher level list of things to take care when updating the application.


Carefully read the diffs for each code file, and either accept the changes or incorporate them manually after `ng init` finishes.

You can find a sample github diff of the changes introduced between a beta.10 and webpack preview project at https://github.com/filipesilva/angular-cli-webpack-upgrade/commit/HEAD.

Here is a summary of the file changes:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Separate this into 5 groups: Unit tests, E2E tests, App code / Components, Project Config, and App Config.

Example:

Unit Tests

Karma Configuration

  • Introduced an angular-cli karma plugin to help us integrate with karma. To add this plugin, replace your frameworks and plugins entries in your karma config by these:
    frameworks: ['jasmine', 'angular-cli'],
    plugins: [
      require('karma-jasmine'),
      require('karma-chrome-launcher'),
      require('karma-coverage'),
      require('angular-cli/plugins/karma')
    ],
  • Note that we also added karma-coverage to handle coverage reporting. If you don't want coverage, you can safely remove it.
  • Removed all the files entries. We only need to link the entry point for testing, which is test.ts. Replace your files entry by:
    files: [
      { pattern: './src/test.ts', watched: false }
    ],
  • We need to add a preprocessor for the file, as it will be handled by the angular-cli plugin:
    preprocessors: {
      './src/test.ts': ['angular-cli']
    },


1. Updated files:
* `./config/karma.conf.js` - `frameworks`/`plugins`/`files`/`exclude`/`preprocessors` entries changed, added `angularCliConfig` entry.
* `./e2e/tsconfig.json` - property cleanup, changed `outdir`, added `typeRoots`
* `./angular-cli.json` - updated version entry.
* `./README.md` - updated version entry, removed route from generator list.
* `./package.json` - removed typings postinstall script, removed `ember-cli-inject-live-reload`/`es6-shim`/`systemjs` dependencies, added `core-js`/`ts-helpers` dependencies, updated `angular-cli`/`codelyzer`/`ts-node`/`ts-lint`/`typescript` devDependencies, added `@types/jasmine`/`@types/protractor`/`karma-coverage` devDependencies.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should #1468 be merged in before the @webpack release, karma-remap-istanbul will be added to the devDependencies list.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aiming to get his merged in asap, so will update it later with this change for an upcoming release.

* `./src/app/app.component.ts` (and all other components) - removed `module.id`, sass/less/stylus preprocessing now uses the real extension in `styleUrls` instead of `.css`.
* `./src/app/index.ts` - import adjusted due to environment files moving (see below).
* `./src/index.html` - removed templating tags and `SystemJS` import script.
* `./src/app/tsconfig.json` - property cleanup, changed `outdir`/`module`, added `libs`/`typeRoots`/`types`
* `./src/typings.d.ts` - added `System`/`require` typings, removed `typings` ref
1. Mobile app updated files:
* `./package.json` - local versions of `angular2-universal` now used by the build system, updated package versions.
* `./src/index.html` - moved service worker code to build system, hardcoded icons.
* `./src/main-app-shell.ts` - reworked to interface with the build system, see comments in file.
1. New files:
* `./src/polyfills.ts` - loads needed polyfills before main app
* `./src/test.ts` - unit test spec loader
1. These files have moved to `./src/app/environments/`:
* `./config/environment.dev.ts`
* `./config/environment.prod.ts`
* `./src/app/environment.ts`

Lastly, you can delete these files as they are not needed anymore.
* `./config/karma-test-shim.js`
* `./src/system-config.ts`
* `./angular-cli-build.js`
* `./typings.json`
* `./.clang-format` (if present)