https://github.com/foo-software/binoculars
A tool to measure web page SEO friendliness
https://github.com/foo-software/binoculars
Last synced: 9 months ago
JSON representation
A tool to measure web page SEO friendliness
- Host: GitHub
- URL: https://github.com/foo-software/binoculars
- Owner: foo-software
- License: mit
- Created: 2020-08-17T00:53:38.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-12-28T18:37:35.000Z (about 5 years ago)
- Last Synced: 2025-04-20T13:19:18.303Z (9 months ago)
- Language: TypeScript
- Size: 2.22 MB
- Stars: 7
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `@foo-software/binoculars`
A tool to measure web page SEO friendliness. Binoculars extends [Google's Lighthouse](https://github.com/GoogleChrome/lighthouse) to provide a more opinionated, SEO specific audit.
- Choice of programmatic usage or CLI.
- Run a single audit or multiple audits at once.
- Upload reports to S3 via simple configuration.
- Automatically post results as comments in GitHub via commits or pull requests (see [options](#options)).
- Automatically post results in Slack (see [options](#options)).
# Meaningful Content
Binoculars extends Lighthouse by adding the following audits in a custom group named "Meaningful Content".
- **Title Length**: Title should be between 50 - 70 characters.
- **Description Length**: Descriptions should be between 100 - 160 characters.
- **Keywords**: Keyword phrases of at least 2 words should exist in the title, description and at least twice in the content of the page.
- **Headings**: Has at least 1 `
` tag and 1 `` tag.
- **Meaningful Text**: Has sufficient textual content (300 characters).
- **Meaningful Tag Structure**: Has at least 2 different informational HTML tags of the following types: `
`, `
# Metrics
Binoculars accounts for metrics from Lighthouse SEO and accessibility categories and weights them accordingly. It combines metrics from these categories with the "Meaningful Content" group detailed above. See the complete list of audits and weighting [here](src/config/auditRefsConfig.ts).
# Usage
Use programmatically or via CLI.
```
npm i @foo-software/binoculars
```
or
```
yarn @foo-software/binoculars
```
## Programmatic Usage
```javascript
const path = require('path');
const binoculars = require('@foo-software/binoculars').default;
(async () => {
const results = await binoculars({
url: 'https://www.foo.software',
// example if you have an "artifacts" directory in your root directory
outputDirectory: path.resolve('./artifacts'),
// any other options go here
});
console.log('local report', results[0].localReport);
// local report ./reports/report-1602194942162.html
console.log('score', results[0].result.categories.binocularsSeo.score);
// score 0.96
})();
```
## CLI Usage
Arguments are represented in the [options section](#options). Any array type relies on the pipe symbol as shown with `urls` in the second example below.
```bash
binoculars --url https://www.foo.software --outputDirectory ./artifacts
```
Use a `|` when auditing multiple URLs like so:
```bash
binoculars --urls "https://www.foo.software|https://www.foo.software/register"
```
# Options
Name
Description
Type
Default
Required
author
For Slack notifications: A user handle, typically from GitHub.
string
undefined
no
awsAccessKeyId
The AWS accessKeyId for an S3 bucket.
string
undefined
no
awsBucket
The AWS Bucket for an S3 bucket.
string
undefined
no
awsRegion
The AWS region for an S3 bucket.
string
undefined
no
awsSecretAccessKey
The AWS secretAccessKey for an S3 bucket.
string
undefined
no
branch
For Slack notifications: A version control branch, typically from GitHub.
string
undefined
no
commentAccessToken
Access token of a user to post PR comments.
string
undefined
no
commentUrl
An endpoint to post comments to. Typically this will be from GitHub's API. Example: https://api.github.com/repos/:owner/:repo/pulls/:pull_number/reviews
string
undefined
no
enableComments
If true and commentAccessToken is set along with commentUrl, scores will be posted as comments.
boolean
true
no
finalScreenshotAwsBucket
The AWS Bucket for an S3 bucket. If this is defined, the final screenshot will be uploaded here
string
undefined
no
minScore
The required minimum score. If score is lower an error will throw.
number
undefined
no
outputDirectory
An absolute directory path to output report. You can do this an an alternative or combined with an S3 upload.
string
undefined
no
pr
For Slack notifications: A version control pull request URL, typically from GitHub.
string
undefined
no
slackWebhookUrl
A Slack Incoming Webhook URL to send notifications to.
string
undefined
no
sha
For Slack notifications: A version control sha, typically from GitHub.
string
undefined
no
url
A URL to run Binoculars against.
string
undefined
yes
urls
An array of URLs. In the CLI this value should be a pipe separated list (|).
string[]
undefined
yes
# Return Payload
`binoculars` is a promise that resolves an array. The reason it resolves with an array is because options allow `url` or `urls`. Because a consistent return is ideal, we return an array regardless if there is only one result or more. Each array item is an object with the below payload.
Name
Description
Type
finalScreenshot
A URL to the final screenshot image. This will only be defined if finalScreenshotAwsBucket parameter was.
string
localReport
A local path to the report (if applicable).
string
result
A comprehensive result - the equivalent of what is returned when using the lighthouse module directly.
object
report
A URL to the report HTML file.
string
# Environment Variables
You can optionally provide environment variables as detailed below.
Name
Description
Type
Default
BINOCULARS_CHROME_PORT
The port for Chrome to run audits on.
number
4000
BINOCULARS_INTEGRATION_SERVER_DOMAIN
Domain of the integration server.
string
localhost
BINOCULARS_INTEGRATION_SERVER_PORT
Port to run the integration server on.
number
3000
BINOCULARS_INTEGRATION_SERVER_PROTOCOL
Protocol of the integration server.
string
http
LOG_LEVEL
The Winston log level (use "off" to run without logging).
string
info
## Credits
> 
This package was brought to you by [Foo - a website quality monitoring tool](https://www.foo.software). Automatically test and monitor website performance, SEO and accessibility with Lighthouse. Analyze historical records of Lighthouse tests with automated monitoring. Report with confidence about SEO and performance improvements to stay on top of changes when they happen!