Updating your version of Mirage

To install a new version of Mirage, run

npm install ember-cli-mirage@X.X.X --save-dev
ember g ember-cli-mirage

The ember g ember-cli-mirage command ensures all of Mirage’s Bower dependencies are added to your project. It runs during ember install, and it’s always a good idea to run it when upgrading.

Use ember-cli-mirage@beta to get the latest beta.


You can view Mirage’s full Changelog here:

0.1.x > 0.2 Upgrade guide

If you’re upgrading your Mirage server from v0.1.x to v0.2.x, here’s what you need to know:

  • The default Mirage directory has changed. The default Mirage directory has moved from /app/mirage to /mirage. When you install 0.2.0, the default blueprint will add the /mirage directory to your project. You can delete it and move your current Mirage files to the new location with something like

    rm -rf mirage
    mv app/mirage mirage

    from the root of your project. Mirage’s directory is also customizable (Although you should move it from the /app directory or else it will not be removed from the build in production mode).

  • All multiword filenames are dasherized. In Mirage 0.1.x, database collection names were taken from filenames. The idea was, if your API returned snake_case collection keys (e.g. blog_posts: []), just name your file fixtures/blog_posts.js. This approach turned out to be insufficiently flexib– what am I saying, it was just a bad idea :P.

    In Mirage 0.2.x, we follow Ember CLI’s conventions of dasherized filenames. So, you’ll just need to go through and change

    # etc.



    You will then use the new Serializer layer to do things like format keys in your json payloads.

  • All JavaScript properties are camelCased. Similar to the previous change, factory properties and database collection names followed the format of your API in Mirage 0.1.x. If you were faking an ActiveModelSerializer backend, multiword keys used snake_case throughout your Mirage code. So, your database table might be db.blog_posts, and your factory keys might be first_name() {..}. Looks pretty cool right?

    Wrong. We’re JavaScript developers here, people. It’s time to start using camelCase. (Also, the idea of tying these keys to your serialization format was bad, as it left us without any conventions. We need to stick to a single format, so the ORM knows how to find foreign keys.)

    You’ll need to update your route handlers, which may look like this:

    let posts = db.blog_posts.filter(p => p.author_id === 1);


    let posts = db.blogPosts.filter(p => p.authorId === 1);

    Note that everything is camelCased, including foreign keys.

    Similarly, factories that look like

    export default Factory.extend({
      first_name() {
      last_name() {

    should be changed to

    export default Factory.extend({
      firstName() {
      lastName() {

    This goes for all attrs that server.create takes (and returns), etc. For many this will be the most painful part of the upgrade. Please find it in your heart to forgive me.

  • Mirage now has its own Model layer (an ORM). In Mirage 0.1.x, you had to define either a factory or a fixture file (or both) in order for a database collection to be created, which let you take advantage of the db in your route handlers. In 0.2, we’ve introduced Mirage Models, which serve as the new canonical source of truth about your database.

    To create a model, use

    ember g mirage-model blog-post

    This will create a file like

    import { Model } from 'ember-cli-mirage';
    export default Model.extend({

    Having that file sets up the db.blogPosts collection, allows you to use the JSON:API serializer, and more. You can still define factories and fixtures - but only if you need them. Models, factories and fixtures all work together, but now you won’t be making blank factory or fixture files just to set up your database. The models themselves serve as the source of truth.

    We needed to add models for association support (which currently exists) and factory relationships (the first feature to come after the 0.2 release). Read through the models guide and serializers guide to see how having models can simplify your Mirage server.

    We also have a plan to make a separate addon that could ascertain your model definitions and their relationships from your Ember Data models. Adding the ORM paves the way for this important future addition.

    Currently, Mirage will still work if a factory/fixture file is defined for a particular db collection without a corresponding model. Eventually, we may require all setups to have model definitions for each collection. But for now, to make for an easier upgrade path, you can start generating models and opt-in to the ORM layer in piecemeal.

  • The ORM object schema is now injected into route handlers. In Mirage 0.1.x, the db was the first parameter injected into route handlers:

    this.get('/posts', function(db, request) {
      // work with db

    Now, the schema object is, so you can take advantage of the Model layer. Fortunately, the db hangs directly off of the schema, so you can leave all your old route handler code intact (with the exception of making the change to camelCase), and just use destructuring to change the function signature to

    this.get('/posts', function({ db }, request) {
      // work with db

    and then start opting-in to the ORM (and using schema) one route handler at a time.

  • Specify a Serializer. If you’re using shorthands, you’ll need to pick a serializer in /mirage/serializers/application.js. See the serializers guide for details.

You can always view the full changelog to see everything that’s changed in 0.2.x. If you think this guide missed a critical part of the upgrade path, please open an issue or help improve it!