Bug report widget for React

This quickstart adds the Mushi Mushi bug-report widget to a React app (Vite or Next.js). Users report from the widget; each report arrives with a screenshot and the console and network tail, followed by a plain-English diagnosis.

Try it live

Get your project ID and API key

The SDK needs two values from a Mushi Mushi project.

• Fastest: run npx mushi-mushi in your app’s folder. It signs you in through the browser, creates or picks a project, installs the SDK and writes both values to .env.local.
• By hand: create a free account  (no card) and create a project. The panel that opens shows the project ID and an API key that starts with mushi_. Copy the key now: it is shown once. You can mint another under Set up → Test it → Generate API key.
• Self-hosting? Your own console gives you the same two values. See Self-hosting.

Put them in .env.local as VITE_MUSHI_PROJECT_ID and VITE_MUSHI_API_KEY (NEXT_PUBLIC_MUSHI_PROJECT_ID and NEXT_PUBLIC_MUSHI_API_KEY on Next.js).

1. Install

pnpm add @mushi-mushi/react
# or: npm install @mushi-mushi/react

@mushi-mushi/react re-exports from @mushi-mushi/core and @mushi-mushi/web, so you only need this one dependency.

2. Wrap your app

import { MushiProvider } from '@mushi-mushi/react'
import { App } from './App'
 
export function Root() {
  return (
    <MushiProvider
      config={{
        projectId: import.meta.env.VITE_MUSHI_PROJECT_ID,
        apiKey: import.meta.env.VITE_MUSHI_API_KEY,
      }}
    >
      <App />
    </MushiProvider>
  )
}

Next.js App Router

<MushiProvider> uses React context, so it goes in a client component, not straight into app/layout.tsx:

'use client'
import { MushiProvider } from '@mushi-mushi/react'
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <MushiProvider
      config={{
        projectId: process.env.NEXT_PUBLIC_MUSHI_PROJECT_ID!,
        apiKey: process.env.NEXT_PUBLIC_MUSHI_API_KEY!,
      }}
    >
      {children}
    </MushiProvider>
  )
}

import { Providers } from './providers'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

npx mushi-mushi writes this providers.tsx for you when it detects Next.js. Keep callbacks such as beforeSend inside providers.tsx, because a Server Component cannot pass functions to a client one.

3. Trigger reports

Add a hook anywhere in your tree to capture programmatic reports:

import { useMushiSdk } from '@mushi-mushi/react'
 
export function CrashFallback({ error }: { error: Error }) {
  const mushi = useMushiSdk()
  return (
    <div role="alert">
      <p>Something broke.</p>
      <button onClick={() => void mushi?.captureException(error, { severity: 'high' })}>
        Send a bug report
      </button>
    </div>
  )
}

useMushiSdk() returns null until the provider has initialised, hence the ?.. To open the report widget from a button instead, use const { report } = useMushi() and call report().

Or rely on the built-in widget, with no extra code. The launcher mounts as soon as <MushiProvider> initialises.

4. Verify

Open your admin console at kensaur.us/mushi-mushi/admin  (or your self-hosted instance). Your first report appears on the Bugs page within seconds, and its AI diagnosis follows shortly after.

A one-sentence test report gets a thin diagnosis. For a real one, bring in a bug you already know about: see Already have Sentry issues? A diagnosis that names your files needs your GitHub repository connected on the console’s Connect page.

Next steps

• Concepts → Classification pipeline
• SDK reference → @mushi-mushi/react
• Plugins → Receive a webhook in your own service