The devtools overlay
Mount the in-app devtools overlay so you and your team can file bugs and feature requests without leaving the product.
The devtools overlay is the in-app panel behind every bug report and feature request. It mounts as an isolated, shadow-DOM floating rail on your own site, captures the page context for you, and posts straight into your project's feedback queue. The same overlay also surfaces your flags, configs, experiments, and i18n keys, so it doubles as a control panel while you're building.
It ships in @shipeasy/devtools and rides the bundle that base setup already wired
into your root layout — in the common case there is nothing to install.
Already wired: just add ?se
If you ran /shipeasy:setup, your root layout renders getBootstrapHtml() into
<head>. That snippet lazily loads the overlay from
https://shipeasy.ai/se-devtools.js only when the URL contains ?se (or
?se_devtools) — so it costs your users nothing until someone asks for it.
Open the overlay
~30 secondsConfirm the bootstrap is in <head>
No bootstrap, no overlay. If it's missing, re-run /shipeasy:setup.
Append ?se to any page
The rail appears bottom-right. Toggle it any time with Shift+Alt+S.
Sign in once, then report
First open prompts a one-time sign-in popup. The report lands in your dashboard within seconds.
Shift+Alt+S toggles the overlay open and closed; ?se-devtools in the URL opens it immediately
on load.
Mount it unconditionally with init()
When you want the rail present without the ?se gate — an internal tool, a staging
build, a demo — call init() once from a client component at app boot:
"use client";
import { init as initDevtools } from "@shipeasy/devtools";
import { useEffect } from "react";
export function Devtools() {
useEffect(() => initDevtools({ accentColor: "var(--brand)" }), []);
return null;
}init() is framework-agnostic — call it from any useEffect, onMounted, or a
plain <script>. It is idempotent and tears itself down via destroy().
Signing in
The overlay is team-facing and authenticated. On first open it pops a window to
{adminUrl}/devtools-auth, you approve access, and it stores a short-lived,
browser-scoped admin token in sessionStorage (valid ~10 minutes). Reports post
to the admin endpoints (POST /api/admin/bugs, /api/admin/feature-requests) with
that token — no cookies, no SDK key embedded in the page.
If the sign-in popup never returns or the overlay never appears, base setup is
incomplete — getBootstrapHtml() isn't rendering into <head>. Re-run
/shipeasy:setup before debugging anything else.
What a report captures
The bug form asks for a title, steps to reproduce, actual result, expected result, and an optional priority. On top of what the user types, the overlay attaches the page context automatically:
Auto-attached context→
pageUrl (the current location.href), userAgent, and viewport (width×height) — so a
report is reproducible without asking "where were you?"
Screenshot & screen recording→
One click grabs a screenshot or a screen recording (with audio) via the browser's
getDisplayMedia() and uploads it alongside the report.
Feature requests use the same flow with a title, description, and use-case, plus the same auto-attached page context.
Demo mode
Pass seed to skip the sign-in popup and preload a project — useful for marketing
pages, screenshots, and tests. Seeded values are written to sessionStorage only
when absent, so a real session is never clobbered:
initDevtools({
seed: {
session: { token: "demo", projectId: "proj_demo" },
project: { id: "proj_demo", name: "Acme", modules: { feedback: true } },
activePanel: "feedback",
},
});Verify the install
shipeasy modules enable feedback # the overlay needs the feedback module on
shipeasy modules list # expect: feedback ✓
# then load any page with ?se=1 and confirm the rail appears
shipeasy feedback bugs list # CLI mirror — expect [] or rows, never 403/shipeasy:ops:install runs these checks for you and drops the project pointer
skills.