https://github.com/dockyard/ember-app-shell
https://github.com/dockyard/ember-app-shell
addon chrome-headless ember ember-cli ember-service-worker service-worker
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/dockyard/ember-app-shell
- Owner: DockYard
- License: mit
- Created: 2017-09-25T13:30:28.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2018-06-25T19:21:29.000Z (over 7 years ago)
- Last Synced: 2025-08-19T05:23:20.328Z (about 2 months ago)
- Topics: addon, chrome-headless, ember, ember-cli, ember-service-worker, service-worker
- Language: JavaScript
- Size: 208 KB
- Stars: 24
- Watchers: 8
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ember-app-shell
**[ember-app-shell is built and maintained by DockYard, contact us for expert Ember.js consulting](https://dockyard.com/ember-consulting)**.
Renders an App Shell based on your actual running Ember.js application using Headless Chrome! It also inlines the relevant minimal CSS using the [Critical](https://github.com/addyosmani/critical) tool.
## How does this work?
Near the end of Ember CLI's build process, this addon loads your app in a Headless Chrome session and takes the rendered HTML and replaces `index.html` with the output of the `/app-shell` route. This way you are able to serve some static html before Ember boots up in the browser, but not having to maintain that manually in the `index.html` file.
See _[The App Shell Model](https://developers.google.com/web/fundamentals/architecture/app-shell)_ on Google's Developer website for more information about what an App Shell is.
This addon is intended to be used with [Ember Service Worker](http://ember-service-worker.com) and the [ember-service-worker-index](https://github.com/DockYard/ember-service-worker-index) addon.
## Installation
```shell
ember install ember-app-shell
```### Make sure Google Chrome is installed on the build environment
You also need to make sure that every environment that will build your app runs Google Chrome (Canary).
See the [README](https://www.npmjs.com/package/chrome-launcher#continuous-integration) of the `chrome-launcher` NPM package for more details on how to install Chrome on CI environments.### Export application global
To properly ensure app rendering of the app shell this addon makes use of Ember's visit API. To do this in all environments you must
configure your app to export its application global for all environments. By default, Ember does not do this in `production`.
[Read more about exporting your application's global](https://github.com/ember-cli/ember-export-application-global).## Getting Started
This addon will visit `/app-shell` by default when the Ember app is built by Ember CLI, so we need to make sure that route exists. The easiest way is to generate one using Ember CLI:
```shell
ember generate route app-shell
```Now let's assume your `application.hbs` and `app-shell.hbs` look like the following:
```handlebars
{{! application.hbs}}
My App's Name
![]()
{{outlet}}
```
```handlebars
{{! app-shell.hbs}}
![]()
```Then after building (e.g. `ember build`) the built `index.html` file (e.g. `dist/index.html`) will contain:
```html
My App's Name
![]()
![]()
```If you now open up your app in the browser, you'll see the app shell content until the Ember.js app renders.
## Configuration
There are multiple things you can configure, here's an example of how it can look like:
```javascript
var EmberApp = require('ember-cli/lib/broccoli/ember-app');module.exports = function(defaults) {
var app = new EmberApp(defaults, {
'ember-app-shell': {
visitPath: '/my-app-shell',
outputFile: 'my-app-shell.html',
// https://peter.sh/experiments/chromium-command-line-switches/
chromeFlags: [],
// https://github.com/addyosmani/critical#options
criticalCSSOptions: {
width: 1300,
height: 900
},
// enabled: false (if you want to disable it. You can also pass `APP_SHELL_DISABLED=true` when running `ember serve`)
}
});return app.toTree();
};
```### `visitPath`
This determines which route in your application is used to render the app shell. If you have your router configured with `locationType: 'hash'` then you might need to set `visitPath: '/#/app-shell'`.
Default: `/app-shell`.
### `outputFile`
This determines where the App Shell file is written to in your build.
Specifying `index.html` will overwrite the existing `index.html`.Default: `index.html`
### `chromeFlags`
Flags passed to chrome by [`chrome-launcher`](https://github.com/GoogleChrome/chrome-launcher).
Default: `[]`
### `criticalCSSOptions`
The options passed to the [`critical`](https://github.com/addyosmani/critical) module.
Default: `{ minify: true }`
## Troubleshooting
### `ember server` fails to start
If `ember server` results in a long idle time followed by an error similar to this, try enabling adding `--no-sandbox` to the `chromeFlags` option.
```
Error: connect ECONNREFUSED 127.0.0.1:44625
at Object._errnoException (util.js:1021:11)
at _exceptionWithHostPort (util.js:1043:20)
at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1175:14)
```
This may be needed on certain UNIX systems, which need this flag as a workaround to get chrome headless running (see https://github.com/GoogleChrome/chrome-launcher/issues/6 and https://github.com/GoogleChrome/lighthouse/issues/2726).## Legal
[DockYard](http://dockyard.com/), Inc. © 2017
[@dockyard](http://twitter.com/dockyard)
[Licensed under the MIT license](http://www.opensource.org/licenses/mit-license.php)