@arsams/mockkit-react

React integrations for @arsams/mockkit - hooks and control panel components for MSW mocking in React applications.

Installation

pnpm install @arsams/mockkit-react @arsams/mockkit msw react react-dom

Note: @arsams/mockkit is a required peer dependency. You must install it separately.

Features

• React Hooks - useStore hook for consuming mock config state with efficient re-renders
• Control Panel Component - Visual UI for controlling mocks during development
• Stream Event Injection - Hook for injecting stream events into your Redux store
• TypeScript Support - Full type safety with types from @arsams/mockkit

Quick Start

1. Set up the core package

First, follow the @arsams/mockkit setup guide to create handlers, scenarios, and stream sequences.

2. Initialize MSW Worker (Browser)

// src/main.tsx or src/index.tsx
import { startMockWorker } from "@arsams/mockkit/browser";
import { handlers } from "./mocks/handlers";
import "./mocks/scenarios"; // Register scenarios
import "./mocks/streamSequences"; // Register stream sequences

const bootstrapApp = async () => {
  if (import.meta.env.DEV) {
    await startMockWorker({
      handlers,
      initialScenario: "success",
    });
  }
  
  // Render your app
  ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
};

bootstrapApp();

3. Add the Control Panel (Development Only)

// src/App.tsx
import { MSWControlPanel } from "@arsams/mockkit-react";

function App() {
  return (
    <>
      {/* Your app content */}
      <YourApp />
      
      {/* MSW Control Panel - only shows in development */}
      {import.meta.env.DEV && <MSWControlPanel />}
    </>
  );
}

4. Use the Store Hook

import { useStore } from "@arsams/mockkit-react";

function MyComponent() {
  const enabled = useStore((state) => state.enabled);
  const routes = useStore((state) => state.routes);
  
  return (
    <div>
      <p>Mocking is {enabled ? "enabled" : "disabled"}</p>
      <p>Registered routes: {Object.keys(routes).length}</p>
    </div>
  );
}

5. Stream Event Injection (Optional)

If you're using Redux for stream events:

import { useStreamEventInjection } from "@arsams/mockkit-react";
import { useSetStreamEvents, useGetStreamEvents } from "./store/hooks";

function App() {
  const setStreamEvents = useSetStreamEvents();
  const getStreamEvents = useGetStreamEvents();
  
  useStreamEventInjection({
    setStreamEvents,
    getStreamEvents,
  });
  
  return <YourApp />;
}

API Reference

useStore<T>(selector: (state: MockConfigState) => T): T

React hook for consuming the mock config store. Uses @nanostores/react for efficient subscriptions.

Example:

const enabled = useStore((state) => state.enabled);
const routes = useStore((state) => state.routes);

useStreamEventInjection(options?)

React hook that injects stream events into Redux when a stream sequence is active.

Options:

• setStreamEvents?: (events: StreamEventMap) => void - Function to set stream events in your Redux store
• getStreamEvents?: () => StreamEventMap | undefined - Function to get current stream events from your Redux store

Example:

useStreamEventInjection({
  setStreamEvents: (events) => dispatch(setStreamEvents(events)),
  getStreamEvents: () => selectStreamEvents(getState()),
});

<MSWControlPanel />

React component that provides a visual UI for controlling MSW mocks during development. Includes:

• Global mocking toggle
• Scenario selection
• Stream sequence selection
• Per-route controls (enable/disable, mode selection)
• Request logging toggle

The panel is designed to be visually distinct but non-intrusive, with a floating design that can be toggled open/closed.

TypeScript Support

Full TypeScript support is included. All types are exported from @arsams/mockkit and can be imported directly:

import type { MockConfigState, ResponseMode, RouteConfig } from "@arsams/mockkit";

Dependencies

This package requires:

• @arsams/mockkit - Core package (peer dependency)
• react - React 16.8+ (peer dependency)
• react-dom - React DOM 16.8+ (peer dependency)
• @nanostores/react - For React hooks integration (dependency)

Relationship to Core Package

This package is a thin wrapper around @arsams/mockkit that provides React-specific integrations:

• React hooks for consuming the framework-agnostic store
• React components for the control panel UI
• React-specific utilities for stream event injection

All core functionality (stores, handlers, scenarios, etc.) comes from @arsams/mockkit. This package only adds React bindings.

License

MIT

Related Packages

• @arsams/mockkit - Core framework-agnostic package (required dependency)

Contributing

See the core package CONTRIBUTING.md for guidelines. When contributing React-specific features, make sure core functionality remains in @arsams/mockkit.