Automatically detect the tech stack of any project and generate structured output (JSON, Markdown, or badges).
Designed for portfolios, READMEs, dashboards, and CI automation.
StackScan scans a repository (dependencies + file structure), normalizes detected technologies into categories, and maps them to logos with sensible fallbacks.
- 🔍 Detect dependencies from
package.json - 🖼 Built-in SVG logos with graceful fallbacks
- 💾 Generate JSON, Markdown, and asset files
- 🎨 Support for Brand, White, Black, or Custom color modes
- 🤖 Automates Portfolio / Monorepo README updates
npx stackscan@latestnpm install -g stackscan
stackscan- Prepare Input:
- Place your project folders inside
stackscan/. - OR simply drop your
package.jsonfiles directly intostackscan/.- If you have multiple, you can name them
package (1).json,package (2).json, etc. - StackScan will automatically create folders based on the project name defined in each file.
- If you have multiple, you can name them
- Place your project folders inside
- Run Scan:
npx stackscan scanYou can also add a project from anywhere on your disk using the CLI. You can point to a package.json file OR a project directory:
# Point to a file
npx stackscan add ./path/to/package.json
# Point to a folder (automatically finds package.json)
npx stackscan add ../my-projectThis will copy the package.json into a new folder inside stackscan/ (e.g., stackscan/my-project/), handling name collisions automatically.
This will:
- Scan all projects in
stackscan/. - Generate
stack.jsonandstack.mdinside each project folder. - Copy logo assets to
public/assets/logos/. - Update your root
README.mdwith a "My Projects" section.
# Use white logos
npx stackscan scan --color white
# Use black logos
npx stackscan scan --color black
# Use brand colors (default)
npx stackscan scan --color brandFor each project in stackscan/, a stack.json is generated in the same folder.
Example stack.json:
[
{
"name": "TypeScript",
"slug": "typescript",
"logo": "https://raw.githubusercontent.com/benjamindotdev/stackscan/main/public/assets/logos/language/typescript.svg",
"relativePath": "public/assets/logos/language/typescript.svg",
"color": "#3178C6"
},
{
"name": "Next.js",
"slug": "next",
"logo": "https://raw.githubusercontent.com/benjamindotdev/stackscan/main/public/assets/logos/frameworks/nextjs.svg",
"relativePath": "public/assets/logos/frameworks/nextjs.svg",
"color": "#000000"
}
]Anything without a known logo still renders cleanly using category defaults (e.g. a lock icon for auth).
StackScan resolves logos in the following order:
- Built-in curated registry
- Known aliases (e.g.
next-auth→ Auth.js) - External icon registries (when available)
- Category fallback icon (e.g. auth → lock)
This guarantees usable output even when a logo is missing.
Use StackScan in CI to keep stack metadata up to date:
name: stackscan
on:
push:
branches: [ main ]
jobs:
stackscan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx stackscan scan- ❌ It does not execute or analyze runtime code
- ❌ It does not attempt to infer architectural quality
- ❌ It does not require network access to be useful
This keeps it fast, safe, and CI-friendly.
Contributions are welcome — especially:
- new detection rules
- logo mappings and aliases
- edge cases (monorepos, uncommon stacks)
See CONTRIBUTING.md for development workflow and guidelines.
MIT
---
### Final notes (important but quick)
- This README is **npm-ready** and **user-focused**
- Your internal branch/version automation should move to:
- `CONTRIBUTING.md` or `.github/`
- The tone is correct for a free, public dev tool:
*clear, confident, not over-marketed*
You’re genuinely at the “ship it” point.
If you want, next I can:
- tighten CLI flag descriptions to exactly match `commander`
- write `CONTRIBUTING.md`
- review your npm publish checklist line by line
