MIGRATION.md

Migration Guides

If this guide is not clear, feel free to create an issue!

Custom Configurations

For all migrations, first, make sure you have no altered any of the following files:

• karma.conf.js
• tasks/rollup.js
• webpack/*

If you have, it is highly suggested that you move whatever customizations you have done into configuration files per the Custom Configurations section of the README.md.

Upgrading

Unless the migration states it, the best path of migration is to first use the built-in upgrade command in one of the following ways:

ngl u
ngl up
ngl upgrade
npm run g u
npm run g up
npm run g ugrade

After doing that, following the version-specific list of migration steps.

Again, if read the migration steps first before running this command. You may need to take steps before running the upgrade command!

Migrations

• 1.0.0
• 1.0.0-beta.13
• < 1.0.0-beta.12 to 1.0.0-beta.12

1.0.0

Upgrade Node Version

In order to support the latest and greatest, Librarian now requires a version of Node >= 8.6 to support the spread operator on Objects. See this issue for the discussion.

Removing np

Older projects that upgrade to v1.0.0 should make sure that the np library is removed from the local project and installed globally. When Angular upgraded to version 5, it upgraded RxJS to v5.5.x--the np library will break if it uses RxJS past 5.4.3.

To ensure np is not installed locally, after upgrading Librarian (see above):

1. Check that it is not installed:

   npm ls np

2. If np shows up in the ls command, remove it:

   npm rm --save-dev np

3. Install it globally:

   npm install -g np

Typings

For a while TypeScript has been leveraging the @types organization to manage type definitions. Prior to this it used typings. Using typings now gives a deprecation warning, so it can be removed from your projects with:

npm rm --save-dev typings

While this shouldn't affect your project, it is always good to remove deprecated technologies.

Rollup Failing

If you are having issues similar to issue #89, try deleting your package-lock.json file, as suggested by @SirDarquan. The lock file can cause old files to remain and not be overwritten (because its job is to create consistency), by deleting & performing npm install again, you may have success.

1.0.0-beta.13

A small bug was introduced and not accounted for with tasks/rollup.js. Line 28 reads:

moduleName: librarianUtils.dashToCamel(nameParts.package),

But should read:

moduleName: librarianUtils.caseConvert.dashToCamel(nameParts.package),

The bug has been fixed but will not be available until the next release.

From < 1.0.0-beta.12 to 1.0.0-beta.12

To perform this migration, make the changes below.

Note, should be the value of the name attribute in your package.json without scope (i.e, @myscope/my-package should be my-package).

1. Go into your package.json and set the angular-librarian version to 1.0.0-beta.12, run npm update, then run ngl upgrade
2. Remove files:
   • tsconfig.build.json
   • webpack/webpack.build.json
3. Remove from package.json:
   • scripts
     • build:aot
     • build:copy
     • build:pack
     • pretagVersion
   • jsnext:main
   • types
4. Add to package.json:
   • "es2015": "./<package name>.js"
   • "module": "./<package name>.es5.js"
   • "typings": "./<package name>.d.ts"
5. Change in package.json:
   • "main": "./<package name>.bundle.js" to "main": "./bundles/<package name>.umd.js"
   • "angular-librarian": "<version>" to "angular-librarian": "1.0.0-beta.12"
6. Change in build TS configs (tsconfig.es5.json and tsconfig.es2015.json):
   • "flatModuleOutFile": "{{ packageName }}.js" to "flatModuleOutFile": "<package name>.js"
7. Any Angular packages you may be pulling in, should be added to a configs/rollup.config.js, per the Custom Configurations documentation. For instance, if you pull in @angular/forms, the Rollup config would be:

'use strict';

module.exports = {
    external: [
        '@angular/forms',
    ],
    globals: {
        '@angular/forms': 'ng.forms',
    }
};

Run npm install and/or npm update again, to ensure all dependencies are up-to-date.