Getting Started

Choose an option below to see framework specific guides on how to set up Palette.

1

Install Palette

npm

npm install @palette.dev/browser

pnpm

pnpm install @palette.dev/browser

yarn

yarn add @palette.dev/browser

2

Initialize Palette

Import palette before all other imports in your app's entrypoint file.

Get your client key at https://palette.dev/[your-username]/[your-project]/settings

Next.js

_app.js

// Import palette before all other imports
import { init, events, markers, network, vitals, profiler, paint } from "@palette.dev/browser";

init({
  key: "YOUR_CLIENT_KEY",
  // Collect click, network, performance events, and profiles
  plugins: [events(), network(), vitals(), markers(), profiler(), paint()],
});

// Start the profiler on the following events:
profiler.on(
  [
    "paint.click",
    "paint.keydown",
    "paint.scroll",
    "paint.mousemove",
    "markers.measure",
    "events.load",
    "events.dcl",
  ],
  {
    sampleInterval: 1,
    maxBufferSize: 100_000,
  }
);

// Your other imports...

Create React App

src/index.js

// Import palette before all other imports
import { init, events, markers, network, vitals, profiler, paint } from "@palette.dev/browser";

init({
  key: "YOUR_CLIENT_KEY",
  // Collect click, network, performance events, and profiles
  plugins: [events(), network(), vitals(), markers(), profiler(), paint()],
});

// Start the profiler on the following events:
profiler.on(
  [
    "paint.click",
    "paint.keydown",
    "paint.scroll",
    "paint.mousemove",
    "markers.measure",
    "events.load",
    "events.dcl",
  ],
  {
    sampleInterval: 1,
    maxBufferSize: 100_000,
  }
);

// Your other imports...

Other

index.js (your app's entrypoint)

// Import palette before all other imports
import { init, events, markers, network, vitals, profiler, paint } from "@palette.dev/browser";

init({
  key: "YOUR_CLIENT_KEY",
  // Collect click, network, performance events, and profiles
  plugins: [events(), network(), vitals(), markers(), profiler(), paint()],
});

// Start the profiler on the following events:
profiler.on(
  [
    "paint.click",
    "paint.keydown",
    "paint.scroll",
    "paint.mousemove",
    "markers.measure",
    "events.load",
    "events.dcl",
  ],
  {
    sampleInterval: 1,
    maxBufferSize: 100_000,
  }
);

// Your other imports...

3

Upload source maps

Configure your bundler to upload source maps during build time.

This step is required if you are using a framework or a bundler (like Next.js, Webpack, Vite, or Parcel).

Next.js

npm

npm install @palette.dev/webpack-plugin --save-dev

pnpm

pnpm install @palette.dev/webpack-plugin --save-dev

yarn

yarn add @palette.dev/webpack-plugin --dev

next.config.js

const { withPalette } = require("@palette.dev/webpack-plugin/next");

const withPalettePlugin = withPalette({
  key: process.env.PALETTE_ASSET_KEY,
});

module.exports = withPalettePlugin({
  // your next config...
});

Create React App (ejected)

npm

npm install @palette.dev/webpack-plugin --save-dev

pnpm

pnpm install @palette.dev/webpack-plugin --save-dev

yarn

yarn add @palette.dev/webpack-plugin --dev

config/webpack.config.js

const PalettePlugin = require("@palette.dev/webpack-plugin");

module.exports = {
  // ...
  plugins: [
    isEnvProduction &&
      new PalettePlugin({
        key: process.env.PALETTE_ASSET_KEY,
        include: ["build/static/js"],
      }),
  ].filter(Boolean),
};

Webpack

npm

npm install @palette.dev/webpack-plugin --save-dev

pnpm

pnpm install @palette.dev/webpack-plugin --save-dev

yarn

yarn add @palette.dev/webpack-plugin --dev

webpack.config.js

const PalettePlugin = require("@palette.dev/webpack-plugin");

module.exports = {
  // ...
  plugins: [
    new PalettePlugin({
      key: process.env.PALETTE_ASSET_KEY,
    }),
  ],
};

Vite

npm

npm install @palette.dev/plugin-vite --save-dev

pnpm

pnpm install @palette.dev/plugin-vite --save-dev

yarn

yarn add @palette.dev/plugin-vite --dev

vite.config.ts

import path from "path";
import { defineConfig } from "vite";
import palette from "@palette.dev/plugin-vite";

export default defineConfig({
  plugins: [
    // Add palette plugin
    palette({
      key: process.env.PALETTE_ASSET_KEY,
      outputPath: "dist/assets",
    }),
  ],
  build: {
    // Output source maps
    sourcemap: true,
    rollupOptions: {
      output: {
        // Set source maps paths relative to the current working directory
        sourcemapPathTransform: (relativeSourcePath, sourcemapPath) =>
          path.relative(process.cwd(), path.resolve(path.dirname(sourcemapPath), relativeSourcePath)),
      },
    },
  },
});

Other

npm

npm install @palette.dev/cli --save-dev

pnpm

pnpm install @palette.dev/cli --save-dev

yarn

yarn add @palette.dev/cli --dev

Directory Structure

my-project/
├── dist/
│   └── main.js
└── package.json

package.json

{
  "scripts": {
    "upload": "palette upload dist"
  }
}

Set asset key

In your CI, set an env variable named PALETTE_ASSET_KEY to your asset key. This is necessary since source maps are only uploaded in CI.

Get your asset key at https://palette.dev/[your-username]/[your-project]/settings.

Vercel

npx vercel env add

Netlify

npx netlify env:set PALETTE_ASSET_KEY "YOUR_ASSET_KEY"

GitHub Workflows

gh secret set PALETTE_ASSET_KEY

4

Add headers

To enable profiling, you need to add the "Document-Policy": "js-profiling" to your server responses.

Next.js

You can skip this step, this was handled by the withPalette util in step 3.

Vercel

vercel.json

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Document-Policy",
          "value": "js-profiling"
        }
      ]
    }
  ]
}

Netlify

_headers

Document-Policy: js-profiling