ember-enginesEmber Asset Loader
Provides experimental support for the Asset Manifest RFC and Asset Loader Service RFC.
Compatibility
- Ember.js v3.24 or above
- Ember CLI v3.24 or above
- Node.js v14 or above
Usage
Ember Asset Loader does three primary things:
- Provides a base class to easily generate an Asset Manifest,
- Provides an Ember service to use the generated manifest at runtime, and
- Initializes the above service with the above generated manifest.
Generating an Asset Manifest
You can generate an Asset Manifest by creating either a standalone or in-repo addon which extends from the
ManifestGenerator base class:
var ManifestGenerator = require('ember-asset-loader/lib/manifest-generator');
module.exports = ManifestGenerator.extend({
name: 'asset-generator-addon',
manifestOptions: {
bundlesLocation: 'engines-dist',
supportedTypes: [ 'js', 'css' ]
}
});
The ManifestGenerator will generate an asset manifest and merge it into your build tree during post-processing. It
generates the manifest according to the options specified in manifestOptions:
The
bundlesLocationoption is a string that specifies which directory in the build tree contains the bundles to be placed into the asset manifest. This defaults tobundles. Each bundle is a directory containing files that will be downloaded when the bundle is requested. You are responsible for getting the right files into those directories.The
supportedTypesoption is an array that specifies which types of files should be included into the bundles for the asset manifest. This defaults to[ 'js', 'css' ].
_Note: This class provides default contentFor, postprocessTree, and postBuild hooks so be sure that you call
_super if you override one of those methods._
Why isn't a manifest generated by default?
This addon doesn't perform manifest generation just by virtue of being installed because there is no convention for bundling assets within Ember yet. Thus, to prevent introducing unintuitive or conflicting behavior, we provide no default generation and you must perform asset generation in your own addon using the base class provided by this addon.
If no manifest is generated, you'll get a warning at build time to ensure that you understand no manifest has been
generated and thus you'll have to provide a manifest manually in order to use the Asset Loader Service. This warning can
be disabled via the noManifest option from the consuming application:
var app = new EmberApp(defaults, {
assetLoader: {
noManifest: true
}
});
Generating Custom URIs
Custom URIs are often needed due to serving assets from CDNs or another server that does not share the same root
location as your application. Instead of having to write a custom Broccoli plugin or other build-time transform, you can
specify a generateURI function as part of your application's options:
var app = new EmberApp(defaults, {
assetLoader: {
generateURI: function(filePath) {
return 'http://cdn.io/' + filePath;
}
}
});
The function receives the filePath for each asset and must return a string.
Ignore Files
To ignore specific files during the manifest generation, use filesToIgnore.
Both string and regex patterns are accepted.
var app = new EmberApp(defaults, {
assetLoader: {
filesToIgnore: [/foo-engine/**/engine-vendor.js$/, 'vendor.js']
}
});
Using With broccoli-asset-rev
You need to make sure that broccoli-asset-rev runs after your ManifestGenerator addon runs. Here is an example of how to do that:
Create an in-repo-addon:
ember generate in-repo-addon asset-generator-addonMake it generate the manifest by editing
lib/asset-generator-addon/index.jsas described under "Generating an Asset Manifest" above.Edit
lib/asset-generator-addon/package.jsonto configure the addon to run afterbroccoli-asset-rev
{
"name": "asset-generator-addon",
"keywords": [
"ember-addon"
],
"ember-addon": {
"after": "broccoli-asset-rev"
}
}
Usage with FastBoot / Server-Side Rendering Solutions
Using lazily loaded assets with a server-side rendering solution, such as FastBoot, is often desirable to maximize performance for your consumers. However, lazy loading assets on your server is not the same as on the client and can actually have negative performance impact. Due to that, the recommendation is to pre-load all your assets in the server.
Additionally, at build time we will generate an assets/node-asset-manifest.js file that should be included in your SSR
environment to ensure that your application can correctly access asset information.
See the "How to handle running in Node" issue for more information.
Pre-loading Assets During Testing
For test environments it is often useful to load all of the assets in a manifest upfront. You can do this by using the
preloadAssets helper, like so:
// tests/test-helper.js
import preloadAssets from 'ember-asset-loader/test-support/preload-assets';
import manifest from 'app/config/asset-manifest';
preloadAssets(manifest);
Resetting Test State
When testing applications with lazy assets, it is important to reset the state of those assets in between tests. To do
this, Ember Asset Loader provides two helpers: cacheLoadedAssetState() and resetLoadedAssetState().
// tests/test-helper.js
import preloadAssets from 'ember-asset-loader/test-support/preload-assets';
import { cacheLoadedAssetState, resetLoadedAssetState } from 'ember-asset-loader/test-support/loaded-asset-state';
import manifest from 'app/config/asset-manifest';
cacheLoadedAssetState();
preloadAssets(manifest).then(() => {
resetLoadedAssetState(); // Undoes the previous load!
});
It is important to note that resetLoadedAssetState can only remove additional scripts, stylesheets, and modules loaded
since cacheLoadedAssetState was called. If any of the loaded assets modified global state, we'll be unable to restore
that state. Therefore, it is important to keep your lazy assets encapsulated and make sure they don't modified any state
already in the browser.
Note: If you use QUnit, it may be worthwhile to turn on the noglobals config option,
to help catch mutated global state.
Installation
git clone https://github.com/ember-engines/ember-asset-loadercd ember-asset-loadernpm installbower install
Running
ember serve- Visit the tests at http://localhost:4200/tests.
Running Tests
One of three options:
npm test(Runsember try:eachto test your addon against multiple Ember versions)ember testember test --server
Building
ember build
For more information on using ember-cli, visit http://ember-cli.com/.