prelaunch

Catch launch-day mistakes before your visitors (and Google) do.

prelaunch crawls a website and checks the things that get forgotten when a site goes live: the noindex left over from staging, a robots.txt that blocks Google, a public .env file, PHP warnings printed into the page, broken links, missing share images, missing security headers and more.

It runs in one command, needs no account or API key, and produces a clean HTML report you can hand to a client.

npx prelaunch example.com

_{The HTML report for the deliberately broken demo site. It adapts to light and dark mode and prints cleanly.}

Why

Lighthouse is great at performance and accessibility, and SEO tools are great at SEO. What is missing is a quick go-live checklist that also covers the boring, costly mistakes, the ones that happen when a site moves from staging to production:

• the staging <meta name="robots" content="noindex"> that quietly keeps the site out of Google for months
• Disallow: / in robots.txt, or a canonical URL pointing at localhost
• a .env, .git/ or database dump in the public folder
• APP_DEBUG=true or display_errors=On, printing stack traces and file paths to visitors
• a broken favicon, a missing share image, links to pages that no longer exist

prelaunch checks all of that in one pass, in a few seconds.

Usage

# Audit a site and print the results
npx prelaunch https://example.com

# Save a shareable HTML report (and/or .md, .json)
npx prelaunch example.com -o report.html

# Fail a CI job on warnings too, and skip rules you do not care about
npx prelaunch staging.example.com --fail-on warning --ignore security/csp,performance

Option	Description
-o, --output <file>	Write a report. The format comes from the extension: .html, .md, .json or .txt. Repeatable.
-f, --format <format>	Terminal output: text (default), json, md or html.
--max-pages <n>	Same-site pages to crawl (default 10).
--max-links <n>	Links and files to check (default 500).
--no-external	Do not check links to other websites.
--ignore <rules>	Skip rules (seo/h1) or whole categories (performance), comma-separated.
--fail-on <level>	Exit with code 1 on error (default), warning or never.
--timeout <ms>	Per-request timeout (default 15000).
--concurrency <n>	Parallel requests (default 8).
-v, --verbose	Also list passed checks.
-q, --quiet	Hide the progress line.

Exit codes: 0 passed, 1 issues at or above --fail-on were found, 2 invalid usage or the site could not be loaded.

What it checks

39 rules in 7 categories. Each result is an error (fix before launch), a warning (strongly recommended) or a note.

SEO

Rule	Catches
seo/noindex	noindex in <meta name="robots">, googlebot or the X-Robots-Tag header
seo/canonical	Missing canonical, or one that points to localhost, a staging domain, another host or the wrong protocol
seo/title	Missing, too short or too long <title> (ignores <title> inside inline SVG)
seo/duplicate-title	Several pages sharing one title
seo/meta-description	Missing, too short or too long meta description
seo/h1	No <h1>, or several
seo/lang	Missing <html lang>
seo/viewport	Missing mobile viewport tag
seo/charset	No declared character encoding

Social previews

Rule	Catches
social/og-image	Missing, relative, broken, non-image or oversized og:image
social/og-title	Missing og:title
social/og-description	Missing og:description
social/twitter-card	Missing twitter:card

Crawling & indexing

Rule	Catches
crawl/robots-txt	Missing robots.txt, Disallow: / for Google, HTML served as robots.txt, server errors
crawl/sitemap	No sitemap, a broken sitemap listed in robots.txt, or one listing URLs on another (staging) host
crawl/not-found	"Soft 404s": missing pages that return 200 or redirect to the home page
crawl/redirects	Redirect chains on the home page
crawl/www	www and bare domain that do not redirect to one another, or one that does not resolve

Links

Rule	Catches
links/broken	Internal and external links that return 4xx/5xx or fail to connect, with the pages that link to them
links/broken-resources	Images, scripts, stylesheets and embeds that fail to load

Security

Rule	Catches
security/exposed-files	Public .env, .git/, laravel.log, phpinfo.php, .vscode/sftp.json, .htpasswd, .DS_Store, SQL dumps, config backups (verified by content, not just status code)
security/debug-output	PHP errors, Laravel/Symfony/Django debug pages and stack traces in pages or the 404 page
security/directory-listing	Folders that list their files ("Index of /…")
security/https	Site served over plain HTTP
security/http-redirect	http:// not redirecting to https://
security/mixed-content	HTTPS pages loading files over http://
security/server-banner	Server, X-Powered-By and similar headers revealing software versions
security/hsts	Missing or short Strict-Transport-Security
security/content-type-options	Missing X-Content-Type-Options: nosniff
security/clickjacking	No X-Frame-Options or CSP frame-ancestors
security/referrer-policy	Missing Referrer-Policy
security/csp	Missing Content-Security-Policy

Performance

Rule	Catches
performance/response-time	Home page taking over a second to respond
performance/compression	HTML served without gzip/Brotli
performance/html-size	HTML documents over 500 KB
performance/large-images	Images over 500 KB

Images & icons

Rule	Catches
assets/favicon	Missing or broken favicon
assets/apple-touch-icon	Missing home screen icon
assets/img-alt	<img> without an alt attribute

Every finding in the reports comes with a short "how to fix" note.

GitHub Action

Run prelaunch against a staging or preview deployment on every push. The job summary shows the Markdown report, and the HTML report is uploaded as an artifact.

name: Pre-launch check
on: [push]

jobs:
  prelaunch:
    runs-on: ubuntu-latest
    steps:
      - uses: Arda-dd/prelaunch@v0
        with:
          url: https://staging.example.com
          fail-on: error            # error | warning | never
          ignore: security/csp      # optional

Input	Default	Description
url	(required)	Site to audit
fail-on	error	Fail the job on error, warning or never
max-pages	10	Pages to crawl
ignore		Rules or categories to skip, comma-separated
external-links	true	Also check links to other sites
report-name	prelaunch-report	Artifact name for the HTML report; empty to skip the upload

Outputs: score, grade, errors, warnings.

Node API

import { audit, renderHtml } from 'prelaunch';
import { writeFile } from 'node:fs/promises';

const result = await audit('https://example.com', { maxPages: 20, ignore: ['performance'] });
console.log(result.score, result.grade, result.counts);
await writeFile('report.html', renderHtml(result));

result.findings is a flat list of { rule, category, severity, message, url?, details? }, and result.rules has the title and fix advice for each rule.

Scoring

Each rule is scored by its worst finding: pass or note = 100%, warning = 50%, error = 0%. A category score is the average of its rules, and the overall score is the average of the categories. Grades: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F below.

Try it locally

The repository includes a demo site full of typical mistakes:

python -m http.server 8000 --directory examples/demo-site
npx prelaunch http://localhost:8000 -o report.html

Responsible use

prelaunch sends ordinary GET/HEAD requests, about one per page, link and checked file. It sends at most 8 requests in parallel and 4 to any single site. When a site starts rate-limiting, it backs off and skips that site's remaining links. Its probes for sensitive files only request a short list of well-known paths. Even so, only audit sites you own or have permission to test.

Roadmap

• Config file (prelaunch.config.json) for per-project rules and thresholds
• Optional headless-browser mode for JavaScript-rendered sites and console errors
• Structured data (JSON-LD) validation
• Translated HTML reports
• SSL certificate expiry warnings

Ideas and pull requests are welcome; see CONTRIBUTING.md.

License

MIT