Skip to content

Latest commit

 

History

History
386 lines (297 loc) · 16.6 KB

README.md

File metadata and controls

386 lines (297 loc) · 16.6 KB
Raw

ember-auto-import

Just import from NPM, with zero configuration.

Installation

npm install --save-dev ember-auto-import webpack

If you're upgrading from 1.x to 2.x see the upgrade guide.

Usage

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

npm install --save-dev lodash-es

or

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:

  1. npm install --save-dev babel-eslint

  2. In your .eslintrc.js file, add

    parser: 'babel-eslint'

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

let app = new EmberApp(defaults, {
  babel: {
    plugins: [require.resolve('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 to 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 aliases 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',

      // We do a prefix match by default, so the above would also
      // convert "handlebars/foo" to "handlebars/dist/handlesbars/foo".
      // If instad you want an exact match only, you can use a trailing "$".
      // For example, this will rewrite "some-package/alpha" to "customized"
      // but leave "some-package/beta" alone.
      'some-package/alpha$': 'customized',
    },
    exclude: ['some-package'],
    skipBabel: [
      {
        // when an already-babel-transpiled package like "mapbox-gl" is
        // not skipped, it can produce errors in the production mode
        // due to double transpilation
        package: 'mapbox-gl',
        semverRange: '*',
      },
    ],
    watchDependencies: [
      // trigger rebuilds if "some-lib" changes during development
      'some-lib',
      // trigger rebuilds if "some-lib"'s inner dependency "other-lib" changes
      ['some-lib', 'other-lib'],
    ],
    webpack: {
      // extra webpack configuration goes here
    },
  },
});

Supported Options

  • alias: object, Map from imported names to substitute names that will be imported instead. This is a prefix match by default. To opt out of prefix-matching and only match exactly, add a $ suffix to the pattern.
  • earlyBootSet: function, returning an array of strings, (only supported on ember-source >= 3.27.0) defaults to undefined, but when used, the function will receive the default earlyBootSet, which is a list of common modules found at the source of rare timing / package / ordering issues in the compatibility / cross-communication between requirejs and webpack. This is a temporary escape hatch to allow non-embroider apps to consume v2 addons at any place in their dependency graph to help ease transitioning to embroider as this problem doesn't occur once an app is using embroider. See issue#504 for details. Note that if any modules listed here belong to v2 addons, they will be removed from the set. To opt out of default behavior, return an empty array.
  • 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).
  • forbidEval: boolean, defaults to false. We use eval in development by default (because that is the fastest way to provide sourcemaps). If you need to comply with a strict Content Security Policy (CSP), you can set forbidEval: true. You will still get sourcemaps, they will just use a slower implementation.
  • insertScriptsAt: string, defaults to undefined. Optionally allows you to take manual control over where ember-auto-import's generated <script> tags will be inserted into your HTML and what attributes they will have. See "Customizing HTML Insertion" below.
  • insertStylesAt: string, defaults to undefined. Optionally allows you to take manual control over where ember-auto-import's generated <link rel="stylesheet"> tags (if any) will be inserted into your HTML and what attributes they will have. See "Customizing HTML Insertion" below.
  • publicAssetURL: the public URL to your /assets directory on the web. Many apps won't need to set this because we try to detect it automatically, but you will need to set this explicitly if you're deploying your assets to a different origin than your app (for example, on a CDN) or if you are using <script defer> (which causes scripts to be unable to guess what origin they loaded from).
  • skipBabel: list of objects, defaults to []. The specified packages will be skipped from babel transpilation.
  • watchDependencies: list of strings or string arrays, defaults to []. Tells ember-auto-import that you'd like to trigger a rebuild if one of these auto-imported dependencies changes. Pass a package name that refers to one of your own dependencies, or pass an array of package names to address a deeper dependency.
  • 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.

Installing ember-auto-import in an addon

To add ember-auto-import to your addon:

  • add ember-auto-import to your dependencies, not your devDependencies, so it will be present when your addon is used by apps

  • add webpack to your devDependencies (to support your test suite) but not your dependencies (the app's version will be used)

  • document for your users that their app must depend on ember-auto-import >= 2 in order to use your addon

  • configure ember-auto-import (if needed) 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'],
    },
  },
};

  • if your addon uses Dynamic Import, it is required that you register the babel plugin in your index.js instead of ember-cli-build.js:

    // index.js
module.exports = {
  options: {
    babel: {
      plugins: [require.resolve('ember-auto-import/babel-plugin')],
    },
  },
};

Caveats in addons

  • ember-auto-import will refuse to import devDependencies of your addon into addon code (because that would fail in a consuming application). You can import devDependencies into your test suite & dummy app.
  • ember-auto-import will not detect import statements inside your app folder. This is because the files inside app are conceptually not part of your addon's own package namespace at all, so they don't get access to your addon's dependencies. Do all your auto-importing from the addon folder, and reexport in app as needed.
  • while addons are allowed to pass the autoImport.webpack option to add things to the webpack config, this makes them less likely to be broadly compatible with apps using different webpack versions. If you need to rely on a specific webpack feature, you should document which versions of webpack you support.

Customizing HTML Insertion

