Claron
    Documentation
    COMPILER PLUGINSReviewed

    Frontend SDK

    Add the frontend SDK to your JSX/TSX build to attach source-location tokens to page elements. Deploy the new build and use an Element annotation to check the source context for that version.

    Requirements and compatibility

    You need permission to change the application's build configuration and access to the corresponding Claron project. This guide describes the current @claron/sdk frontend plugin interfaces. Check the installed package version before copying a configuration.

    The Vite plugin instruments JSX and TSX, including React applications. Using Vite alone does not enable source attribution for Vue templates, Svelte components, or Angular templates. The Next.js wrapper uses webpack; a Turbopack build does not run its webpack instrumentation.

    The backend SDK is a separate, optional setup. Installing a frontend compiler plugin does not enable server evidence.

    Set the project and build credentials

    1. Copy the project's UUID from its project details or project URL

      Use the project that receives your extension reports.

    2. Open Settings → Developer & API and create a named key with sdk:create

      Copy the key once and store it in the build environment's secret store. See API Keys.

    3. Set CLARON_PROJECT_ID to that UUID and CLARON_API_KEY to the key in the build environment

      Do not use NEXT_PUBLIC_, VITE_, or another browser-exposed prefix for the key.

    4. Install the package in the application directory

      Development tagging is off by default; set CLARON_ENABLED=true only when you deliberately want tagging in a development build.

    bash
    npm install --save-dev @claron/sdk

    React with Vite

    Keep your existing plugins and add claronVitePlugin. Run your normal production build and deploy its output.

    EXPLORER
    vite.config.ts×
    +
    typescript
    1import { defineConfig } from 'vite'
    2import react from '@vitejs/plugin-react'
    3import { claronVitePlugin } from '@claron/sdk/vite'
    4
    5export default defineConfig({
    6  plugins: [claronVitePlugin(), react()],
    7})
    vite.config.tsLn 7, Col 1TYPESCRIPTUTF-8

    Next.js with webpack

    Wrap the existing configuration instead of replacing it. On Next.js versions that default to Turbopack, explicitly use webpack for the build. Keep all existing Next.js settings.

    EXPLORER
    next.config.ts×
    +
    typescript
    1import type { NextConfig } from 'next'
    2import { withClaron } from '@claron/sdk/next'
    3
    4const nextConfig: NextConfig = {
    5  // Keep your existing configuration here.
    6}
    7
    8export default withClaron()(nextConfig)
    next.config.tsLn 8, Col 1TYPESCRIPTUTF-8
    bash
    npx next build --webpack

    React with webpack

    Add ClaronWebpackPlugin to the existing plugins array. Keep the application's entry, output, loaders, and JSX/TypeScript compilation. The plugin adds source tagging; it does not replace your normal compiler.

    EXPLORER
    webpack.config.mjs×
    +
    javascript
    1import { ClaronWebpackPlugin } from '@claron/sdk/webpack'
    2
    3export default {
    4  // Keep your existing webpack settings and plugins.
    5  plugins: [new ClaronWebpackPlugin()],
    6}
    webpack.config.mjsLn 6, Col 1JAVASCRIPTUTF-8

    JSX and TSX with Rollup

    Add claronRollupPlugin before the plugin that compiles JSX/TSX. Preserve the existing React, TypeScript, resolution, and output configuration.

    EXPLORER
    rollup.config.mjs×
    +
    javascript
    1import { claronRollupPlugin } from '@claron/sdk/rollup'
    2
    3export default {
    4  // Keep your existing input and output settings.
    5  plugins: [
    6    claronRollupPlugin(),
    7    // Keep your existing JSX/TypeScript and other plugins here.
    8  ],
    9}
    rollup.config.mjsLn 9, Col 1JAVASCRIPTUTF-8

    JSX and TSX with esbuild

    Add claronEsbuildPlugin to the existing build's plugins. It reads application JSX/TSX files before esbuild compiles them; keep your normal entry points and output options.

    EXPLORER
    build.mjs×
    +
    javascript
    1import { build } from 'esbuild'
    2import { claronEsbuildPlugin } from '@claron/sdk/esbuild'
    3
    4await build({
    5  entryPoints: ['src/index.tsx'],
    6  bundle: true,
    7  outdir: 'dist',
    8  plugins: [claronEsbuildPlugin()],
    9  // Keep your application's other build options and plugins.
    10})
    build.mjsLn 10, Col 1JAVASCRIPTUTF-8

    Nuxt, SvelteKit, Astro, and Angular templates

    The generic frontend plugins above instrument JSX/TSX. Adding the Vite plugin alone does not instrument Vue, Svelte, Astro, or Angular templates.

    For supported applications built and hosted by Claron, dedicated framework integrations handle template source attribution alongside the hosted build. Follow Projects and the hosted framework requirements. A separately hosted application needs its framework-specific integration; do not substitute the React/Vite example for a template adapter.

    Verify the deployed result

    1. Open the new deployment in the browser extension, with the correct project selected.

    2. Inspect a JSX/TSX element in the browser's Elements panel

      It should have a data-claron-src attribute. Elements created with innerHTML and uninstrumented third-party code may not have one.

    3. Create a new Element annotation and open its source context in Claron

      Check the file and line against that exact deployed commit. Existing reports do not gain evidence retroactively.

    Upload private source maps (optional)

    Uploading source maps lets Claron resolve the code that started a failing network request to your original file and line. Build with source maps enabled, then run uploadDeployment once per deployment with the same CLARON_PROJECT_ID and CLARON_API_KEY. It records the git branch and commit, gzips every .map file under outDir, and stores them privately in your project.

    Uploads run only for production (from CLARON_ENVIRONMENT or NODE_ENV) unless CLARON_ENABLED=true. Pass uploadSourceMaps: false to register the deployment without maps. Claron keeps uploaded maps private; check separately that your own host does not serve .map files publicly.

    EXPLORER
    scripts/claron-upload.mjs×
    +
    javascript
    1// Run after your build: node scripts/claron-upload.mjs
    2import { uploadDeployment } from '@claron/sdk'
    3
    4await uploadDeployment({ outDir: 'dist' })
    scripts/claron-upload.mjsLn 4, Col 1JAVASCRIPTUTF-8

    Source attribution unavailable

    Check that the plugin ran in the deployed build, the selected element is JSX/TSX, CLARON_ENABLED is not false, the build key is present, and the report belongs to the matching project and deployment. Restart the build after changing configuration.

    If the SDK blocks a build, set CLARON_ENABLED=false and rebuild. Report the compiler error with the framework and package versions before re-enabling it.

    Claron's uploaded source maps are stored privately. Your own hosting may still serve .map files generated by your build. Check the deployed URLs and configure the host to exclude those files if they must stay private. The compiler plugin does not guarantee that your hosting makes them inaccessible.

    SOURCE TOKENS AND PRIVATE UPLOADS

    BUNDLER CONFIGURATION EXAMPLES

    Install @claron/sdk, then load the plugin in your framework configuration with zero arguments. It automatically resolves keys from your local environment variables or configuration files.

    bash
    npm install --save-dev @claron/sdk

    Next.js Setup

    EXPLORER
    next.config.ts×
    +
    typescript
    1import { withClaron } from '@claron/sdk/next'
    2
    3export default withClaron()({
    4  // Your normal nextConfig
    5})
    next.config.tsLn 5, Col 1TYPESCRIPTUTF-8

    Vite Setup

    EXPLORER
    vite.config.ts×
    +
    typescript
    1import { defineConfig } from 'vite'
    2import { claronVitePlugin } from '@claron/sdk/vite'
    3
    4export default defineConfig({
    5  plugins: [claronVitePlugin()]
    6})
    vite.config.tsLn 6, Col 1TYPESCRIPTUTF-8

    EXPECTED SDK OUTPUTS

    Compilation & Build Outputs

    data-claron-src Injection
    Instrumented JSX/TSX elements receive an opaque encrypted source token: <button data-claron-src="cl1....">.
    Deployment Manifest
    A compatible manifest is required for a separate deployment upload. The current Vite/webpack compiler plugins do not create it automatically.
    Source Map Payload
    A separately configured uploadDeployment call uploads an existing compatible manifest and source maps. Compiler tagging alone does not upload them.

    EDGE CASES & COMPILER BEHAVIOR

    Compiler Safeguards & Fallbacks

    Missing API Keys
    A separately configured uploadDeployment call warns and skips its upload when the project ID or API key is missing. Compiler tagging alone does not run that upload. Check the build key separately when element source context is missing.
    Non-Production Builds
    Bundler integrations enable production tagging by default; CLARON_ENABLED=false disables those integrations and configured uploads. Development tagging needs explicit enablement. A direct Babel integration must be gated in its own build configuration.
    Dynamic / Runtime Elements
    Elements created dynamically at runtime via innerHTML do not have build-time data-claron-src tokens; the extension falls back to durable DOM context and selectors.
    Third-Party Libraries
    Libraries in node_modules are excluded; annotations fall back to the closest parent element with a valid data-claron-src or durable target identity.

    WHAT TO DO IF THE SDK FAILS