Configuration

peek can be configured through CLI flags, a config file, or both. The config file is useful for setting project-wide defaults for layout checks.

Config File

Create peek.config.js (or peek.config.mjs) in your project root:

export default {
  ignore: ['.ad-banner', '[data-testid="skeleton"]'],
  checks: {
    overflow: { horizontal: true, vertical: false },
    touchTargets: { minWidth: 44, minHeight: 44 },
    textOverflow: { allowEllipsis: true },
  },
  severity: {
    touchTargets: 'warning',
  },
};

Pass it to peek check with the -c flag:

peek check http://localhost:3000 -c peek.config.js

Config Structure

ignore

An array of CSS selectors for elements to skip during all checks. This is merged with any --ignore flags from the CLI.

ignore: ['.ad-banner', '.cookie-popup', '[data-testid="loading"]']

checks

Per-check configuration. Each check can be set to true (enabled with defaults), false (disabled), or an object with check-specific options.

checks: {
  overflow: { horizontal: true, vertical: false },
  clickability: { checkCorners: true },
  touchTargets: { minWidth: 44, minHeight: 44 },
  textOverflow: { allowEllipsis: true },
  visibility: true,
  viewportMeta: true,
}

severity

Override the default severity level for specific checks. Valid values are 'error', 'warning', and 'info'.

severity: {
  touchTargets: 'warning',
  textOverflow: 'info',
}

The data-peek-ignore Attribute

Add data-peek-ignore to any HTML element to exclude it from all checks:

<div data-peek-ignore>
  <!-- This element and its children are ignored by peek -->
</div>

This is the recommended way to skip specific elements without modifying your peek config.

CLI Flag Precedence

CLI flags override config file values. For example, if your config file includes ignore: ['.banner'] and you also pass --ignore .popup, the final ignore list will include both .banner and .popup.

Setup Scripts

For authenticated pages, create a setup script that runs before the main action:

// login.ts
export default async (page) => {
  await page.goto('http://localhost:3000/login');
  await page.type('#email', 'user@example.com');
  await page.type('#password', 'password');
  await page.click('button[type="submit"]');
  await page.waitForNavigation();
};

Pass it to any command with --setup:

peek snap http://localhost:3000/dashboard --setup ./login.ts
peek check http://localhost:3000/dashboard --setup ./login.ts

The setup script receives a Puppeteer Page object. Session cookies persist across pages within the same browser, so any subsequent navigation within that command will be authenticated.

Built with Ptero