ember-auto-import

Just import from NPM, with zero configuration.

Installation

ember install ember-auto-import

Usage

Add whatever dependency you want to your project using NPM or yarn like:

npm install --save-dev lodash-es

yarn add --dev lodash-es

Then just import it from your Ember app code:

import { capitalize } from 'lodash-es';

There is no step two. Works from both app code and test code.

Dynamic Import

In addition to static top-level import statements, you can use dynamic import() to lazily load your dependencies. This can be great for reducing your initial bundle size.

Dynamic import is currently a Stage 3 ECMA feature, so to use it there are a few extra setup steps:

npm install --save-dev babel-eslint
In your .eslintrc.js file, add
```
 parser: 'babel-eslint'
```

In your ember-cli-build.js file, enable the babel plugin provided by ember-auto-import:

 let app = new EmberApp(defaults, {
   babel: {
     plugins: [ require('ember-auto-import/babel-plugin') ]
   }
 });

Once you're setup, you can use dynamic import() and it will result in loading that particular dependency (and all its recursive dependencies) via a separate Javascript file at runtime. Here's an example of using dynamic import from within a Route, so that the extra library needed for the route is loaded at the same time the data is loaded:

export default Route.extend({
  model({ id }) {
    return Promise.all([
      fetch(`/data-for-chart/${id}`).then(response => response.json()),
      import('highcharts').then(module => module.default)
    ]).then(([ dataPoints, highcharts ]) => {
      return { dataPoints, highcharts };
    });
  }
});

If you're using custom deployment code, make sure it will include all the Javascript files in dist/assets, not just the default app.js and vendor.js.

Customizing Build Behavior

While most NPM packages authored in CommonJS or ES Modules will Just Work, for others you may need some give ember-auto-import a hint about what to do.

You can set options like this in your ember-cli-build.js:

// In your ember-cli-build.js file
let app = new EmberApp(defaults, {
  autoImport: {
    alias: {
      // when the app tries to import from "plotly.js", use
      // the real package "plotly.js-basic-dist" instead.
      'plotly.js': 'plotly.js-basic-dist',

      // you can also use alises to pick a different entrypoint
      // within the same package. This can come up when the default
      // entrypoint only works in Node, but there is also a browser
      // build available (and the author didn't provide a "browser"
      // field in package.json that would let us detect it
      // automatically).
      'handlebars': 'handlebars/dist/handlebars'
    },
    exclude: ['some-package'],
    webpack: {
      // extra webpack configuration goes here
    }
  }
});

Suported Options

alias: object, Map from package names to substitute packages that will be used instead.
exclude: list of strings, defaults to []. Packages in this list will be ignored by ember-auto-import. Can be helpful if the package is already included another way (like a shim from some other Ember addon).
publicAssetURL: where to load additional dynamic javascript files from. You usually don't need to set this -- the default works for any Ember app that isn't doing something unusual.
webpack: object, An object that will get merged into the configuration we pass to webpack. This lets you work around quirks in underlying libraries and otherwise customize the way Webpack will assemble your dependencies.

Usage from Addons

Using ember-auto-import inside an addon is almost exactly the same as inside an app. The only differences are:

ember-auto-import must be in the dependencies of your addon, not in devDependencies. Otherwise it won't come along when people install your addon.
ember-auto-import will refuse to import devDependencies of your addon, for the same reason. Whatever you're importing must be in dependencies.

you configure ember-auto-import in your index.js file (not your ember-cli-build.js file), like this:

// In your addon's index.js file
module.exports = {
  name: 'sample-addon',
  options: {
    autoImport:{
      exclude: ['some-package'],
      webpack: {
        // extra webpack configuration goes here
      }
    }
  }
};

FAQ

I use Content Security Policy (CSP) and it breaks ember-auto-import.

You need to either add "unsafe-eval" to your policy, or use one of the suggestions for making webpack not require unsafe-eval.

I'm trying to load a jQuery plugin, but it doesn't attach itself to the copy of jQuery that's already in my Ember app.

Ember apps typically get jQuery from the ember-source or @ember/jquery packages. Neither of these is the real jquery NPM package, so ember-auto-import cannot "see" it statically at build time. You will need to give webpack a hint to treat jQuery as external:

// In your ember-cli-build.js file
let app = new EmberApp(defaults, {
  autoImport: {
    webpack: {
      externals: { jquery: 'jQuery' }
    }
  }
});

Also, some jQuery plugins like masonry and flickity have required manual steps to connect them to jQuery.

Debugging Tips

Set the environment variable DEBUG="ember-auto-import:*" to see debug logging during the build.

To see Webpack's console output, set the environment variable AUTO_IMPORT_VERBOSE=true.

Credit / History

Takes inspiration and some code from ember-browserify and ember-cli-cjs-transform. This package is basically what you get when you combine the ideas from those two addons.

Contributing

Installation

git clone <repository-url>
cd ember-auto-import
yarn install

Building

You can build the TypeScript into Javascript with

yarn compile

If you're making interactive changes, you can leave the compiler watching:

yarn compile --watch

Linting

yarn lint:js
yarn lint:js --fix

Running tests

Our test setup is not typical for an Ember addon. While there is a normal Ember addon dummy app that you can run the normal way (with ember test), we also have multiple other apps under /test-apps. This lets us test how ember-auto-import gets integrated under multiple scenarios.

The test apps share the top-level node_modules automatically, no need to run separate npm installs for them. They should get symlinked to each other automatically when you install the top-level deps (see ./scripts/link-them.sh). You can also cd directly into any of the test apps and run its tests like a normal Ember app.

The top-level test runner script (/scripts/test.sh) probably only works under Unix-like environments, because it relies on GNU parallel to run all the apps at once.

Index of test apps:

sample-direct: an app that directly uses ember-auto-import
sample-addon: an addon that uses ember-auto-import to implement a feature that will be used in apps, and also exercises auto-import for devDependencies in its dummy app.
sample-indirect: an app that uses sample-addon but does not directly depend on ember-auto-import
sample-failure: an addon that should refuse to build due to importing a devDependency from addon code

License

This project is licensed under the MIT License.

bjornharrtell/ember-auto-import

ember-auto-import

Installation

Usage

Dynamic Import

Customizing Build Behavior

Usage from Addons

FAQ

I use Content Security Policy (CSP) and it breaks ember-auto-import.

I'm trying to load a jQuery plugin, but it doesn't attach itself to the copy of jQuery that's already in my Ember app.

Debugging Tips

Credit / History

Contributing

Installation

Building

Linting

Running tests

License