Last spring our frontend team had a sprint planned around a new orders dashboard. The designs were done, the tickets were groomed, and the backend was nowhere close. The API contract existed as a shared doc with three open comments on it. Four frontend devs were about to spend two weeks building against TODO and hard-coded arrays.
I'd seen that movie before. Everyone writes their own fake data inside components, nobody's fake data matches anyone else's, and the week the real API lands you spend two days ripping out mocks and finding out the date format was different all along.
So I blocked off an afternoon and gave the team a shared mock server instead. Here's exactly what I did, what worked, and the one thing I'd do differently.
Start from the contract, not from the UI
The temptation is to look at the Figma file and invent data that makes the screens look good. Don't. Open the API contract (or whatever the backend team has written down, even a Slack thread) and copy the field names exactly. If they say created_at in snake case, your fake data says created_at in snake case, even if it annoys you.
I asked the backend lead for fifteen minutes and we agreed on three endpoints:
-
GET /ordersreturning a list -
GET /orders/:idreturning one order with line items -
PATCH /orders/:idto update status
That was enough to unblock the whole dashboard.
The JSON file
I used json-server because it takes a single file and gives you REST routes for free. Install it as a dev dependency so it's pinned with the project:
npm install --save-dev json-server
Then a mock/db.json at the repo root:
{
"orders": [
{
"id": 1001,
"status": "pending",
"customer_name": "Test Customer A",
"total_cents": 4599,
"currency": "USD",
"created_at": "2026-03-02T09:14:00Z",
"items": [
{ "sku": "SKU-RED-01", "qty": 2, "price_cents": 1500 },
{ "sku": "SKU-BLU-07", "qty": 1, "price_cents": 1599 }
]
},
{
"id": 1002,
"status": "shipped",
"customer_name": "Test Customer B",
"total_cents": 0,
"currency": "USD",
"created_at": "2026-03-01T22:40:00Z",
"items": []
}
]
}
Notice order 1002. Zero total, empty items. I put that in on purpose. Mock data that only has happy, fully populated records trains your UI to break on the first weird row in production.
Add a script:
"scripts": {
"mock": "json-server --watch mock/db.json --port 4000"
}
Run npm run mock and you've got GET /orders, GET /orders/1001, PATCH /orders/1001 and friends, all backed by a file you can commit.
Point the app at it with one variable
The frontend already read its API base URL from an env var. I added a .env.mock:
VITE_API_URL=http://localhost:4000
and a script dev:mock that loaded it. That's the whole switch. No if (isMock) branches in components, no special fetch wrapper. When the real API shows up, you change the URL and nothing else.
Fake the slow and the broken too
Real APIs are slow sometimes and fail sometimes. A json mock server that always answers in 2ms hides every loading-state bug you have. json-server takes a --delay flag, so I added a second script:
"mock:slow": "json-server --watch mock/db.json --port 4000 --delay 1500"
For errors I wrote a tiny middleware file that returns a 500 whenever a request has ?fail=1 on it. Twelve lines. It caught two missing error states in the first week, which paid for the whole afternoon.
What I got wrong
I let the mock data drift. By week two people had added fields to db.json that weren't in the contract because "the UI needed it." Some of those were reasonable asks, but they never made it back to the backend team. When the real API landed, three fields we'd been rendering didn't exist.
The fix is boring. Any change to db.json goes in its own PR, and the backend lead is a required reviewer on that path. Mock data is a contract, and contracts need two signatures.
There's a deeper issue too, and it's the reason I don't think hand-written mocks should live forever. A file you wrote by hand only knows what you thought the API would do. Once a real backend exists, it's worth looking at approaches that capture real responses and replay them, so your fakes are grounded in actual traffic. If you want the bigger picture on how a json mock server fits next to recorded mocks and other options, that write-up covers the trade-offs well.
My opinion: keep it dumb
People asked if we should add GraphQL, auth simulation, random data generators, the works. I said no. The value of this setup was that anyone on the team could open one JSON file and understand what the "API" would return. The moment your mock needs its own documentation, it's become a second backend that nobody owns.
Faker-style random data is the one I'd push back on hardest. Random names are fine, but random structure makes bugs unreproducible. If a teammate says "the table breaks on order 1002," everyone should see the same order 1002.
How the sprint actually went
The frontend shipped the dashboard against the mock in nine working days. The real API landed on day eleven. Switching over took about half a day, most of it spent on those three drifted fields I mentioned. Not zero, but a lot better than four devs idling for a week.
A practical tip before you try this
Put the mock server in the repo, not on someone's laptop or a shared box. When it's a committed file plus an npm script, new hires get it on day one, CI can run against it, and nobody has to ask "is the mock up?" ever again.
What's the weirdest record you keep in your mock data on purpose?

Top comments (0)