ngx-hybrid-helper
Overview
This package helps to bootstrap an AngularJS application with Angular 5, so that you can migrate easily.
This is certainly not the only way to run an hybrid application, but it worked for me for many applications.
There are few steps to follow, but it can save some of your time, that I've lost to find this configuration.
You should read the official angular documentation about how to upgrade AngularJS apps https://angular.io/guide/upgrade
Prerequisites
- Node v8+
- npm v5+
Steps
You have to do the following steps so that it can work.
step-1 Install package
Install the ngx-hybrid-helper
package :
npm install ngx-hybrid-helper --save
step-2 Install Angular dependencies
Install the following Angular dependencies :
"@angular/common": "~5.1.0"
"@angular/compiler": "~5.1.0",
"@angular/core": "~5.1.0",
"@angular/platform-browser": "~5.1.0",
"@angular/platform-browser-dynamic": "~5.1.0",
"@angular/upgrade": "~5.1.0",
"core-js": "~2.5.3",
"rxjs": "~5.5.5",
"zone.js": "^0.8.4"
npm install @angular/common@~5.1.0 @angular/compiler@~5.1.0 @angular/core@~5.1.0 @angular/platform-browser@~5.1.0 @angular/platform-browser-dynamic@~5.1.0 @angular/upgrade@~5.1.0 core-js@~2.5.3 rxjs@~5.5.5 zone.js@^0.8.4 --save
Install the following devDependencies :
"typescript": "~2.4.2",
"webpack-dev-server": "~2.9.5",
"rimraf": "^2.5.4"
npm install typescript@~2.4.2 webpack-dev-server@~2.9.5 rimraf@^2.5.4 --save-dev
step-3 Create TypeScript configuration file
At the root of your application, create a tsconfig.json
file that contains :
typings/typings.d.ts
file, usefull for TypeScript
step-4 Create a The file should contain :
declare ; declare ; declare ;
WebPack
configuration file
step-5 Create At the root of the application, create a webpack.config.js
file that should contains
const path = ;const webPackGenericConf = ; module { const webPackConfig = ; return webPackConfig;};
app/ngx/imports.ts
file
step-6 Create an This file will tell to TypeScript transpiler which files to import in the application.
Create this file in a ngx
directory, it should contains :
//polyfills for es5 browsers;//Import ng1 component;//Import ng5 scripts;
package.json
step-7 Replace start command line in
step-8 Create a main AngularJS module
Create an AngularJS module that depends on ngx-hybrid-helper
and on your main module (the one which is in the ng-app
property)
angular;
step-9 Create a main AngularJS component
Create an AngularJS component named ng1AppRoot
that will be your root node, it should contains your main component that was in your index.html
angular //<- replace by your main module (from ng-app) ;
index.html
step-10 index.html
Remove ng-app from You have to remove your ng-app="your-main-app-module"
from your index.html
, because from now, it is Angular 5 that will bootstrap your application.
Replace your main AngularJS node
<!--Remove this node--><!--Add this one-->
step-11 Run your application
Launch npm start
, open your browser on localhost:8000
, and your application should be running as before, but bootstraped by Angular 5.
Next steps to develop Angular modules
With previous steps, you have validated that your AngularJS application could be running with Angular 5, but if it's not working, don't pursue next steps.
Create your own components
To add your own Angular code to your application, you have to bootstrap the application by your own in order to add your modules in the build process.
step-1 Root module
In the ngx
directory, create an app.module.ts
file, it will be the main module of your application.
The file should contains
;;;
step-2 bootstrap application
In the ngx
directory, create an app.bootstrap.ts
file, it will bootstrap your main AppModule
The file should contains
; ; platformBrowserDynamic.bootstrapModuleAppModule;
step-3 Import bootstrap file
In the app/ngx/imports.ts
file, change this :
//Remove this line;//Replace with this one;
step-4 Run application
Launch npm start
, open your browser on localhost:8000
, and your application should be running as before, but bootstraped by your own Angular 5 module.
step-5 Create your components
You can now create your components/services... and import them in the app.module.ts
file
step-6 Webpack
Don't hesitate to copy webpack.config.js
file in your application because you will certainly need to have your own build configuration.
Production
To build your application for production use, you can add the following command in your package.json
and run npm run build
"scripts":
This command will build Angular dependencies in dist
directory, but you have to create your own task to copy/bundle your .js
or .css
files for instance.