Skip to content

Latest commit

 

History

History
98 lines (73 loc) · 5.02 KB

debugging.md

File metadata and controls

98 lines (73 loc) · 5.02 KB
Raw

For most Ember applications, Ember CLI "just works". Run ember server in your Terminal and you get a LiveReload development server at http://localhost:4200. Run ember build, and you get a dist/ 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.

Logging

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 * or ember-cli:*. 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.

Breakpoints

As a JavaScript programmer or Ember Application author, you may be used to using the debugger statement 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 ember build, 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, set a 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 by typing cont (or simply c). Once the program begins executing, it will stop at any debugger statements it finds. You can then enter a REPL, by typing repl.

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.

Linking Addons

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 true from the 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:

  1. Clone the repo: git clone git@github.com:cibernox/ember-power-select.git
  2. In the index.js file make sure that the object exported has a method called isDevelopingAddon and it returns true.
  3. In the addon repo, run npm link
  4. 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.

Broccoli Debug

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:

  • Run npm install or yarn install
  • Delete the node_modules directory and run npm install or yarn install
  • Delete the dist directory (found in apps with versions < 3.4), delete node_modules, and npm install or yarn install