Version 4.0.0 of ngX-Rocket Now Available

We are thrilled to announce version 4.0.0 of our Angular project generator. This is a major release, meaning that among new features and bugfixes it also comes with some breaking changes if you plan to upgrade your existing projects.

Here’s a list of the biggest changes in v4, along with a migration guide. For the full list, please see the changelog.

For those wondering what’s ngX-Rocket, here is the catch-up version: it’s an extensible, well-documented, enterprise-grade Angular project generator. It comes with popular framework integrations such as Bootstrap, Angular-Material or Ionic and supports multiple targets like PWA or hybrid mobile apps. Learn more about it at https://github.com/ngx-rocket/generator-ngx-rocket.

New features

In addition to the usual round of bugfixes and dependencies updates, a few important features were added to this new version.

HttpClient extension

As soon as the Http service was deprecated, we were willing to make the move to use the new HttpClient API that was introduced with Angular 4.3, but due to https://github.com/angular/angular/issues/18155 we were holding off the move until now. The feature has been reported a few times, and since it’s actually unclear if the API will ever be fixed we decided to take the plunge.

Finding a solution using the new API that keeps the same per-request configuration abilities as what we were doing with the old Http API was quite a challenge, as we wanted to rely on standard HTTP interceptors for compatibility and reusability between projects.

We now use a new HttpService class extending HttpClient that can directly be injected as a replacement of HttpClient, but providing an extra fluent API to configure dynamically your HTTP interceptors per request. For example to cache any HTTP request you just have to call .cache() before making your request:

this.httpClient
   .cache()
   .get('https://myapi.com');

For HTTP interceptors that should always be enabled, you can still use the HTTP_INTERCEPTORS token to provide them.

Lazy loading

If you wanted to enable lazy loading for your feature modules previously you had to make the changes yourself in modules and routes configuration.

When generating a new project, you now have the option to enable lazy loading directly, allowing for better startup performance in large applications. It’s not enabled by default as it requires a bit more complex configuration and may have a negative effect for small applications, so use it with care!

Note: If you choose Ionic for your UI, the lazy loading option is currently disabled due to incompatibilities between the Ionic navigation system and the Angular router lazy loading features (see https://github.com/ngx-rocket/generator-ngx-rocket/pull/241). We are currently searching for a workaround, any help on this would be appreciated.

TypeScript 2.6

New projects now comes with typescript@2.6 installed, the last currently supported version by Angular (2.7 support will comme with Angular 6).

In addition, we fixed compatibility issues when using the --strict mode so can now safely enable it in new projects if you want.

Also, to make sure that future added features won’t break this compatibility as it’s not enabled by default in generated projects, we have now dedicated CI branch builds that check this. 😉

Toolchain only

A new --tools option has been added, allowing to generate only the toolchain and skip application templates. This is especially useful when updating your projects generated with an older version of ngX-Rocket, to limit the number of manual merge operations. See this mini updating guide to know more about project updating.

Migration guide

We are very careful when adding new features in our generator to avoid breaking changes whenever it’s possible and to provide a comprehensible migration path when it’s not.

One of our goals is to lessen the tooling maintenance pain, by providing a way to update existing projects generated with previous versions using our CLI.

First make sure that your project use version control and that you have no pending changes in your working directory. Then update your project with ngx update and merge changes manually using your favorite merge editor.

Once it’s done, you can start migrating your application code.

Routes migration

In order to support the new lazy-loading option of the generator, we had to make small a breaking change in core/route.service.ts:

Route.withShell() method now returns a single route, so you have to update your modules using it. Change your route modules from:

const routes: Routes = Route.withShell([
  {
    path: 'about',
    component: AboutComponent,
    data: { title: extract('About') }
  }
]);

to:

const routes: Routes = [
  Route.withShell([
    {
      path: 'about',
      component: AboutComponent,
      data: { title: extract('About') }
    }
  ])
];

So basically you just have to add brackets [] around the Route.withShell() calls.

HttpService migration

To migrate your application to use the new API, follow these steps:

1. Replace all these imports in your application:

import { Http, Response } from '@angular/http';

with:

import { HttpClient } from '@angular/common/http';

2. Inject HttpClient instead of Http in your service/components.
Instead of:

constructor(private http: Http) { }

use:

constructor(private httpClient: HttpClient) { }

3. The new HttpClient does not provide a way to pass options directly with your requests, so we went with a new fluent API instead.

For example, instead of:

this.http.get(routes.quote(context), { cache: true })

you shall now use:

 this.httpClient
   .cache()
   .get(routes.quote(context))

You may have to adapt this on your specific use cases.

Also, if you added your own extensions to the HttpService class before, you will have to rewrite them as interceptors, then add additional methods to the new HttpService to use them.

See https://angular.io/api/common/http/HttpInterceptor and the new provided default interceptors as example.