First of all, you need to install Node.js and npm, which we already mentioned in the TypeScript fundamentals you need to know section. Why do we need npm? In HTML and SystemJS configuration, we could reference all dependencies from https://unpkg.com. But, we prefer to install all dependencies locally so that IDEs are fine with autocompletion. For instance, to install SystemJS, you have to run the following command in a console of your choice:
npm install systemjs --save
For readers, we created a complete demo seed project where all dependencies are listed in the package.json file.
https://github.com/ova2/angular-development-with-primeng/tree/master/chapter1/primeng-systemjs-setup.
All dependencies in the seed project can be installed by running npm install in the project root. If you explore the index.html file, you can see that the SystemJS library is included in the <head> tag. After that, it becomes available as a global System object, which exposes two static methods: System.import() and System.config(). The first method is used to load a module. It accepts one argument--a module name, which can be either a file path or a logical name mapped to the file path. The second method is used for setting configuration. It accepts a configuration object as an argument. Normally, the configuration is placed within the systemjs.config.js file. Complete scripts to be included in index.html are TypeScript compiler, Polyfills, and SystemJS related files. The bootstrapping occurs by executing System.import('app'):
<script src="../node_modules/typescript/lib/typescript.js"></script>
<script src="../node_modules/core-js/client/shim.min.js"></script>
<script src="../node_modules/zone.js/dist/zone.js"></script>
<script src="../node_modules/systemjs/dist/system.src.js"></script>
<script src="../systemjs.config.js"></script>
<script>
System.import('app').catch(function (err) {
console.error(err);
});
</script>
An excerpt from the configuration object for Angular projects is listed here:
System.config({
transpiler: 'typescript',
typescriptOptions: {
"target": "es5",
"module": "commonjs",
"moduleResolution": "node",
"sourceMap": true,
"emitDecoratorMetadata": true,
"experimentalDecorators": true
},
map: {
'@angular/animations':
'node_modules/@angular/animations/bundles/animations.umd.min.js',
'@angular/common':
'node_modules/@angular/common/bundles/common.umd.min.js',
'@angular/compiler':
'node_modules/@angular/compiler/bundles/compiler.umd.min.js',
'@angular/core':
'node_modules/@angular/core/bundles/core.umd.min.js',
'@angular/forms':
'node_modules/@angular/forms/bundles/forms.umd.min.js',
...
'rxjs': 'node_modules/rxjs',
'app': 'src'
},
meta: {
'@angular/*': {'format': 'cjs'}
},
packages: {
'app': {
main: 'main',
defaultExtension: 'ts'
},
'rxjs': {main: 'Rx'}
});
A brief explanation gives an overview of the most important configuration options:
- The transpiler option specifies a transpiler for TypeScript files. Possible values are typescript, babel, and traceur. The transpilation happens in browser on-the-fly.
- The typescriptOptions option sets the TypeScript compiler options.
- The map option creates aliases for module names. When you import a module, the module name is replaced by an associated value according to the mapping. In the configuration, all entry points for Angular files are in UMD format.
- The packages option sets meta information for imported modules. For example, you can set the main entry point of the module. Furthermore, you can specify default file extensions to be able to omit them when importing.
