【Next.js + Orval + MSW】型安全 API クライアント & モック環境構築

使用環境

- node: 23.9.0
- npm: 11.1.0
- next: 15.3.1,
- react: 19.0.0,
- @tanstack/react-query: 5.74.4,
- msw: 2.7.5,
- orval: 7.8.0,

  my-next-app/
  ├─ app/
  ├─ schemas/
+ │     └─ openapi.yaml
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

$ npm install orval --save-dev

  my-next-app/
  ├─ app/
  ├─ schemas/
  │     └─ openapi.yaml
+ ├─ orval.config.ts
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

orval.config.ts

import { defineConfig } from "orval";

export default defineConfig({
  
  color_api: {
    input: "./schemas/openapi.yaml", 
    output: "./apiClient/colors", 
  },
});

orval.config.ts

import { defineConfig } from "orval";

export default defineConfig({
  
  color_api: {
    input: {
      target: "./schemas/openapi.yaml", 
    },
    output: {
      target: "./apiClient/colors", 
      schemas: "./apiClient/schemas", 
      client: "react-query", 
      httpClient: "fetch", 
      mode: "split", 
      clean: true, 
      
      mock: {
        type: "msw",
        useExamples: true, 
      },
      override: {
        mutator: {
          path: "./apiClient/customFetch.ts", 
          name: "customFetch",
        },
        fetch: {
          includeHttpResponseReturnType: false, 
        },
        mock: {
          required: true, 
        },
      },
    },
    hooks: {
      
      
      afterAllFilesWrite: "npx @biomejs/biome format --write", 
    },
  },
});

  my-next-app/
+ ├─ apiClient/
+ │     └─ customFetch.ts
  ├─ app/
  ├─ schemas/
  │     └─ openapi.yaml
  ├─ orval.config.ts
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

apiClient/customFetch.ts

export const customFetch = async TData>(
  url: string,
  options: RequestInit = {}
): PromiseTData> => {
  const baseUrl = "http://localhost:7777"; 
  const requestUrl = new URL(url, baseUrl);

  const headers = {
    "Content-Type": "application/json", 
    ...options.headers,
    
    
  };

  try {
    const response = await fetch(requestUrl, {
      ...options,
      headers,
    });

    
    if (!response.ok) {
      throw new Error(
        `API request failed with status ${response.status}: ${response.statusText}`
      );
    }

    
    const data: TData = await response.json();
    return data;
  } catch (error) {
    console.error("customFetch Error:", error);
    throw error;
  }
};

package.json

{
  "scripts": {
    ...
    "generate:api": "orval --config ./orval.config.ts"
  }
}

  my-next-app/
  ├─ apiClient/
+ │     ├─ colors/
+ │     │     ├─ colorsAPI.msw.ts
+ │     │     └─ colorsAPI.ts
+ │     ├─ schemas
+ │     │     ├─ colorListResponse.ts
+ │     │     ├─ errorResponse.ts
+ │     │     └─ index.ts
  │     └─ customFetch.ts
  ├─ app/
  ├─ schemas/
  │     └─ openapi.yaml
  ├─ orval.config.ts
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

$ npm install msw --save-dev

$ npx msw init public/ --save

  my-next-app/
  ├─ apiClient/
  ├─ app/
  ├─ public/
+ │   └─ mockServiceWorker.js #   ├─ schemas/
  │     └─ openapi.yaml
  ├─ orval.config.ts
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

  my-next-app/
  ├─ apiClient/
  ├─ app/
  ├─ public/
  │   └─ mockServiceWorker.js
+ ├─ mocks/
+ │     ├─ browser.ts
+ │     ├─ server.ts
+ │     ├─ handlers.ts
  ├─ schemas/
  │     └─ openapi.yaml
  ├─ orval.config.ts
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

browser.ts

import { setupWorker } from 'msw/browser';
import { handlers } from './handlers';

export const worker = setupWorker(...handlers);

server.ts

import { setupServer } from 'msw/node';
import { handlers } from './handlers';

export const server = setupServer(...handlers);

handlers.ts

import { getColorsAPIMock } from "@/apiClient/colors/colorsAPI.msw";
import type { RequestHandler } from "msw";


