vue-ts-types is a lightweight, TypeScript-first library designed to simplify and enhance the definition of Vue.js component props. It provides a fluent API for declaring prop types, addressing common pain points such as verbose prop declarations (especially when using Vue's built-in PropType utility), error-prone optional complex prop annotations (e.g., forgetting to union with `| undefined`), contradictions between `required` and `default` properties which lead to ambiguous behavior and ESLint warnings, and the inability to provide helpful custom validation error messages beyond a boolean result. The library is currently at version 1.9.0 and maintains an active release cadence with frequent minor updates. It supports both Vue 2.6+ and Vue 3.2+, shipping with full TypeScript type definitions. Since v1.9.0, it provides dual CommonJS and ES Module support, ensuring broad compatibility. Its core value lies in making prop definitions significantly more concise, type-safe, and less prone to common development errors in Vue projects utilizing TypeScript.
npm install vue-ts-typesVerified import paths — ran on the pinned version, not inferred.
This example demonstrates how to define various component props using `vue-ts-types`, including optional, nullable, required, and validated props, showcasing type inference, default values, and how a component using these props might be defined and instantiated.
If encountering module resolution errors, upgrade to v1.7.1 or higher. For v1.9.0 and later, review your `tsconfig.json`'s `moduleResolution` and your bundler's configuration to correctly handle dual package exports, typically preferring ESM where supported.
When using `vue-ts-types`, strictly choose between `.required` (for truly mandatory props with no default) or `.withDefault(value)` (for optional props that provide a fallback). The library's API prevents you from combining these conflicting modifiers, guiding you towards correct prop definitions.
Leverage `vue-ts-types`'s `.optional` or `.nullable` modifiers (e.g., `objectProp<MyType>().optional` or `stringProp().nullable`). These methods automatically infer and apply the correct `| undefined` or `| null` union type, ensuring your component's props are type-safe without manual `PropType` casting.
For projects using modern tooling, ensure your `tsconfig.json`'s `moduleResolution` (e.g., set to 'Bundler' or 'NodeNext') and your bundler's configuration (e.g., Webpack, Rollup, Vite) are set up to correctly resolve ES Modules. If explicitly targeting CommonJS, ensure your build picks up the CJS bundle; since v1.9.0, both are provided via the `exports` map in `package.json`.
When using `vue-ts-types`, you should explicitly choose either the `.required` chainable method (for props that must always be provided) or the `.withDefault(value)` method (for optional props with a fallback). The library's API design prevents you from making this contradictory declaration.
Verify that the generic type argument provided to functions like `arrayProp<T>()`, `objectProp<T>()`, or `functionProp<T>()` precisely matches the intended data structure. For props that are optional at runtime, ensure you use the `.optional` or `.nullable` modifiers (e.g., `stringProp().optional`) to correctly infer the `T | undefined` or `T | null` type, thus satisfying TypeScript's strict type checking.