Ember: Remove usage of global Ember variable

[benedikt]

This pull request is an effort to remove the usage of the Ember global variable from @storybook/ember.

Motivation

The global Ember variable has been deprecated since 2021, but #103 added a workaround to keep @storybook/ember working with it.

However, with Ember’s new build system (Embroider) on the horizon, the workaround is about to stop working. In fact, it’s already causing problems when Ember apps are built using Embroider’s staticEmberSource: true configuration.

Approach

The current implementation relies on the Ember global in two locations. It uses Ember.Component directly (as a wrapping component for the rendered story), and Ember.HTMLBars.template as a factory for precompiled Handlebars templates.

Our approach to remove the usage of the Ember global is based on two ideas:

1. Instead of using Ember.Component directly in @storybook/ember, we create a <Storybook::Story /> component in @storybook/ember-cli-storybook and load it in @storybook/ember using Ember’s dependency injection mechanism.
2. Instead of relying on Ember.HTMLBars.template to wrap the precompiled templates, we’re using createTemplateFactory from @ember/template-factory.

Changes to @storybook/ember

Removing babel-plugin-ember-modules-api-polyfill

This babel plugin was responsible for replacing any imports from Ember packages with calls to the Ember global.

# Original
import { inject } from "@ember/service";

# Transformed
const inject = Ember.inject.service;

By removing the plugin, this transformation doesn’t happen anymore.

Replacing babel-plugin-htmlbars-inline-precompile with babel-plugin-ember-template-compilation

These two babel plugins essentially do the same thing. They transform any precompileTemplate, or hbs tagged template strings into precompiled handlebars templates. However, babel-plugin-htmlbars-inline-precompile is considered deprecated, so it felt like a good opportunity to swap it with the supported version.

We also tweak the configuration a little bit to transform files within certain packages in node_modules. This way we can also precompile templates within Ember itself. While there aren’t a lot, they need to be precompiled at build time, otherwise things will break at runtime.

