ember-cli-amd

Ember CLI Addon that can load AMD modules.


Keywords
ember-addon, amd, ember-cli, javascript, web-development
License
Apache-2.0
Install
npm install ember-cli-amd@3.2.2

Documentation

ember-cli-amd

If your project needs to use an AMD based library, the Ember loader will conflict with the AMD loader.

The issue is that the Ember Loader defines the same globals require and define but are not AMD compatible.

The solution is to make the Ember Loader not conflicting anymore with the AMD Loader and to load the Ember App as an AMD module.

This addon will:

  • Allow you to import AMD modules from you Ember code. Example: import Map from 'esri/Map';
  • Update the code generated by Ember to avoid conflicts with the AMD loader
  • Update the index.html to use the AMD Loader:
    • load any pure AMD modules found in the code first using the AMD loader.
    • load the Ember code as AMD modules (app and vendor)
    • reference the AMD modules inside the Ember loader

View it live using the ArcGIS API for JavaScript.

Usage

ember install ember-cli-amd

Update your ember-cli-build file. See configuration below as an example:

var app = new EmberApp({
  amd : {
    // Specify the loader path. Can be a CDN path or a relative path in the dist folder
    // - CDN: loader: 'https://js.arcgis.com/4.14/'
    // - Local: loader: 'assets/jsapi/init.js'
    loader: 'https://js.arcgis.com/4.14/',
    
    // AMD packages from which modules are imported from in your application.
    // Used to parse the import statements and discover the AMD modules from the other modules.
    packages: ['esri','dojo'],
    
    // Optional: a list of relative paths from the build directory that should not be parsed by ember-cli-amd.
    // This is useful for:
    // - when using an AMD api locally and copied under public folder. The files will be copied under the build folder. These files are pure AMD
    //   modules and should not be converted.
    // - when copying from public to build directory files that are pure JS or pure AMD
    excludePaths: ['assets/jsapi', 'assets/myLibThatDontUseEmberDefineOrRequire'],

    // Optional: the path to javascript file that will be created for loading the AMD modules
    // default: assets
    loadingFilePath: 'assets'
  }
});

Example using the CDN resources

Your ember-cli-build.js:

module.exports = function(defaults) {

  var app = new EmberApp(defaults, {
    amd :{
      loader: 'https://js.arcgis.com/4.14/',
      packages: ['esri','dojo'],
      excludePaths: ['assets/workers']
    }
  });

  return app.toTree();
};

Your component:

import Component from '@glimmer/component';
import Map from 'esri/Map';

class MapComponent extends Component {
  // Do something with Map: const map = new Map({});
}

Your original index.html:

<!DOCTYPE html>
<html>

<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <title>My App</title>
  <meta name="description" content="">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  {{content-for "head"}}
  <link rel="stylesheet" href="assets/vendor.css">
  <link rel="stylesheet" href="assets/myapp.css">
  {{content-for "head-footer"}}

</head>

<body>

  {{content-for "body"}}
  <script src="assets/vendor.js"></script>
  <script src="assets/myapp.js"></script>
  {{content-for "body-footer"}}
</body>

</html>

The results will be:

  • a transformed index.html in your dist directory
  • an additional script file will be created under the dist directory under assets/amd-loading.js

dist/index.html:

<!DOCTYPE html>
<html>

<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <title>My App</title>
  <meta name="description" content>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="assets/vendor.css">
  <link rel="stylesheet" href="assets/myapp.css">
</head>

<body>
  <script src="https://jsdev.arcgis.com/4.15/init.js" data-amd="true"></script>
  <script src="assets/amd-loading.js" data-amd-loading="true"></script>
</body>

</html>

dist/assets/amd-loading.js

require([
  'esri/Map'
], function(mod0) {
  var adoptables = [{
    name: 'esri/Map',
    obj: mod0
  }];
  var isVendor = new RegExp('vendor(.*js)');

  function recursiveRequire(i, scripts) {
    if (i >= scripts.length) {
      return;
    }
    require([scripts[i]], function() {
      if (isVendor.test(scripts[i])) {
        adoptables.forEach(function(adoptable) {
          enifed(adoptable.name, [], function() {
            return adoptable.obj;
          });
        });
      }
      recursiveRequire(++i, scripts);
    });
  }
  recursiveRequire(0, ["assets/vendor.js", "assets/nickel.js"]);
});

Breaking changes

The version 3.x introduce the following breaking changes:

  • No more configPath. Use other addons to load the scripts you need in your header
  • The AMD module loading will be done in a separate javascript file. This is to keep the index.html as small as possible and optimized for caching
  • The loading script will be fingerprinted if you have turned on this feature in your build

Dependencies

  • Ember.js v3.12 or above
  • Ember CLI v2.13 or above
  • Node.js v10 or above

Resources

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Licensing

Copyright 2018 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file