Upcoming deprecation of baseURL in Ember CLI 2.7

Apr 28, 2016 – By Nathan Hammond

The baseURL configuration option and the accompanying <base> tag in Ember CLI applications are often and tragically misunderstood. There have been at least 67 issues opened for Ember CLI referencing baseURL, making it one of the most common points of discussion. As a result, in Ember CLI's canary channel, we have deprecated baseURL and removed the default <base> inside of index.html. The intent is that this change will be released with Ember CLI 2.7 stable in roughly 10 weeks.

Existing applications are able to continue using baseURL with a deprecation warning. If you are eager to adopt this change, you should note that the removal of the <base> tag may impact how your application is deployed, and if so, will likely require some small migration effort, detailed below.

This is the culmination of a lot of research and work by Tobias Bieniek and we're incredibly grateful for his efforts.

What was it?

baseURL allowed an Ember application and assets to be deployed to a subdirectory without requiring rewriting of asset URLs, instead allowing them to be included relatively. For example given an HTML file:

<head>
  <base href="http://emberapp.example.com/path/to/application/">
  <link rel="stylesheet" href="assets/style.css">
</head>
<body>
  <img src="assets/images/image.png">
</body>

The style would be fetched from http://emberapp.example.com/path/to/application/assets/style.css, and the image from http://emberapp.example.com/path/to/application/assets/images/image.png. If you are curious, here is a good read on the base tag. In short, baseURL is the configuration property Ember CLI used to identify what value to put in the <base href="..." /> tag included in index.html. This determined where assets for the application should be loaded from, including app.js, vendor.js, app.css, and anything else that isn't specified with a fully-qualified path.

Why are we deprecating it?

Variations on the baseURL solution has been Ember CLIs default asset prefixing behavior for two years. There are a number of reasons why we're moving away from this pattern, but a few things really made it unnecessarily complicated.

API Design Bugs

Since we added this feature two years ago apps can have both baseURL and rootURL configuration values. These two names are far too similar and do things which are far too similar. Where baseURL identified the asset prefix of an application, rootURL identifies the path at which an Ember application is served so Ember's router can know which path segments to ignore.

Implicit Behavior

Not only are there two confusing configuration options, but if only one of baseURL or rootURL was set Ember CLI made a best-effort guess at populating the other's value. This implicit behavior violated the principle of least surprise for many people. An explicit requirement for both values always being set and clearer documentation would have averted some of the pain but would have added additional things to the learning curve.

Integration With Other Applications

Not every Ember application is full green field development. If you happened to have legacy user-generated HTML, or other data containing relative links, this didn't play nicely with the <base> tag. Rewriting this content is an option, but incurs cost and bugs that can be avoided by not including the <base> tag.

SVG

Worst of all, and something that we can't code or document around, SVG <use> elements break in an unexpected way when used with a <base> tag. It turns out that the relatively common pattern of <use xlink:xhref="#__SVG_ID__"></use> referencing a fragment identifier doesn't play nicely with the <base> tag. We like to play nicely with the web ecosystem and this fault is the final straw that resulted in the decision of removing the <base> tag.

How Do I Migrate?

Existing applications are able to continue using baseURL with a deprecation warning. For users who do want to migrate, the steps depend primarily on how your application is deployed. It's our goal is to make it easy for you to achieve the same behaviors you've had in the past.

New Applications

If you're starting a new application using an Ember CLI canary (or eventually 2.7 stable) everything should work correctly out of the box. We've been very careful to make sure that the out of the box experience is as smooth as possible. For the built-in development server all assets will be served at the rootURL. Relative URLs will continue to work fine inside of your CSS files and paths to assets included in your templates, index.html, or inserted via {{content-for}} should specify a root-relative path.

Upgrading

If you are upgrading your application to the new version of Ember CLI (canary with this change, or eventually 2.7 stable), you should pay close attention to the configuration changes inside of the modified blueprint files. We have also inserted deprecation warnings which will hopefully guide you through each of these changes.

