{"id":36541699,"url":"https://github.com/paceaux/selector-finder","last_synced_at":"2026-01-12T05:47:33.802Z","repository":{"id":53849792,"uuid":"327616368","full_name":"paceaux/selector-finder","owner":"paceaux","description":"Find a CSS selector on a public site","archived":false,"fork":false,"pushed_at":"2025-10-20T14:40:09.000Z","size":900,"stargazers_count":25,"open_issues_count":10,"forks_count":2,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-10-20T16:32:47.525Z","etag":null,"topics":["crawler","css","javascript","nodejs","screenshots","selector-finder"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paceaux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["paceaux"]}},"created_at":"2021-01-07T13:13:46.000Z","updated_at":"2025-09-04T02:20:27.000Z","dependencies_parsed_at":"2024-11-26T20:35:45.065Z","dependency_job_id":null,"html_url":"https://github.com/paceaux/selector-finder","commit_stats":{"total_commits":121,"total_committers":3,"mean_commits":"40.333333333333336","dds":0.1322314049586777,"last_synced_commit":"c5d0d3e928aedba0afb86f79083d454b844545bf"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/paceaux/selector-finder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paceaux%2Fselector-finder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paceaux%2Fselector-finder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paceaux%2Fselector-finder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paceaux%2Fselector-finder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paceaux","download_url":"https://codeload.github.com/paceaux/selector-finder/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paceaux%2Fselector-finder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28335264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crawler","css","javascript","nodejs","screenshots","selector-finder"],"created_at":"2026-01-12T05:47:33.725Z","updated_at":"2026-01-12T05:47:33.786Z","avatar_url":"https://github.com/paceaux.png","language":"JavaScript","funding_links":["https://github.com/sponsors/paceaux"],"categories":[],"sub_categories":[],"readme":"# Selector Hound: sniff out CSS Selectors on a site\n\n`SelectorHound` lets you find CSS selectors on a public or local site. Rename, refactor, and delete unused CSS with a bloodhound on your side.\n\nA sitemap or a site URL is enough to get started. Provide a single CSS selector, a comma separated string of selectors, or even a stylesheet.\n\nPages with _zero_ matches aren't put in the results. Pages with at least _one_ match are in the result, and you find out which CSS selectors _aren't_ used. (That's right, it's a selector _finder_ **and** ... \"not founder\").\n\nOptionally take a screenshot of the elements (though it may hurt performance).\n\nPages not showing up that should? Check the `log.txt` for any issues.\n\n## Installation\n\n### Prerequisites\n\n- Node LTS (as of August 2024, Node 20.16.0)\n\n#### Some possible Puppeteer setup for Mac Users\n\nIf you want to use the `-d` or `-c` (`--isSpa` and `--takeScreenshots` ) options, this requires Puppeteer which in turn requires Chromium.\n\nYou may (or may not) need `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true` and `PUPPETEER_EXECUTABLE_PATH` environment variables set. They were necessary for older versions of Puppeteer and seem to be unnecessary for new ones.\n\nIf you're having issues, run `printenv` in your terminal to see if those variables are set. If they are, you may need to unset them with `unset PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` and `unset PUPPETEER_EXECUTABLE_PATH`. Then `source ~/.bashrc` or `source ~/.zshrc` to be sure, and run `printenv` once again.\n\nBut if they aren't set, you may need to do this.\n\nAfter you play with those variables, reinstall this package.\n\n### Running on-demand\n\nDownload this package. Then run\n\n```shell\nnpm install\n```\n\n### Globally via NPM\n\n```shell\nnpm i -g selector-hound\n```\n\n## Usage\n\n### Basic Scanning\n\nOnly scan the first 20 pages for `.yourthing`\n\n```shell\nSelectorHound --sitemap=https://wherever.com/xml --limit=20 --selector=\".yourthing\"\nSelectorHound -u https://wherever.com/xml -l 20 -s \".yourthing\"\n```\n\n### Re-using, regenerating, and providing a list of links\n\nBefore the site scanning begins, this generates a `\u003csite\u003e.sitemap.json` file containing all of the links it will scan. This file is generated from the `sitemap.xml` file you provided **or** from crawling the site looking for links. To improve performance, SelectorHound will look for this file _first_ before attempting to retrieve/generate a sitemap.\n\nIf you want to re-generate this `\u003csite\u003e.sitemap.json` file, you can force it:\n\n```shell\nSelectorHound --sitemap=https://wherever.com/xml  --selector=\".yourthing\" --dontUseExportedSitemap\nSelectorHound -u https://mysite.com/landing -r -s '.yourThing' -X\n```\n\n#### Formatting\n\nBy default, SelectorHound will generate a format that's based off of how sitemap XML looks, which is an array of objects with a `loc` property:\n\n```JavaScript\n[\n    {\n        'loc': 'https://mysite.com/path'\n    },\n    {\n        'loc': 'https://mysite.com/another'\n    }\n]\n```\n\nHowever, you can also provide your own list of links as just an array of strings:\n\n```JavaScript\n    [\n        \"https://mysite.com/path\",\n        \"https://mysite.com/another\"\n    ]\n```\n\n### Crawling instead of using a sitemap\n\nCrawl the site, starting from a landing page.\n\n```shell\nSelectorHound -u https://mysite.com/landing -r -s \".myClass\"\n```\n\n### Taking Screenshots or dealing with SPAs\n\nScan the first 20 pages and take screenshots\n\n```shell\nSelectorHound -u https://wherever.com/xml -l 20 -s \".yourthing\" -c\n```\n\nScan those pages, but treat them like Single Page Applications (`-d`), and search for all the selectors in `mystyles.css`\n\n```shell\nSelectorHound -u https://wherever.com/xml -f \"mystyles.css\" -d\n\n```\n\n### Options\n\n| Option | Alias | Description   | Defaults  |\n|---|---|---|---|\n| `--sitemap` |`-u`  | Must be fully qualified URL to an XML Sitemap **or** fully qualified URL to a page **if** `crawl` is `true`. Required. | `https://frankmtaylor.com/sitemap.xml` |\n| `--dontUseExportedSitemap` |`-X`  | if a `\u003csite\u003e.sitemap.json` file has been already been created, ignore it and generate a new one. Optional. | `false` |\n| `--limit` | `-l`  |  Maximum number of pages to crawl. Optional. | `0`  |\n| `--selector` | `-s`  |  A valid CSS selector. Required. |  `.title` |\n| `--cssFile` | `-f`  | A CSS file to use instead of a single selector. Optional. |   |\n| `--isSpa`| `-d`  | Uses Puppeteer instead of Cheerio (in case some content is dynamic). Optional. | `false`|\n| `--takeScreenshots`| `-c`  | Takes screenshots with Puppeteer. Optional. | `false` |\n| `--outputFileName` | `-o` | A provided value will be prepended to `pages.json` and will be output in your current directory. Оptional. | `pages.json` |\n| `--showElementDetails` | `-e`  | Show details for elements that match result (`tag`, `innerText`, `attributes`) . Optional. |   `false` |\n| `--showHtml` | `-m` | Shows HTML of the elements that match the result. Optional. | `true` |\n| `--crawl`| `-r` | Crawls the site instead of using a sitemap. Outputs a file called `\u003csitename\u003e.sitemap.json`. Optional.  | `false` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaceaux%2Fselector-finder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaceaux%2Fselector-finder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaceaux%2Fselector-finder/lists"}