Skip to content

docs(ivy): add /migration/lazy-routes to AIO #29730

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

Closed
alexeagle wants to merge 1 commit into from
Closed

docs(ivy): add /migration/lazy-routes to AIO #29730

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
68 changes: 68 additions & 0 deletions aio/content/migration/lazy-routes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Updating Angular Lazy Routes

When we first introduced lazy routes, there wasn't browser support for dynamically loading additional JavaScript.
Angular created our own scheme using the syntax `loadChildren: './lazy/lazy.module#LazyModule'` and built complex tooling to support it.

@kara kara Apr 5, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Can we pull out the old syntax into a code snippet? Otherwise it's hard to find what pattern is necessary to change.

Now that EcmaScript dynamic import is a standard and is supported in many browsers, it's time for Angular applications to use this new syntax.

@trotyl trotyl Apr 14, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

EcmaScript -> ECMAScript for consistency?

@trotyl trotyl Apr 14, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

dynamic import is a standard

It is NOT a standard, which got stuck in stage 3 due to security issue. (Need to land Realms first)


> Updating your lazy routes to dynamic import is *required* in order to use Angular Ivy.

@filipesilva filipesilva Apr 19, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

At the moment it is not required anymore, just highly recommended.

@jbogarthyde jbogarthyde Apr 19, 2019 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This would be where to put the new text from #29955:

The string syntax for the loadChildren route specification is deprecated in Angular version 8, in favor of new syntax that uses an import statement.
As part of updating an application to Angular version 8, it is recommended that you update to the new import syntax.
You can use angular-lazy-routes-fix to perform the transformation automatically.

For example:

const routes: Routes = [{
  path: 'lazy',
  // The string syntax for loadChildren is deprecated:
  //   loadChildren: './lazy/lazy.module#LazyModule'
  // This has been transformed to use the new import syntax.
  loadChildren: () => import('./lazy/lazy.module').then(m => m.LazyModule)
}];

Ivy supports both the deprecated string syntax and the recommended import syntax.
If you have updated your lazy routes to use the import() statement but are not using Ivy,
make sure your default build options in angular.json include the flag "experimentalImportFactories": true.

> See /guide/ivy for full instructions for opting-in to Ivy.

Angular community member Craig Spence created an automated migrator tool, which he writes about at https://blog.angularindepth.com/automatically-upgrade-lazy-loaded-angular-modules-for-ivy-e760872e6084.

We recommend that all Angular developers run this migration, after successfully updating to Angular 8.

## Performing the migration

1. Update to Angular 8. This version includes support for the new dynamic import syntax.

1. Make sure your application is working, and that you are in a clean checkout of your project.
In case the migration causes problems for your application, you maybe want to revert these changes.

1. Install the migrator:

```sh
$ npm install @phenomnomnominal/angular-lazy-routes-fix -D

@trotyl trotyl Apr 14, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Would it better to use full-form of CLI options? People may forget about what it stands for.

```

or for yarn users,

```sh
$ yarn add -D @phenomnomnominal/angular-lazy-routes-fix
```

1. Replace your `tslint.json` file with:

```json
{
"extends": [
"@phenomnomnominal/angular-lazy-routes-fix"
],
"no-lazy-module-paths": [true],
}
```

1. Run `ng lint --fix`

1. Revert the changes to the `tslint.json` file.

1. Make sure your `tsconfig.json` has `module: "esnext"`.
Otherwise you'll get a type-check error from TypeScript that the `import()` syntax is not supported.

1. You can un-install the migrator tool now.

```sh
$ npm uninstall @phenomnomnominal/angular-lazy-routes-fix
```

or for yarn users,

```sh
$ yarn remove @phenomnomnominal/angular-lazy-routes-fix
```

## FAQ

1. Why isn't this migration run automatically by `ng update`?

This migration is optional in Angular 8.

@filipesilva filipesilva Apr 19, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

angular/angular-cli#14181 doesn't seem to be optional currently.

Since we expect the majority of users will not opt-into Ivy, we don't want to introduce the risk of breaking your application in case your code or a library you use depends on the current string-based syntax in some way.

@kara kara Apr 5, 2019

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
Since we expect the majority of users will not opt-into Ivy, we don't want to introduce the risk of breaking your application in case your code or a library you use depends on the current string-based syntax in some way.
Since we expect the majority of users will not opt into Ivy, we don't want to introduce the risk of breaking your application in case your code or a library you use depends on the current string-based syntax in some way.

2 changes: 1 addition & 1 deletion aio/tools/transforms/angular-content-package/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ module.exports = new Package('angular-content', [basePackage, contentPackage])
readFilesProcessor.sourceFiles = readFilesProcessor.sourceFiles.concat([
{
basePath: CONTENTS_PATH,
include: CONTENTS_PATH + '/{getting-started,guide,tutorial}/**/*.md',
include: CONTENTS_PATH + '/{getting-started,guide,tutorial,migration}/**/*.md',
fileReader: 'contentFileReader'
},
{
Expand Down