breaking: rename $effect.active to $effect.tracking (#12022)

* breaking: rename $effect.active to $effect.tracking

* update type

* add more helpful error

* tweak changeset

* fix prettier config

---------

Co-authored-by: Rich Harris <[email protected]>

Author: trueadm

.changeset/khaki-cheetahs-refuse.md

@@ -0,0 +1,5 @@
+---
+"svelte": patch
+---
+
+breaking: rename `$effect.active` to `$effect.tracking`

.prettierignore

@@ -44,4 +44,4 @@ sites/svelte.dev/src/lib/generated
 .prettierignore
 .changeset
 pnpm-lock.yaml
-pnpm-workspace.yaml
+pnpm-workspace.yaml

packages/svelte/messages/compile-errors/script.md

@@ -114,6 +114,10 @@
 
 > Cannot use rune without parentheses
 
+## rune_renamed
+
+> `%name%` is now `%replacement%`
+
 ## runes_mode_invalid_import
 
 > %name% cannot be used in runes mode

packages/svelte/src/ambient.d.ts

@@ -201,26 +201,26 @@ declare namespace $effect {
 	export function pre(fn: () => void | (() => void)): void;
 
 	/**
-	 * The `$effect.active` rune is an advanced feature that tells you whether or not the code is running inside an effect or inside your template.
+	 * The `$effect.tracking` rune is an advanced feature that tells you whether or not the code is running inside a tracking context, such as an effect or inside your template.
 	 *
 	 * Example:
 	 * ```svelte
 	 * <script>
-	 *   console.log('in component setup:', $effect.active()); // false
+	 *   console.log('in component setup:', $effect.tracking()); // false
 	 *
 	 *   $effect(() => {
-	 *     console.log('in effect:', $effect.active()); // true
+	 *     console.log('in effect:', $effect.tracking()); // true
 	 *   });
 	 * </script>
 	 *
-	 * <p>in template: {$effect.active()}</p> <!-- true -->
+	 * <p>in template: {$effect.tracking()}</p> <!-- true -->
 	 * ```
 	 *
 	 * This allows you to (for example) add things like subscriptions without causing memory leaks, by putting them in child effects.
 	 *
-	 * https://svelte-5-preview.vercel.app/docs/runes#$effect-active
+	 * https://svelte-5-preview.vercel.app/docs/runes#$effect-tracking
 	 */
-	export function active(): boolean;
+	export function tracking(): boolean;
 
 	/**
 	 * The `$effect.root` rune is an advanced feature that creates a non-tracked scope that doesn't auto-cleanup. This is useful for

packages/svelte/src/compiler/errors.js

@@ -363,6 +363,17 @@ export function rune_missing_parentheses(node) {
 	e(node, "rune_missing_parentheses", "Cannot use rune without parentheses");
 }
 
+/**
+ * `%name%` is now `%replacement%`
+ * @param {null | number | NodeLike} node
+ * @param {string} name
+ * @param {string} replacement
+ * @returns {never}
+ */
+export function rune_renamed(node, name, replacement) {
+	e(node, "rune_renamed", `\`${name}\` is now \`${replacement}\``);
+}
+
 /**
  * %name% cannot be used in runes mode
  * @param {null | number | NodeLike} node

packages/svelte/src/compiler/phases/2-analyze/validation.js

@@ -880,7 +880,7 @@ function validate_call_expression(node, scope, path) {
 		}
 	}
 
-	if (rune === '$effect.active') {
+	if (rune === '$effect.tracking') {
 		if (node.arguments.length !== 0) {
 			e.rune_invalid_arguments(node, rune);
 		}
@@ -1141,6 +1141,10 @@ export const validation_runes = merge(validation, a11y_validators, {
 				parent = /** @type {import('estree').Expression} */ (path[--i]);
 
 				if (!Runes.includes(/** @type {Runes[number]} */ (name))) {
+					if (name === '$effect.active') {
+						e.rune_renamed(parent, '$effect.active', '$effect.tracking');
+					}
+
 					e.rune_invalid_name(parent, name);
 				}
 			}

packages/svelte/src/compiler/phases/3-transform/client/visitors/javascript-runes.js

@@ -215,7 +215,7 @@ export const javascript_visitors_runes = {
 			const rune = get_rune(init, state.scope);
 			if (
 				!rune ||
-				rune === '$effect.active' ||
+				rune === '$effect.tracking' ||
 				rune === '$effect.root' ||
 				rune === '$inspect' ||
 				rune === '$state.snapshot' ||
@@ -434,8 +434,8 @@ export const javascript_visitors_runes = {
 			return b.id('$$props.$$host');
 		}
 
-		if (rune === '$effect.active') {
-			return b.call('$.effect_active');
+		if (rune === '$effect.tracking') {
+			return b.call('$.effect_tracking');
 		}
 
 		if (rune === '$state.snapshot') {

packages/svelte/src/compiler/phases/3-transform/server/transform-server.js

@@ -407,7 +407,7 @@ const global_visitors = {
 			return b.id('undefined');
 		}
 
-		if (rune === '$effect.active') {
+		if (rune === '$effect.tracking') {
 			return b.literal(false);
 		}
 
@@ -571,7 +571,7 @@ const javascript_visitors_runes = {
 		for (const declarator of node.declarations) {
 			const init = declarator.init;
 			const rune = get_rune(init, state.scope);
-			if (!rune || rune === '$effect.active' || rune === '$inspect') {
+			if (!rune || rune === '$effect.tracking' || rune === '$inspect') {
 				declarations.push(/** @type {import('estree').VariableDeclarator} */ (visit(declarator)));
 				continue;
 			}

packages/svelte/src/compiler/phases/constants.js

@@ -39,7 +39,7 @@ export const Runes = /** @type {const} */ ([
 	'$derived.by',
 	'$effect',
 	'$effect.pre',
-	'$effect.active',
+	'$effect.tracking',
 	'$effect.root',
 	'$inspect',
 	'$inspect().with',

packages/svelte/src/internal/client/index.js

@@ -90,7 +90,7 @@ export {
 } from './dom/template.js';
 export { derived, derived_safe_equal } from './reactivity/deriveds.js';
 export {
-	effect_active,
+	effect_tracking,
 	effect_root,
 	legacy_pre_effect,
 	legacy_pre_effect_reset,