ember-auto-import uses webpack to generate one or more chunk files containing all your auto-imported dependencies, and then ember-auto-import inserts <script> tags to your HTML to make sure those chunks are included into your app (and tests, as appropriate). By default, the "app" webpack chunk(s) will be inserted after Ember's traditional "vendor.js" and the "tests" webpack chunk(s) will be inserted after "test-support.js".

If you need more control over the HTML insertion, you can use the insertScriptsAt option (or the insertStylesAt option, which is exactly analogous but for standalone CSS instead of JS). To customize HTML insertion:

  1. Set insertScriptsAt to a custom element name. You get to pick the name so that it can't collide with any existing custom elements in your site, but a good default choice is "auto-import-script":

    let app = new EmberApp(defaults, {
  autoImport: {
    insertScriptsAt: 'auto-import-script',
  },
});

  2. In your index.html and tests/index.html, use the custom element to designate exactly where you want the "app" and "tests" entrypoints to be inserted:

     <!-- in index.html -->
 <body>
   {{content-for "body"}}
   <script src="{{rootURL}}assets/vendor.js"></script>
+   <auto-import-script entrypoint="app"></auto-import-script>
   <script src="{{rootURL}}assets/your-app.js"></script>
   {{content-for "body-footer"}}
 </body>
     <!-- in tests/index.html -->
 <body>
   {{content-for "body"}}
   {{content-for "test-body"}}

   <div id="qunit"></div>
   <div id="qunit-fixture">
     <div id="ember-testing-container">
       <div id="ember-testing"></div>
     </div>
   </div>

   <script src="/testem.js" integrity=""></script>
   <script src="{{rootURL}}assets/vendor.js"></script>
+   <auto-import-script entrypoint="app"></auto-import-script>
   <script src="{{rootURL}}assets/test-support.js"></script>
+   <auto-import-script entrypoint="tests"></auto-import-script>
   <script src="{{rootURL}}assets/your-app.js"></script>
   <script src="{{rootURL}}assets/tests.js"></script>

   {{content-for "body-footer"}}
   {{content-for "test-body-footer"}}
 </body>

  3. Any attributes other than entrypoint will be copied onto the resulting <script> tags inserted by ember-auto-import. For example, if you want <script defer></script> you can say:

    <auto-import-script defer entrypoint="app"> </auto-import-script>

    And this will result in output like:

    <script defer src="/assets/chunk-12341234.js"></script>

Once you enable insertScriptsAt you must designate places for the "app" and "tests" entrypoints if you want ember-auto-import to work correctly. You may also optionally designate additional entrypoints and manually add them to the webpack config. For example, you might want to build a polyfills bundle that needs to run before vendor.js on pre-ES-module browsers:

// ember-cli-build.js
let app = new EmberApp(defaults, {
  autoImport: {
    insertScriptsAt: 'auto-import-script',
    webpack: {
      entry: {
        polyfills: './lib/polyfills.js',
      },
    },
  },
});

// lib/polyfills.js
import 'core-js/stable';
import 'intl';
<!-- index.html -->
<auto-import-script nomodule entrypoint="polyfills"></auto-import-script>
<script src="{{rootURL}}assets/vendor.js"></script>
<auto-import-script entrypoint="app"></auto-import-script>
<script src="{{rootURL}}assets/your-app.js"></script>

Fastboot

ember-auto-import works with Fastboot to support server-side rendering.

When using Fastboot, you may need to add your Node version to config/targets.js in order to only use Javascript features that work in that Node version. When you do this, it may prevent webpack from being able to infer that it should still be doing a build that targets the web. This may result in an error message like:

For the selected environment is no default script chunk format available:
JSONP Array push can be chosen when 'document' or 'importScripts' is available.
CommonJs exports can be chosen when 'require' or node builtins are available.
Make sure that your 'browserslist' includes only platforms that support these features or select an appropriate 'target' to allow selecting a chunk format by default. Alternatively specify the 'output.chunkFormat' directly.

You can fix this by setting the target to web explicitly:

// ember-cli-build.js
let app = new EmberApp(defaults, {
  autoImport: {
    webpack: {
      target: 'web',
    },
  },
});

FAQ

global is undefined or can't find module "path" or can't find module "fs"

You're trying to use a library that is written to work in NodeJS and not in the browser. You can choose to polyfill the Node feature you need by passing settings to webpack. For example:

let app = new EmberApp(defaults, {
  autoImport: {
    webpack: {
      node: {
        global: true,
        fs: 'empty'
      }
    }
  }

See webpack's docs on Node polyfills.

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

See forbidEval above.

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.

I upgraded my ember-auto-import version and now things don't import. What changed?

As of version 1.4.0, by default, ember-auto-import does not include webpack's automatic polyfills for certain Node packages. Some signs that your app was depending on these polyfills by accident are things like "global is not defined," "can't resolve path," or "default is not a function." You can opt-in to Webpack's polyfills, or install your own. See this issue for an example.

I get Uncaught ReferenceError: a is not defined 251 with an already babel transpiled addon, e.g: mapbox-gl

We should skip that specific addon from the ember-auto-import's babel transpilation as:

// In your app's ember-cli-build.js file or check the `Usage from Addons` section for relevant usage of the following in addons
let app = new EmberApp(defaults, {
  autoImport: {
    skipBabel: [
      {
        package: 'mapbox-gl',
        semverRange: '*',
      },
    ],
  },
});

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

See CONTRIBUTING.md

License

This project is licensed under the MIT License.