Stack Detection

Stack detection

Most wrong frontend edits are correct code for a stack the project does not use. Detection is cheap; guessing is not.

When this fires

Before the first edit in a frontend repo you have not already mapped in this session, and again whenever you catch yourself about to say "this project probably uses". It does not fire for a repo whose conventions you have already read this session.

Procedure

1. Find the right package.json first. In a monorepo the root one describes the workspace, not the app. Locate the nearest package.json above the file you are changing, and note whether a root one also exists — dependencies can be hoisted, tooling config usually is.
2. Read dependencies and scripts together. dependencies and devDependencies say what is installed; scripts say what is actually run. The dev, build and test commands are the ones to use later — do not invent npm run dev if the project spells it differently.
3. Get real versions from the lockfile, not the range. ^15.0.0 in package.json is a constraint. The lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock*) holds the resolved version, and its filename is also the only reliable statement of which package manager to invoke. Two lockfiles present is a finding, not a choice.
4. Read the config files that exist, and note the ones that do not. Build/framework config, TypeScript config, lint and format config, test config. Their presence tells you the tool is wired in; their contents tell you path aliases, strictness, and what is excluded.
5. Confirm the routing and rendering model from the directory layout, not from the framework name. Which route directories exist, where the entry file is, whether routes are file-based or declared in code, and — for frameworks with a server/client split — which files carry the directives that mark the boundary.
6. Identify the styling layer and its version. A config file's existence does not pin a major version; check the lockfile and how the stylesheet imports the framework. Also check for a CSS modules / styled-in-JS / vanilla CSS layer coexisting with it — mixed styling is common and changes what you should write.
7. Check for a vendored component layer. components.json or an equivalent marker plus a UI directory means components were copied in and are now project source (see shadcn-ui).
8. Open two or three real source files in the area you will touch. Config says what is possible; the source says what this team actually does — import style, file naming, test colocation, state library usage.
9. Write the stack down in one short block, with the file each claim came from, and a separate list of what you could not determine. That list is part of the result.

What a signal does and does not license

• A framework in dependencies → the framework is installed. It does not tell you which router, rendering mode or directory convention is in use. Read the layout.
• A config file exists → that tool runs. It does not tell you the major version, and majors move config between files. The lockfile decides.
• TypeScript installed → files are typed. It does not mean strict is on, that any is discouraged, or that generated types are current. Read tsconfig and one real file.
• A test framework installed → tests can run. It does not mean they pass, cover this area, or are run in CI. Running them is a separate act.
• A state or data library installed → it is available somewhere. It does not mean the module you are editing uses it. Grep the directory you are in.
• components.json present → a component CLI was used at some point. It does not mean the components are unmodified, current, or the only UI layer.
• A lockfile entry → what would install. node_modules is what actually runs; if behaviour contradicts the lockfile, the installed tree is the tiebreaker.

Checklist

• The package.json read is the one governing the file being changed
• Package manager identified from the lockfile, not from habit
• Framework and styling versions taken from the lockfile
• Routing/rendering model confirmed from the directory layout
• Dev, build and test commands quoted from scripts
• At least two real source files read for convention
• Unknowns written down rather than filled in by assumption

Failure handling

• No lockfile — versions are unknown. Say so; do not resolve the range in your head. Behaviour that depends on a major version has to be checked against the installed tree or the docs.
• Conflicting signals (two lockfiles, a config for a tool that is not installed, a framework version that contradicts the layout) — report the conflict. Picking one silently makes you the source of the next bug.
• Vendored or patched dependencies (patches/, resolutions/overrides, a checked-in fork) — upstream documentation may not describe what runs here. Read the patch.
• Detection disagrees with the user — say what you found and where, then follow the user. Do not quietly rewrite their description of their own project.

Evidence to report

A short stack block — package manager, framework and version, router/rendering model, styling layer and version, component layer, TypeScript posture, test setup, dev/build/test commands — with the file each line came from, followed by an explicit "not determined" list. A stack summary with no file references is a guess with formatting.