How to use the command "lighthouse" (with examples)

The lighthouse command is a powerful tool for analyzing web applications and web pages. It collects modern performance metrics and provides insights on developer best practices. With lighthouse, developers can generate reports in various formats and configure specific settings to suit their needs.

Use case 1: Generate an HTML report for a specific website and save it to a file in the current directory

Code:

lighthouse https://example.com

Motivation: When analyzing a specific website, generating an HTML report can be useful for sharing and reviewing the results with others. By saving the report to a file in the current directory, it can be easily accessed and distributed.

Explanation:

• lighthouse: The command itself.
• https://example.com: The website URL for analysis.

Example output: The command will generate an HTML report for https://example.com and display the results in the terminal. The report can also be accessed by opening the generated HTML file in the current directory.

Use case 2: Generate a JSON report and print it

Code:

lighthouse --output json https://example.com

Motivation: JSON reports offer a structured and machine-readable format, making it easy to parse and integrate with other tools or systems. Printing the JSON report allows developers to quickly view the results in the terminal.

Explanation:

• --output json: Specifies the output format as JSON.
• https://example.com: The website URL for analysis.

Example output: The command will generate a JSON report for https://example.com and print the results in the terminal.

Use case 3: Generate a JSON report and save it to a specific file

Code:

lighthouse --output json --output-path path/to/file.json https://example.com

Motivation: Saving the JSON report to a specific file enables developers to easily store, share, or process the results at a later time. This is particularly useful when conducting regular performance audits or integrating the reports into automated workflows.

Explanation:

• --output json: Specifies the output format as JSON.
• --output-path path/to/file.json: Specifies the file path where the JSON report will be saved.
• https://example.com: The website URL for analysis.

Example output: The command will generate a JSON report for https://example.com and save it to the specified file path (path/to/file.json).

Use case 4: Generate a report using the browser in headless mode without logging to stdout

Code:

lighthouse --quiet --chrome-flags="--headless" https://example.com

Motivation: Running lighthouse in a headless mode (without a visible browser) is useful for automation purposes. By suppressing logging to stdout using the --quiet flag, the command becomes more suitable for running in scripts or as part of build pipelines.

Explanation:

• --quiet: Prevents logging to stdout.
• --chrome-flags="--headless": Provides custom flags for the underlying Chrome browser, in this case, allowing it to run in headless mode.
• https://example.com: The website URL for analysis.

Example output: The command will generate a report for https://example.com using the browser in headless mode. However, since the --quiet flag is used, no logging information will be displayed in the terminal.

Use case 5: Generate a report, using the HTTP header key/value pairs in the specified JSON file for all requests

Code:

lighthouse --extra-headers=path/to/file.json https://example.com

Motivation: Specifying custom HTTP headers for requests can help simulate specific scenarios, such as passing authentication tokens or manipulating requests for testing purposes. By referencing a JSON file with header key/value pairs, developers can easily configure and reuse complex sets of headers.

Explanation:

• --extra-headers=path/to/file.json: Specifies the path to a JSON file containing HTTP header key/value pairs.
• https://example.com: The website URL for analysis.

Example output: The command will generate a report for https://example.com while including the specified additional headers from the JSON file.

Use case 6: Generate a report for specific categories only

Code:

lighthouse --only-categories=performance,accessibility,best-practices,seo,pwa https://example.com

Motivation: When analyzing web applications, it can be beneficial to focus on specific categories of performance metrics and best practices. By specifying the desired categories, developers can receive more targeted insights and recommendations, making it easier to prioritize optimizations.

Explanation:

• --only-categories=performance,accessibility,best-practices,seo,pwa: Specifies the categories of metrics and best practices to include in the report.
• https://example.com: The website URL for analysis.

Example output: The command will generate a report for https://example.com that only includes the specified categories: performance, accessibility, best practices, SEO, and Progressive Web App (PWA) metrics.

Use case 7: Generate a report with device emulation and all throttling disabled

Code:

lighthouse --screenEmulation.disabled --throttling-method=provided --no-emulatedUserAgent https://example.com

Motivation: Simulating different devices and network conditions is essential for understanding how a web application performs under real-world scenarios. By disabling screen emulation, throttling, and the emulated user agent in lighthouse, developers can analyze the website’s raw performance without artificial constraints.

Explanation:

• --screenEmulation.disabled: Disables device screen emulation.
• --throttling-method=provided: Disables network throttling.
• --no-emulatedUserAgent: Disables emulating a user agent.
• https://example.com: The website URL for analysis.

Example output: The command will generate a report for https://example.com while disabling device emulation, network throttling, and the emulated user agent. The report will provide insights into the website’s performance under ideal conditions.

Use case 8: Display help

Code:

lighthouse --help

Motivation: When first starting with the lighthouse command or when in need of a quick reference, displaying the help information can provide guidance on available options and command usage.

Explanation:

• --help: Displays the command’s help information.

Example output: The command will display the lighthouse command’s help information, which includes available options and usage examples.

Conclusion:

The lighthouse command offers a range of powerful features for analyzing web applications and web pages. By providing various output formats, configuration options, and performance settings, developers can generate detailed reports tailored to their specific needs. Whether it’s analyzing specific categories, saving reports in different formats, or simulating real-world conditions, lighthouse is an invaluable tool for improving web application performance and adhering to best practices.