The primary migration effort is that you should expect to adjust any relative paths which appear in your templates, are inserted via {{content-for}}, or directly present in index.html. Because you will be serving index.html from the server for any arbitrary route in your application you must modify these to be either a fully-qualified path or a root-relative URL.

As an example, given this configuration where you have configured a different rootURL and baseURL:

// config/environment.js
var ENV = {
  /* ... */
  rootURL: '/path/to/application/',
  baseURL: '/assets/go/here/'
  /* ... */
}

You would remove the baseURL option and modify your templates like so:

{{!-- Old: --}}
<img src="images/logo.png" />

{{!-- New: --}}
<img src="/assets/go/here/images/logo.png" />

How To Use a CDN

One of the most common use cases for baseURL was pointing to assets on a CDN. After this change to remove baseURL you should use the prepend option for broccoli-asset-rev which is included with Ember CLI apps by default. For example, in ember-cli-build.js:

// ember-cli-build.js
var app = new EmberApp(defaults, {
  // Add options here
  fingerprint: {
    prepend: 'https://cdn.example.com/'
  }
});

Note that the prepend option only applies when doing production builds via something like ember build --prod. Given the above example, and this input:

// config/environment.js
var ENV = {
  /* ... */
  rootURL: '/path/to/application/'
  /* ... */
}

<!-- Snipped from the <head> of the new `index.html` blueprint.  -->
<link rel="stylesheet" href="{{rootURL}}assets/vendor-844b5cc5093b11929a8b3c1ef59c3d98.css">
<link rel="stylesheet" href="{{rootURL}}assets/app-name.css">

The output for asset paths in index.html would look something like:

<link rel="stylesheet" href="https://cdn.example.com/path/to/application/assets/vendor-e37004361bf9cda2ab3379d96c9eba4b.css">
<link rel="stylesheet" href="https://cdn.example.com/path/to/application/assets/app-name-dc477601773d4043b0c461b2a0ae8aef.css">

Note that rootURL is present as part of the path for the CDN-hosted assets inside of index.html. rootURL is an Ember CLI concept primarily concerned with supporting the behavior of ember server.

Configuring the Router

We also use the setting for rootURL at runtime in the application's router:

// app/router.js
import Ember from 'ember';
import config from './config/environment';

const Router = Ember.Router.extend({
  rootURL: config.rootURL
});

In most cases this does exactly what you want it to do. However, if you wish to mount the application at a different place than the Ember CLI rootURL specifies for its ember serve location, you may add an additional property in your config, routerRootURL, to specify the path that your application will live at runtime.

// config/environment.js
var ENV = {
  /* ... */
  rootURL: '/',
  routerRootURL: '/path/to/application/'
  /* ... */
}

You would then reference that inside of your application's router like so:

const Router = Ember.Router.extend({
  rootURL: config.routerRootURL
});

This provides a method to remove the '/path/to/application/' prefix from assets inside of index.html which will be served from a CDN.

CSS, Fonts, and Other Static Assets

Depending upon how these were included into an application, their paths may need to be adjusted. Assets like these are often handled outside the Ember CLI build pipeline, but do check to make sure that everything is works as expected.

Addon Consumption and Development

It's possible that you have addons which rely on rewriting asset URLs. If there is any impact, it is most likely going to impact users of ember-cli-deploy. Please let us know what you discover during this canary/beta process, we'd like to see what each addon is attempting to accomplish and make sure we can support that use case.

Everything is Broken! Help!

If for some reason removing baseURL and the default <base> tag causes problems, you can still add a <base> tag directly to your index.html file:

<base href="/what/your/baseURL/was/" />

This can be useful to address relative URLs which are being inserted via templates, index.html, or {{content-for}}. For pathing to your built CSS and JS assets use the method described for CDNs.

How Can I Try This?

Using our new release channel setup, you can try this change by upgrading your Ember CLI app to the canary channel:

npm install --save-dev ember-cli/ember-cli#canary

If you discover any problems with this change please file an issue, we'll be paying especially close attention to this topic.