vite-plugin-simple-json-server

0.6.2 verified Mon Apr 27 auth: no javascript

A Vite plugin that provides a file-based mock API using JSON files during development. Version 0.6.2 (Feb 2025) is the latest stable release, published under MIT license. It offers zero-config CRUD endpoints from JSON files placed in a 'mock' directory, with built-in pagination, sorting, filtering (including operators like ne, lt, gt), and OpenAPI/Swagger UI support. Unlike heavier mock servers, it integrates directly into Vite's dev server, requires no database, and ships TypeScript types. It also serves static files and allows custom route handlers. Node >=15.7.0 required; Vite ^4.0.0 peer dependency.

Common errors

error Error: The plugin 'vite-plugin-simple-json-server' requires Vite ^4.0.0 but current Vite version is 5.x ↓

cause Plugin peer dependency restricts to Vite 4.x.

fix

Downgrade Vite to 4.x, or wait for plugin update that supports Vite 5.

error Error: require() of ES Module vite-plugin-simple-json-server not supported. Instead change the require to a dynamic import. ↓

cause Package is ESM-only but being used in a CJS context.

fix

Use import statement (native ESM) or enable experimental ESM support in Node.

error JSON at position 0 unexpected token ↓

cause File in mockDir is not valid JSON or has BOM.

fix

Ensure all JSON files are valid and start with '[' or '{'. Remove BOM characters.

Warnings

breaking v0.6.0: 'count' query parameter replaced by HEAD method. Existing code using ?count= will break. ↓

fix Use HEAD /collection or /collection?filter=value to get count via X-Total-Count header instead of ?count=true.

breaking v0.5.0: mockRootDir option renamed to mockDir. Existing configs using mockRootDir will be ignored. ↓

fix Rename option from 'mockRootDir' to 'mockDir' in vite config.

breaking v0.5.0: POST, PUT, PATCH operations now also work for non-array JSON. Previously they only worked for arrays. This may affect custom behavior relying on read-only non-array endpoints. ↓

fix Ensure non-array JSON files are not accidentally mutated via POST/PUT/PATCH requests if unintended; consider adding custom handlers or restricting methods.

gotcha Query parameters for sorting/filtering that do not match any JSON field are silently ignored. Misspelled field names may go unnoticed. ↓

fix Double-check field names in query parameters; use exact field names from the JSON data.

gotcha Pagination (offset/limit) and count only work for JSON files that contain arrays at the top level. Single objects or nested data will not paginate. ↓

fix Ensure mock JSON files for collection endpoints are arrays of objects; for single resources, use object files without array wrapper.

deprecated The plugin only works with Vite ^4.0.0. Incompatible with Vite 5+ until updated. ↓

fix Use Vite 4.x; check latest version for Vite 5 support.

Install

npm install vite-plugin-simple-json-server

yarn add vite-plugin-simple-json-server

pnpm add vite-plugin-simple-json-server

Imports

default
```
import jsonServer from 'vite-plugin-simple-json-server'
```
Default export is the Vite plugin function. CommonJS require works but TypeScript may need esModuleInterop.
SimpleJsonServerOptions
```
import type { SimpleJsonServerOptions } from 'vite-plugin-simple-json-server'
```
TypeScript type for plugin options; can also be imported as a named type.

Plugin

wrong

const jsonServer = require('vite-plugin-simple-json-server') as any

correct

import { Plugin } from 'vite'; import jsonServer from 'vite-plugin-simple-json-server'

The plugin returns a Vite Plugin object; the default export is a function that returns the plugin.

Quickstart

Minimal setup for file-based mock API with Vite, including CRUD, pagination, sorting, filtering.

// vite.config.ts
import { defineConfig } from 'vite';
import jsonServer from 'vite-plugin-simple-json-server';

export default defineConfig({
  plugins: [jsonServer()],
});

// mock/products.json
// [
//   { "id": 1, "name": "Banana", "price": 2, "weight": 1 },
//   { "id": 2, "name": "Apple", "price": 1.5, "weight": 0.8 }
// ]

// After starting dev server:
// curl http://localhost:5173/products -> returns the full array
// curl "http://localhost:5173/products?sort=-price" -> sorted by price descending
// curl "http://localhost:5173/products?name=Apple" -> filtered by name (exact match)
// curl "http://localhost:5173/products?offset=0&limit=1" -> paginated, first item
// curl -X POST -H "Content-Type: application/json" -d '{"name":"Orange","price":3}' http://localhost:5173/products -> creates a new item
// Swagger UI at http://localhost:5173/__swagger