@embroider/macros

What is @embroider/macros?

@embroider/macros is a package designed for use with the Embroider build system for Ember.js applications. It provides a set of macros that allow developers to write conditional code that can be optimized away at build time, enabling features like dead code elimination and environment-specific code paths.

What are @embroider/macros's main functionalities?

Environment-Specific Code

This feature allows you to write code that only runs in specific environments, such as production or development. The `macroCondition` and `getOwnConfig` functions are used to determine the environment and conditionally execute code.

import { macroCondition, getOwnConfig } from '@embroider/macros';

if (macroCondition(getOwnConfig().isProduction)) {
  console.log('This code runs only in production');
} else {
  console.log('This code runs in development');
}

Dead Code Elimination

This feature allows you to write code that is only included in the build if certain conditions are met, such as the presence of a specific dependency version. This can help reduce the size of your final build by eliminating unnecessary code.

import { macroCondition, dependencySatisfies } from '@embroider/macros';

if (macroCondition(dependencySatisfies('ember-source', '>=3.20.0'))) {
  console.log('This code runs only if ember-source version is 3.20.0 or higher');
}

Static Configuration

This feature allows you to access static configuration values at build time. The `getConfig` function retrieves configuration values that can be used in your application code.

import { getConfig } from '@embroider/macros';

const config = getConfig();
console.log(`API endpoint: ${config.apiEndpoint}`);

Other packages similar to @embroider/macros

babel-plugin-macros

babel-plugin-macros is a Babel plugin that allows you to create compile-time code transformations using macros. It provides similar functionality to @embroider/macros by enabling conditional code and static configuration, but it is not specific to Ember.js and can be used with any JavaScript project.

webpack

Webpack is a popular module bundler for JavaScript applications. It provides features like environment-specific code and dead code elimination through plugins and configuration options. While it is more general-purpose and not specific to Ember.js, it can achieve similar results to @embroider/macros with the right setup.

rollup

Rollup is a module bundler for JavaScript that focuses on creating smaller and faster bundles. It offers features like tree-shaking (dead code elimination) and can be configured to handle environment-specific code. Like webpack, it is not specific to Ember.js but can be used to achieve similar goals.

README

@embroider/macros

A standardized solution for modifying your package's Javascript and Glimmer templates at app-compilation-time.

Motivation

Traditionally, Ember addons have a lot of power to run arbitrary code during the build process. This lets them do whatever they need to do, but it also makes them hard to statically analyze and makes them play badly with some tooling (like IDEs).

The Embroider package spec proposes fixing this by making Ember addons much more static. But they will still need the ability to change themselves in certain ways at app compilation time. Hence this package.

This package works in both Embroider builds and normal ember-cli builds, so that addon authors can switch to this newer pattern without disruption.

Examples

import { dependencySatisfies, macroCondition, failBuild } from '@embroider/macros';

if (macroCondition(dependencySatisfies('ember-data', '^3.0.0'))) {
} else

The Macros

dependencySatisfies

Tests whether a given dependency is present and satisfies the given semver range.

Setting Configuration: from an Ember app

1. Add @embroider/macros as devDependency.

2. In ember-cli-build.js, do:

   let app = new EmberApp(defaults, {
     '@embroider/macros': {
       // this is how you configure your own package
       setOwnConfig: {
         // your config goes here
       },
       // this is how you can optionally send configuration into your
       // dependencies, if those dependencies choose to use
       // @embroider/macros configs.
       setConfig: {
         'some-dependency': {
           // config for some-dependency
         },
       },
     },
   });
   

Setting Configuration: from an Ember Addon

1. Add @embroider/macros as dependency.

2. In index.js, do:

   module.exports = {
     name: require('./package').name,
     options: {
       '@embroider/macros': {
         setOwnConfig: {
           // your config goes here
         },
         setConfig: {
           'some-dependency': {
             // config for some-dependency
           },
         },
       },
     },
   };
   

Changelog

0.14.0

• ENHANCEMENT: multiple additions and bugfixes to the macro system by @simonihmig
• COMPAT: ast transforms in stage1 didn't see the same moduleNames as under stock ember-cli, by @SparshithNR
• COMPAT: always define runningTests by @thoov
• COMPAT: resolve ambiguous addon merges in the same order as stock ember-cli by @thoov
• COMPAT: more progress on engines support
• COMPAT: more progress on fastboot support by @SparshithNR
• BUGFIX: correctly handle ember-auto-import's dynamic import()
• DOCS: add info about disabling the webpack bundle analyzer browser by @ohcibi