Skip to Content
Skyelight BuildSetup

Setup

This guide installs @skyelight/build in your app and connects your preview builds to a Skyelight project. It takes about five minutes and needs no key or token.

Before you start, you need:

  • Node.js 18 or later.
  • An app built with Next.js, Vite, Remix, Astro or WXT, with its config file (such as next.config.ts or vite.config.ts) next to package.json.
  • A Skyelight project, and the owner or admin role in its workspace to add the preview address. Someone else with that role can do step 2 for you.

  1. Run the setup

    From your project’s root, where package.json is:

    npx @skyelight/build

    Setup detects your framework, config file and package manager, then asks what the plugin should do:

    All three options are selected by default. Press Space to toggle an option, Enter to confirm, or Esc to exit without changing anything. Setup then shows the change to your config file and asks you to confirm before it installs the package or edits the file.

    Setup writes every answer into your config, for example withSkyelight(nextConfig, { stamp: true, widget: true, production: false }), so the config shows what each build gets. It ends with a summary of what preview, local and production builds get.

    Setup accepts two flags:

    • --yes skips the questions and uses the defaults. Setup does the same on CI, or anywhere without an interactive terminal.
    • --pm <name> sets the package manager: npm, pnpm, yarn or bun. Without it, setup reads packageManager in package.json, then your lockfile. If the project has more than one lockfile, setup asks.

  2. Add your preview address in Skyelight

    A project owner or admin adds the address your previews are served from under Project settings Review Links. This step happens in Skyelight, not in your code. Until an address is on the list, nobody can sign in to the badge on it. The list also tells Skyelight which project the threads belong to. See Preview URLs.

    If your previews use Vercel Deployment Protection, also add your bypass secret. Without it, reviewers see Vercel’s login page first. See Deployment bypass.

  3. Deploy a preview and open it

    Push a branch and open its preview:

    • On Next.js, the badge’s mark appears in a corner of the page.
    • On Vite, Remix, Astro or WXT, the badge waits for a link that includes ?skyelight=1. Add it to the address on your first visit. Links from Skyelight include it.

    Sign in when the badge asks, then pin an element. The thread appears in your project with its source location.

    To confirm that setup worked:

    • Under Project settings Review Links, the preview address shows Connected, the plugin version (Build v…) and the settings the build reported.
    • In your browser’s developer tools, a stamped element has a data-sky-src attribute, such as data-sky-src="app/page.tsx:12".

  4. Check production in CI (optional)

    After a production build, run:

    npx @skyelight/build verify

    verify reads the build output and exits with an error if it finds any Skyelight attribute or the badge’s script. Run it in CI to catch a config change that would ship source paths to production. It checks .next, dist, build, out and .output by default. To check other directories, name them:

    npx @skyelight/build verify dist

    A clean build prints No Skyelight attributes or script in followed by the directories checked. verify reads files only and makes no network calls.

    verify needs @skyelight/build 0.14.0 or later. npx runs the copy installed in your project, so an older copy prints Unknown command: verify. Update it first:

    npm install -D @skyelight/build@latest

You can run setup again on a project that already has the plugin. It offers to add any options your config is missing, and it updates an installed copy that is older than the version you ran.

If setup fails

Setup changes nothing when it stops early. The message tells you why:

MessageWhat to do
No package.json here.Run setup from the directory that contains package.json.
Could not tell which framework this is.Setup supports Next.js, Vite, Astro and WXT (Remix uses Vite). Add the plugin by hand.
Found …, but no config file to add the plugin to in this directory.Create the framework’s config file, or add the plugin by hand.
This project has more than one lockfilePass --pm with the package manager to use.
Could not edit … automaticallySetup prints the two lines to add. Add them by hand.

For problems after setup, such as the badge not appearing or sign-in failing, see Troubleshooting.

By hand

To set up the plugin yourself, install the package as a dev dependency:

npm install -D @skyelight/build

Then add it to your config. Pass { production: false } to keep the plugin out of production builds, as setup does. See Options and environments.

Wrap your existing export:

// next.config.ts
import { withSkyelight } from "@skyelight/build/next";
 
export default withSkyelight(nextConfig, { production: false });

The package includes TypeScript declarations, and withSkyelight returns the same type as the config you pass in.

For another bundler, @skyelight/build/core exports the transform, stampSource, so you can write your own adapter.

Last updated on
Review badgeOptions and environments