LH4U provides Google Lighthouse as a service, surfaced by both a friendly UI+API, and backed by Elastic Search for all your query and visualization needs

Usage no npm install needed!

<script type="module">
  import lighthouse4u from '';




LH4U provides Google Lighthouse as a service, surfaced by both a friendly UI+API, and backed by various storage and queue clients to support a wide range of architectures.



Start server via CLI:

npm i -g lighthouse4u
lh4u server --config local --config-dir ./app/config --config-base defaults --secure-config ./app/config/secure --secure-file some-private.key

Or locally to this repo via npm start (you'll need to create test/config/local.json5 by copying test/config/COPY.json5).


With the release of v1, we've decoupled compute and storage into multiple tiers to permit a diverse set of architectures. Not only are custom storage and queue clients supported, but compute can even be run serverless.

Queue Architecture

This most closely resembles that of v0.7, but without the restrictions of being locked into Elasticsearch and RabbitMQ.

  reader: {
    module: 'lighthouse4u-elasticsearch', options: { /* ... */ }
  writer: {
    module: 'lighthouse4u-elasticsearch', options: { /* ... */ }
  queue: { // rabbit
    module: 'lighthouse4u-amqp', options: { /* ... */ }

Note: The lighthouse4u-elasticsearch storage client is not yet available. Happy to take contributions!

Serverless Architecture

Same as above, you're not tied to Elasticsearch. Use whatever storage and queue client fits your needs. Due to the nature of AWS Lambda, your Lighthouse "runner" (triggered via SQS) is separate from the Lighthouse4u UI+API.

Serverless example via AWS Lambda

Configuration Options

Option Type Default Desc
store reader writer
->.module string required Path of client module to import. See storage clients
->.options object Collection of options supplied to storage client
queue Queue configuration
->.module string required Path of client module to import. See queue clients
->.idleDelayMs number 1000 Time (in MS) between queue checks when queue is empty
->.enabled boolean true Consuming queue may be disabled
->.options object Collection of options supplied to queue client
http HTTP(S) Server options
->.bindings Hash<HttpBinding> An object of named bindings
->.bindings.{name} HttpBinding With {name} being the name of the binding -- can be anything, ex: myMagicBinding. See value to false if you want to disable this binding.
->.bindings.{name}.port number 8994 Port to bind to
->.bindings.{name}.ssl TLS Options undefined Required to bind HTTPS/2
->.auth Zero or more authorization options
->.auth.{authName} HttpAuth A set of auth options keyed by any custom {authName}
->.auth.{authName}.type basic|custom required Type of auth, be it built-in Basic auth, or custom provided by customPath module
->.auth.{authName}.groups string|array<string> * required
->.auth.{authName}.customPath string Path of the custom module
->.auth.{authName}.options Options provided to the auth module
->.authRedirect undefined URL to redirect UI to if auth is enabled and fails
->.routes Optional set of custom routes
->.routes.{name} string|HttpRoute If value of type string that'll be used as path
->.routes.{name}.path string Path to resolve to connect middleware, relative to current working directory
->.routes.{name}.method string GET Method to bind to
->.routes.{name}.route string Uses {name} if undefined Route to map, ala /api/test
->.staticFiles Optional to bind routes to static assets
->.staticFiles.{route} Express Static Options to supply to static middleware
lighthouse Options related to Lighthouse usage
->.config LighthouseOptions Google Lighthouse configuration options
->.config.extends string lighthouse:default What options to default to
->.config.logLevel string warn Level of logging
->.config.chromeFlags array<string> [ '--headless', '--disable-gpu', '--no-sandbox' ] Array of CLI arguments
->.config.settings LighthouseSettings See Defaults Settings applied to Lighthouse
->.validate hash<string> Zero or more validators
->.validate.{groupName} string Path of validation module used to determine if the response is coming from the intended server. Useful in cases where you only want to measure results coming from an intended infrastructure
->.concurrency number 1 Number of concurrently processed tasks permitted
->.report bool true Save the full report, viewable in LH viewer
->.samples After N lighthouse samples are taken, only the best result is recorded
->.samples.default number 3 Default number of lighthouse tests performed
->.samples.range tuple<min,max> [1, 5] Minimum and maximum samples taken before returning result
->.attempts Number of attempts at running Google Lighthouse before giving up due to failures
->.attempts.default number 2 Default number of attempts before giving up
->.attempts.range tuple<min,max> [1, 10] Minimum and maximum attempts before giving up
->.attempts.delayMsPerExponent number 1000 Exponential backoff after failure
->.delay Time (in ms) before a test is executed
->.delay.default number 0 Default time to wait before test can be run
->.delay.range tuple<min,max> [0, 1000 * 60 * 60] Minimum and maximum time before test can be run
->.delay.delayMsPerExponent number 1000 * 30 Maximum time before delayed messages will be requeued


API - GET /api/website

Fetch zero or more website results matching the criteria.

Query String Options

Option Type Default Desc
format string json Format of results, be it json, svg, reportHtml, or reportJson
scale number 1 Scale of svg
q string optional Query by URL or document ID
top number 1 Maximum records to return. Only applicable for json format

API - GET /api/website/compare

Similar to the single website GET, but instead compares results from q1 with q2.

Query String Options

Option Type Default Desc
format string json Format of results, be it json or svg
scale number 1 Scale of svg
q1 string required First query by URL or document ID
q2 string required Second query by URL or document ID

API - POST /api/website

Submit to process website with Google Lighthouse.

JSON Body Options

Option Type Default Desc
url string required URL to process via Google Lighthouse
wait number optional Block returning until job is complete, or the wait time (in ms) has elapsed, resulting in a partial 206 response
headers hash<string> optional Collection of HTTP headers to supply in request
secureHeaders hash optional Same use as headers, but stored securely in queue, and never persisted to ElasticSearch
samples number (See options.lighthouse.samples) Number of samples to take before recording result
attempts number (See options.lighthouse.attempts) Number of failure attempts before giving up
hostOverride string optional Map host of request to an explicit IP. Not yet supported by Chrome in Headless mode
delay number (See options.lighthouse.delay) Delay (in milliseconds) before test will be performed. Useful if the intended service or domain is not expected to be available for some time
group string unknown Group to categorize result to. Useful when searching/filtering on different groups of results
report bool true If the full report should be stored, allowing for viewing in LH Viewer
auditMode false|'simple'|'details'|'all' 'simple' How much of the audits data to persist to storage
cookies array<{name=string|Cookie}> optional Auto-translates cookies to set to the required commands
cookies[idx].value string required Value to set for cookie
cookies[idx].domain string optional Domain to apply cookie to. Defaults to root of requestedUrl domain
cookies[idx].url string optional If the page required to apply cookie to differs from the requestedUrl you can set that here
cookies[idx].path string optional Path to apply to cookie
cookies[idx].secure boolean optional Is cookie secured
cookies[idx].httpOnly boolean optional HTTP only
commands array<Commmand> optional DevTool Commands to be executed prior to running Lighthouse
commands[idx].command string required DevTool Command to execute
commands[idx].options object required DevTool Command Options to supply command
meta object optional Object containing metadata that will be attached to final lighthouse results


Storage Clients

  • AWS S3 - Store and basic query support via S3 buckets.
  • File System - Not recommended for production usage. Good for local testing.
  • Elasticsearch - Store and query support via Elasticsearch.

Queue Clients

  • AWS SQS - Support for Simple Queue Service.
  • AMQP - Support for RabbitMQ and other AMQP compatible queues.

Secure Configuration

Optionally you may run LH4U with the --secure-config {secureConfigPath} and --secure-file {securePrivateFile} powered by Config Shield.

npm i -g config-shield
cshield ./app/config/secure some-private.key
> help
> set queue { options: { url: 'amqp://' } }
> get queue
: { "options": { "url": "amqp://" } }
> save
> exit

The example above will allow you to merge sensitive credentials with your existing public configuration. Only options defined in the secure config will be deeply merged.