fix(lint): suppress false positives in noUnusedVariables for Svelte store subscriptions and $bindable() props (#10534)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Carson McManus <carson.mcmanus1@gmail.com>

Author: 3 people

.changeset/fix-svelte-store-bindable.md

@@ -0,0 +1,5 @@
+---
+"@biomejs/biome": patch
+---
+
+Fixed [`noUnusedVariables`](https://biomejs.dev/linter/rules/no-unused-variables/) false positives in Svelte files: Svelte store subscriptions (`$store` references in templates now keep the underlying `store` binding from being flagged), and `$bindable()` props that are only written to in the script block (write-only is intentional for bindable props) are no longer reported as unused.

crates/biome_js_analyze/src/lint/correctness/no_unused_variables.rs

@@ -9,10 +9,10 @@ use biome_js_semantic::{ReferencesExtensions, SemanticModel};
 use biome_js_syntax::binding_ext::{AnyJsBindingDeclaration, AnyJsIdentifierBinding};
 use biome_js_syntax::declaration_ext::is_in_ambient_context;
 use biome_js_syntax::{
-    AnyJsExpression, JsClassExpression, JsForStatement, JsFunctionExpression,
+    AnyJsExpression, JsCallExpression, JsClassExpression, JsForStatement, JsFunctionExpression,
     JsIdentifierExpression, JsModuleItemList, JsSequenceExpression, JsSyntaxKind, JsSyntaxNode,
-    TsConditionalType, TsDeclarationModule, TsInferType, TsInterfaceDeclaration,
-    TsTypeAliasDeclaration,
+    JsVariableDeclarator, TsConditionalType, TsDeclarationModule, TsInferType,
+    TsInterfaceDeclaration, TsTypeAliasDeclaration,
 };
 use biome_languages::JsFileSource;
 use biome_languages::javascript::JsEmbeddingKind;
@@ -424,7 +424,11 @@ impl Rule for NoUnusedVariables {
                             | AnyJsBindingDeclaration::JsVariableDeclarator(_)
                     )
                 });
