devstack-detect

Instantly analyze any project folder and detect its full technology stack — frameworks, databases, languages, styling, auth, testing, build tools, and more.

Why devstack-detect?

• Onboarding — Understand an unfamiliar codebase in seconds
• Auditing — Document the tech stack across many repos at once
• CI/CD — Gate pipelines on detected stack requirements
• Monorepo support — Detects and reports per sub-project automatically

Installation

Global install (recommended)

npm install -g devstack-detect
devstack-detect ./my-project

One-shot with npx (no install required)

npx devstack-detect ./my-project

Local dev / contribution

git clone https://github.com/you/devstack-detect.git
cd devstack-detect
npm install
npm link                        # makes `devstack-detect` available globally
devstack-detect ./test-projects/mern-test

CLI Commands

# Default — colored terminal output
devstack-detect ./project

# JSON output to stdout (pipe-friendly)
devstack-detect ./project --json

# Save JSON report to a file (also prints to terminal)
devstack-detect ./project --output report.json

# Verbose — show which files triggered each detection
devstack-detect ./project --verbose

# CI mode — exits with code 1 if nothing is detected
devstack-detect ./project --ci

# Show tool version
devstack-detect --version

Example Output

═══════════════════════════════════════════════════
  DEVSTACK REPORT — ./my-project
═══════════════════════════════════════════════════

  Package Manager:  npm

  Frontend:
  ✔ React (v18.2.0)
  ✔ Next.js (v14.0.0)

  Backend:
  ✔ Express.js (v4.18.2)

  Database:
  ✔ MongoDB
  ~ PostgreSQL (possible)

  ORM:
  ✔ Mongoose (v8.0.0)
  ✔ Prisma (v5.6.0)

  Styling:
  ✔ TailwindCSS (v3.4.0)

  Auth:
  ✔ JWT
  ✔ NextAuth

  Testing:
  ✔ Jest (v29.7.0)
  ✔ Cypress (v13.6.0)

  Build Tools:
  ✔ Vite (v5.0.0)

  Language:
  ✔ TypeScript (v5.2.0)

═══════════════════════════════════════════════════
  Detected 12 technologies | Confidence: High
═══════════════════════════════════════════════════

Monorepo output

  [frontend/]
  ✔ React, Next.js, TailwindCSS, TypeScript

  [backend/]
  ✔ Express.js, MongoDB, JWT, TypeScript

Verbose mode

  Frontend:
  ✔ React (v18.2.0)
       [strong] package.json dependency: react
       [weak]   .jsx/.tsx files found (12) → src/App.tsx
       [weak]   React hooks usage in source → src/App.tsx

Detection Coverage

| Category | Technologies Detected | |----------------|---------------------------------------------------------------------| | Frontend | React, Vue, Angular, Svelte, Next.js, Nuxt.js | | Backend | Express.js, Fastify, NestJS, Koa | | Database | MongoDB, PostgreSQL, MySQL, Redis, SQLite | | ORM | Prisma, Mongoose, TypeORM, Sequelize, Drizzle | | Styling | TailwindCSS, styled-components, Sass/SCSS, CSS Modules | | Auth | JWT, Passport.js, Auth0, NextAuth | | Testing | Jest, Vitest, Mocha, Cypress, Playwright | | Build Tools | Vite, Webpack, Rollup, esbuild, Turbopack | | Package Manager| npm, Yarn, pnpm | | Language | TypeScript, JavaScript (ES Modules), JavaScript (CommonJS) |

Detection Strategy

For each technology, signals are collected in priority order:

1. package.json dependencies — strongest signal (weight: 2)
2. Config files — tsconfig.json, tailwind.config.js, jest.config.js, prisma/schema.prisma, etc. (weight: 2)
3. Lock files — yarn.lock, pnpm-lock.yaml, package-lock.json (weight: 2)
4. .env files — DATABASE_URL=mongodb://, JWT_SECRET, etc. (weight: 2)
5. Import/require statements — in source files (weight: 1)
6. Code pattern matching — mongoose.connect(), jwt.sign(), etc. (weight: 1)

