Mirage.js — Client-Side API Mock Server for Frontend Development

Introduction

Mirage.js runs a mock server entirely in the browser by intercepting fetch and XMLHttpRequest calls. It provides a full data layer with models, relationships, factories, and serializers, letting frontend teams develop and test against a realistic API without backend dependencies.

What Mirage.js Does

• Intercepts HTTP requests in the browser and returns configured responses
• Provides an in-memory database (Mirage DB) with ORM-like models and relationships
• Generates test data via factories and the Faker-powered seed system
• Simulates network latency and error responses for edge case testing
• Supports passthrough routes to forward certain requests to a real server

Architecture Overview

Mirage.js patches the global fetch and XMLHttpRequest constructors to route matching requests through its handler pipeline. Route handlers interact with an in-memory database backed by a schema of models and relationships. Serializers transform database records into API response formats (JSON:API, REST, or custom).

Self-Hosting & Configuration

• Install via npm and create a server in your app entry point
• Define models and relationships in the server config for the ORM layer
• Create factories for generating realistic seed data
• Use timing option to simulate network latency during development
• Disable or passthrough routes when connecting to a real backend

Key Features

• Full ORM with hasMany, belongsTo, and polymorphic relationships
• Factory system for generating large datasets with realistic attributes
• Serializer layer supporting JSON:API, Active Model, and custom formats
• Route shorthands that auto-generate CRUD endpoints from models
• Works with any frontend framework: React, Vue, Angular, Svelte

Comparison with Similar Tools

• MSW (Mock Service Worker) — Intercepts at the service worker level; Mirage.js includes a data layer
• JSON Server — File-based REST mock; Mirage.js runs in-browser with an ORM
• Polly.js — Records real API responses; Mirage.js builds mock responses from scratch
• Nock — Node.js-only HTTP mocking; Mirage.js runs in the browser
• WireMock — Java mock server; Mirage.js needs no separate process

FAQ

Q: Does Mirage.js work in production? A: It is designed for development and testing. Disable or remove it before deploying to production.

Q: Can I use it alongside a real API? A: Yes. Use this.passthrough() for routes you want to forward to the actual backend.

Q: Does it support GraphQL? A: Not natively, but you can define custom route handlers that parse GraphQL queries and return data from the Mirage DB.

Q: How do I seed the database with initial data? A: Use the seeds(server) hook in the server config to call server.create() with your factories.

Sources

• https://github.com/miragejs/miragejs
• https://miragejs.com/