From 6c90fd7b4c678d16d77ec58596c3f3600bb6d498 Mon Sep 17 00:00:00 2001
From: TKman <102001532+greekr4@users.noreply.github.com>
Date: Wed, 22 Jul 2026 18:09:34 +0900
Subject: [PATCH] docs: note exception-safe cleanup of JS Yoga trees

---
 website/docs/getting-started/laying-out-a-tree.mdx | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/website/docs/getting-started/laying-out-a-tree.mdx b/website/docs/getting-started/laying-out-a-tree.mdx
index 66d437d630..f87046b657 100644
--- a/website/docs/getting-started/laying-out-a-tree.mdx
+++ b/website/docs/getting-started/laying-out-a-tree.mdx
@@ -99,6 +99,18 @@ root.insertChild(child1, 1);
 
 Yoga Nodes are not freed automatically and should be discarded when no longer needed. Individual nodes may be freed by calling `node.free()`, or an entire Yoga tree may be freed by calling `node.freeRecursive()`.
 
+Nodes live in the WebAssembly heap, which is not visible to the JavaScript garbage collector. An application which repeatedly leaks nodes will grow the heap until new nodes fail to allocate. If an exception may be thrown after nodes are created (e.g. from within a [measure function](../advanced/external-layout-systems.mdx) during layout), freeing in a `finally` block guarantees the tree is released:
+
+```ts
+const root = buildYogaTree();
+try {
+  root.calculateLayout(undefined, undefined, Direction.LTR);
+  readLayoutResults(root);
+} finally {
+  root.freeRecursive();
+}
+```
+
 A future revision of JavaScript bindings for Yoga may move to garbage collection to remove this requirement.
 
 :::