Ember.js

Installation

In your application's directory:

npm

npm install @responsive-image/ember

yarn

yarn add @responsive-image/ember

pnpm

pnpm add @responsive-image/ember

Image component

The addon provides a <ResponsiveImage> component for rendering the set of images, taking local images or remote images as the @src input. Please refer to the main image component guide for all details and supported arguments!

Local images

To process local images you will need to setup one of the build plugins depending on your app's setup.

Classic build with ember-auto-import

In a classic build with ember-auto-import (make sure you are at least on version 2.7.1!), we use the webpack plugin to pass the custom webpack config to the autoImport options:

// ember-cli-build.js
let app = new EmberApp(defaults, {
  autoImport: {
    allowAppImports: ['images/**/*'],
    webpack: {
      module: {
        rules: [
          {
            resourceQuery: /responsive/,
            use: require('@responsive-image/webpack').setupLoaders(),
          },
        ],
      },
    },
  },
});

IMPORTANT

For more information on how to configure @responsive-image/webpack and setupLoaders() refer to the webpack plugin documentation.

NOTE

Note the use of allowAppImports here, which is a way to make the build use ember-auto-import and thus Webpack to handle the files configured by the glob pattern of this configuration option. You can place the images files in a central subfolder under /app, like app/images as in this example, or even colocate them next to other JavaScript files by targeting specific image extensions instead of certain folders (e.g. **/*/*.jpg). Either way make sure that image files you import for use by @responsive-image/ember are correctly covered by at least one glob pattern passed to allowAppImports!

Embroider + webpack

To apply this configuration to an Embroider-powered Ember app, edit your ember-cli-build.js file and pass the Webpack config using the options argument of compatBuild:

const { Webpack } = require('@embroider/webpack');
return require('@embroider/compat').compatBuild(app, Webpack, {
  packagerOptions: {
    webpackConfig: {
      module: {
        rules: [
          {
            resourceQuery: /responsive/,
            use: require('@responsive-image/webpack').setupLoaders(),
          },
        ],
      },
    },
  },
});

IMPORTANT

For more information on how to configure @responsive-image/webpack and setupLoaders() refer to the webpack plugin documentation.

Embroider + Vite

For an Ember app running on the latest Polaris edition setup using Embroider and Vite (assuming you use the app v2 blueprint), you need to add the image plugins provided by @responsive-image/vite-plugin to the plugins array of your vite.config.mjs:

import { defineConfig } from 'vite';
import { setupPlugins } from '@responsive-image/vite-plugin';

export default defineConfig({
  // other config...
  plugins: [
    // all your other Ember/Vite plugins ...
    setupPlugins({
      include: /^[^?]+\.jpg\?.*responsive.*$/,
    }),
  ],
});

IMPORTANT

For more information on how to configure @responsive-image/vite-plugin and setupPlugins() refer to the Vite plugin documentation.

Remote images

Multiple image provider helpers are provided to support remote images served from different image CDNs for use with the <ResponsiveImage/> component.

The @responsive-image/ember addon exposes these as globally available helpers (app-js) for use in classic .hbs files. When using template tag (.gjs/.gts) you can import there directly from the @responsive-image/cdn package.

Please refer to the image CDN guide for details on all supported options and examples of the respective image CDN.

TypeScript and Glint

All components and helpers have proper Glint types, which allow you to get strict type checking in your templates.

Unless you are using template tag components with explicit imports already, you need to import the addon's Glint template registry and extend your app's registry declaration as described in the Using Addons documentation:

import '@glint/environment-ember-loose';

import type ResponsiveImageRegistry from '@responsive-image/ember/template-registry';

declare module '@glint/environment-ember-loose/registry' {
  export default interface Registry
    extends ResponsiveImageRegistry /* other addon registries */ {
    // local entries
  }
}

If you are using one of the build plugins, also make sure to have the necessary ambient declaration for image imports in place as described here!

FastBoot

Server-side rendering using FastBoot is fully supported, but might require some tweaks.

If you are using remote images using some of the providers for image CDNs, they require exposing some browser globals to the FastBoot sandbox. FastBoot does not allow access to globals that are available in both browser and node.js environments by default, like fetch or URLSearchParams, and URL has some known issue. To workaround these deficiencies, you need to explicitly expose some needed globals by creating a config/fastboot.js file in your app:

'use strict';

module.exports = function () {
  return {
    buildSandboxGlobals(defaultGlobals) {
      return { ...defaultGlobals, URL, URLSearchParams };
    },
  };
};