React Integration Guide

Install IssueCapture in React

Add bug reporting to your React application in 5 minutes. Works with Create React App, Vite, and any React setup.

Quick Summary

Time: 5 minutes (7 simple steps)

Prerequisites: React 16.8+, Jira account

Method: Script tag or useEffect

Works with: CRA, Vite, React Router

Prerequisites

React 16.8 or higher (hooks support)
Create React App, Vite, or any React bundler
Jira Cloud account (Software or JSM)
IssueCapture account (sign up free)

Step-by-Step Installation

Follow these steps to get up and running in minutes.

Get Your API Key

Go to issuecapture.com/signup and create a free account
Connect your Jira instance via OAuth
Navigate to the Widgets page and create a new widget
Copy your API key (starts with "ic_")

Add Environment Variable

Store your API key in your environment configuration

Create React App: Use REACT_APP_ prefix
Vite: Use VITE_ prefix
Never commit .env files to version control
Restart dev server after adding environment variables

# .env (Create React App)
REACT_APP_ISSUECAPTURE_API_KEY=ic_your_api_key_here

# .env.local (Vite)
VITE_ISSUECAPTURE_API_KEY=ic_your_api_key_here

Install via Script Tag (Recommended)

Add IssueCapture to your public/index.html file

Place script tag at the end of <body> for optimal loading
Create React App automatically replaces %REACT_APP_*% tokens
Vite requires manual replacement (see Step 4 for programmatic approach)
type="module" is required for ESM imports

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Your React App</title>
  </head>
  <body>
    <div id="root"></div>

    <!-- IssueCapture Widget -->
    <script type="module">
      import IssueCapture from 'https://issuecapture.com/widget.js';

      IssueCapture.init({
        apiKey: '%REACT_APP_ISSUECAPTURE_API_KEY%', // CRA
        // apiKey: '%VITE_ISSUECAPTURE_API_KEY%',   // Vite
        trigger: 'auto',
        button: {
          position: 'bottom-right',
          text: 'Report Bug'
        }
      });
    </script>
  </body>
</html>

Alternative: Programmatic Initialization

Initialize IssueCapture from your React component using useEffect

Loads widget only when component mounts
Works with both Create React App and Vite
Cleanup function destroys widget on unmount
Useful for single-page applications with routing

// src/App.jsx or src/App.tsx
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Dynamically load IssueCapture widget
    const script = document.createElement('script');
    script.type = 'module';
    script.innerHTML = `
      import IssueCapture from 'https://issuecapture.com/widget.js';

      IssueCapture.init({
        apiKey: '${process.env.REACT_APP_ISSUECAPTURE_API_KEY || process.env.VITE_ISSUECAPTURE_API_KEY}',
        trigger: 'auto',
        button: {
          position: 'bottom-right',
          text: 'Report Bug'
        }
      });
    `;
    document.body.appendChild(script);

    return () => {
      // Cleanup on unmount
      if (window.IssueCapture) {
        window.IssueCapture.destroy();
      }
    };
  }, []);

  return (
    <div className="App">
      <h1>Your React Application</h1>
      {/* Your components */}
    </div>
  );
}

export default App;

Custom Trigger Component

Create a React component to trigger the widget

Use window.IssueCapture.open() to open programmatically
Check if IssueCapture exists before calling
Add aria-label for accessibility
Integrate into navbar, footer, or error boundaries

// src/components/BugReportButton.jsx
import React from 'react';

export default function BugReportButton() {
  const openWidget = () => {
    if (window.IssueCapture) {
      window.IssueCapture.open();
    }
  };

  return (
    <button
      onClick={openWidget}
      className="bug-report-btn"
      aria-label="Report a bug"
    >
      Report Bug
    </button>
  );
}

// Usage in your app:
// import BugReportButton from './components/BugReportButton';
// <BugReportButton />

Set User Context (Optional)

Pre-fill user information for authenticated users

Pre-fill reporter name and email for authenticated users
Update user context when auth state changes
Component field maps to Jira components for routing
Improves bug report context for developers

// src/App.jsx
import { useEffect } from 'react';
import { useAuth } from './hooks/useAuth'; // Your auth hook

function App() {
  const { user } = useAuth();

  useEffect(() => {
    if (window.IssueCapture && user) {
      // Update user context when user logs in
      window.IssueCapture.init({
        apiKey: process.env.REACT_APP_ISSUECAPTURE_API_KEY,
        trigger: 'auto',
        user: {
          name: user.name,
          email: user.email,
          component: 'Frontend' // Optional: Jira component
        }
      });
    }
  }, [user]);

  return <div className="App">{/* Your app */}</div>;
}

Test the Integration

Verify IssueCapture is working correctly

Start your dev server: npm start or npm run dev
Open your app in the browser
You should see the floating bug report button
Click it and submit a test issue
Check your Jira project for the created issue
Open browser console and type: window.IssueCapture.isOpen()

Troubleshooting

Common integration issues and how to solve them.

TypeScript: Property 'IssueCapture' does not exist on type 'Window'

Add type declarations to your project (src/types/issuecapture.d.ts)

Create a type declaration file in src/types/issuecapture.d.ts
Declare the global Window interface with IssueCapture property
Export an empty object to make it a module

Environment variables not working

Create React App: Must use REACT_APP_ prefix
Vite: Must use VITE_ prefix
Restart dev server after adding/changing .env
Never use NEXT_PUBLIC_ prefix in React (Next.js only)

Widget loads multiple times (React Router)

Initialize widget once in root component
Use empty dependency array in useEffect: []
Check if window.IssueCapture exists before loading

Different widget configs per page not loading

Call IssueCapture.init() with new API key - auto-reloads config
Use IssueCapture.reloadConfig() to force reload
Use destroy() and init() for full teardown if needed

Domain allowlist errors when submitting issues (often shown as CORS)

Add localhost:3000 to allowed domains in dashboard
Add production domain to allowed domains
Check IssueCapture dashboard → Widgets → Domains

Ready to get started?

Get Started Free View All Docs