Confidence levels

| Symbol | Meaning | Rule | |--------|-----------|-------------------------------| | ✔ | Detected | Total signal weight ≥ 2 | | ~ | Possible | Total signal weight = 1 |

A single weak pattern match alone never produces a ✔.

Monorepo Support

devstack-detect automatically detects monorepos by scanning for multiple package.json files. Each sub-project is reported independently with a label based on its directory path relative to the root.

my-monorepo/
├── frontend/package.json   → reported as [frontend/]
├── backend/package.json    → reported as [backend/]
└── packages/
    └── api/package.json    → reported as [packages/api/]

JSON Output

devstack-detect ./project --json

[
  {
    "label": "root",
    "projectPath": "/absolute/path/to/project",
    "totalDetected": 10,
    "stacks": {
      "frontend": [
        {
          "name": "React",
          "confidence": "detected",
          "version": "^18.2.0",
          "signals": [
            { "strength": "strong", "source": "package.json dependency: react" }
          ]
        }
      ]
    }
  }
]

GitHub Actions Usage

name: Stack Audit

on: [push, pull_request]

jobs:
  detect-stack:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run devstack-detect
        run: npx devstack-detect . --output stack-report.json --ci

      - name: Upload stack report
        uses: actions/upload-artifact@v4
        with:
          name: stack-report
          path: stack-report.json

The --ci flag causes the action to fail if no technologies are detected, useful for verifying new repos have a recognizable stack.

Local Testing

# Install dependencies
npm install

# Link globally for local testing
npm link

# Run against the built-in test projects
devstack-detect ./test-projects/react-test
devstack-detect ./test-projects/express-test
devstack-detect ./test-projects/mern-test

# Verbose mode to inspect signals
devstack-detect ./test-projects/mern-test --verbose

# JSON output
devstack-detect ./test-projects/mern-test --json

# Unlink when done
npm unlink -g devstack-detect

Publishing to npm

# 1. Make sure you are logged in
npm login

# 2. Bump the version
npm version patch   # or minor / major

# 3. Publish
npm publish --access public

How to Add a New Detector

Adding support for a new technology takes one file:

1. Create src/detectors/my-tech.js

import { buildDetection } from '../confidence.js';

function hasDep(packageJson, name) {
  if (!packageJson) return false;
  return name in (packageJson.dependencies || {}) ||
         name in (packageJson.devDependencies || {});
}

export function detect(files, packageJson) {
  const signals = [];

  // Strong signal — dependency in package.json
  if (hasDep(packageJson, 'my-tech')) {
    signals.push({ strength: 'strong', source: 'package.json dependency: my-tech' });
  }

  // Strong signal — config file
  const config = files.find(f => f.name === 'my-tech.config.js');
  if (config) {
    signals.push({ strength: 'strong', source: 'my-tech.config.js exists', file: config.relativePath });
  }

  // Weak signal — code pattern
  const usageFiles = files.filter(f => f.content && /myTech\.init\(/.test(f.content));
  if (usageFiles.length > 0) {
    signals.push({ strength: 'weak', source: 'myTech.init() in source', file: usageFiles[0].relativePath });
  }

  return [buildDetection('MyTech', signals, null)].filter(Boolean);
}

2. Register it in src/analyzer.js

import { detect as detectMyTech } from './detectors/my-tech.js';

// Inside analyzeProject():
const stacks = {
  // ...existing detectors...
  myTech: detectMyTech(files, packageJson),
};

3. Render it in src/formatter.js

renderSection('My Tech', stacks.myTech, verbose);

That's it. The confidence scoring, signal tracking, and JSON output work automatically.

Requirements

• Node.js v18.0.0 or higher
• npm v7+ (for npx support)

Roadmap

Future detectors planned:

• Django, Flask (Python)
• Laravel, Symfony (PHP)
• Spring Boot (Java)
• Docker / Kubernetes
• GraphQL, tRPC
• Supabase, Firebase
• Cloudflare Workers
• Astro, SolidJS, Remix
• Bun, Deno runtimes

License

MIT © devstack-detect contributors