Add a pixel mascot to a Next.js site

Perch edits the right Next.js file for you, including layouts inside route groups like app/(site)/layout.tsx.

1. Run the command

cd your-next-app
npx perch-pet

It looks for every root layout (a layout.tsx that renders <html> and <body>), in app/ and src/app/, at any depth. One root layout is picked for you. Several (one per route group) become a menu.

2. What it changes

Copies perch.js and perch-tuner.js to public/.
App router: adds import Script from "next/script" and one <Script src="/perch.js" strategy="afterInteractive" /> before </body>.
Pages router: adds a script tag to pages/_document (creates it if missing).

Preview it first with npx perch-pet --dry. Undo with npx perch-pet --remove.

3. Choose the layout yourself

npx perch-pet --file "app/(marketing)/layout.tsx"
# several route groups:
npx perch-pet --file "app/(marketing)/layout.tsx" --file "app/(app)/layout.tsx"

4. Tune it

Run npm run dev. A gear button appears at the bottom left on localhost. Swap the creature, show floors, pick your call to action with a click. Then run the command it shows, for example:

npx perch-pet set creature=cat stickiness=0.8 goal=".hero a"

The tuner file is deployed with your site but is only loaded on localhost, local-network addresses and ?perch=tune. Visitors on your live site never get it. This demo site is the one exception: it opts in with data-tuner="true".

Questions

Does it work with the Next.js app router and route groups?

Yes. It finds root layouts at any depth, including layouts inside route groups such as app/(site)/layout.tsx.

Does it need a client component?

No. It uses next/script with strategy afterInteractive, so your layout stays a server component.

Will it work with a strict Content Security Policy?

Yes, if script-src allows your own origin. The script loads from /perch.js on your site.

What is Perch? GitHub