Vite Plugin Fake Server

Common errors

• TypeError: defineFakeRoute is not a function

  cause The `defineFakeRoute` utility was imported from the main package instead of the specific `/client` subpath.
  fix Change the import statement to `import { defineFakeRoute } from 'vite-plugin-fake-server/client'`.

• Module not found: Can't resolve 'vite-plugin-fake-server/client'

  cause This error typically occurs if the subpath export for `/client` is not correctly resolved by your module bundler or if the package installation is corrupted.
  fix Ensure `vite-plugin-fake-server` is correctly installed. Try deleting `node_modules` and `package-lock.json` (or `yarn.lock`) and reinstalling dependencies. Verify your Vite configuration for any unusual alias settings.

• Fake server routes are not updating or new fake files are not detected in development.

  cause This indicates an issue with the file watcher, which was a known problem in older versions, particularly with `chokidar@v4`.
  fix Upgrade `vite-plugin-fake-server` to version 2.2.0 or higher, which includes fixes for watcher-related issues. Also, verify that your Vite configuration's `include` option in the plugin matches your fake route file directory.

Warnings

• breaking Older versions of `vite-plugin-fake-server` might not be compatible with newer Vite versions. Specifically, ensure you are using v2.2.3 or higher for compatibility with Vite 8, and v2.1.3 or higher for Vite 6.
  Fix: Upgrade to the latest `vite-plugin-fake-server` version (currently v2.2.3) to ensure broad Vite compatibility.
• gotcha When defining fake routes, the `defineFakeRoute` function must be imported from `vite-plugin-fake-server/client`. Forgetting the `/client` subpath will lead to import errors.
  Fix: Always use `import { defineFakeRoute } from 'vite-plugin-fake-server/client'` in your fake route files.
• gotcha Users on older versions (pre-v2.2.2) might encounter issues with request bodies being missing in Firefox when using XHR/Fetch, due to a bug in the underlying `xhook` library.
  Fix: Upgrade to `vite-plugin-fake-server` v2.2.2 or newer to resolve Firefox request body issues.
• gotcha File watcher issues, particularly with `chokidar@v4`, preventing new fake route files from being detected or changes from being reloaded, were present in versions prior to v2.2.0.
  Fix: Ensure you are using `vite-plugin-fake-server` v2.2.0 or higher to benefit from watcher fixes.

Install

• npm install vite-plugin-fake-server npm
• yarn add vite-plugin-fake-server yarn
• pnpm add vite-plugin-fake-server pnpm

Imports

• vitePluginFakeServer
  wrong:

  const vitePluginFakeServer = require('vite-plugin-fake-server')

  correct:

  import { vitePluginFakeServer } from 'vite-plugin-fake-server'

  This is the main plugin function, typically configured in `vite.config.ts`.
• defineFakeRoute
  wrong:

  import { defineFakeRoute } from 'vite-plugin-fake-server'

  correct:

  import { defineFakeRoute } from 'vite-plugin-fake-server/client'

  The `defineFakeRoute` utility for creating route configurations must be imported from the `/client` subpath.
• FakeRoute

  import type { FakeRoute } from 'vite-plugin-fake-server/client'

  Used for type hinting when defining fake server routes. Use `import type` for type-only imports.

Quickstart

This quickstart demonstrates how to configure `vite-plugin-fake-server` in `vite.config.ts` and define two fake API routes using `defineFakeRoute` in `fake/user.fake.ts`. One route uses Mock.js, and the other uses Faker.js to generate user data, illustrating the plugin's flexibility. It also includes client-side JavaScript to show how to consume these fake endpoints.

import { defineConfig } from "vite";
import { vitePluginFakeServer } from "vite-plugin-fake-server";
import { faker } from "@faker-js/faker";
import Mock from "mockjs";
import { defineFakeRoute } from "vite-plugin-fake-server/client";

// vite.config.ts
export default defineConfig({
	plugins: [
		vitePluginFakeServer({
			// Optional: specify base directory for fake routes
			include: 'fake',
			// Other options can go here, e.g., enable: true
		}),
	],
});

// fake/user.fake.ts (create this file in the 'fake' directory)
export default defineFakeRoute([
	{
		url: '/mock/get-user-info',
		method: 'GET',
		response: () => {
			return Mock.mock({
				id: '@guid',
				username: '@first',
				email: '@email',
				avatar: '@image("200x200")',
				role: 'admin',
			});
		},
	},
	{
		url: '/fake/get-user-info-faker',
		method: 'GET',
		response: () => {
			return {
				id: faker.string.uuid(),
				avatar: faker.image.avatar(),
				birthday: faker.date.birthdate().toISOString().split('T')[0],
				email: faker.internet.email(),
				firstName: faker.person.firstName(),
				lastName: faker.person.lastName(),
				sex: faker.person.sexType(),
				role: 'user',
			};
		},
	},
]);

// Example client-side usage (e.g., in App.vue or index.ts)
async function fetchUserInfo() {
  try {
    const mockResponse = await fetch('/mock/get-user-info');
    const mockData = await mockResponse.json();
    console.log('Mock.js user info:', mockData);

    const fakerResponse = await fetch('/fake/get-user-info-faker');
    const fakerData = await fakerResponse.json();
    console.log('Faker.js user info:', fakerData);
  } catch (error) {
    console.error('Failed to fetch user info:', error);
  }
}

fetchUserInfo();