Registry — `snippets-index.json` · Docs

The registry is the single machine-readable record of every DevSnips resource. Generated by scripts/tooling/indexing/rebuild_index.py (or the combined entry point build_resource_indexes.py, which also regenerates the specialized indexes). Never hand-edit it.

Live URL (what the CLI fetches):

https://raw.githubusercontent.com/sarthakbystander/DevSnips/main/snippets-index.json

Top-level shape

{
  "version": "2.0",
  "lastUpdated": "<YYYY-MM-DD>",
  "description": "DevSnips component library index - organized as design system families with production-ready variants",
  "stats": { /* aggregate counts */ },
  "families": [ /* every family, each with its variants */ ],
  "technologies": [ /* technology records */ ],
  "contributionGuidelines": { /* structure conventions */ }
}

Field	Type	Required	Meaning	Stability
`version`	string	yes	Registry schema version. Currently `"2.0"`.	Changes only with a schema change.
`lastUpdated`	date	yes	Date of the last regeneration.	Changes on every regeneration.
`description`	string	yes	Human-readable description of the index.	Stable.
`stats`	object	yes	Live aggregate counts (see below).	Recomputed every run — never quote from memory.
`families`	array	yes	The inventory.	Additive; ordering sorted by path.
`technologies`	array	yes	One record per technology.	Additive.
`contributionGuidelines`	object	yes	Declarative structure conventions for contributors.	Stable.

`stats`

{
  "totalFamilies": <int>,
  "totalVariants": <int>,
  "totalSubVariants": <int>,
  "totalStyles": <int>,
  "technologies": ["Tailwind CSS", "Vanilla HTML/CSS/JS", "React"],
  "tailwindByType": { "component": <int>, "section": <int>, "template": <int> },
  "vanillaByType":  { "component": <int>, "section": <int>, "template": <int> },
  "reactByType":    { "component": <int>, "section": <int>, "template": <int> }
}

All values are recomputed on every regeneration. Agents must fetch the registry and read stats in the current session; never report counts from documentation or memory. The *ByType keys are per-technology resource counts by type.

`technologies[]`

{
  "name": "Tailwind CSS",
  "path": "library/Tailwind/",
  "status": "active",
  "families": ["Accordions", "Buttons", "..."]
}

Field	Meaning
`name`	The canonical technology string: `React`, `Tailwind CSS`, `Vanilla HTML/CSS/JS`. Use exactly these when filtering.
`path`	The technology's on-disk root (`library/<Tech>/`).
`status`	`"active"` for all current technologies.
`families`	Family display names, annotated where disambiguation is needed (e.g. `"Navbar (Tailwind)"`).

Family object

{
  "name": "Buttons",
  "path": "Tailwind/Components/Buttons/",
  "tech": "Tailwind CSS",
  "type": "component",
  "category": "Components",
  "description": "…",
  "variantsCount": <int>,
  "tags": ["…"],
  "searchTerms": ["…"],
  "variants": [ /* variant objects */ ]
}

Field	Type	Required	Meaning	Allowed values / example
`name`	string	yes	Family display name.	`"Buttons"`, `"Logo-Cloud"`, `"AI-Product"`
`path`	string	yes	Family location, tech-first, trailing slash, no `library/` prefix.	`"Tailwind/Components/Buttons/"`
`tech`	string	yes	Canonical technology string.	`"React"` \| `"Tailwind CSS"` \| `"Vanilla HTML/CSS/JS"`
`type`	string	yes*	Resource type filter key.	`"component"` \| `"section"` \| `"template"` — always lowercase. Most family objects carry it; a few Vanilla families may omit it (the `category` alone disambiguates).
`category`	string	yes	Capitalized content type.	`"Components"` \| `"Sections"` \| `"Templates"`
`description`	string	usually	Curated family summary. Preserved across regenerations.	—
`variantsCount`	integer	yes	Number of variants. Recomputed.	—
`tags`	array	usually	Lowercase search words. Curated, preserved.	`["button", "cta"]`
`searchTerms`	array	optional	Longer user-intent phrases. Present on some families.	—
`variants`	array	yes	The resources in this family.	See below.

type is the field to filter on; category is the display/bucket form. Do not conflate them.

Variant object

{
  "name": "Basic Accordion",
  "path": "Tailwind/Components/Accordions/basic-accordion/",
  "type": "component",
  "description": "…",
  "tags": ["accordion", "basic", "documentation"],
  "features": ["chevron rotation", "height animation"],
  "styles": ["basic", "documentation"],
  "files": ["README.md", "code.html", "metadata.json", "preview.html"]
}

Field	Type	Required	Meaning
`name`	string	yes	Variant display name.
`path`	string	yes	The variant's registry path (trailing slash). This is the CLI id — `npx devsnips add <path without slash>`.
`type`	string	yes	Same vocabulary as family `type`.
`description`	string	usually	What the variant is; indexed copy of the resource's metadata.
`tags`	array	usually	Lowercase search words.
`features`	array	usually	Short human-readable feature phrases (e.g. `"focus-visible rings"`).
`styles`	array	optional	Style words (e.g. `"minimal"`, `"neo-brutalism"`).
`files`	array	yes	File manifest built from disk. Basis of the CLI's install set.

Notes on files:

Entries are bare file names, or one-level paths prefixed pages/ (Tailwind/Vanilla templates) or src/, components/, data/, sections/, styles/ (React templates).
Files nested deeper than one level under those directories are not listed.
The CLI installs from this manifest, excluding metadata.json and preview.html, so an incomplete manifest means an incomplete install.

The master registry does not carry per-variant id or install fields — those exist only in the specialized indexes (Schemas). In the master, the id is the variant path itself.

Path convention

All paths in the registry are tech-first without the library/ prefix. The on-disk location of every entry is library/<path>. Paths carry a trailing slash. The prefix is stripped portably by the generator (rel_path()) so output never contains machine-specific absolute paths; the CLI re-adds the prefix when downloading (buildRepoFilePath()).

How the registry is produced

Load the previous index to preserve curated fields (family description, tags, searchTerms; variant fields).
Re-scan the disk for leaves under each content-type tree.
Cross-validate: every indexed variant must exist on disk, and every valid disk leaf must be indexed.
Recompute stats and the per-technology family lists.
Write only if validation found no problems — otherwise print the problems and leave the file untouched.

Regenerate with:

python scripts/tooling/indexing/rebuild_index.py

If a curated field is deleted from metadata.json, regeneration may still keep the old indexed value via the previous-index fallback — check the registry entry after regenerating.

Consumer contract summary

Filter by families[].tech (exact strings), type, and category.
Match intent against family/variant names, tags, searchTerms, features, styles.
Install with npx devsnips add <variant path> (trailing slash optional).
Fetch files at library/<variant path>/<file> (raw GitHub or a checkout).
Counts — read stats from a registry fetched this session.