@sentryqa/vite

Vite plugin for activating SentryQA during development: injects the client, instruments React, and exposes the local bridge that reads and writes Markdown issues.

Recommended Installation

In a React + Vite project, the preferred path is the CLI:

npx sentryqa init
npm run dev

For Docker/non-loopback development, use the explicit secure opt-in (the origin must be exact):

npx sentryqa init --docker --origin http://localhost:4173

Plain npx sentryqa init never enables non-loopback access automatically.

To configure it manually:

npm install -D @sentryqa/vite

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { sentryQa } from '@sentryqa/vite';

export default defineConfig({
  plugins: [react(), sentryQa()],
});

The plugin requires Vite >=5.0.0 <9.0.0. It applies only to serve, not build or preview, and does not add SentryQA to production builds.

Canonical viewport capture

sentryQa() mounts the development runtime independently from canonical capture. The local canonical-capture adapter loads only when a canonical v2 issue is saved, so a capture integration failure leaves the bubble available and reports capture as unavailable at save time. On healthy paths, saving a canonical v2 issue captures the current viewport as a PNG at the browser device-pixel ratio; it never silently downscales. Capture fails instead when either dimension exceeds 32,768 pixels or the image exceeds 32 million pixels, and the issue remains open for correction.

The cloned capture omits SentryQA runtime and [data-sentryqa-ignore] nodes. Form controls and [data-sentryqa-redact] content are replaced by opaque masks without changing their layout. The adapter disables CORS loading and tainted canvases, so unavailable cross-origin content causes capture failure rather than an unsafe or partial PNG.

Docker and Non-Loopback Hosts

By default, the bridge accepts only loopback clients and local origins detected by Vite. Serving Vite with --host 0.0.0.0 does not change this behavior.

If the server runs inside Docker, explicitly enable both options and restrict allowedOrigins to the exact origin the browser will use:

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 4174,
  },
  plugins: [
    react(),
    sentryQa({
      allowNonLoopback: true,
      allowedOrigins: ['http://localhost:4174'],
    }),
  ],
});

Example command:

docker compose up --build

allowNonLoopback authorizes connections from the container network. allowedOrigins preserves an exact origin check. You must use both options; if either is missing, the bridge remains disabled or rejects the request. Never use allowedOrigins: ['*'], and never enable this configuration in an environment exposed to the Internet.

Relationship to the Other Packages

• Integrates @sentryqa/runtime, @sentryqa/react, and @sentryqa/core as dependencies.
• sentryqa init installs this package, edits vite.config.*, and prepares .sentryqa/issues/.
• If you do not use Vite, this package is not the right integration; you would need to mount the runtime and provide your own bridge.

Public Options

sentryQa() accepts watcher to enable or disable issue change watching, as well as allowNonLoopback and allowedOrigins for controlled Docker opt-in.