@opencookies/vite

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.

See also

• @opencookies/scanner — underlying detection engine, suppression syntax, custom rules
• @opencookies/core — runtime store and <ConsentGate> / has() shapes the scanner looks for
• Framework adapters — React, Vue, Solid, Svelte

License

Apache-2.0