const orvalHandlers = [...getColorsAPIMock()];


const originalHandlers: RequestHandler[] = [];


export const handlers: RequestHandler[] = [...originalHandlers, ...orvalHandlers];

apiClient/colors/colorsAPI.msw.ts

...省略
export const getColorsAPIMock = () => [getGetApiColorsMockHandler()];

handler.ts

import { getGetApiColorsMockHandler } from "@/apiClient/colors/colorsAPI.msw";
...
const originalHandlers = [
  getGetApiColorsMockHandler(["rainbow", "superRainbow", "hyperRainbow"]),
];
...

  my-next-app/
  ├─ apiClient/
  ├─ app/
  ├─ public/
  ├─ mocks/
  ├─ schemas/
+ ├─ components/
+ │     ├─ MswClientProvider.tsx
+ │     └─ MswProvider.tsx
  ├─ orval.config.ts
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

components/MswClientProvider.tsx

"use client";
import { use } from "react";


const mockingEnabledPromise =
  typeof window !== "undefined"
    ? import("@/mocks/browser").then(async ({ worker }) => {
        await worker.start({ onUnhandledRequest: "bypass" });
      })
    : Promise.resolve();


export const MswClientProvider = ({
  children,
}: {
  children: React.ReactNode;
}) => {
  
  use(mockingEnabledPromise);
  return children;
};

components/MswProvider.tsx

import { Suspense, type ReactNode } from "react";
import { MswClientProvider } from "./MswClientProvider";

if (process.env.NEXT_RUNTIME === "nodejs") {
  const { server } = await import("@/mocks/server");
  server.listen({ onUnhandledRequest: "bypass" });
}


export const MswProvider = ({ children }: { children: ReactNode }) => {
  return (
    Suspense fallback={null}>
      MswClientProvider>{children}MswClientProvider>
    Suspense>
  );
};

app/layout.tsx

import "./globals.css";
import { MswProvider } from "@/components/MswProvider";

export default function RootLayout({
  children,
}: Readonly  children: React.ReactNode;
}>) {
  return (
    html lang="ja">
      body>
+       MswProvider>{children}MswProvider>
      body>
    html>
  );
}

$ npm install @tanstack/react-query

  my-next-app/
  ├─ apiClient/
  ├─ app/
+ │     └─ page.tsx
  ├─ public/
  ├─ mocks/
  ├─ schemas/
  ├─ components/
  │     ├─ MswClientProvider.tsx
  │     ├─ MswProvider.tsx
+ │     ├─ SampleSever.tsx
+ │     └─ SampleClient.tsx
  ├─ instrumentation.ts
  ├─ orval.config.ts
  ├─ next.config.js
  ├─ package.json
  └─ tsconfig.json

app/page.tsx

import SampleClient from "@/components/SampleClient";
import SampleServer from "@/components/SampleServer";

const Page = () => {
  return (
    >
      SampleServer />
      SampleClient />
    >
  );
};

export default Page;

components/SampleSever.tsx

import { getApiColors } from "@/apiClient/colors/colorsAPI";
import { Suspense } from "react";

const Body: React.FC = async () => {
  const response = await getApiColors();

  return (
    >
      h2>Server Componenth2>
      {response.map((color, i) => (
        p key={i}>{color}p>
      ))}
    >
  );
};

const SampleServer: React.FC = async () => {
  return (
    Suspense fallback={div>SampleServer Loading...div>}>
      Body />
    Suspense>
  );
};

export default SampleServer;

components/SampleClient.tsx

"use client";
import { useGetApiColors } from "@/apiClient/colors/colorsAPI";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const Body: React.FC = () => {
  const { data, isPending, error, isError } = useGetApiColors();

  if (isError) {
    return p>{error.message}p>;
  }

  if (isPending) {
    return p>SampleClient Loading...p>;
  }

  return (
    >
      h2>Client Componenth2>
      {data.map((color, i) => (
        p key={i}>{color}p>
      ))}
    >
  );
};

const SampleClient: React.FC = () => {
  
  const queryClient = new QueryClient();

  return (
    QueryClientProvider client={queryClient}>
      Body />
    QueryClientProvider>
  );
};

export default SampleClient;