oxc-project/oxc · warning · OxcDiagnostic

Avoid destructuring from `defineProps`.

Error message

Avoid destructuring from `defineProps`.

What it means

Diagnostic from oxlint's vue/define-props-destructuring rule (style category, since oxlint 1.20.0). It fires when defineProps() results are destructured while the rule is set to Destructure::Never, which requires storing props in a variable. This mode protects codebases where destructured values would lose reactivity (pre-Vue 3.5 compilers or runtime-only builds).

Source

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

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,
    /// Requires using a variable to store props and prohibits destructuring
    Never,
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. Store the result and access members: const props = defineProps(['foo']); props.foo
2. Upgrade to Vue 3.5+ where reactive props destructuring is supported, then switch the option to "always" or the default
3. Disable the rule for files that must destructure (e.g., withDefaults-free simple props)

Example fix

// before (option { "destructure": "never" })
const { foo } = defineProps(['foo'])
// after
const props = defineProps(['foo'])
console.log(props.foo)

# find destructured defineProps before switching to { "destructure": "never" }
grep -rnE "const *\{[^}]*\} *= *(withDefaults\()?\s*defineProps" --include='*.vue' src

When it happens

Trigger: Config sets "vue/define-props-destructuring": ["error", { "destructure": "never" }] and a file contains `const { foo } = defineProps(['foo'])` or destructuring of a withDefaults(defineProps(...)) call.

Common situations: Projects on Vue < 3.5 (or using defineProps without the compiler transform) where destructured props stop updating; teams standardize on `props.foo` access and enforce it with this option.

Related errors

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

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