oxc-project/oxc · warning · OxcDiagnostic

Avoid using `withDefaults` with destructuring.

Error message

Avoid using `withDefaults` with destructuring.

What it means

Diagnostic from oxlint's vue/define-props-destructuring rule (style category, since oxlint 1.20.0). It fires when withDefaults() is combined with destructuring, e.g. `const { baz } = withDefaults(defineProps(...), { baz: 'x' })`. All three modes of the rule warn against this pattern; with Vue 3.5+ defaults belong directly in the destructuring pattern, and on older versions the combination is the least portable style.

Source

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

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,
}

#[derive(Debug, Default, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct DefinePropsDestructuring {
    /// Require or prohibit destructuring.

View on GitHub (pinned to e1e7af627c)

Solutions

1. Inline the default into the destructure: const { baz = 'default' } = defineProps<{ baz?: string }>() (Vue 3.5+)
2. Or keep withDefaults but assign it to a variable and access props via that variable (pre-3.5)
3. Remove withDefaults entirely when the default can be handled at usage sites

Example fix

// before
const { baz } = withDefaults(defineProps<{ baz?: string }>(), { baz: 'default' })
// after
const { baz = 'default' } = defineProps<{ baz?: string }>()

# find withDefaults usages, then check which are destructured
grep -rn "withDefaults" --include='*.vue' src

When it happens

Trigger: A file contains destructuring of a withDefaults(defineProps(...), {...}) call. The rule detects the parent withDefaults CallExpression span around a destructured defineProps and reports it under every destructure option.

Common situations: Copying typed-props boilerplate from Vue 3.0-3.4 era docs or blog posts into a codebase whose lint config uses this rule; CI then flags the legacy withDefaults idiom.

Related errors

• Prefer destructuring from `defineProps` directly.
• Avoid destructuring from `defineProps`.
• 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/25d3429125a7ca1f. Report an issue: GitHub.