How Framework Extractors Identify React, Next.js, Django, and Express in Understand-Anything

Framework extractors identify frameworks by scanning manifest files like package.json and requirements.txt for specific package names declared in detectionKeywords, then validating against optional entry-point files to confirm presence.

Understand-Anything automatically detects the technologies powering your codebase through a sophisticated framework extraction system. This engine inspects dependency manifests and source file patterns to identify frameworks like React, Next.js, Django, and Express without manual configuration. By leveraging declarative FrameworkConfig objects and targeted file system analysis, the extractors provide accurate technology detection that powers downstream architectural insights.

The FrameworkConfig Detection Schema

Core Configuration Properties

Each supported framework is defined by a FrameworkConfig object that declares detection criteria. According to the source code in packages/core/src/languages/frameworks/, these configurations specify:

• id: Stable internal identifier (e.g., react, next, django)
• displayName: Human-readable label for UI rendering
• languages: Target languages (e.g., typescript, javascript, python)
• detectionKeywords: NPM package names or PyPI imports that uniquely identify the framework (e.g., react, react-dom, @types/react for React)
• manifestFiles: Dependency lists to scan (e.g., package.json, requirements.txt, pyproject.toml)
• entryPoints: Optional validation files (e.g., src/App.tsx, manage.py)
• layerHints: Architectural classifications for the framework's directories

The Five-Step Detection Pipeline

The extraction process implemented in packages/core/src/plugins/extractors/base-extractor.ts follows a systematic approach:

1. Load the Registry: All *-config.ts files under packages/core/src/languages/frameworks/ are imported and combined into a map keyed by id.
2. Parse Manifest Files: The extractor reads each manifestFiles entry and extracts declared dependencies.
3. Match Detection Keywords: Any dependency name appearing in a framework's detectionKeywords flags that framework as present.
4. Validate Entry Points: Optional entryPoints are checked on disk to increase confidence scores.
5. Generate Results: The framework's id, displayName, and inferred layer mapping are added to the analysis output consumed by llm-analyzer.ts.

Framework-Specific Detection Examples

React and Next.js Detection

In packages/core/src/languages/frameworks/react.ts, React is identified through detectionKeywords including react, react-dom, and @types/react. The config also targets entry points like src/App.tsx to confirm React usage.

Next.js extends this pattern in packages/core/src/languages/frameworks/next.ts by adding keywords such as next and next/router, while also checking for the pages/ directory structure characteristic of Next.js applications.

Express Detection

Express configuration in packages/core/src/languages/frameworks/express.ts targets the express NPM package and validates against typical entry files like src/index.js or app.js.

Django Detection

For Python frameworks, packages/core/src/languages/frameworks/django.ts reads requirements.txt or pyproject.toml for the Django package. It further validates by detecting the conventional manage.py entry script and settings.py configuration module.

Running Framework Detection Programmatically

You can invoke the detection engine directly using the detectFrameworks function from the core package:

import { detectFrameworks } from '@understand-anything/core';

const projectRoot = '/path/to/project';

// Returns array of detected frameworks
const frameworks = await detectFrameworks(projectRoot);
console.log('Detected:', frameworks);
// Output: [{ id: 'react', displayName: 'React', ... }]

Extending Detection with Custom Frameworks

To add support for additional frameworks like Vue, create a new config file satisfying the FrameworkConfig interface:

export const vueConfig = {
  id: 'vue',
  displayName: 'Vue',
  languages: ['typescript', 'javascript'],
  detectionKeywords: ['vue', '@vue/compiler-sfc'],
  manifestFiles: ['package.json'],
  promptSnippetPath: './frameworks/vue.md',
  entryPoints: ['src/main.ts', 'src/main.js'],
  layerHints: { components: 'ui', store: 'service' },
} satisfies FrameworkConfig;

Place this in packages/core/src/languages/frameworks/ and the registry will automatically include it in the next analysis run.

Testing Framework Detection

The accuracy of these extractors is verified in packages/core/src/__tests__/framework-registry.test.ts, which validates detection from sample package.json snapshots:

import { expect, test } from 'vitest';
import { detectFrameworks } from '@understand-anything/core';

test('detects React from package.json', async () => {
  const fixtures = '/tmp/fixture-react';
  const detected = await detectFrameworks(fixtures);
  expect(detected.map(f => f.id)).toContain('react');
});

Summary

• FrameworkConfig objects define detection criteria through detectionKeywords, manifestFiles, and optional entryPoints.
• The extractor scans package.json, requirements.txt, and similar manifests to match dependency names against registered frameworks.
• Framework-specific configurations reside in packages/core/src/languages/frameworks/ (e.g., react.ts, django.ts).
• Entry-point validation increases detection confidence by verifying conventional file patterns like src/App.tsx or manage.py.
• The detectFrameworks function in base-extractor.ts orchestrates the registry loading, manifest parsing, and keyword matching pipeline.

Frequently Asked Questions

What files does the framework extractor scan to identify dependencies?

The extractor primarily scans manifestFiles defined in each FrameworkConfig, which typically include package.json for Node.js projects, requirements.txt or pyproject.toml for Python projects, and pom.xml for Java projects. It extracts the dependency list from these files and checks for matches against detectionKeywords.

How does the extractor distinguish between similar frameworks like React and Next.js?

While Next.js depends on React, the extractor uses specific detectionKeywords to differentiate them. Next.js configs include unique package names like next and next/router, and check for framework-specific directories such as pages/. Each framework has a distinct id and keyword set, allowing simultaneous detection of related technologies.

Can I customize which entry points the extractor validates for existing frameworks?

Yes, you can modify the entryPoints array in the respective framework configuration files under packages/core/src/languages/frameworks/. Adding or removing paths from this array changes which files the extractor checks to validate framework presence, though the core detectionKeywords matching on manifest files remains the primary detection mechanism.

How do I add detection for a new framework not currently supported?

Create a new TypeScript file in packages/core/src/languages/frameworks/ that exports a FrameworkConfig object with unique detectionKeywords (package names) and appropriate manifestFiles. Include entryPoints and layerHints for enhanced accuracy. The registry automatically loads all *-config.ts files in this directory, making your framework detectable immediately.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}