Unofficial lighthouserc.yml schema

lighthouserc.schema.yml

$schema: https://json-schema.org/draft/2020-12/schema
title: .lighthouserc
description: Lighthouse CI configuration JSON schema. Reference: https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md
type: object
properties:
  ci:
    type: object
    properties:
      collect:
        type: object
        properties:
          method:
            enum:
              - node
              - psi
            default: node
            description: "The method used to run Lighthouse. There are currently two options available, \"node\" which runs Lighthouse locally via node, and \"psi\" which runs Lighthouse by making a request to the PageSpeed Insights API.\n\nThe PageSpeed Insights method has the major limitation that only sites publicly available over the internet can be tested and no other collection options will be respected."
          headful:
            type: boolean
            default: false
            description: "Boolean that controls whether Chrome is launched in headless or headful mode. This flag does not apply when using puppeteerScript."
          additive:
            type: boolean
            default: false
            description: "Boolean that controls whether the .lighthouseci directory is cleared before starting. By default, this directory is cleared on every invocation of lhci collect to start fresh."
          url:
            type: array
            items:
              type: string
            description: "An array of the URLs that you'd like Lighthouse CI to collect results from.\n\nWhen used with staticDistDir:\n\nAutomatic detection of URLs based on HTML files on disk will be disabled.\nURLs will have their port replaced with the port of the local server that Lighthouse CI starts for you. This allows you to write URLs as http://localhost/my-static-page.html without worrying about the chosen temporary port.\nWhen used without staticDistDir:\n\nURLs will be used as-is without modification."
          staticDistDir:
            type: string
            description: "The path to the directory where the project's productionized static assets are kept. Lighthouse CI uses this to spin up a static server on your behalf that will be used to load your site.\n\nUse this option when the project is a static website to be hosted locally that does not require a separate server. DO NOT use this option if url will point to an origin that isn't localhost or the project uses startServerCommand to start a separate server."
          isSinglePageApplication:
            type: boolean
            default: false
            description: "Boolean that controls whether the static server started in staticDistDir should act like a single-page application that serves index.html instead of a 404 for unrecognized paths. This flag has no function when staticDistDir is not set."
          chromePath:
            type: string
            description: "The path of the Chrome executable to use for puppeteerScript and running Lighthouse. Lighthouse CI will use Chrome installations in the following priority order:\n\nchromePath option\nCHROME_PATH Environment Variable\nExecutable path returned by puppeteer or puppeteer-core, if installed.\nHighest priority installation returned by the chrome-launcher npm package."
          puppeteerScript:
            type: string
            description: "An optional path to a JavaScript file that exports a function that uses puppeteer to login to your page, setup cache data, or otherwise manipulate the browser before Lighthouse is run."
          puppeteerLaunchOptions:
            type: string
            description: "An object of options to pass to puppeteer's launch method. Only used when puppeterScript is set."
          psiApiKey:
            type: string
            description: "The API key to use for making PageSpeed Insights requests. Required if using method=psi. You can obtain a PSI API key from Google APIs."
          psiApiEndpoint:
            type: string
            description: "The API endpoint to hit for making a PageSpeed Insights request. It is very unlikely you should need to use this option. Only use this if you have self-hosted a custom version of the PSI API."
          psiStrategy:
            enum:
              - mobile
              - desktop
            default: mobile
            description: "Use this option to change the strategy to use for PageSpeed Insights runner method. Use mobile or desktop. The default value is mobile."
          startServerCommand:
            type: string
            description: "The shell command to use to start the project's webserver. LHCI will use this command to start the server before loading the urls and automatically shut it down once collection is complete.\n\nUse this option when your project requires a special webserver. DO NOT use this option when your project is just a collection of static assets. Use staticDistDir instead to use the built-in static server."
          startServerReadyPattern:
            type: string
            description: "The regex pattern to look for in the server command's output before considering the server ready for requests. Only used when startServerCommand is set.\n\nFor example, when using the default listen|ready, Lighthouse would start collecting results once the the startServerCommand process printed Listening on port 1337 to stdout."
          startServerReadyTimeout:
            type: string
            description: "The maximum amount of time in milliseconds to wait for startServerCommand to print the startServerReadyPattern before continuing anyway. Only used when startServerCommand is set."
          settings:
            type: object
            description: "The Lighthouse CLI flags to pass along to Lighthouse. This can be used to change configuration of Lighthouse itself. See Lighthouse documentation on custom configs for more."
          numberOfRuns:
            type: number
            default: 1
            multipleOf: 1
            minimum: 1
        dependentRequired:
          puppeteerLaunchOptions:
            - puppeteerScript
          startServerReadyPattern:
            - startServerCommand
          startServerReadyTimeout:
            - startServerCommand
      assert:
        type: object
        properties:
          assertions:
            type: object
            default:
              aggregationMethod: optimistic
              minScore: 1
            description: "The result of any audit in Lighthouse can be asserted. Assertions are keyed by the Lighthouse audit ID and follow an eslint-style format of level | [level, options]. For a reference of the audit IDs in each category, you can take a look at the default Lighthouse config. When no options are set, the default options of {\"aggregationMethod\": \"optimistic\", \"minScore\": 1} are used."
          assertMatrix:
            type: array
            items:
              type: object
              properties:
                matchingUrlPattern:
                  type: string
                assertions:
                  type: object
              required:
                - matchingUrlPattern
                - assertions
            description: "assertMatrix can be used to assert against multiple URLs at the same time. When checking the results of runs against multiple URLs, different assertions can be made for different URL patterns."
          preset:
            enum:
              - lighthouse:all
              - lighthouse:recommended
              - lighthouse:no-pwa
            description: "There are three presets available to provide a good starting point. Presets can be extended with manual assertions.\n\nlighthouse:all - Asserts that every audit received a perfect score. This is extremely difficult to do. Only use as a base on very high quality, greenfield projects and lower the thresholds as needed.\nlighthouse:recommended - Asserts that every audit outside performance received a perfect score, that no resources were flagged for performance opportunities, and warns when metric values drop below a score of 90. This is a more realistic base that disables hard failures for flaky audits.\nlighthouse:no-pwa - lighthouse:recommended but without any of the PWA audits enabled."
          budgetsFile:
            type: string
            description: "Instead of configuring using Lighthouse CI assertions against Lighthouse audits, a budget.json file can be used instead. This option cannot be used in conjunction with any other assert option."
          includePassedAssertions:
            type: boolean
            default: false
            description: "Boolean that controls whether passed assertions should be included in the output. Only assertions that didn't pass are shown normally."
    upload:
      type: object
      properties:
        target:
          enum:
            - lhci
            - temporary-public-storage
            - filesystem
          default: lhci
          description: "The target location to which Lighthouse CI should upload the reports.\n\ndefault: lhci"
        token:
          type: string
          description: "The build token for your Lighthouse CI project. Required when using target=lhci. This token should be given to you by lhci wizard --wizard=new-project. If you've forgotten your token, connect directly to your server and run lhci wizard --wizard=reset-build-token.\n\n"
        ignoreDuplicateBuildFailure:
          type: boolean
          default: false
          description: "Boolean that controls whether upload failures due to duplicate build hashes should be ignored. The build token only allows the creation of data on the server and not the editing or destruction of data on the LHCI server. When the CLI attempts to upload a Lighthouse report for a hash that already exists, the server will reject it.\n\nUse this option when you don't run Lighthouse CI as the last step of your CI process or reruns are common."
        githubToken:
          type: string
          description: "The GitHub token to use when setting a status check on a GitHub PR. Use this when the project is hosted on GitHub and not using the official GitHub App."
        githubApiHost:
          type: string
          description: "The GitHub API host to use when attempting to set a status check. Use this when the project is hosted on a private GitHub enterprise server and not using the public GitHub API."
        githubAppToken:
          type: string
          description: "The GitHub App token returned when installing the GitHub App. Use this to set status checks on GitHub PRs when using the official GitHub App."
        githubStatusContextSuffix:
          type: string
          description: "The suffix to use when setting the status check on a GitHub PR.\n\nFor example, by default lhci is used as the root of the status check label, but this can be configured to lhci-app by setting githubStatusContextSuffix to -app."
        extraHeaders:
          type: object
          description: "A map of additional headers to add the requests made to the LHCI server. Useful for adding bespoke auth tokens."
        basicAuth:
          type: object
          properties:
            username:
              type: string
            password:
              type: string
          required:
            - username
            - password
          description: "An object containing a username and password pair for authenticating with a Basic auth protected LHCI server. Use this setting when you've protected your LHCI server with Basic auth."
        serverBaseUrl:
          type: string
          description: "The base URL of the LHCI server to upload to. Required when using target=lhci."
        uploadUrlMap:
          type: boolean
          default: false
          description: "Boolean that controls whether to update the latest build in temporary public storage associated with this repo. If you use master as your default branch, DO NOT use this option. If you don't use master as your default branch, set this option when you upload results from your actual default branch."
        urlReplacementPatterns:
          type: array
          items:
            type: string
            pattern: "^s(.)(.*)\\1(.*)\\1([gim]*)$"
        outputDir:
          type: string
          description: "The directory relative to the current working directory in which to output a manifest.json along with the Lighthouse reports collected. Any existing manifest.json in that directory will be overwritten."
        reportFilenamePattern:
          type: string
          description: "The pattern to use for report filenames when writing the reports to the filesystem. Basic string interpolation is supported replacing %%HOSTNAME%% with the URL's hostname, %%PATHNAME%% with the page path, %%DATETIME%% with the ISO string of the UTC report generated timestamp, %%DATE%% with the ISO-style string of the UTC report generated date, %%EXTENSION%% with the extension of the file.\n\nIn the case of filename collisions between runs, the last written report wins and all others will be overwritten. Median reports are written to disk last."
      dependentRequired:
        lhci:
          - token
    server:
      type: object
      properties:
        port:
          type: number
          multipleOf: 1
          minimum: 0
          maximum: 65535
          description: "The port for the server to listen on. A value of 0 will use a random available port. https://nodejs.org/api/net.html#net_server_listen_port_host_backlog_callback"
        host:
          type: string
          description: "The host to bind the server to. The default is to use the unspecified IPv6 address (::) when IPv6 is available, or the unspecified IPv4 address (0.0.0.0) otherwise. To only accept connections on IPv4 use 0.0.0.0 as host."
        storage:
          type: object
          properties:
            sqlDialect:
              enum:
                - mysql
                - postgres
                - sqlite
              description: "One of mysql, postgres, or sqlite. sqlite in a local file on disk has been sufficient for most use cases."
            sqlDatabasePath:
              type: string
              description: "The path to the sqlite database on the local filesystem relative to the current working directory."
            sqlConnectionUrl:
              type: string
              description: "The database connection URL string for the MySQL or PostgreSQL database of the form <dialect>://<user>:<password>@<host>:<port>/<database>."
            sqlDangerouslyResetDatabase:
              type: boolean
              default: false
              description: "WARNING: this option will delete all data in the database\n\nBoolean flag useful during setup if things have gone wrong. This flag will reset the schema of all LHCI tables to factory fresh, deleting all data in the process."
            sequelizeOptions:
              description: "Additional raw options object to pass to sequelize. Refer to the sequelize documentation for more information on available settings."
            sqlMigrationOptions:
              type: object
              properties:
                tableName:
                  type: string
                  default: SequelizeMeta
                  description: "Use a different Sequelize table name. Default: SequelizeMeta. Refer to the sequelize migrations documentation for more information."

          }
        }
      }
      description: "Options that control how the historical Lighthouse data is stored. Currently only SQL-based storage mechanisms are supported."
    psiCollectCron:
      type: object
      properties:
        psiApiKey:
          type: string
          description: "The API key to use with the PSI API. You can obtain a PSI API Key by following the official documentation."
        sites:
          type: array
          items:
            type: object
            properties:
              urls:
                type: array
                items:
                  type: string
                description: "The array of sites to collect results for. This configuration will only be possible once the server has been setup and project have been created."
              schedule:
                type: string
                description: "The cron-style schedule on which to collect results."
              projectSlug:
                type: string
                description: "The unique slug identifier of the project in which results should be saved. The easiest way to tell the project slug is to open the project on the server and look at the URL bar."
              numberOfRuns:
                type: number
                default: 5
                minimum: 1
                multipleOf: 1
                description: "The number of reports to collect for each URL on each iteration of the schedule. Defaults to 5."
              label:
                type: string
                description: "The human-friendly label for this set of URLs to use when logging status to stdout/stderr. Not used for anything other than logging."
              branch:
                type: string
                description: "The \"branch\" on which to report the results. Defaults to the base branch of the project referenced by projectSlug."
            required:
              - urls
              - schedule
              - projectSlug
          description: "The array of sites to collect results for. This configuration will only be possible once the server has been setup and project have been created."
    deleteOldBuildsCron:
      type: array
      items:
        type: object
        properties:
          schedule:
            type: string
            description: "The cron-style schedule on which to collect results."
          maxAgeInDays:
            type: number
            multipleOf: 1
            minimum: 0
            description: "A number of days to keep a records."
          onlyBranches:
            type: array
            items:
              type: string
            description: "Array of branch names, which should be deleted."
          skipBranches:
            type: array
            items:
              type: string
            description: "Array of branch names, which should be excluded during cleanup."
        description: "The configuration to automatically delete old records. This job only works when storage.storageMethod is set sql. Might be an array of objects, or just a single object."
  wizard:
    type: object
    properties:
      extraHeaders:
        type: string
        description: "If you're running the lhci server behind a reverse proxy or any other component that requires some extra headers you can configure them in the wizard section extraHeaders."
      serverBaseUrl:
        type: string
        description: "If you're running the lhci wizard multiple times, you can configure a default serverBaseUrl to avoid typing it in at each lhci wizard run."