shadcn-schema

library0.5.0jsnpmunverified

Provides reusable TypeScript types and runtime schema definitions for the Shadcn registry, currently at version 0.5.0. This package defines the structure of shadcn registry entries using Zod schemas, enabling validation and type-safe handling of registry items. It is updated irregularly alongside shadcn's evolving registry specification. Key differentiators: it is the official schema library for shadcn's new v2 registry format, offering both Zod validation and first-class TypeScript support. Alternative approaches require manual type definitions or ad-hoc validation.

testing

npm install shadcn-schema

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SHADCN-SCHEMA

shadcn-schema

testingjavascriptv0.5.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

registrySchema

✓ import { registrySchema } from 'shadcn-schema'

✗ import registrySchema from 'shadcn-schema'

Named export, not default. Use named import syntax.

Registry

✓ import { Registry } from 'shadcn-schema'

✗ const Registry = require('shadcn-schema').Registry

TypeScript type export — can be used as a type. CommonJS require is possible but not idiomatic in TS projects.

RegistryItem

✓ import type { RegistryItem } from 'shadcn-schema'

✗ import { RegistryItem } from 'shadcn-schema'

RegistryItem is a type, not a value. Use `import type` for better tree-shaking and clarity.

Validates a shadcn registry entry using the provided Zod schema and prints the parsed result or a detailed validation error.

import { registrySchema } from 'shadcn-schema'; import { fromZodError } from 'zod-validation-error'; const result = registrySchema.safeParse({ name: 'my-component', type: 'registry:component', files: [ { path: 'my-component.tsx', content: 'export function MyComponent() { return <div>Hello</div> }', type: 'registry:component', }, ], }); if (!result.success) { console.error(fromZodError(result.error)); process.exit(1); } console.log('Valid registry entry:', result.data);

Debug

Known issues

breakingRegistry schema structure differs between v1 and v2 of shadcn. shadcn-schema targets v2 only.

fix

Ensure your registry entries conform to the v2 spec. Migrate from v1 by adapting file metadata and type fields.

affects: >=0.1.0

gotchaDo not rely on the schema being completely stable; minor versions may introduce breaking changes until v1.0.

fix

Pin to a specific minor version and test after updates.

affects: >=0.1.0 <1.0.0

gotchaThe `type` field in files has a constrained set of allowed values; using an unrecognized string will cause validation failure.

fix

Use only the types defined in shadcn's documentation: 'registry:component', 'registry:page', 'registry:ui', etc.

affects: >=0.3.0

deprecatedThe `registryItemSchema` (singular) was renamed to `registryItem` in v0.5.0.

fix

Replace `registryItemSchema` with `registryItem` in your imports and usage.

affects: <0.5.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'safeParse')

Forgetting to destructure the named export or importing incorrectly as default.

fix

Use `import { registrySchema } from 'shadcn-schema'` instead of default import.

ValidationError: Expected 'registry:component' | 'registry:page' | ... but received 'xxx'

Using an invalid file type string in a file entry.

fix

Correct the `type` field to one of the allowed values (e.g., 'registry:component').

TypeScript error: 'RegistryItem' refers to a type, but is being used as a value here.

Importing a type without using `import type` leads to runtime issues in some bundlers.

fix

Use `import type { RegistryItem } from 'shadcn-schema'` or enable `verbatimModuleSyntax` in tsconfig.

Cannot find module 'shadcn-schema' or its corresponding type declarations.

Package not installed or missing tsconfig moduleResolution.

fix

Run `npm install shadcn-schema` and ensure moduleResolution is set to 'bundler' or 'node16'.

Upgrade

Version history

0.5.0latest on npm

Audit

Dependencies

zodrequiredUsed for runtime schema validation of registry entries

zod-validation-erroroptionalProvides better error messages for Zod validation failures

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/ocavue/shadcn-schema ↗

packageshadcn-schema ↗

homepagehttps://github.com/ocavue/shadcn-schema#readme ↗