@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.

Javascript macros

• getOwnConfig(): a macro that returns arbitrary JSON-serializable configuration that was sent to your package. See "Setting Configuration" for how to get configuration in.

  Assuming a config of { flavor: 'chocolate' }, this code:

  import { getOwnConfig } from '@embroider/macros';
  console.log(getOwnConfig().flavor);
  

  Compiles to:

  console.log({ flavor: 'chocolate' }.flavor);
  

• getConfig(packageName): like getOwnConfig, but will retrieve the configuration that was sent to another package. We will resolve which one based on node_modules resolution rules from your package.

• dependencySatisfies(packagename, semverRange): a macro that compiles to a boolean literal. It will be true if the given package can be resolved (via normal node_modules resolution rules) and meets the stated semver requirement. The package version will be semver.coerce()'d first, such that nonstandard versions like "3.9.0-beta.0" will appropriately satisfy constraints like "> 3.8".

  Assuming you have ember-source 3.9.0 available, this code:

  import { dependencySatisfies } from '@embroider/macros';
  let hasNativeArrayHelper = dependencySatisfies('ember-source', '>=3.8.0');
  

  Compiles to:

  let hasNativeArrayHelper = true;
  

• macroIf(predicate, consequent, alternate): a compile time conditional. Lets you choose between two blocks of code and only include one of them. Critically, it will also strip import statements that are used only inside the dead block. The predicate is usually one of the other macros.

  This code:

  import { dependencySatisfies, macroIf } from '@embroider/macros';
  import OldComponent from './old-component';
  import NewComponent from './new-component';
  export default macroIf(dependencySatisfies('ember-source', '>=3.8.0'), () => NewComponent, () => OldComponent);
  

  Will compile to either this:

  import NewComponent from './new-component';
  export default NewComponent;
  

  Or this:

  import OldComponent from './old-component';
  export default OldComponent;
  

• failBuild(message, ...params): cause a compile-time build failure. Generally only useful if you put it inside a macroIf. All the arguments must be statically analyzable, and they get passed to Node's standard utils.format().

  import { macroIf, failBuild, dependencySatisfies } from '@embroider/macros';
  macroIf(
    dependencySatisfies('ember-source', '>=3.8.0'),
    () => true,
    () => failBuild('You need to have ember-source >= 3.8.0')
  );
  

• importSync(moduleSpecifier): exactly like standard ECMA import() except instead of returning Promise<Module> it returns Module. Under Emroider this is interpreted at build-time. Under classic ember-cli it is interpreted at runtime. This exists to provide synchronous & dynamic import. That's not a think ECMA supports, but it's a thing Ember historically has done, so we sometimes need this macro to bridge the worlds.

Template macros

These are analogous to the Javascript macros, although here (because we don't import them) they are all prefixed with "macro".

• macroGetOwnConfig: works like a helper that pulls values out of your config. For example, assuming you have the config:

  {
    "items": [{ "score": 42 }]
  }
  

  Then:

  <SomeComponent @score={{macroGetOwnConfig "items" "0" "score" }} />
  {{! ⬆️compiles to ⬇️ }}
  <SomeComponent @score={{42}} />
  

  If you don't pass any keys, you can get the whole thing (although this makes your template bigger, so use keys when you can):

  <SomeComponent @config={{macroGetOwnConfig}} />
  {{! ⬆️compiles to ⬇️ }}
  <SomeComponent @config={{hash items=(array (hash score=42))}} />
  

• macroGetConfig: similar to macroGetOwnConfig, but takes the name of another package and gets that package's config. We will locate the other package following node_modules rules from your package. Additional extra arguments are treated as property keys just like in the previous examples.

  <SomeComponent @config={{macroGetConfig "liquid-fire"}} />
  

• macroDependencySatisfies

  <SomeComponent @canAnimate={{macroDependencySatisfies "liquid-fire" "*"}} />
  {{! ⬆️compiles to ⬇️ }}
  <SomeComponent @canAnimate={{true}} />
  

• macroIf: Like Ember's own if, this can be used in both block form and expresion form. The block form looks like:

  {{#macroIf (macroGetOwnConfig "shouldUseThing") }}
    <Thing />
  {{else}}
    <OtherThing />
  {{/macroIf}}
  
  {{! ⬆️compiles to ⬇️ }}
  <Thing />
  

  The expression form looks like:

  <div class="box {{macroIf (macroGetOwnConfig "extraModeEnabled") extraClass regularClass}}" />
  {{! ⬆️compiles to ⬇️ }}
  <div class="box {{extraClass}}"/>
  

• macroMaybeAttrs: This macro allows you to include or strip HTML attributes themselves (not just change their values). It works like an element modifier:

  <div {{macroMaybeAttr (macroGetConfig "ember-test-selectors" "enabled") data-test-here data-test-there=42}} >
  {{! ⬆️compiles to either this ⬇️ }}
  <div data-test-here data-test-there=42 >
  {{! or this ⬇️ }}
  <div>
  

• macroFailBuild: cause a compile-time build failure. Generally only useful if you put it inside a macroIf. All the arguments must be statically analyzable, and they get passed to Node's standard utils.format().

  {{#macroIf (dependencySatisfies "important-thing" ">= 1.0")}}
    <UseThing />
  {{else}}
    {{macroFailBuild "You need to have import-thing >= 1.0"}}
  {{/macroIf}}
  

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
           },
         },
       },
     },
   };
   

Setting Configuration: Low Level API

Configuration is stored per NPM package, based off their true on-disk locations. So it's possible to configure two independent copies of the same package when they're being consumed by different subsets of the total NPM dependency graph.

Configuration gets set during the build process, from within Node.

The entrypoints to the low level API are:

• import { MacrosConfig } from '@embroider/macros': constructs the shared global object that stores config. It has methods for setting configuration and for retrieving the necessary Babel and HTMLBars plugins that will implment the config. See macros-config.ts for details.

Changelog

0.13.0

• COMPAT: follow the stock build's special-case behavior that forbids "template.hbs" as a template-only component
• ENHANCEMENT: add support for apps with custom app-boot content by @dnalagatla
• ENHANCEMENT: allow explicitly declared relative externals, which makes it easier to workaround some badly-behaved addons
• BUGFIX: fixed a bug in the way we make module paths relative
• COMPAT: support ember-cli 3.16, which dropped a function we were calling.