-        let is_used_as_reference = embedded.is_used(binding_token_text);
+        let is_used_as_reference = embedded.is_used(binding_token_text.clone())
+            || matches!(
+                file_source.as_embedding_kind(),
+                JsEmbeddingKind::Svelte { .. }
+            ) && embedded.is_svelte_store_used(binding_token_text);
 
         if is_underscore_prefixed || is_defined_in_embedded_binding || is_used_as_reference {
             return None;
@@ -443,6 +447,16 @@ impl Rule for NoUnusedVariables {
         }
 
         if is_unused(model, binding) {
+            // In Svelte 5, assigning to a `$bindable()` prop reflects the value back to the
+            // parent component. Such a variable may be write-only in the script block but is
+            // still meaningful — suppress the diagnostic to avoid a false positive.
+            if matches!(
+                file_source.as_embedding_kind(),
+                JsEmbeddingKind::Svelte { .. }
+            ) && is_svelte_bindable_prop(binding)
+            {
+                return None;
+            }
             suggested_fix_if_unused(binding, ctx.options())
         } else {
             None
@@ -675,6 +689,57 @@ fn is_declaration_merged_with_used(
     }
 }
 
+/// Returns `true` if `call` is a call to a simple identifier named `name`.
+fn is_call_to(call: &JsCallExpression, name: &str) -> bool {
+    let Ok(AnyJsExpression::JsIdentifierExpression(ident)) = call.callee() else {
+        return false;
+    };
+    ident.name().is_ok_and(|n| n.has_name(name))
+}
+
+/// Returns `true` if the binding is a `$bindable()` shorthand property in a `$props()`
+/// destructuring in a Svelte 5 component.
+///
+/// In Svelte 5, assigning to a `$bindable()` prop reflects the new value back to the parent
+/// component. A variable that appears write-only in the script is therefore intentional and
+/// should not be flagged as unused.
+fn is_svelte_bindable_prop(binding: &AnyJsIdentifierBinding) -> bool {
+    // The binding must be declared as a shorthand property in an object destructuring pattern.
+    let Some(decl) = binding.declaration() else {
+        return false;
+    };
+    let AnyJsBindingDeclaration::JsObjectBindingPatternShorthandProperty(shorthand) = decl else {
+        return false;
+    };
+
+    // The shorthand property must have a default initializer `= $bindable(...)`.
+    let Some(init) = shorthand.init() else {
+        return false;
+    };
+    let Ok(AnyJsExpression::JsCallExpression(call)) = init.expression() else {
+        return false;
+    };
+    if !is_call_to(&call, "$bindable") {
+        return false;
+    }
+
+    // Walk up to find the enclosing `JsVariableDeclarator` whose rhs must be `$props()`.
+    let Some(declarator) = shorthand
+        .syntax()
+        .ancestors()
+        .find_map(JsVariableDeclarator::cast)
+    else {
+        return false;
+    };
+    let Some(declarator_init) = declarator.initializer() else {
+        return false;
+    };
+    let Ok(AnyJsExpression::JsCallExpression(props_call)) = declarator_init.expression() else {
+        return false;
+    };
+    is_call_to(&props_call, "$props")
+}
+
 /// Returns `true` if `binding` is considered as unused.
 pub fn is_unused(model: &SemanticModel, binding: &AnyJsIdentifierBinding) -> bool {
     if matches!(binding, AnyJsIdentifierBinding::TsLiteralEnumMemberName(_)) {

crates/biome_js_analyze/src/services/embedded.rs

@@ -5,7 +5,8 @@ use biome_workspace_db::embedded::bindings::{
     InternedBindingText, InternedBindingTokenText, get_binding_by_name, get_binding_by_text,
 };
 use biome_workspace_db::embedded::references::{
-    InternedReference, is_reference_used, is_type_reference_used, is_value_reference_used,
+    InternedReference, is_reference_used, is_svelte_store_reference_used, is_type_reference_used,
+    is_value_reference_used,
 };
 use camino::Utf8PathBuf;
 use std::rc::Rc;
@@ -57,6 +58,16 @@ impl EmbeddedService {
             InternedReference::new(self.db.as_ref(), self.path.clone(), identifier),
         )
     }
+
+    /// Svelte stores are a special case. The `$` prefix is used to "dereference" the store and get its value.
+    ///
+    /// See also: https://svelte.dev/docs/svelte/stores
+    pub(crate) fn is_svelte_store_used(&self, identifier: TokenText) -> bool {
+        is_svelte_store_reference_used(
+            self.db.as_ref(),
+            InternedReference::new(self.db.as_ref(), self.path.clone(), identifier),
+        )
+    }
 }
 
 impl std::fmt::Debug for EmbeddedService {

crates/biome_js_analyze/tests/specs/correctness/noUnusedVariables/valid-svelte-bindable-props.svelte

@@ -0,0 +1,18 @@
+<!-- should not generate diagnostics -->
+<!-- Regression test: $bindable() props that are only written to in the script should  -->
+<!-- not be flagged as unused. In Svelte 5, assigning to a $bindable() prop reflects  -->
+<!-- the value back to the parent component, so write-only usage is intentional.       -->
+<script>
+	let {
+		backButton = $bindable(),
+		nextButton = $bindable(),
+	} = $props();
+
+	// backButton is only written to — intentional for a $bindable() prop.
+	backButton = { label: 'Back', onClick: () => {} };
+	backButton = { label: 'Cancel', onClick: () => {} };
+</script>
+
+{#if nextButton}
+	<button onclick={nextButton.onClick}>{nextButton.label ?? 'Next'}</button>
+{/if}

crates/biome_js_analyze/tests/specs/correctness/noUnusedVariables/valid-svelte-bindable-props.svelte.snap

@@ -0,0 +1,27 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+assertion_line: 149
+expression: valid-svelte-bindable-props.svelte
+---
+# Input
+```svelte
+<!-- should not generate diagnostics -->
+<!-- Regression test: $bindable() props that are only written to in the script should  -->
+<!-- not be flagged as unused. In Svelte 5, assigning to a $bindable() prop reflects  -->
+<!-- the value back to the parent component, so write-only usage is intentional.       -->
+<script>
+	let {
+		backButton = $bindable(),
+		nextButton = $bindable(),
+	} = $props();
+
+	// backButton is only written to — intentional for a $bindable() prop.
+	backButton = { label: 'Back', onClick: () => {} };
+	backButton = { label: 'Cancel', onClick: () => {} };
+</script>
+
+{#if nextButton}
+	<button onclick={nextButton.onClick}>{nextButton.label ?? 'Next'}</button>
+{/if}
+
+```

crates/biome_js_analyze/tests/specs/correctness/noUnusedVariables/valid-svelte-store-subscription.svelte

@@ -0,0 +1,15 @@
+<!-- should not generate diagnostics -->
+<!-- Regression test: $errors/$form in the template should suppress the -->
+<!-- "unused variable" diagnostic for the destructured `errors`/`form`  -->
+<!-- bindings in the script, even when $-prefixed references only appear  -->
+<!-- in the HTML template (not in the script block itself).              -->
+<script lang="ts">
+	import { superForm } from 'sveltekit-superforms';
+
+	const { form, errors, enhance } = superForm();
+</script>
+
+<form use:enhance>
+	<input bind:value={$form.email} />
+	<span>{$errors.email}</span>
+</form>

crates/biome_js_analyze/tests/specs/correctness/noUnusedVariables/valid-svelte-store-subscription.svelte.snap

@@ -0,0 +1,23 @@
+---
+source: crates/biome_js_analyze/tests/spec_tests.rs
+expression: valid-svelte-store-subscription.svelte
+---
+# Input
+```svelte
+<!-- should not generate diagnostics -->
+<!-- Regression test: $errors/$form in the template should suppress the -->
+<!-- "unused variable" diagnostic for the destructured `errors`/`form`  -->
+<!-- bindings in the script, even when $-prefixed references only appear  -->
+<!-- in the HTML template (not in the script block itself).              -->
+<script lang="ts">
+	import { superForm } from 'sveltekit-superforms';
+
+	const { form, errors, enhance } = superForm();
+</script>
+
+<form use:enhance>
+	<input bind:value={$form.email} />
+	<span>{$errors.email}</span>
+</form>
+
+```

crates/biome_workspace_db/src/embedded/references.rs

@@ -78,6 +78,51 @@ pub fn is_reference_used(db: &dyn LanguageDb, reference: InternedReference<'_>)
     })
 }
 
+/// Svelte stores are a special case. The `$` prefix is used to "dereference" the store and get its value.
+///
+/// See also: https://svelte.dev/docs/svelte/stores
+#[salsa::tracked]
+pub fn is_svelte_store_reference_used(
+    db: &dyn LanguageDb,
+    reference: InternedReference<'_>,
+) -> bool {
+    let Some(parsed_source) = db.parsed_source_for_path(reference.path(db)) else {
+        return false;
+    };
+
+    embedded_references_from_source(db, parsed_source)
+        .iter()
+        .any(|refs| {
+            refs.iter().any(|value_reference| {
+                svelte_store_reference_name(value_reference.text.text()).is_some_and(
+                    |reference_store_name| reference_store_name == reference.name(db).text(),
+                )
+            })
+        })
+}
+
+fn svelte_store_reference_name(reference_name: &str) -> Option<&str> {
+    // These are special Svelte runes that are not valid store names, so we should ignore them.
+    const SVELTE_RUNES: [&str; 7] = [
+        "$bindable",
+        "$derived",
+        "$effect",
+        "$host",
+        "$inspect",
+        "$props",
+        "$state",
+    ];
+
+    if SVELTE_RUNES.contains(&reference_name) {
+        return None;
+    }
+    let store_name = reference_name.strip_prefix('$')?;
+    if store_name.is_empty() || store_name.starts_with('$') {
+        return None;
+    }
+    Some(store_name)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;