aboutsummaryrefslogtreecommitdiff
path: root/thirdparty/systemjs/docs/overview.md
blob: a3899f297ccf1dbfead2a1e28110dda153971270 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
### Loading Modules

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

```html
<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:
```javascript
  export class q {
    constructor() {
      this.es6 = 'yay';
    }
  }
```

```html
  <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](es6-modules-overview.md).
* To build for production, see the [production workflows](production-workflows.md).
* [Read more about SystemJS module format support](module-formats.md).

### Loader Configuration

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

For a reference see the [Config API](config-api.md) 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:

```javascript
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:

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

Map configuration can also be used to map subpaths:

```javascript
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](https://github.com/systemjs/builder).

To create a custom plugin, see the documentation on [creating plugins](creating-plugins.md).

#### Basic Use

> Note that if using the `defaultJSExtensions` compatibility feature, plugins for resources with custom extensions will only work by using the [package configuration](config-api.md#packages) `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](https://github.com/systemjs/plugin-text) as an example.

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

```javascript
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
```javascript
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:

```javascript
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.