@opencookies/vite

Vite plugin — surfaces ungated cookie and vendor calls in dev and CI

Vite plugin for OpenCookies. Runs @opencookies/scanner against your source on dev start and on every HMR update, and surfaces ungated cookie writes / vendor calls as Vite warnings — or build failures.

Install#

bun add -D @opencookies/vite @opencookies/scanner @opencookies/core

Usage#

// vite.config.ts
import { defineConfig } from "vite";
import { openCookies } from "@opencookies/vite";

export default defineConfig({
  plugins: [
    openCookies({
      config: {
        categories: [
          { key: "necessary", label: "Necessary", locked: true },
          { key: "analytics", label: "Analytics" },
          { key: "marketing", label: "Marketing" },
        ],
      },
    }),
  ],
});

Options#

Option	Type	Default	Description
`config`	`OpenCookiesConfig`	required	The runtime consent config used at runtime. The plugin uses `categories[].key` to know which categories are covered when `autoSync` is enabled.
`mode`	`"warn" \| "error" \| "off"`	`"warn"` in dev, `"error"` in build	Controls how findings are reported. `error` causes `vite build` to fail when ungated findings remain. `off` skips scanning entirely.
`include`	`string[]`	scanner default	Forwarded to the scanner.
`exclude`	`string[]`	scanner default	Forwarded to the scanner.
`rules`	`Rule[]`	`defaultRules`	Override the rule set.
`vendors`	`VendorRegistry`	`defaultVendors`	Override the vendor registry.
`autoSync`	`boolean`	`false`	When true, prints a copy-pasteable list of vendor categories that are missing from your `config.categories`.

Modes#

warn (dev default): prints findings via Vite's logger. Does not fail the dev server.
error (build default): same console output, plus throws at buildEnd if any ungated findings remain — so CI fails.
off: scanner does not run.

Output#

Each ungated finding is printed as:

[opencookies] ungated google-analytics (analytics) call via global at src/app.tsx:12:3
  Rule: vendor-imports
  Fix: wrap call sites in <ConsentGate category="…"> or guard with store.has("category")
  Suppress: // opencookies-ignore-next-line

A summary line follows: [opencookies] N cookies, M vendors, K ungated.

HMR#

On every save, the plugin re-runs the scanner against the changed file only (no full project re-scan). Findings added or cleared by the edit are logged inline. The incremental path stays under 50 ms on typical files.

autoSync#

autoSync: true flags vendor categories your scan detected that are not yet declared in config.categories. The plugin prints a suggested snippet — it does not write to disk. Persisted sync (writing to your config file) is handled by @opencookies/cli.

Suppression#

Inherits the scanner's comment syntax:

// opencookies-ignore-next-line
gtag("event", "ad_view");

Or per-file (must appear in the first 10 lines):

// opencookies-ignore-file

Compatibility#

Compatible with Vite 5 and 6. Framework-agnostic — works with React, Vue, Svelte, SolidStart, SvelteKit, Astro, Nuxt 3, and Remix because the plugin only consumes file paths and source text.

License#

Apache-2.0