Vue TypeScript Prop Type Definitions

Common errors

• Module parse failed: Unexpected token 'export' (at line X, column Y) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/configuration/module/#rule-type

  cause This error typically occurs when a CommonJS-based environment or build setup attempts to import `vue-ts-types` as an ES Module, or if your tooling is not correctly configured to resolve dual packages.
  fix 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`.

• [vue/no-required-prop-with-default] The 'required' prop 'X' should not have a default value.

  cause This ESLint error, part of `eslint-plugin-vue`, indicates that a Vue prop has been declared as both `required: true` and includes a `default` value. This is a logical contradiction, as a default value inherently makes a prop optional.
  fix 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.

• Type 'X' is not assignable to type 'PropType<Y>'. Property 'Z' is missing in type 'X' but required in type 'Y'.

  cause This TypeScript error often points to a mismatch between the expected prop type and the provided type. It can occur if the generic type argument passed to `vue-ts-types` helpers is incorrect, or if an optional prop is not correctly typed to include `undefined`.
  fix 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.

Warnings

• breaking Version 1.7.0 mistakenly switched the package to ES Modules (ESM) only, causing immediate breaking changes for existing CommonJS (CJS) users. This was swiftly reverted in v1.7.1, but highlights potential module resolution issues. Since v1.9.0, dual ESM and CJS builds are officially provided, but careful configuration of your build tooling (e.g., Webpack, Rollup, Vite) is crucial to ensure it picks the correct module format for your target environment.
  Fix: 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.
• gotcha Attempting to combine `required: true` with a `default` value in standard Vue prop definitions is contradictory. Vue implicitly treats any prop with a `default` as optional, regardless of the `required` flag, leading to unexpected behavior and often triggering the `vue/no-required-prop-with-default` ESLint rule. `vue-ts-types` is designed to prevent this logical conflict.
  Fix: 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.
• gotcha A common TypeScript footgun in Vue is failing to explicitly union `PropType` with `undefined` or `null` for optional or nullable complex props (e.g., `PropType<MyType>` instead of `PropType<MyType | undefined>`). This results in incorrect type inference, leading to TypeScript errors when the prop might legitimately be absent or null.
  Fix: 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.

Install

• npm install vue-ts-types npm
• yarn add vue-ts-types yarn
• pnpm add vue-ts-types pnpm

Imports

• stringProp
  wrong:

  const stringProp = require('vue-ts-types').stringProp

  correct:

  import { stringProp } from 'vue-ts-types'

  Use named imports for individual prop type functions. Since v1.9.0, both ESM and CJS builds are provided, but named imports are generally preferred for tree-shaking in modern bundlers.
• oneOfProp
  wrong:

  import { oneOfProp as customOneOfProp } from 'vue-ts-types/dist/oneOfProp'

  correct:

  import { oneOfProp } from 'vue-ts-types'

  All prop type definitions are available as named exports directly from the main package entry point. Avoid importing from internal paths, as these are not considered part of the public API and may change.
• isPositive
  wrong:

  const isPositive = require('vue-ts-types').isPositive

  correct:

  import { isPositive } from 'vue-ts-types'

  Validator functions like `isPositive` are also named exports. Ensure your project is configured to handle ESM imports correctly if targeting an environment that doesn't support CJS by default (e.g., modern Node.js or browser builds).

Quickstart

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.

import { defineComponent, createApp } from 'vue';
import {
  arrayProp,
  booleanProp,
  functionProp,
  isPositive,
  numberProp,
  oneOfProp,
  stringProp
} from 'vue-ts-types';

const MyComponent = defineComponent({
  props: {
    disabled: booleanProp().withDefault(false),
    // resulting prop type: boolean

    title: stringProp().optional,
    // resulting prop type: string | undefined

    description: stringProp().nullable,
    // resulting prop type: string | null

    items: arrayProp<string>().required,
    // resulting prop type: string[]

    callback: functionProp<() => void>().optional,
    // resulting prop type: (() => void) | undefined

    color: oneOfProp(['red', 'green', 'blue'] as const).withDefault('red'),
    // resulting prop type: 'red' | 'green' | 'blue'

    timeout: numberProp(isPositive).required,
    // resulting prop type: number
  },
  template: `
    <div>
      <h1 v-if="title">{{ title }}</h1>
      <p v-if="description">{{ description }}</p>
      <button :disabled="disabled" @click="callback">Click Me</button>
      <ul>
        <li v-for="item in items" :key="item">{{ item }}</li>
      </ul>
      <p>Selected color: {{ color }}</p>
      <p>Timeout (ms): {{ timeout }}</p>
    </div>
  `,
  setup(props) {
    // console.log(props.timeout);
    return { };
  }
});

// To run this in a browser, you would typically mount it:
// const app = createApp(MyComponent);
// app.mount('#app');

// Example usage if you were creating a root app:
const app = createApp({
  components: { MyComponent },
  template: `<MyComponent title="Hello Vue Props" :items="['Apple', 'Banana']" :timeout="100" />`
});

// In a real application, you'd mount this to an element in your HTML
// app.mount('#app'); // Assuming you have <div id="app"></div> in your HTML