Lighthouse Apify Actor

Actor that runs Google Lighthouse on a given page URL and pushes a structured performance report into an Apify Dataset.

MVP is designed to be used directly from the Apify Console UI:

• The Input tab is generated from INPUT_SCHEMA.json.
• The Output tab shows a curated Overview table based on .actor/actor.json.
• Full details (including individual issues and "how to fix" descriptions) are available in the Dataset JSON.

Detailed product and technical specs live under:

• specs/lighthouse-apify-actor/prd.md
• specs/lighthouse-apify-actor/low-level-tech-design.md
• specs/lighthouse-apify-actor/implementation-plan.md

---

What this Actor does

For each run, the Actor:

• Accepts a page URL and a couple of Lighthouse configuration options.
• Launches headless Chrome in the Apify environment.
• Runs Lighthouse with the default configuration for the selected device type.
• Extracts key scores, Core Web Vitals metrics, and issue summaries.
• Persists a single, flattened report record into the default Dataset.

This makes the Apify Dataset act as a lightweight performance reporting backend, ready for consumption directly in the Console or by external tools / UIs via the Apify API.

Typical use cases

• Benchmark a landing page before and after marketing or UX changes.
• Give non-technical stakeholders a quick performance health snapshot they can understand.
• Feed Lighthouse metrics and issue lists into your own dashboards or reporting tools.

---

Input

Inputs are defined in INPUT_SCHEMA.json and automatically rendered in the Apify Console Input tab.

Current input fields:

• url (string, required)

  • The page URL to analyze with Lighthouse.

• emulatedDevice (string, optional)

  • One of: mobile, desktop.
  • Controls Lighthouse formFactor and device emulation.
  • Default: mobile.

• throttlingProfile (string, optional)

  • One of: default, no-throttling.
  • Controls network/CPU throttling profile used during the Lighthouse run.
  • Default: default.

When running on the Apify platform, you normally just set these in the Input tab. When running locally with apify run, the same fields live in storage/key_value_stores/default/INPUT.json.

---

Output

Each run writes one item into the default Dataset. The output schema is defined by the TypeScript model in src/schema/derivedReportModel.ts and the dataset Overview view in .actor/actor.json.

Summary fields (Overview table)

These fields are shown in the overview dataset view in the Apify Console:

• Metadata

  • url – Page URL.
  • runDatetime – ISO timestamp when the run was executed.
  • emulatedDevice – mobile or desktop.
  • throttlingProfile – default or no-throttling.

• Lighthouse category scores (0–100)

  • scorePerformance
  • scoreAccessibility
  • scoreBestPractices
  • scoreSeo

• Key metrics

  • metricLCP – Largest Contentful Paint (ms).
  • metricCLS – Cumulative Layout Shift.
  • metricINP – Interaction to Next Paint (ms).
  • metricTBT – Total Blocking Time (ms).

• Issue counts

  • numHighSeverityIssues
  • numMediumSeverityIssues
  • numLowSeverityIssues

These fields give a high-level view of page health directly from the Apify Output tab.

Detailed issue lists (JSON only)

The full dataset item also contains three arrays with per-issue details:

• highSeverityIssues: Issue[]
• mediumSeverityIssues: Issue[]
• lowSeverityIssues: Issue[]

Each Issue has:

• id – Lighthouse audit id (e.g. uses-optimized-images).
• title – Human-readable issue title.
• description – Lighthouse description explaining why it matters and how to fix it.
• score – Audit score on a 0–100 scale.
• numericValue – Numeric metric value (if available).
• displayValue – Human-readable value (e.g. 1.2 s).
• category – Category id inferred from Lighthouse categories (e.g. performance, seo, accessibility).

These detailed lists are ideal for:

• Building a custom reporting UI on top of this Actor.
• Generating tailored performance reports for stakeholders.
• Performing more advanced analysis outside of Apify.

---

How to run locally

Prerequisites:

• Node.js 18+.
• apify-cli installed globally (npm i -g apify-cli).
• Google Chrome (or Chromium) available on your machine.

1. Install dependencies

$npm install

2. Build the project

$npm run build

3. Prepare local input

Create or edit storage/key_value_stores/default/INPUT.json:

{
  "url": "https://example.com",
  "emulatedDevice": "mobile",
  "throttlingProfile": "default"
}

4. Run the Actor

$apify run

This will:

• Simulate the Apify environment locally.
• Run Lighthouse for the provided URL.
• Store results under storage/datasets/default/ as JSON files (000000001.json, 000000002.json, ...).

You can open these files directly to inspect both the summary fields and the detailed issue arrays.

---

Running on Apify platform

1. Log in with apify-cli:

   $apify login
   

2. Deploy the Actor from this directory:

   $apify push
   

   This uploads the code together with .actor/actor.json and INPUT_SCHEMA.json.

3. In the Apify Console:

   • Open the newly deployed Actor.
   • In the Input tab, configure url, emulatedDevice, throttlingProfile.
   • Click Start.

4. After the run finishes:

   • Go to the Storage / Dataset section of the run.
   • Use the overview view for a table of summary fields.
   • Switch to JSON view or export to see detailed issue arrays.

---

Environment notes

• Chrome executable path:

  • The Actor attempts to use the Chrome/Chromium available in the Apify environment.
  • Locally, you can override the path using environment variables such as CRAWLEE_CHROME_EXECUTABLE_PATH or APIFY_CHROME_EXECUTABLE_PATH if needed.

• Logging:

  • All major steps (launching Chrome, running Lighthouse, pushing dataset records) are logged via Apify's logger.

---

Dockerfile & runtime on Apify

This Actor uses a custom Dockerfile based on apify/actor-node:20:

• Installs dependencies (including dev dependencies for TypeScript).

• Copies the project into /usr/src/app.

• Runs npm run build to produce dist/main.js.

• Prunes dev dependencies with npm prune --production.

• Starts the Actor with:

  $node dist/main.js
  

If you change the build output directory or the main entrypoint, update both:

• package.json scripts (e.g. build, start).
• Dockerfile CMD / build steps.

This keeps local apify run behavior and Apify cloud runs aligned.

---

Pricing & run cost transparency

This Actor runs a single Lighthouse audit per run. The main factors influencing cost and duration are:

• Target page complexity and size (heavier pages take longer to audit).
• Chosen device and throttling profile (mobile + default throttling is typically slower than desktop + no throttling).

When monetizing on Apify, a Pay per event (PPE) model maps naturally to this Actor:

• 1 run = 1 Lighthouse audit for 1 URL.
• Users can roughly estimate costs by multiplying their number of URLs by your per-run price and considering typical Lighthouse runtimes (usually under a few minutes per URL).

Document any concrete pricing in the Apify Console pricing section when you publish the Actor.

---

Roadmap / Future extensions

Planned improvements (beyond the current MVP):

• Dedicated, rich web reporting UI built on top of the dataset outputs.
• Integration with Chrome UX (CrUX) data for real-world performance signals.
• Additional Apify dataset views (e.g. flattened issue table using unwind).
• Optional scheduling / recurring runs for monitoring over time.

For more details about planned phases and design decisions, see the specs under specs/lighthouse-apify-actor/.