Vite plugin options

@gutternote-devs/vite-plugin has two independent jobs:

emit branch, commit, and pull request metadata;
stamp source locations onto JSX, TSX, and Svelte elements.

import { defineConfig } from 'vite'
import { gutternote } from '@gutternote-devs/vite-plugin'

export default defineConfig({
  plugins: [gutternote({ enabled: 'auto' })],
})

Options

Option	Type	Default	Effect
`enabled`	`boolean \| 'auto'`	`false`	Controls source-location stamping.
`deployment`	`boolean`	`true`	Emits available branch, commit, and pull request meta tags on non-production deployments. Independent of `enabled`.
`include`	Rollup filter pattern	JSX, TSX, and Svelte globs	Selects files eligible for stamping.
`exclude`	Rollup filter pattern	none	Excludes additional files. `node_modules` stays excluded.
`repoRoot`	`string`	nearest `.git` ancestor of the Vite root	Makes stamped paths relative to this directory.
`commitSha`	`string`	detected from the environment	Overrides the commit used in `gutternote:commit`.

Source-stamping matrix

Whether elements are stamped, by build and enabled value:

Build	`false`	`'auto'`	`true`
Dev server	no	yes	yes
Development-mode build	no	no	yes
Recognized preview	no	yes	yes
Unlabeled production-mode build	no	no	no
Production deployment	no	no	no

A recognized preview has VERCEL_ENV=preview, CONTEXT=deploy-preview, CONTEXT=branch-deploy, or a truthy GUTTERNOTE_STAMP.

Truthy values are 1, true, on, and yes. Falsy values are 0, false, off, and no. GUTTERNOTE_STAMP=0 disables stamping even when the option is true.

VERCEL_ENV=production and CONTEXT=production always turn stamping off. So does an unlabeled vite build, because Vite cannot tell a preview from a public build.

Output

Source stamping adds a one-based, repository-relative location to native DOM elements:

<section data-sn-loc="apps/web/src/Pricing.tsx:42:5">

It also emits gutternote:loc=1 when stamping is on.

Files in node_modules or outside repoRoot are skipped. Elements created at runtime, component library internals and <svelte:element> are not stamped.

The plugin needs Vite 5 or later. Svelte support needs Svelte 4 or later.

Deployment variables

The plugin reads the first valid value in each list. A commit must contain 7 to 40 hexadecimal characters. A pull request must be a positive integer.

Value	Variables, in priority order
Branch	`GUTTERNOTE_BRANCH`, `VERCEL_GIT_COMMIT_REF`, `BRANCH`, `GITHUB_HEAD_REF`, `GITHUB_REF_NAME`, `CI_COMMIT_REF_NAME`, `BUILDKITE_BRANCH`, `CF_PAGES_BRANCH`
Commit	`GUTTERNOTE_COMMIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, `GIT_COMMIT_SHA`, `COMMIT_REF`, `GITHUB_SHA`
Pull request	`GUTTERNOTE_PR`, `VERCEL_GIT_PULL_REQUEST_ID`, `REVIEW_ID`, `CHANGE_ID`, `CI_MERGE_REQUEST_IID`, `BUILDKITE_PULL_REQUEST`

The plugin also parses a pull request number from a GITHUB_REF shaped like refs/pull/128/merge.

For host-specific examples, see Build metadata by hosting provider.