Options and environments

Pass options as the second argument to withSkyelight(nextConfig, options) in Next.js, or as the only argument to skyelight(options) in Vite, Remix, Astro and WXT. Every option is optional. With the options setup writes, preview and local builds get stamps and the badge, and production builds get nothing.

Options

Option	Default	What it does
`production`	unset	`false`: production builds get nothing from the plugin. `true`: production builds follow `stamp` and `widget`. Unset: see Configs without `production`.
`stamp`	`true` when `production` is set	Adds stamps. `false` writes no stamps: no attributes on elements, and no commit or branch on `<html>`.
`widget`	`true` when `production` is set	Adds the review badge’s script tag.
`enabled`	unset	`false` turns the whole plugin off: no stamps and no badge. In a config without `production`, `true` turns stamps on.
`autoStart`	`true`, except in production	Next.js only. Shows the badge’s mark on arrival, without a `?skyelight=1` link. Production builds never auto-start.
`project`	unset	A Skyelight project ID, written on the script tag as `data-project`. Needed only when the same address is listed on two projects.
`widgetSrc`	`https://app.skyelight.ai/a.js`	The URL of the badge script. Leave it unset unless you test against another Skyelight address.
`buildId`	from the environment	Overrides the stamped commit.
`branch`	from the environment	Overrides the stamped branch.
`root`	the git repository root	Vite only. The directory that stamped paths are relative to.

Setup writes stamp, widget and production into your config, so the config shows what each build gets.

Keeping it out of production

With production: false, a production build gets nothing from the plugin. The Next.js adapter returns your config unchanged, and the Vite plugin doesn’t apply. No plugin code runs, no attribute or script reaches your HTML, and no environment variable can turn either back on.

With production: true, production builds follow stamp and widget. Use it to collect feedback on a live site. In production, the badge never shows its mark on arrival. It waits for a link with ?skyelight=1, or for a reviewer who has signed in on that site before.

To check a production build, run npx @skyelight/build verify after the build (0.14.0 or later). See Setup.

How the plugin tells builds apart

The plugin checks these in order and uses the first that applies:

Where it builds	How the environment is read
Vercel	`VERCEL_ENV`: `production` is production, `preview` is preview, anything else is development
Netlify	`CONTEXT`: `production` is production, every other context is preview
Other CI	`SKYELIGHT_ENV=preview` or `SKYELIGHT_ENV=production`, if you set it
Anywhere else	`NODE_ENV=production` is production, anything else is development

On other CI, set SKYELIGHT_ENV=preview for preview builds. Without it, a build with NODE_ENV=production counts as production and gets nothing from the plugin. A preview treated as production loses stamps and the badge. A production build treated as a preview would get source paths in its HTML.

Where the badge shows on its own

Next.js previews and local builds: the badge’s mark appears on arrival.
Vite, Remix, Astro and WXT previews: the badge waits for a link with ?skyelight=1, or for a reviewer who has signed in on that site before. Links from Skyelight, such as emails, Slack messages and the web app, include ?skyelight=1.
Production, when production: true: the badge always waits for one of those.

Adding ?skyelight=0 to an address signs that browser out of the badge on that site.

Configs without `production`

Configs written before setup asked about production have no production key. They keep the earlier behavior: stamps and the badge each have their own environment variable, and the variable overrides the platform:

	Force on / off	Vercel	Netlify	Elsewhere
Stamping	`SKYELIGHT_STAMP=1` / `0`	on for `preview` only	on unless `CONTEXT=production`	on unless `NODE_ENV=production`
Badge tag	`SKYELIGHT_WIDGET=1` / `0`	on for `preview` only	on unless `CONTEXT=production`	on unless `NODE_ENV=production`

The two variables are separate so that you can run the badge on a live site without putting source paths in its HTML.

Once your config sets production, as setup does, the plugin ignores SKYELIGHT_STAMP and SKYELIGHT_WIDGET. Use the stamp and widget options instead. For example, stamp: false stops writing source paths.

The commit and the branch

The plugin reads the commit and branch from your build environment, and falls back to git locally. The first value found wins:

	Read from
Commit	`SKYELIGHT_BUILD_ID`, `VERCEL_GIT_COMMIT_SHA`, `GITHUB_SHA`, `COMMIT_REF`, `CF_PAGES_COMMIT_SHA`, then `git rev-parse --short HEAD`
Branch	`SKYELIGHT_BRANCH`, `VERCEL_GIT_COMMIT_REF`, `GITHUB_HEAD_REF`, `GITHUB_REF_NAME`, `BRANCH`, `CF_PAGES_BRANCH`, then `git rev-parse --abbrev-ref HEAD`
Commit subject	Next.js only. `SKYELIGHT_COMMIT_SUBJECT`, `VERCEL_GIT_COMMIT_MESSAGE`, then `git log -1`

The commit is shortened to seven characters. The branch is stamped in full. On a GitHub pull request, GITHUB_HEAD_REF comes first, because GITHUB_REF_NAME holds the merge ref there instead of your branch. If your CI sets none of these, set SKYELIGHT_BUILD_ID and SKYELIGHT_BRANCH, or pass buildId and branch.

Neither value is required. A build that can’t find one still succeeds and stamps what it has.

Testing against another Skyelight address

SKYELIGHT_ORIGIN changes where the badge script loads from. The default is https://app.skyelight.ai. It’s for testing and self-hosting only. The plugin reads it at build time, so a change takes effect on the next build.