For most Ember applications, Ember CLI "just works". Run
ember server in your Terminal and you get
a LiveReload development server at
ember build, and you get a
directory with compiled assets ready to be deployed to your production server.
But things don't always go smoothly and CLI commands can fail inexplicably with error messages that can sometimes be difficult to act on. In these cases, it can be useful to have tools to figure out what went wrong.
In most programming languages, the two most useful debugging tools are logging and breakpoints. Let's cover both of these tools in the context of Ember CLI.
Ember CLI's default output is pretty quiet. Under the hood it uses the
debug library to log messages.
You can see this output by setting the
DEBUG environment variable to
Typically, environment variables specific to a command are set by prefixing the command. For example:
DEBUG=ember-cli:* ember build
You can set the variable to
*. Consult the
debug library documentation for additional ways to
focus on the logs you care about.
to pause execution and enter a REPL where you can inspect the current state of the program. By default,
when you run a Node.js program such as
debugger statements are ignored. In order to
pause execution and enter a REPL as you can in a browser, you can use
node inspect. For example,
debugger at the top of
ember-cli-build.js, and then run:
node inspect ./node_modules/.bin/ember build
You'll first see the build command pause at the start of the program. You can tell it to continue
cont (or simply
c). Once the program begins executing, it will stop at any
statements it finds. You can then enter a REPL, by typing
In addition to stepping through this code using the Node.js debugger, you can also "attach" other debugging
clients such as Google Chrome to this session. For example, to attach Google Chrome, open a new Google Chrome
window, go to
chrome://inspect in the location bar, and click on the "Inspect" link.
You can use this technique for build steps in your app, addon, or custom blueprint or any other part of the build pipeline.
Read more about debugging Node.js here.
While logging and breakpoints are useful, there are additional challenges when the code you are trying
to debug lives in an Ember addon (or other module). A useful way of debugging addons or testing changes
is to use
npm link. Although linking dependencies is not specific to Ember addons, for debugging
run time code (such as Components or Services) while the development server is running, you can return
isDevelopingAddon method in
index.js. This will ensure that the Ember CLI knows to rebuild
your app when code in the linked addon changes.
For example, if your app installs
ember-power-select, and you want to test a code change, you can:
- Clone the repo:
git clone email@example.com:cibernox/ember-power-select.git
- In the
index.jsfile make sure that the object exported has a method called
isDevelopingAddonand it returns
- In the addon repo, run
- In your app, run
npm link ember-power-select
You can verify this did the intended thing by checking that
node_modules/ember-power-select is now
a symlink pointing to the cloned repo.
Now, in your app, if you run
ember server, it should use the linked repo and any code changes in
your local clone of
ember-power-select should get picked up by the app.
Ember CLI is a wrapper around the Broccoli asset pipeline. Most of the functionality that Ember CLI
provides (asset compilation, fingerprinting, integrating addons, etc) is implemented through various
Broccoli plugins. Because this plugin system is unique to Broccoli, a unique debugging plugin
can sometimes be helpful. This is also implemented as the
broccoli-debug plugin. Check
out the documentation in its README to learn how to use it!
Assets and Dependencies
Sometimes build tools show especially broken output. This can happen for a variety of reasons, but the all-purpose technique of "turning it on and off" can apply to Ember CLI as well.
Some common steps are to stop the server, try one or more of these steps, and start the server again:
- Delete the
node_modulesdirectory and run
- Delete the
distdirectory (found in apps with versions < 3.4), delete