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 a folder for each desired project inside
public/stackscan/. - Each folder should contain a
package.jsonfile.
- Place a folder for each desired project 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 public/stackscan/ (e.g., public/stackscan/my-project/), handling name collisions automatically.
This will:
- Scan all projects in
public/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 brandWhen hosting package.json files for analysis, security tools like Dependabot may incorrectly flag them as vulnerable dependencies of your project.
To prevent this, StackScan will automatically rename any package.json found in public/stackscan/ to _package.json.
- Dependabot ignores
_package.json. - StackScan prioritizes reading
_package.jsonon future runs.
For each project in public/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.
Special thanks to these amazing icon libraries that make StackScan possible:
- Simple Icons – The primary source for brand logos and hex colors.
- Lucide – Provides the beautiful category fallback icons.
MIT