PreflightJS & Dashboard

PreflightJS is an automated “sanity check” pipeline for frontend deployments paired with a modern dashboard that tells release managers whether the next push to staging is safe. The CLI enforces nine guardrails (build, runtime, UX, and accessibility) while the Next.js SPA makes those results human friendly.

---

Why we built this

Traditional CI warns us when tests fail, but it rarely catches “felt” regressions that only show up once assets are built, deployed, and opened in a browser. PreflightJS adapts the ML sanity-check playbook to frontend stacks by watching for:

1. Build pipeline failures or warnings that slip through CI
2. API contract drift between backend and frontend
3. Missing or misconfigured environment variables
4. Component rendering / hydration problems during real navigation
5. Bundle size creep and sudden asset growth
6. Visual regressions on critical screens
7. Runtime console errors or warnings in production routes
8. Lighthouse performance drops
9. Accessibility violations beyond an allowed severity

Every run surfaces these issues before release, outputs structured JSON/Markdown artifacts, and drives the accompanying dashboard.

---

System architecture

Layer	Description
Config	preflight.config.json defines build commands, artifact paths, routes, thresholds, required env vars, and reporter destinations.
Runner (src/runner.ts)	Loads the config via a strict Zod schema, instantiates each enabled check from src/checks, executes them with shared context (logger, temp dir, env), and aggregates results.
Checks (src/checks/*.ts)	Each module implements CheckDefinition. They run in isolation, report pass/warn/fail/skipped, and can attach artifacts (screenshots, diff images, etc.). Heavy dependencies (Playwright, Lighthouse, axe) are optional and lazily imported.
Reporters (src/reporters/*.ts)	Console reporter prints a release-friendly summary; Markdown and JSON reporters emit files for dashboards, PR comments, or other tooling.
Dashboard (web/ Next.js app)	Consumes snapshot data (sample or real reports), renders a glassmorphic release console, highlights failing gates, and includes onboarding + automation guidance.

Config file → Runner → Checks → Results → Reporters → CLI exit + Dashboard

---

Repository layout

.
├── src/                 # TypeScript CLI
│   ├── checks/          # build, env, API, bundle, rendering, visual, console, Lighthouse, a11y
│   ├── reporters/       # console, markdown, json
│   ├── utils/           # exec helpers, lazy Playwright loader, logger
│   ├── config.ts        # Zod schema + config loader
│   ├── runner.ts        # orchestrates checks and reporting
│   └── index.ts         # CLI entry point (`preflightjs`)
├── preflight.sample.config.json
├── web/                 # Next.js dashboard (Tailwind, Lucide, Space Grotesk)
│   ├── app/             # App Router pages and layouts
│   ├── components/      # SnapshotHeader, OverviewPanels, CheckCard, etc.
│   ├── lib/sample.ts    # Sample snapshot data used until real reports are wired
│   └── tailwind.config.ts
└── README.md

---

Using the CLI runner

1. Install dependencies

   npm install         # from repo root

2. Create a config

   cp preflight.sample.config.json preflight.config.json
   # Edit commands, routes, thresholds, env vars, etc.

3. Compile and run

   npm run build                                 # tsc → dist/
   npm run preflight -- --config preflight.config.json
   # exit code 0 => all gates pass; 1 => at least one fail

4. Inspect artifacts

   • Console summary lists each check with PASS/WARN/FAIL/SKIP.
   • .preflight/report.json and .preflight/report.md contain structured + human-readable reports the dashboard can ingest.

Developing locally? Run npm run dev -- --config path/to/config to skip the tsc build step.

---

Available checks

Check	What it protects	Dependencies
Build	Runs your build command and captures artifacts	Shell
Env vars	Ensures required secrets/config are present	—
API contracts	Diffs baseline and candidate schemas (file or remote)	—
Bundle guard	Sums built JS/CSS, enforces byte limits & growth caps	globby
Component rendering	Uses Playwright to visit critical routes, watch for console/page errors, and take screenshots	playwright (optional)
UI regression	Runs pixelmatch/pngjs on baseline vs candidate screenshots	pixelmatch, pngjs (optional)
Runtime console	Captures browser console output while walking routes	playwright (optional)
Lighthouse	Executes Lighthouse via Chrome launcher, checks category thresholds	lighthouse, chrome-launcher (optional)
Accessibility	Injects axe into Playwright pages and fails on high-impact issues	playwright, @axe-core/playwright (optional)

Each check returns a CheckResult with status, summary, details, and optional artifacts. Failures bubble up through the CLI exit code so CI can block a release automatically.

---

Using the dashboard (web/)

1. Install & run

   cd web
   npm install
   npm run dev        # http://localhost:3000

2. Feed it data

   • By default it imports lib/sample.ts.
   • Replace sampleSnapshot with a JSON parse of .preflight/report.json, or expose an API route that calls the CLI and returns the latest run.

3. Production build

   npm run build
   npm start          # or deploy to Vercel/Netlify

4. What the UI shows

   • Release hero summarizing snapshot metadata, pass/warn/fail counts, and quick actions.
   • Deployment health cards, focus items, and workflow steps.
   • Grid of check cards (same data as CLI) with gradients, badges, and detail tooltips.
   • Automation tips to integrate with CI/CD.

The design intentionally mirrors modern release consoles so non-engineering stakeholders can understand risk at a glance.

---

Extending the suite

1. Add a new file under src/checks/yourCheck.ts that exports a CheckDefinition.
2. Implement the run function with access to context.config, context.logger, etc.
3. Append the check to allChecks in src/checks/index.ts.
4. If it creates artifacts, save them to ctx.tmpDir or a path referenced in your config so reporters can surface them.

Want to extend the dashboard? Add additional components under web/components/ and either enhance the sample dataset or wire it to live API routes.

---

Roadmap ideas

• GitHub/GitLab status reporters and PR annotations
• Storybook story auto-discovery for rendering + visual checks
• Trend charts for Lighthouse scores and bundle size deltas
• Scheduled “post-deploy” monitors that continue running after staging goes live
• Self-service API for other teams to request on-demand preflight runs

---

License

MIT © PreflightJS contributors