Skip to content

Commit 346c39f

Browse files
EisenbergEffectEisenbergEffect
authored
Merge pull request #488 from niieani/webpack-docs
doc(webpack): initial documentation of Webpack-based Aurelia
2 parents 263bf72 + 50c4d4f commit 346c39f

File tree

5 files changed

+479
-7
lines changed

5 files changed

+479
-7
lines changed

‎doc/article/en-US/app-configuration-and-startup.md‎

Lines changed: 50 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,21 @@ This causes the `my-root${context.language.fileExtension}`/`my-root.html` to be
145145

146146
## [Bootstrapping Older Browsers](aurelia-doc://section/3/version/1.0.0)
147147

148-
Aurelia was originally designed for Evergreen Browsers. This includes Chrome, Firefox, IE11 and Safari 8. However, we also support IE9 and above through the use of additional polyfills. To support these earlier browsers, you need the [requestAnimationFrame Polyfill](https://www.npmjs.com/package/raf) and the [MutationObserver polyfill](https://github.com/webcomponents/webcomponentsjs/tree/master/src). Once you have installed these, change your `index.html` startup code as follows:
148+
Aurelia was originally designed for Evergreen Browsers. This includes Chrome, Firefox, IE11 and Safari 8. However, we also support IE9 and above through the use of additional polyfills. To support these earlier browsers, you need the [requestAnimationFrame Polyfill](https://www.npmjs.com/package/raf) and the [MutationObserver polyfill](https://github.com/webcomponents/webcomponentsjs/tree/master/src). Once you have installed these, you'll need to adjust your code to load them before Aurelia is initialized.
149+
150+
In case you are using Webpack, create a bootstrapper file, e.g. `bootstrapper.js`:
151+
152+
<code-listing heading="Polyfill Configuration">
153+
<source-code lang="HTML">
154+
import 'webcomponents/webcomponentsjs/MutationObserver';
155+
import * as raf from 'raf';
156+
raf.polyfill();
157+
</source-code>
158+
</code-listing>
159+
160+
After you have created the file, add it as the first file in your `aurelia-bootstrapper` bundle. You can find bundle configuration in the `webpack.config.js` file.
161+
162+
If you are using JSPM change your `index.html` startup code as follows:
149163

150164
<code-listing heading="Polyfill Configuration">
151165
<source-code lang="HTML">
@@ -180,9 +194,9 @@ Aurelia was originally designed for Evergreen Browsers. This includes Chrome, Fi
180194
181195
## [Manual Bootstrapping](aurelia-doc://section/4/version/1.0.0)
182196

183-
So far, we've been bootstrapping our app declaratively by using the `aurelia-app` attribute. That's not the only way though. You can manually bootstrap the framework as well. Here's how you would change your HTML file to use manual bootstrapping:
197+
So far, we've been bootstrapping our app declaratively by using the `aurelia-app` attribute. That's not the only way though. You can manually bootstrap the framework as well. In case of JSPM, here's how you would change your HTML file to use manual bootstrapping:
184198

185-
<code-listing heading="Manual Bootstrapping">
199+
<code-listing heading="Manual Bootstrapping with JSPM">
186200
<source-code lang="HTML">
187201
<!doctype html>
188202
<html>
@@ -208,6 +222,37 @@ So far, we've been bootstrapping our app declaratively by using the `aurelia-app
208222
</source-code>
209223
</code-listing>
210224

225+
In case you use Webpack, you can replace the `aurelia-boostrapper-webpack` package with the `./src/main` entry file in the `aurelia-boostrapper` bundle defined inside of `webpack.config.js`, and call the boostrapper manually:
226+
227+
228+
<code-listing heading="Manual Bootstrapping with Webpack">
229+
<source-code lang="ES 2015/2016">
230+
import {bootstrap} from 'aurelia-bootstrapper-webpack';
231+
232+
bootstrap(async aurelia => {
233+
aurelia.use
234+
.standardConfiguration()
235+
.developmentLogging();
236+
237+
await aurelia.start();
238+
aurelia.setRoot('app', document.body);
239+
});
240+
</source-code>
241+
<source-code lang="TypeScript">
242+
import {Aurelia} from 'aurelia-framework';
243+
import {bootstrap} from 'aurelia-bootstrapper-webpack';
244+
245+
bootstrap(async (aurelia: Aurelia) => {
246+
aurelia.use
247+
.standardConfiguration()
248+
.developmentLogging();
249+
250+
await aurelia.start();
251+
aurelia.setRoot('app', document.body);
252+
});
253+
</source-code>
254+
</code-listing>
255+
211256
The function you pass to the `bootstrap` method is the same as the `configure` function from the examples above.
212257

213258
## [Making Resources Global](aurelia-doc://section/5/version/1.0.0)
@@ -330,7 +375,7 @@ So far you've seen Aurelia replacing a portion of the DOM with a root component.
330375

331376
Imagine that you want to generate your home page on the server, including using your server-side templating engine to render out HTML. Perhaps you've got custom components you created with Aurelia, but you want to render the custom elements on the server with some content, in order to make things a bit more SEO friendly. Or perhaps you have an existing, traditional web app, that you want to incrementally start adding Aurelia to. When the HTML is rendered in the browser, you want to progressively enhance that HTML and "bring it to life" by activating all the Aurelia component's rich behavior.
332377

333-
All this is possible with Aurelia, using a single method call: `enhance`. Instead of using `aurelia-app` let's use manual bootstrapping for this example. To progressively enhance the entire `body` of your HTML page, you can do something like this:
378+
All this is possible with Aurelia, using a single method call: `enhance`. Instead of using `aurelia-app` let's use manual bootstrapping for this example. To progressively enhance the entire `body` of your HTML page, you can do something like this (JSPM-based example):
334379

335380
<code-listing heading="Progressive Enhancement">
336381
<source-code lang="HTML">
@@ -364,7 +409,7 @@ All this is possible with Aurelia, using a single method call: `enhance`. Instea
364409

365410
It's important to note that, in order for `enhance` to identify components to enhance in your HTML page, you need to declare those components as global resources, as we have above with the `my-component` component.
366411

367-
Optionally, you can provide an object instance to use as the data-binding context for the enhancement, or provide a specific part of the DOM to enhance. Here's an example that shows both:
412+
Optionally, you can provide an object instance to use as the data-binding context for the enhancement, or provide a specific part of the DOM to enhance. Here's an example that shows both (JSPM-based):
368413

369414
<code-listing heading="Customized Progressive Enhancement">
370415
<source-code lang="HTML">

‎doc/article/en-US/jspm-bundling.md‎ renamed to ‎doc/article/en-US/bundling-jspm.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
{
3-
"name": "JSPM Bundling",
3+
"name": "Bundling with JSPM",
44
"culture": "en-US",
55
"description": "Before deploying your app to production, you'll want to bundle the assets for efficient use of the network.",
66
"engines" : { "aurelia-doc" : "^1.0.0" },

0 commit comments

Comments
 (0)