overview.md

Loading Modules

Any URL can be loaded as a module with standard URL syntax:

<script src="system.js"></script>
<script>
  // loads relative to the current page URL
  System.import('./local-module.js'); 

  // load from an absolute URL directly
  System.import('https://code.jquery.com/jquery.js');
</script>

Any type of module format can be loaded and it will be detected automatically by SystemJS.

File access from files

Note that when running locally, ensure you are running from a local server or a browser with local XHR requests enabled. If not you will get an error message.

For Chrome on Mac, you can run it with: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --allow-file-access-from-files &> /dev/null &

In Firefox this requires navigating to about:config, entering security.fileuri.strict_origin_policy in the filter box and toggling the option to false.

Loading ES6

app/es6-file.js:

  export class q {
    constructor() {
      this.es6 = 'yay';
    }
  }

  <script>
    System.import('./app/es6-file.js').then(function(m) {
      console.log(new m.q().es6); // yay
    });
  </script>

ES6 modules define named exports, provided as getters on a special immutable Module object.

• Read more about ES6 modules and syntax.
• To build for production, see the production workflows.
• Read more about SystemJS module format support.

Loader Configuration

Some of the standard configuration options and their use cases are described below.

For a reference see the Config API page.

baseURL

The baseURL provides a special mechanism for loading modules relative to a standard reference URL.

This can be useful for being able to refer to the same module from many different page URLs or environments:

System.config({
  baseURL: '/modules'
});


// loads /modules/jquery.js
System.import('jquery.js');

Module names of the above form are referred to as plain names and are always loaded baseURL-relative instead of parentURL relative like one would expect with ordinary URLs.

Note we always run the System.config function instead of setting instance properties directly as this will set the correct normalized baseURL in the process.

Map Config

The baseURL is very useful for providing an absolute reference URL for loading all modules, but we don't necessarily want to have to locate every single shared dependency from within one folder.

Sometimes we want to load things from different places.

Map configuration is useful here to be able to specific exactly where to locate a given package:

System.config({
  map: {
    jquery: 'https://code.jquery.com/jquery.js'
  }
});

Map configuration can also be used to map subpaths:

System.config({
  map: {
    app: '/app/'
  }
});

// will load /app/main.js
System.import('app/main.js');

Map configuration is always applied before the baseURL rule in the loader.

Plugin Loaders

Plugins handle alternative loading scenarios, including loading assets such as CSS or images, and providing custom transpilation scenarios.

Plugins can also inline into bundles or remain separate requests when using SystemJS Builder.

To create a custom plugin, see the documentation on creating plugins.

Basic Use

Note that if using the defaultJSExtensions compatibility feature, plugins for resources with custom extensions will only work by using the package configuration defaultExtension: false option to override this for specific packages.

To use a plugin, set up the plugin itself as a standard module, either locating it in the baseURL or providing map configuration for it.

In this case, we're using the text plugin as an example.

Then configure a custom resource to be loaded via the plugin, we then use meta configuration:

System.config({
  // locate the plugin via map configuration
  // (alternatively have it in the baseURL)
  map: {
    text: '/path/to/text-plugin.js'
  },
  // use meta configuration to reference which modules
  // should use the plugin loader
  meta: {
    'templates/*.html': {
      loader: 'text'
    }
  }
});

Now any code that loads from [baseURL]/templates/*.html will use the text loader plugin and return the loaded content:

app.js

import htmlSource from 'templates/tpl.html';

document.querySelector('.container').innerHTML = htmlSource;

When we build app.js, the text plugin will then automatically inline the templates into the bundle during the build.

Plugin Syntax

It is also possible to use syntax to load via plugins instead of configuration:

System.import('some/file.txt!text')

When no plugin is explicitly specified the extension is used as the plugin name itself.

Note it is usually advisable to use plugin loader configuration over plugin syntax.