{"_id":"@autotracer/plugin-vite-react19","name":"@autotracer/plugin-vite-react19","dist-tags":{"latest":"1.0.0-alpha.55"},"versions":{"1.0.0-alpha.55":{"name":"@autotracer/plugin-vite-react19","version":"1.0.0-alpha.55","description":"Vite plugin for auto-injecting useReactTracer in React 19 applications","author":{"name":"Carl Ribbegårdh"},"license":"MIT","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"dependencies":{"rollup-plugin-external-globals":"^0.13.0","unplugin":"3.3.0","@autotracer/inject-react19":"1.0.0-alpha.55","@autotracer/react19":"1.0.0-alpha.55"},"peerDependencies":{"@autotracer/react19":"1.0.0-alpha.55","vite":"8.2.1"},"peerDependenciesMeta":{"@autotracer/react19":{"optional":false},"vite":{"optional":true}},"devDependencies":{"@types/node":"^22.12.0","@typescript/typescript6":"~6.0.2","@vitest/coverage-v8":"4.1.10","jsdom":"^24.1.0","oxlint":"1.77.0","rimraf":"^6.0.1","rollup":"^4.61.1","typescript":"~7.0.2","vite":"8.2.1","vitest":"4.1.10"},"sideEffects":false,"scripts":{"build":"pnpm run check:typescript6 && tsc","prebuild":"pnpm run clean","postbuild":"tsc --project ./tests/tsconfig.json --noEmit && pnpm run check:typescript6:consumer","check:typescript6":"tsc6 --project tsconfig.typescript6.json","check:typescript6:consumer":"tsc6 --project tests/typescript6-consumer/tsconfig.json","clean":"rimraf dist coverage","lint":"oxlint src tests","lint:fix":"oxlint src tests --fix","test":"vitest run","test:coverage":"vitest run --coverage"},"_id":"@autotracer/plugin-vite-react19@1.0.0-alpha.55","_integrity":"sha512-LGeC6Gg8/4g4NnXWKiY81wiLdlpbWr3aZQcVZ3iVqabsm2rMWxqLKXcg9Mtjz6L2Z9N/JWgrHKnz/F5EhKlQlw==","_resolved":"C:\\Users\\CARL~1.DES\\AppData\\Local\\Temp\\e09d24bf3bb1f7f230070cab71472cf3\\autotracer-plugin-vite-react19-1.0.0-alpha.55.tgz","_from":"file:autotracer-plugin-vite-react19-1.0.0-alpha.55.tgz","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-LGeC6Gg8/4g4NnXWKiY81wiLdlpbWr3aZQcVZ3iVqabsm2rMWxqLKXcg9Mtjz6L2Z9N/JWgrHKnz/F5EhKlQlw==","shasum":"1a55a7fe4120ff613ed4e09b370c5fbac612ef47","tarball":"https://registry.npmjs.org/@autotracer/plugin-vite-react19/-/plugin-vite-react19-1.0.0-alpha.55.tgz","fileCount":6,"unpackedSize":27393,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHrWB7Jshk/vBZDp+dzwKPK88D+nIU9CSQzPOGp9D8ygAiEA8I+nWbU3KW6LzSKP4kVIrKZHdi9YmkgwkJOtPHC25u4="}]},"_npmUser":{"name":"carlribbegaardh","email":"carl.ribbegaardh+npm@gmail.com"},"directories":{},"maintainers":[{"name":"carlribbegaardh","email":"carl.ribbegaardh+npm@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-vite-react19_1.0.0-alpha.55_1787724307672_0.7797126696744179"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-26T06:05:07.523Z","1.0.0-alpha.55":"2026-08-26T06:05:07.804Z","modified":"2026-08-26T06:05:08.128Z"},"maintainers":[{"name":"carlribbegaardh","email":"carl.ribbegaardh+npm@gmail.com"}],"description":"Vite plugin for auto-injecting useReactTracer in React 19 applications","author":{"name":"Carl Ribbegårdh"},"license":"MIT","readme":"# @autotracer/plugin-vite-react19\r\n\r\nAutomatic React 19 component instrumentation for Vite 8 applications. Use this package in local development or restricted internal test/QA builds to inject `useReactTracer()` calls and preserve source-level component and hook labels.\r\n\r\n## Why Use It\r\n\r\nThe plugin connects Vite's transform lifecycle to `@autotracer/inject-react19`. It can:\r\n\r\n- Instrument eligible JSX and TSX function components.\r\n- Preserve source variable names for supported state and hook values.\r\n- Apply include, exclude, pragma, hook-label, and React Server Component settings from the injector.\r\n- Load project theme files before the application starts.\r\n- Seed the output mode and optionally mount `@autotracer/dashboard`.\r\n- Add a stable prefix for islands or microfrontends sharing one browser console.\r\n\r\nAutoTracer exposes component state, props, and application structure. Exclude this plugin at build time from public-facing applications.\r\n\r\n## Requirements\r\n\r\n- React and ReactDOM `19.2.0` or a compatible `^19.2.0` release\r\n- Vite `8.2.1`\r\n- Node.js 24 for repository development and package tooling\r\n- TypeScript 6 or newer for consumers; package artifacts are built with TypeScript 7\r\n\r\n## Installation\r\n\r\n```bash\r\npnpm add @autotracer/react19\r\npnpm add -D @autotracer/plugin-vite-react19\r\n```\r\n\r\nInitialize the runtime before React renders, then register the Vite plugin.\r\n\r\n```ts\r\n// src/main.tsx\r\nimport { reactTracer } from \"@autotracer/react19\";\r\n\r\nreactTracer();\r\n```\r\n\r\n```ts\r\n// vite.config.ts\r\nimport react from \"@vitejs/plugin-react\";\r\nimport { reactTracer } from \"@autotracer/plugin-vite-react19\";\r\nimport { defineConfig } from \"vite\";\r\n\r\nexport default defineConfig(({ mode }) => ({\r\n  plugins: [\r\n    reactTracer.vite({\r\n      inject: mode === \"development\",\r\n    }),\r\n    react(),\r\n  ],\r\n}));\r\n```\r\n\r\n## Configuration\r\n\r\n| Option | Type | Default | Purpose |\r\n| --- | --- | --- | --- |\r\n| `inject` | `boolean` | `true` | Enables all transforms and plugin side effects. `TRACE_INJECT=0` also disables them. |\r\n| `mode` | `\"opt-in\" \\| \"opt-out\"` | Injector default | Selects pragma eligibility behavior. |\r\n| `include` | Injector path/component filter | Injector default | Restricts eligible files and components. |\r\n| `exclude` | Injector path/component filter | Injector default | Excludes files and components. |\r\n| `importSource` | `string` | `@autotracer/react19` | Changes the injected runtime import. |\r\n| `labelHooks` | `string[]` | `[]` | Adds hook names whose returned values should be labeled. |\r\n| `labelHooksPattern` | `string` | Injector default | Adds hook names by regular-expression source. |\r\n| `serverComponents` | `boolean` | `false` | Restricts injection to modules with a top-level `\"use client\"` directive. |\r\n| `prefix` | `string` | none | Prefixes injected component names. |\r\n| `outputMode` | `\"devtools\" \\| \"copy-paste\"` | Runtime default | Seeds output behavior before runtime initialization. |\r\n| `dashboardConfig` | object | none | Configures and mounts `@autotracer/dashboard`. |\r\n| `buildWithWorkspaceLibs` | `boolean` | `false` | Enables restricted internal global-script workspace build support. |\r\n| `reactUmdSrc` | `string` | none | Script exposing `window.React`; required with `buildWithWorkspaceLibs`. |\r\n| `reactDomUmdSrc` | `string` | none | Script exposing `window.ReactDOM`; required with `buildWithWorkspaceLibs`. |\r\n\r\nThe [React 19 Vite API](https://docs.autotracer.dev/api/plugin-vite-react19) lists the public entry point and types. The [Vite settings reference](https://docs.autotracer.dev/reference/build/react19/vite/) documents each option separately.\r\n\r\n### Hook Labels\r\n\r\n```ts\r\nreactTracer.vite({\r\n  labelHooks: [\"useState\", \"useReducer\", \"useAppSelector\"],\r\n  labelHooksPattern: \"^use[A-Z].*\",\r\n});\r\n```\r\n\r\n### Islands And Microfrontends\r\n\r\n```ts\r\nreactTracer.vite({\r\n  inject: mode === \"development\",\r\n  prefix: \"AccountIsland\",\r\n});\r\n```\r\n\r\nThe prefix produces names such as `AccountIsland:ProfilePanel` in trace output.\r\n\r\n## React Compiler\r\n\r\nAutoTracer is verified with `babel-plugin-react-compiler@1.0.0` on React `19.2.0`, Vite `8.2.1`, and `@vitejs/plugin-react` 4.x. Register the AutoTracer plugin before the React plugin so AutoTracer adds labels while the component still has its source-level hook declarations. React Compiler then analyzes the instrumented component.\r\n\r\n```ts\r\nexport default defineConfig({\r\n  plugins: [\r\n    reactTracer.vite({\r\n      labelHooks: [\"useState\"],\r\n    }),\r\n    react({\r\n      babel: {\r\n        plugins: [[\"babel-plugin-react-compiler\", { target: \"19\" }]],\r\n      },\r\n    }),\r\n  ],\r\n});\r\n```\r\n\r\nThat result covers the versions and plugin order above. Other React Compiler versions and other build integrations require their own verification.\r\n\r\n## Workspace Builds\r\n\r\nFor workspace libraries consumed as source, alias `@autotracer/react19` to the host application's installed copy. This keeps React in the normal Vite bundle and is the preferred setup.\r\n\r\n`buildWithWorkspaceLibs` preserves the React 18 plugin's restricted internal global-loading path, with one required React 19 adaptation: React 19 no longer publishes official React or ReactDOM UMD files. You must provide scripts that are compatible with React 19.2.0 and expose `window.React` and `window.ReactDOM`.\r\n\r\n```ts\r\nreactTracer.vite({\r\n  inject: process.env.DEPLOY_ENV === \"qa\",\r\n  buildWithWorkspaceLibs: process.env.DEPLOY_ENV === \"qa\",\r\n  reactUmdSrc: \"/vendor/react-19.global.js\",\r\n  reactDomUmdSrc: \"/vendor/react-dom-19.global.js\",\r\n});\r\n```\r\n\r\nThe plugin still emits the package-provided `@autotracer/react19/dist/index.umd.js` artifact as `auto-tracer-react19.umd.js`. It externalizes React, ReactDOM, and AutoTracer from the entire application bundle. If any global script fails to load, the application fails to start.\r\n\r\nDo not use this mode in public-facing deployments. Do not point these settings at React 18 UMD files.\r\n\r\n## Theme Files\r\n\r\nThe plugin loads matching files from the Vite project root:\r\n\r\n1. `*react-theme.json`\r\n2. `*react-theme-light.json`\r\n3. `*react-theme-dark.json`\r\n\r\nLater files override earlier theme-file values. Loaded values are assigned to `globalThis.__REACTTRACER_THEME__` before application scripts execute.\r\n\r\n## React Server Components\r\n\r\nThis package instruments client components; it does not trace React Server Component execution. Set `serverComponents: true` when processing an RSC-oriented source tree so only modules with a top-level `\"use client\"` directive are eligible.\r\n\r\n## Building And Testing\r\n\r\nRun repository-defined scripts from the monorepo root:\r\n\r\n```bash\r\npnpm build\r\npnpm test\r\npnpm verify\r\n```\r\n\r\nThe package build emits declarations with TypeScript 7, checks source compatibility with TypeScript 6, and compiles a TypeScript 6 fixture against the emitted declarations. `pnpm verify` also runs oxlint and the Vitest suite. Coverage uses Vitest 4.1.10 with 80% global branch, function, line, and statement thresholds.\r\n\r\n## License\r\n\r\nMIT © Carl Ribbegårdh\r\n","readmeFilename":"README.md","_rev":"1-906bcff66a3827c00b733d815445ed96"}