psi-svg
v1.0.9
Published
Generates a SVG of a given url's PageSpeed Insights statistics via a http endpoint or a cli command.
Downloads
34
Maintainers
Readme
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)
- Clone the repository
git clone https://www.github.com/nico-i/psi-svg
- Build the image
docker build -t psi-svg .
- 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.