PageSpeed Insights SVG

This node module performs a Google PageSpeed Insights analysis on a given webpage and returns the result as an SVG.

Installation

npm

npm i -g psi-svg

bun

bun i -g psi-svg

yarn

yarn global add psi-svg

Usage

psi-svg can be used as a CLI tool or as a web server. Different options can be used to customize the output in both cases.

CLI

To use psi-svg in the CLI, install it and run it with the URL of the webpage to analyze and the path to the output SVG as arguments:

Example:

psi-svg https://www.example.com ./out.svg

Flags

The following flags can be used to customize the page speed analysis and the output:

| Flag | Description | Type | Default Value | | ---------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ | | --strategy or -s | On what type of device the site should be analyzed | desktop | mobile | mobile | | --categories or -c | The categories to include in the analysis (CSV) | performance | accessibility | best-practices | seo | pwa | performance, accessibility, best-practices, seo, pwa | | --legend or -l | Whether to include the legend in the SVG | true | false | true |

npx

psi-svg can also be run with npx:

npx psi-svg https://www.example.com ./out.svg

Server

To run the psi-svg web server, the --srv or -s flag can be set:

psi-svg -s

By default the server will listen on port 3000. To change this, the --port or -p option can also be set:

psi-svg -s -p 8080

After the server has been started, an insights SVG can be generated by sending a GET request to the server with the URL to analyze as a query parameter:

curl http://localhost:3000/?url=https://www.example.com > example-insights.svg

Query Parameters

The server accepts similar parameters as the CLI tool:

| Parameter | Description | Values | Default | | ------------ | -------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------ | | url | URL to the site to analyze | string | - | | strategy | See Flags | desktop | mobile | mobile | | categories | See Flags | performance | accessibility | best-practices | seo | pwa | performance, accessibility, best-practices, seo, pwa | | legend | See Flags | true | false | true |

This GET request for example

curl http://localhost:3000/?url=https://www.example.com\&strategy=desktop\&categories=performance,accessibility,seo\&legend=false > example-insights.svg

will return this SVG

Note: this analysis ran on the 17. November of 2023; the example page may have changed so the example SVG above may not be accurate anymore.

Environment Variables

The following environment variables can be used to customize the web server:

| Variable | Description | Values | Default | | ------------------ | ---------------------------------------------------------------------------------------------- | -------- | ------- | | DOMAIN_WHITELIST | A comma-separated list of domains to allow requests from. Currently does not support wildcards | string | - |

Setting the DOMAIN_WHITELIST environment variable to example.com for example will allow requests from https://example.com but not from https://example.org. This is especially useful when running the web server in a public environment.

Docker

The application can also be run as a Docker container by following the following steps: (requires docker to be installed)

1. Clone the repository

git clone https://www.github.com/nico-i/psi-svg

2. Build the image

docker build -t psi-svg .

3. Run the image

docker run -p 3000:3000 psi-svg

Github Actions

The application can also be run as a Github Action. An example workflow can be found in .github/workflows/pagespeed.yml. The results of which are visible in docs/img/. To use the action, simply copy the workflow file to your repository and modify the value of the URL_TO_ANALYZE and RESULTS_DIR variables. Also ensure that the Github Action Workers have write access to the repository. You can configure this under Settings > Code and automation > Actions > General > Workflow permissions.

Development

This project uses Node.js and Typescript for development. To get started, clone the repository and install the dependencies:

git clone https://www.github.com/nico-i/psi-svg
cd psi-svg
npm install

To run the application, use the following command:

npm run build && npm run start

This will start the web server on port 3000.

For development I recommend using the API testing tool bruno, which you can point to the /.bruno/ directory of this repo. It contains some helpful requests to test the application.

Credits

This project is based on ankurparihar's readme-pagespeed-insights.

This project improves the original project in the following ways:

• Added a CLI implementation
• Added Docker compatibility
• Removed unnecessary options which previously bloated the code
• Better SVG generation with individual SVG-files instead of inline SVG strings
• SVG styling CSS moved to an individual file to facilitate intellisense and linting
• Improved the file structure and code coupling with Domain Driven Design (DDD)
• Added the option to disable the legend
• Made Github action independent of running server
• Automated unit tests

License

See LICENSE.