---
title: "Component Index (.deeep.index.json)"
sidebarTitle: "Component Index"
description: "Deep-dive into local component indexing, static prop type analysis, package boundary resolution, and secure sync manifest payload schemas."
keywords: ".deeep.index.json, static prop analysis, component manifest payload"
icon: "component"
---

Both discovery modes generate a local `.deeep.index.json` by default. Use `deeep sync --dry-run` to inspect it without uploading components. The index is generated output; change your source or `deeep.json` and regenerate it instead of editing entries manually.

## Local index structure

| Field | Contents |
| --- | --- |
| `schemaVersion` | Index schema version, currently `1`. |
| `type` | `deeep-component-index`. |
| `generatedAt` | UTC generation timestamp. |
| `generator` | CLI name and version. |
| `project` | Framework, language, and styling settings when available. |
| `discovery` | Discovery mode and its configuration; Storybook also records the index format version and optional URL. |
| `entries` | Component entries keyed by generated identifiers. |
| `summary` | Component, scanned-file, warning, and error counts; Storybook adds story and story-file counts. |
| `diagnostics` | Messages with severity, code, and available file/component/story context. |

Entries include names, source and import paths, exports, framework/language, props and analysis status, local dependencies, declared package versions, styles, asset paths, and a source hash. Storybook entries also include story file paths and story metadata.

The local index is more detailed than the upload manifest. Props, asset lists, diagnostics, and the complete index file are not sent as the component-sync payload.

## CLI discovery coverage

The scanner reads `.js`, `.jsx`, `.mjs`, `.ts`, `.tsx`, and `.vue` files matching `components`, then applies `exclude`. It skips `.d.ts`, symlinked files/directories, and common dependency/build directories, including `node_modules`, `.git`, `dist`, `build`, and `storybook-static`.

Use repository-relative patterns such as `src/components/**/*.{js,jsx,mjs,ts,tsx,vue}`. Brace alternatives and `**/` matching are supported. Re-export-only `index` files are skipped as component entries; point discovery at implementation directories.

Analysis recognizes common exported components, Vue single-file components, and Angular component declarations. It extracts props from supported TypeScript declarations and local type imports, React PropTypes, Vue props, Angular inputs, JSDoc, defaults, and usage. Local source imports and supported TypeScript/JavaScript path aliases contribute dependency paths.

<Note>
Analysis is static and heuristic. It does not execute your application or provide full TypeScript compiler resolution. Review `propsAnalysis` and diagnostics when types are inferred, partial, or unresolved. Svelte can be detected as a project framework, but `.svelte` files are not supported by the direct component scanner.
</Note>

Source files larger than 2 MiB are skipped with `SOURCE_TOO_LARGE`. Unreadable or non-UTF-8 source produces `SOURCE_READ_FAILED`.

## Storybook metadata

The reader recognizes index format versions `2`, `3`, `4`, and `5` (the index's `v` field, not the installed Storybook major version). Other versions are parsed on a best-effort basis with a warning. Both modern `entries` and legacy `stories` collections are accepted; modern docs-only entries are excluded.

Component resolution supports common CSF metadata, typed `Meta<typeof Component>` patterns, namespace imports, local aliases, workspace package imports, and supported barrel re-exports. When a component implementation cannot be resolved, a synthetic entry based on the story file may be retained with `COMPONENT_SOURCE_UNRESOLVED`; inspect it before uploading.

Story metadata includes available IDs, names, export names, titles, tags, JSON-safe args, and per-story argTypes. Meta-level args are merged with story overrides. Functions, expressions, JSX-like values, deeply nested values, and oversized values are omitted rather than executed. Sanitization limits nested containers to six levels and drops dictionary values whose JSON serialization exceeds 4,096 characters.

When present, `.storybook/preview.js`, `.jsx`, `.ts`, or `.tsx` under the configured directory is attached as `previewPath` during manifest creation. It is not part of the component `sourcePaths` list or its content hash. Commit and push preview configuration as well so the referenced revision contains it.

The Storybook index size limit is 25 MiB. A missing index generates a warning and empty local index; a real sync rejects the empty manifest. Invalid JSON or a missing entries/stories collection blocks index generation.

## Package versions

For each component, package imports are matched against the nearest owning `package.json`, walking toward the repository root. The first manifest found is used; undeclared packages are omitted rather than guessed from ancestor manifests.

Declaration precedence is `dependencies`, then `peerDependencies`, then `devDependencies`. Versions are declared ranges, not exact installed or lockfile-resolved versions. Registry ranges such as `^18.0.0` are preserved. Dist-tags without digits and recognized non-registry protocols such as `workspace:`, `file:`, and `git+` become `*`.

## Uploaded manifest

| Field | Contents |
| --- | --- |
| `projectUuid` | Linked project identifier. |
| `discoveryType` | `CLI` or `STORYBOOK`. |
| `branch`, `commitSha` | Named local Git branch and full HEAD commit SHA. |
| `components` | Complete discovered component set, limited to 1,000 entries. |
| `storybookUrl` | Optional deployed URL from Storybook discovery. |
| `manifestHash` | SHA-256 of the canonical discovery, revision, components, and optional URL payload. |

Each component contains `externalId`, `name`, `exportName`, `entryPath`, `sourcePaths`, and `packages`, with optional `storybook` metadata and `contentHash`. Source paths combine discovered local source dependencies, styles, and story files, excluding the entry path itself. Asset paths are not included in this list.

The component `contentHash` is a SHA-256 digest of sorted, unique entry/source paths and their file bytes, separated by null bytes. It differs from the local index's `sourceHash`, which hashes only the entry file and uses a `sha256:` prefix. The content hash is omitted if a required file is missing. The canonical manifest hash supports repeatable sync requests; timestamps from the local index are not included.

## Common diagnostics

| Code | Meaning and next step |
| --- | --- |
| `NO_COMPONENT_FILES` | Check include patterns and excluded directories. |
| `NO_COMPONENT_EXPORT` | Check that the file exports a recognizable component. |
| `BARREL_FILE_SKIPPED` | Informational: a re-export-only index is not a component. |
| `UNRESOLVED_PROPS` | Review unsupported or unresolved type expressions. |
| `STORYBOOK_INDEX_MISSING` | Build Storybook and verify its configured index path. |
| `STORYBOOK_INDEX_VERSION_UNKNOWN` | Inspect results and check for a CLI update. |
| `STORY_SOURCE_UNRESOLVED` / `STORY_SOURCE_READ_FAILED` | Check index import paths against local story sources. |
| `COMPONENT_SOURCE_UNRESOLVED` | Review the synthetic entry and component import resolution. |

Warning/error counts in the generated index do not necessarily fail the command. Review them along with the discovered set before syncing.