oxc-project/oxc · info · OxcDiagnostic

Prefer destructuring from `defineProps` directly.

Error message

Prefer destructuring from `defineProps` directly.

What it means

Diagnostic from oxlint's vue/define-props-destructuring rule (style category, since oxlint 1.20.0). It fires when the result of defineProps() is stored in a variable instead of being destructured, under the "only-when-assigned" (default) or "always" option. The rule pushes the modern Vue 3.5+ pattern where destructured props keep reactivity via compiler transforms.

Source

Thrown at crates/oxc_linter/src/rules/vue/define_props_destructuring.rs:16

use oxc_ast::{AstKind, ast::BindingPattern};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::{
    AstNode,
    context::{ContextHost, LintContext},
    frameworks::FrameworkOptions,
    rule::{DefaultRuleConfig, Rule},
};

fn prefer_destructuring_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Prefer destructuring from `defineProps` directly.").with_label(span)
}

fn avoid_destructuring_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Avoid destructuring from `defineProps`.").with_label(span)
}

fn avoid_with_defaults_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Avoid using `withDefaults` with destructuring.").with_label(span)
}

#[derive(Debug, Default, Clone, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "kebab-case")]
enum Destructure {
    /// Requires destructuring when `defineProps` is assigned to a variable and warns against using `withDefaults` with destructuring
    #[default]
    OnlyWhenAssigned,
    /// Requires destructuring when using `defineProps` and warns against using `withDefaults` with destructuring
    Always,

View on GitHub (pinned to e1e7af627c)

Solutions

1. Destructure at the call site: const { foo } = defineProps(['foo'])
2. Use default values in the destructure (Vue 3.5+): const { bar = 'default' } = defineProps<{ bar?: string }>()
3. If the codebase intentionally uses props.xxx, set the option to { "destructure": "never" }
4. Disable the rule for transitional files with an oxlint-disable comment

Example fix

// before
const props = defineProps(['foo'])
console.log(props.foo)
// after
const { foo } = defineProps(['foo'])
console.log(foo)

# find non-destructured assignments before enabling the rule
grep -rnE "const +[A-Za-z$_][A-Za-z0-9$_]* *= *defineProps" --include='*.vue' src

When it happens

Trigger: A file contains `const props = defineProps(['foo'])` or `const props = defineProps<{ foo?: string }>()` (any call with arguments/type args whose result is assigned) while the rule's `destructure` option is "only-when-assigned" or "always". The rule matches defineProps calls with at least one argument or type parameter.

Common situations: Adopting the newer destructuring convention after upgrading to Vue 3.5+, or inheriting a config tuned for it; older components using `props.foo` everywhere then get flagged during CI.

Related errors

• Use runtime declaration instead of type-based declaration
• Use type-based declaration instead of runtime declaration
• Avoid destructuring from `defineProps`.
• Avoid using `withDefaults` with destructuring.
• `VirtualFree` failed during cleanup: {err}

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/5e3b6e35dcc59344. Report an issue: GitHub.