node-project-scanner

Scan, analyze, run, and build Node.js / JavaScript projects — with smart port control.

Short command: nps

• Web dashboard (default) — open your whole workspace in the browser with health scores, analytics, and one-click run
• Terminal UI — a fast keyboard-driven picker when you stay in the terminal (nps tui)

Features

• Web dashboard — browser-based project analytics: scan overview, per-project health score, findings, and Run buttons for every script
• Terminal UI — projects list, summary, and detail panels with a grouped action menu (Run → Package → Tooling → Scripts)
• Fast recursive scan — discovers every package.json across monorepos, streaming results as it walks
• Auto-detects builders (Next.js, Vite, Nuxt, SvelteKit, Astro, Remix, Gatsby, Angular, …) and package managers (npm, pnpm, yarn, bun)
• Smart ports — detects the port from .env and scripts, auto-bumps when busy, kills stuck processes, and remembers your choice per project
• Auto-open — when a dev/start server is up, the app URL opens in your browser automatically
• Health analysis — score/grade, dependencies, security, dead code, architecture, and performance per project (nps analyze)
• Utilities — SSL certificates, Node heap memory tuning, install/reinit/CI, --doctor health check, --update self-update

Install

npm install -g node-project-scanner

Or run without installing via npx:

npx node-project-scanner scan .
npx node-project-scanner run my-app --port 3005

Quick start

nps                      # scan the current folder, open the dashboard in your browser
nps ~/projects           # scan a different folder

From there you can browse every project, inspect its analytics, and launch any script with one click.

Dashboard (default)

The bare nps command opens the analytics dashboard in your browser.

nps                      # scan current folder, open the dashboard
nps ~/projects           # scan a specific folder
nps . --exclude legacy,archive
nps web --port 9000      # explicit dashboard on a custom port
nps web --no-open        # start the server without opening the browser

The dashboard shows an overview (project count, install status, builders, package managers), a filterable project list, and per-project analytics when you select one:

• Health score / grade with findings broken down by severity and category
• Metrics — source files, lines, dependencies
• Run buttons for every available script (dev/start/build/test/lint/install/reinit/ci/…)

Clicking Run launches the script in the terminal where nps is running, and for dev/start scripts the app URL opens in your browser as soon as the server is up. The list auto-refreshes, and Rescan re-walks the folder.

Choosing the default UI

nps default-ui          # show which UI runs by default
nps default-ui tui      # make the terminal UI the default for `nps`
nps default-ui web      # switch back to the browser dashboard

Explicit nps web and nps tui always launch their UI regardless of the default.

Terminal UI

nps tui                 # keyboard-driven project picker
nps tui ~/projects
nps --no-tui            # ANSI menu instead of the full-screen TUI

Shortcuts

| Key | Action | |-----|--------| | Enter | Grouped action menu (Run → Package → Tooling → Scripts) | | D | Run dev | | S | Run start | | B | Run build | | I | Install dependencies | | U | Reinit (clean artifacts + reinstall) | | C | CI install (frozen lockfile) | | K | Kill the process on the project port | | M | Node memory (GB) | | T | Open a terminal in the project folder | | E | Open the project folder in the file manager | | O | More actions (all scripts) | | R | Rescan | | / | Search / filter | | ? | Help | | Q | Quit |

Port confirm dialog (shown before launch when a script uses a port)

| Key | Action | |-----|--------| | Enter | Launch with the port shown in the field | | K | Kill the process using the detected port, then auto-fill that port | | P | Change the port | | Esc | Cancel |

The field auto-fills: detected port when free → next free port when busy → original port after a kill. Your choice is remembered per project and reused next time; override once with nps run <project> --port.

Action menu (Enter on a project)

| Section | Actions | |---------|---------| | Run | dev, start, build | | Package | install, reinit, ci (frozen lockfile) | | Tooling | test, lint, preview, … | | Scripts | any other package.json scripts |

Command reference

| Command | What it does | |---------|--------------| | nps [dir] | Open the dashboard (default UI) | | nps web [dir] | Open the dashboard explicitly (--port, --no-open) | | nps tui [dir] | Open the terminal UI | | nps default-ui [web\|tui] | Show or set the default UI | | nps scan [dir] | Scan + interactive picker; --list-only prints a table | | nps list [dir] | List projects as JSON | | nps info <project> | Show project metadata (--json) | | nps run <project> | Run a script (default dev; -s, -p, --kill-port) | | nps build <project> | Run the build script | | nps install <project> | Install dependencies | | nps reinit <project> | Remove node_modules/artifacts and reinstall | | nps analyze [dir] | Health report: deps, security, dead code, architecture, performance (--all, --json, --sarif, --baseline) | | nps ssl <project> | Create or renew local HTTPS certificates | | nps kill-port <port> | Free a busy port | | nps memory [gb] | Show or set the Node heap memory limit | | nps ssl-expiry [duration] | Show or set the default SSL certificate lifetime | | nps --doctor | Check installation and environment health | | nps --update | Self-update to the latest release |

Examples

nps run my-app                   # run dev
nps run my-app --script start    # run start
nps run my-app --port 3005       # run dev on a specific port
nps run my-app --port 3000 --kill-port  # free the port first
nps build my-app
nps install my-app
nps reinit my-app
nps run my-app --script ci       # frozen-lockfile install
nps run my-app --script test
nps kill-port 3000
nps scan . --list-only           # table, no picker
nps list . --json                # machine-readable project list
nps info my-app --json

List icons: ✓ deps installed · ○ missing · · checking. Name shows package · folder when they differ.

Port handling

• Detects PORT from .env, .env.local, and .env.development
• Parses --port / -p from npm scripts
• Sets the PORT env var and forwards builder-specific flags (Vite, Next.js, Angular, …)
• Shows port status and the URL before launch
• When the detected port is busy, suggests and uses the next free port
• Kills stuck processes with nps kill-port, --kill-port, or K in the TUI
• Works on Windows, macOS, and Linux (kills the whole process tree)

Troubleshooting

• Port already in use — nps detects it, suggests the next free port, or frees it with K / nps kill-port <port>.
• No terminal UI — run nps in a real terminal (TTY); otherwise use the subcommands (e.g. nps run my-app).
• Dashboard not opening — make sure a browser is installed; start it manually with nps web --no-open and visit the printed URL.
• Version — nps --version.

Requirements

• Node.js 18+
• Windows, macOS, or Linux

License

MIT