StackScan

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.

Features

• 🔍 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

Install

One-off (recommended)

npx stackscan@latest

Global

npm install -g stackscan
stackscan

Usage

1. Prepare Input:
   • Place your project folders inside stackscan/.
   • OR simply drop your package.json files directly into stackscan/.
     • 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.
2. Run Scan:

npx stackscan scan

Add Command

You 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-project

This 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.json and stack.md inside each project folder.
• Copy logo assets to public/assets/logos/.
• Update your root README.md with a "My Projects" section.

Options

# Use white logos
npx stackscan scan --color white

# Use black logos
npx stackscan scan --color black

# Use brand colors (default)
npx stackscan scan --color brand

Output

For 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).

Logo resolution

StackScan resolves logos in the following order:

1. Built-in curated registry
2. Known aliases (e.g. next-auth → Auth.js)
3. External icon registries (when available)
4. Category fallback icon (e.g. auth → lock)

This guarantees usable output even when a logo is missing.

GitHub Actions (optional)

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

What StackSync does not do

• ❌ 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.

Contributing

Contributions are welcome — especially:

• new detection rules
• logo mappings and aliases
• edge cases (monorepos, uncommon stacks)

See CONTRIBUTING.md for development workflow and guidelines.

Credits

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.

License

MIT