mirror of
https://github.com/systemjs/systemjs.git
synced 2026-01-18 14:53:14 +00:00
253 lines
7.1 KiB
Markdown
253 lines
7.1 KiB
Markdown
## Configuration API
|
|
|
|
### Setting Configuration
|
|
|
|
Once SystemJS has loaded, configuration can be set on SystemJS by using the configuration function `System.config`:
|
|
|
|
```javascript
|
|
System.config({
|
|
configA: {},
|
|
configB: 'value'
|
|
});
|
|
```
|
|
|
|
This is a helper function which normalizes configuration and sets configuration properties on the SystemJS instance.
|
|
|
|
`System.config({ prop: 'value' })` is mostly equivalent to `System.prop = value` except that it will extend configuration objects,
|
|
and certain properties will be normalized to be stored correctly.
|
|
|
|
For this reason it is usually advisable to use `System.config` instead of setting instance properties directly.
|
|
|
|
### Configuration Options
|
|
|
|
* [babelOptions](#babeloptions)
|
|
* [bundle](#bundle)
|
|
* [defaultJSExtensions](#defaultjsextensions)
|
|
* [depCache](#depcache)
|
|
* [map](#map)
|
|
* [meta](#meta)
|
|
* [packages](#packages)
|
|
* [paths](#paths)
|
|
* [traceurOptions](#traceuroptions)
|
|
* [transpiler](#transpiler)
|
|
* [typescriptOptions](#typescriptoptions)
|
|
|
|
#### babelOptions
|
|
Type: `Object`
|
|
Default: `{}`
|
|
|
|
Set the Babel transpiler options when [System.transpiler](#transpiler) is set to `babel`:
|
|
|
|
```javascript
|
|
System.config({
|
|
babelOptions: {
|
|
stage: 1
|
|
}
|
|
});
|
|
```
|
|
|
|
A list of options is available in the [Babel project documentation](https://babeljs.io/docs/usage/options/).
|
|
|
|
#### bundle
|
|
Type: `Object`
|
|
|
|
Bundles allow a collection of modules to be downloaded together as a package whenever any module from that collection is requested.
|
|
Useful for splitting an application into sub-modules for production. Use with the [SystemJS Builder](https://github.com/systemjs/builder).
|
|
|
|
```javascript
|
|
System.config({
|
|
bundles: {
|
|
bundleA: ['dependencyA', 'dependencyB']
|
|
}
|
|
});
|
|
```
|
|
|
|
A built bundle file must contain the exact named defines or named System.register statements for the modules it contains.
|
|
Mismatched names will result in separate requests still being made.
|
|
|
|
#### defaultJSExtensions
|
|
|
|
Backwards-compatibility mode for the loader to automatically add '.js' extensions when not present to module requests.
|
|
|
|
This allows code written for SystemJS 0.16 or less to work easily in the latest version:
|
|
|
|
```javascript
|
|
System.defaultJSExtensions = true;
|
|
|
|
// requests ./some/module.js instead
|
|
System.import('./some/module');
|
|
```
|
|
|
|
Note that this is a compatibility property for transitioning to using explicit extensions and will be deprecated in future.
|
|
|
|
#### depCache
|
|
Type: `Object`
|
|
|
|
An alternative to bundling providing a solution to the latency issue of progressively loading dependencies.
|
|
When a module specified in depCache is loaded, asynchronous loading of its pre-cached dependency list begins in parallel.
|
|
|
|
```javascript
|
|
System.config({
|
|
depCache: {
|
|
moduleA: ['moduleB'], // moduleA depends on moduleB
|
|
moduleB: ['moduleC'] // moduleB depends on moduleC
|
|
}
|
|
});
|
|
|
|
// when we do this import, depCache knows we also need moduleB and moduleC,
|
|
// it then directly requests those modules as well as soon as we request moduleA
|
|
System.import('moduleA')
|
|
```
|
|
|
|
Over HTTP/2 this approach may be preferable as it allows files to be individually cached in the browser meaning bundle optimizations are no longer a concern.
|
|
|
|
#### map
|
|
Type: `Object`
|
|
|
|
The map option is similar to paths, but acts very early in the normalization process. It allows you to map a module alias to a
|
|
location or package:
|
|
|
|
```javascript
|
|
System.config({
|
|
map: {
|
|
jquery: '//code.jquery.com/jquery-2.1.4.min.js'
|
|
}
|
|
});
|
|
```
|
|
|
|
```javascript
|
|
import $ from 'jquery';
|
|
|
|
```
|
|
|
|
In addition, a map also applies to any subpaths, making it suitable for package folders as well:
|
|
|
|
```javascript
|
|
System.config({
|
|
map: {
|
|
package: 'local/package'
|
|
}
|
|
});
|
|
```
|
|
|
|
```javascript
|
|
// loads /local/package/path.js
|
|
System.import('package/path.js');
|
|
```
|
|
|
|
> Note map configuration used to support contextual submaps but this has been deprecated for package configuration.
|
|
|
|
#### meta
|
|
Type: `Object`
|
|
Default: `{}`
|
|
|
|
Module meta provides an API for SystemJS to understand how to load modules correctly.
|
|
|
|
Meta is how we set the module format of a module, or know how to shim dependencies of a global script.
|
|
|
|
```javascript
|
|
System.config({
|
|
meta: {
|
|
// meaning [baseURL]/vendor/angular.js when no other rules are present
|
|
'vendor/angular.js': {
|
|
format: 'global', // load this module as a global
|
|
exports: 'angular', // the global property to take as the module value
|
|
deps: [
|
|
// dependencies to load before this module
|
|
'jquery'
|
|
]
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
Wildcard meta is also supported and is additive from least to most specific match:
|
|
|
|
```javascript
|
|
System.config({
|
|
meta: {
|
|
'/vendor/*': { format: 'global' }
|
|
}
|
|
});
|
|
```
|
|
|
|
#### packages
|
|
Type: `Object`
|
|
Default: `{}`
|
|
|
|
Packages provide a convenience for setting meta and map configuration that is specific to a common path.
|
|
|
|
In addition packages allow for setting contextual map configuration which only applies within the package itself.
|
|
This allows for full dependency encapsulation without always needing to have all dependencies in a global namespace.
|
|
|
|
```javascript
|
|
System.config({
|
|
packages: {
|
|
// meaning [baseURL]/local/package when no other rules are present
|
|
'local/package': {
|
|
// when importing the package by name, load /local/package/index.js
|
|
main: 'index.js',
|
|
// all modules are CommonJS format
|
|
format: 'cjs',
|
|
// when requesting a module in the package with no extension, add ".js" automatically
|
|
// this takes preference over defaultJSExtensions compatibility mode for the package
|
|
defaultExtension: 'js',
|
|
// just like map but only for requires within this package
|
|
map: {
|
|
// use local jquery for all jquery requires in this package
|
|
'jquery': './vendor/local-jquery.js'
|
|
|
|
// import '/local/package/custom-import' should route to '/local/package/local/import/file.js'
|
|
'./custom-import': './local/import/file.js'
|
|
}
|
|
meta: {
|
|
// set meta for loading the local vendor files
|
|
'vendor/*': {
|
|
'format': 'global'
|
|
}
|
|
}
|
|
}
|
|
}
|
|
});
|
|
```
|
|
|
|
#### paths
|
|
Type: `Object`
|
|
|
|
The [ES6 Module Loader](https://github.com/ModuleLoader/es6-module-loader/blob/master/docs/loader-config.md) paths implementation, applied after normalization and supporting subpaths via wildcards.
|
|
|
|
_It is usually advisable to use map configuration over paths unless you need strict control over normalized module names._
|
|
|
|
#### traceurOptions
|
|
Type: `Object`
|
|
Default: `{}`
|
|
|
|
Set the Traceur compilation options.
|
|
|
|
```javascript
|
|
System.config({
|
|
traceurOptions: {
|
|
}
|
|
});
|
|
```
|
|
|
|
A list of options is available in the [Traceur project documentation](https://github.com/google/traceur-compiler/wiki/Options-for-Compiling).
|
|
|
|
#### transpiler
|
|
Type: `String`
|
|
Default: `traceur`
|
|
|
|
Sets the module name of the transpiler to be used for loading ES6 modules.
|
|
|
|
Represents a module name for `System.import` that must resolve to either Traceur, Babel or TypeScript.
|
|
|
|
When set to `traceur`, `babel` or `typescript`, loading will be automatically configured as far as possible.
|
|
|
|
#### typescriptOptions
|
|
Type: `Object`
|
|
Default: `{}`
|
|
|
|
Sets the TypeScript transpiler options.
|
|
|
|
A list of options is available in the [TypeScript project documentation](https://github.com/Microsoft/TypeScript/wiki/Compiler%20Options).
|