Adding package aliases for @ember/*, @glimmer/*, and other dependencies.

With babel-plugin-ember-modules-api-polyfill removed, any imports from @ember/* packages will fail because they don’t exists as published packages. Instead they are shipped within embers-source and out of reach. Adding these aliases makes the imports work.

Adding babel-plugin-debug-macros

Things already work fine in the development mode (storybook dev) with the above changes. However, creating static builds (storybook build) fails, because it tries to import debug packages like @glimmer/debug that don’t ship code for production environments.

To fix this, we need to add babel-plugin-debug-macros. This way we can set the DEBUG flag of @glimmer/env to false in production builds. Tree-shaking will take care of the rest and remove the dependency.

Changes to @storybook/ember-cli-storybook

Adding the Storybook::Story component

As @storybook/ember now tries to load the wrapping component from the applications dependency injection mechanism, we actually need to provide a component. In theory, this can be done in the user’s application, but why not be nice and ship it with ember-cli-storybook directly? The component is a classic Ember component. Unfortunately, we couldn’t figure out a way to render a Glimmer component into an HTML element. However, this is also the way Ember’s own rendering tests are currently doing this, so we figured it’s the way to go.

Removing the Ember global workaround

As a last step, we remove the window.Ember = require("ember").default; workaround from the build process for .storybook/preview-head.html. We also remove Ember.testing=true;, because that doesn’t work anymore without the global.

This leaves <script>runningTests = true</script> in the generated preview-head.html file. This global is still required to prevent the Ember application from attaching itself to the root component and rendering itself.

We tried to replicate the same behavior using deferReadiness(), but couldn’t make it work.

Known Issues

With the changes above, Storybook builds and runs as a server, provided the stories are simple and don't rely on app files or app state.

Unfortunately, there are a couple of known issues we discovered so far.

Importing Ember packages from within stories

While importing code from @ember/* packages works, the code doesn’t necessarily work as expected.

One example is importing getOwner from @ember/application from within a story. The getOwner function will exist, but it will be different from the one used inside the Ember application. As a result, calling getOwner on an object instance from the application will not return the application’s owner.

A similar problem exists with on from @ember/object/evented. The function will exist, but it will not have any effect when attached to an instance from the application. For example, an on('init') in the context of a story would previously be called when the story gets rendered. After these changes, it will silently fail and not run at all.

The only possible workaround we found so far is gain relying on the global require and loading things like getOwner and on via that way:

const { getOwner } = global.require('@ember/application');
const { on } = global.require('@ember/object/evented');

Importing from the application itself

While simple files are not a problem, Storybook will fail to build when the files include imports from @ember/* packages (i.e. @ember/string).

Short term improvements

There’s an upcoming change im Ember that changes the folder structure of ember-source/dist so that there isn’t a difference between packages and dependencies anymore. It apparently also will link the packages between themselves using relative paths, which could help with some of the issues we encountered when it comes to imports.

The change will also eventually remove define and require from global, so the current loadEmberApp function will probably need to change in the near future.

Long term solution

We currently think that most of the problems come from the fact that there are two build processes in place:

• First, there’s Ember’s build process that creates the self contained application that is then imported using global.require and booted within the preview iframe.
• Second, there’s a separate build process for stories itself. The story files get generated afterwards and therefore load code entirely separately.

Previously, this was not an issue, because everything relied on the Ember global from the app’s build process and therefore sharing the same code and the same instances.

We believe that the only viable long term solution is getting rid of the initial build process of the app by incorporating it with the story build process itself. This would potentially also remove the need for the @storybook/ember-cli-storybook package, because all its responsibilities would be handled by @storybook/ember itself.

It sounds like this should be possible with Embroider, but we haven’t explored the details, yet. It might also make sense to start this effort as a separate Storybook renderer and builder. There’s likely not going to be a lot of overlap with the current implementation of @storybook/ember.

Acknowledgements

Thanks to @NullVoxPopuli for getting us unstuck with the debug macro and package aliases. Thanks to @gossi for his work on Hokulea’s storybook explorer, which inspired some of the ideas in this PR.

[leoeuclids]

We just found out that, since the new storybook/story component is being added by @storybook/ember-cli-storybook, we can customize it and workaround a few of the dependencies (i.e. on and getOwner).

// components/storybook/story.js

import Component from '@ember/component';
import { service } from '@ember/service';

export default Component.extend({
  store: service('store'),

  didInsertElement() {
    this.setProperties(this.setupStory() ?? {});
  },

  setupStory() {
    return {};
  }
});

// story.stories.js

export const Default = Template.bind({});
Default.args = {
  setupStory() {
    return {
      user: this.store.findRecord('user', 1)
    };
  }
};

[shilman]

@benedikt Sorry for the massive delay on this. I've resolved the conflicts with the current branch, but am unable to push them to your remote.

[benedikt]

@shilman Thanks a lot for this. Much appreciated! Just sent you an invite with Write access to our fork.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 44d5954

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	1m 20s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-07-08 13:40:45 UTC

[storybook-app-bot]

Package Benchmarks

^{Commit: afaaf25, ran on 3 July 2025 at 09:45:27 UTC}

The following packages have significant changes to their size or dependencies:

@storybook/addon-docs

	Before	After	Difference
Dependency count	12	12	0
Self size	2.42 MB	2.12 MB	🎉 -303 KB 🎉
Dependency size	8.93 MB	8.93 MB	0 B
Bundle Size Analyzer	Link	Link

storybook

	Before	After	Difference
Dependency count	51	51	0
Self size	31.75 MB	39.97 MB	🚨 +8.22 MB 🚨
Dependency size	17.43 MB	17.43 MB	0 B
Bundle Size Analyzer	Link	Link

@storybook/ember

	Before	After	Difference
Dependency count	202	213	🚨 +11 🚨
Self size	28 KB	30 KB	🚨 +2 KB 🚨
Dependency size	27.95 MB	31.21 MB	🚨 +3.26 MB 🚨
Bundle Size Analyzer	Link	Link

sb

	Before	After	Difference
Dependency count	52	52	0
Self size	1 KB	1 KB	0 B
Dependency size	49.18 MB	57.40 MB	🚨 +8.22 MB 🚨
Bundle Size Analyzer	Link	Link

@storybook/cli

	Before	After	Difference
Dependency count	217	217	0
Self size	582 KB	580 KB	🎉 -2 KB 🎉
Dependency size	94.81 MB	106.58 MB	🚨 +11.77 MB 🚨
Bundle Size Analyzer	Link	Link

@storybook/codemod

	Before	After	Difference
Dependency count	186	186	0
Self size	31 KB	31 KB	0 B
Dependency size	78.91 MB	87.13 MB	🚨 +8.22 MB 🚨
Bundle Size Analyzer	Link	Link

create-storybook

	Before	After	Difference
Dependency count	1	1	0
Self size	12.50 MB	16.06 MB	🚨 +3.55 MB 🚨
Dependency size	98 KB	98 KB	0 B
Bundle Size Analyzer	Link	Link

[ndelangen]

@gossi I think you're working on a PR, that negates the need for this one, correct?

[gossi]

At the time this PR was created it was legit. Today it is still legit PR but no longer for the next branch of storybook. Though doable in terms of maintenance for the v9 branch of storybook.

Ember build systems and their compatibility with storybook:

• Ember classic build (brocooli): Storybook <= 9
• Embroider build (webpack): Storybook <= 9
• Ember vite bulid: Storybook 10+

Storybook 10 is ESM only, which breaks compat with older Ember build systems. I'm working on the vite system.

So this PR is still worthy but time and context has changed since it has been started, please re-evaluate.

I notice this PR allows to use Ember with Storybook and mock a lot of conecpts necessary to make effective use of storybook at all.
Note to all storybook team members: Migrating your ember app to vite is what we all want to do, but not done overnight, we are speaking about months to quarters.

So even if I might be able to land support Storybook for ember vite, this is still worthy for those companies who bet on Storybook + Ember year(s) ago and will be stuck with storybook v9 + their Ember build system until finishing the migration.