From 2e619e5512d7a8c330d74b85527bb28d9c818159 Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Sat, 23 Aug 2025 21:46:01 -0700
Subject: [PATCH 01/37] start of v2 structure
---
.../advanced-concepts/data.json | 0
.../fine-grained-reactivity.mdx | 0
.../concepts/components/basics.mdx | 0
.../concepts/components/class-style.mdx | 0
.../concepts/components/data.json | 0
.../concepts/components/event-handlers.mdx | 0
.../concepts/components/props.mdx | 0
.../routes => old pages}/concepts/context.mdx | 0
.../control-flow/conditional-rendering.mdx | 0
.../concepts/control-flow/data.json | 0
.../concepts/control-flow/dynamic.mdx | 0
.../concepts/control-flow/error-boundary.mdx | 0
.../concepts/control-flow/list-rendering.mdx | 0
.../concepts/control-flow/portal.mdx | 0
{src/routes => old pages}/concepts/data.json | 0
.../concepts/derived-values/data.json | 0
.../derived-values/derived-signals.mdx | 0
.../concepts/derived-values/memos.mdx | 0
.../routes => old pages}/concepts/effects.mdx | 0
.../concepts/intro-to-reactivity.mdx | 0
{src/routes => old pages}/concepts/refs.mdx | 0
.../routes => old pages}/concepts/signals.mdx | 0
{src/routes => old pages}/concepts/stores.mdx | 0
.../concepts/understanding-jsx.mdx | 0
.../configuration/data.json | 0
.../configuration/environment-variables.mdx | 0
.../configuration/typescript.mdx | 0
.../guides/complex-state-management.mdx | 0
old pages/guides/data.json | 14 ++++
.../guides/deploying-your-app.mdx | 0
.../aws-via-flightcontrol.mdx | 0
.../guides/deployment-options/aws-via-sst.mdx | 0
.../guides/deployment-options/cloudflare.mdx | 0
.../guides/deployment-options/data.json | 0
.../guides/deployment-options/firebase.mdx | 0
.../guides/deployment-options/netlify.mdx | 0
.../guides/deployment-options/railway.mdx | 0
.../guides/deployment-options/stormkit.mdx | 0
.../guides/deployment-options/vercel.mdx | 0
.../guides/deployment-options/zerops.mdx | 0
.../guides/fetching-data.mdx | 0
.../guides/routing-and-navigation.mdx | 0
.../guides/state-management.mdx | 0
.../guides/styling-components/css-modules.mdx | 0
.../guides/styling-components/data.json | 0
.../guides/styling-components/less.mdx | 0
.../guides/styling-components/macaron.mdx | 0
.../guides/styling-components/sass.mdx | 0
.../guides/styling-components/tailwind-v3.mdx | 0
.../guides/styling-components/tailwind.mdx | 0
.../guides/styling-components/uno.mdx | 0
.../guides/styling-your-components.mdx | 0
{src/routes => old pages}/guides/testing.mdx | 0
{src/routes => old pages}/quick-start.mdx | 0
package.json | 2 +-
src/routes/advanced/data.json | 4 +
src/routes/components/data.json | 4 +
src/routes/control-flow/data.json | 4 +
src/routes/data.json | 13 ++--
src/routes/getting-started/counter.mdx | 12 +++
src/routes/getting-started/data.json | 4 +
src/routes/getting-started/quick-start.mdx | 26 +++++++
src/routes/getting-started/todo.mdx | 15 ++++
src/routes/guides/data.json | 12 +--
src/routes/index.mdx | 2 +
src/routes/intro.mdx | 35 +++++++++
src/routes/reactivity/data.json | 12 +++
src/routes/reactivity/effects.mdx | 12 +++
src/routes/reactivity/how-to/async-data.mdx | 8 ++
src/routes/reactivity/how-to/data.json | 4 +
.../reactivity/how-to/debug-reactivity.mdx | 4 +
.../reactivity/how-to/derived-signals.mdx | 11 +++
src/routes/reactivity/memos.mdx | 11 +++
src/routes/reactivity/overview.mdx | 74 +++++++++++++++++++
src/routes/reactivity/resources.mdx | 8 ++
src/routes/reactivity/signals.mdx | 10 +++
src/routes/reactivity/stores.mdx | 4 +
src/routes/rendering/data.json | 4 +
78 files changed, 292 insertions(+), 17 deletions(-)
rename {src/routes => old pages}/advanced-concepts/data.json (100%)
rename {src/routes => old pages}/advanced-concepts/fine-grained-reactivity.mdx (100%)
rename {src/routes => old pages}/concepts/components/basics.mdx (100%)
rename {src/routes => old pages}/concepts/components/class-style.mdx (100%)
rename {src/routes => old pages}/concepts/components/data.json (100%)
rename {src/routes => old pages}/concepts/components/event-handlers.mdx (100%)
rename {src/routes => old pages}/concepts/components/props.mdx (100%)
rename {src/routes => old pages}/concepts/context.mdx (100%)
rename {src/routes => old pages}/concepts/control-flow/conditional-rendering.mdx (100%)
rename {src/routes => old pages}/concepts/control-flow/data.json (100%)
rename {src/routes => old pages}/concepts/control-flow/dynamic.mdx (100%)
rename {src/routes => old pages}/concepts/control-flow/error-boundary.mdx (100%)
rename {src/routes => old pages}/concepts/control-flow/list-rendering.mdx (100%)
rename {src/routes => old pages}/concepts/control-flow/portal.mdx (100%)
rename {src/routes => old pages}/concepts/data.json (100%)
rename {src/routes => old pages}/concepts/derived-values/data.json (100%)
rename {src/routes => old pages}/concepts/derived-values/derived-signals.mdx (100%)
rename {src/routes => old pages}/concepts/derived-values/memos.mdx (100%)
rename {src/routes => old pages}/concepts/effects.mdx (100%)
rename {src/routes => old pages}/concepts/intro-to-reactivity.mdx (100%)
rename {src/routes => old pages}/concepts/refs.mdx (100%)
rename {src/routes => old pages}/concepts/signals.mdx (100%)
rename {src/routes => old pages}/concepts/stores.mdx (100%)
rename {src/routes => old pages}/concepts/understanding-jsx.mdx (100%)
rename {src/routes => old pages}/configuration/data.json (100%)
rename {src/routes => old pages}/configuration/environment-variables.mdx (100%)
rename {src/routes => old pages}/configuration/typescript.mdx (100%)
rename {src/routes => old pages}/guides/complex-state-management.mdx (100%)
create mode 100644 old pages/guides/data.json
rename {src/routes => old pages}/guides/deploying-your-app.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/aws-via-flightcontrol.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/aws-via-sst.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/cloudflare.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/data.json (100%)
rename {src/routes => old pages}/guides/deployment-options/firebase.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/netlify.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/railway.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/stormkit.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/vercel.mdx (100%)
rename {src/routes => old pages}/guides/deployment-options/zerops.mdx (100%)
rename {src/routes => old pages}/guides/fetching-data.mdx (100%)
rename {src/routes => old pages}/guides/routing-and-navigation.mdx (100%)
rename {src/routes => old pages}/guides/state-management.mdx (100%)
rename {src/routes => old pages}/guides/styling-components/css-modules.mdx (100%)
rename {src/routes => old pages}/guides/styling-components/data.json (100%)
rename {src/routes => old pages}/guides/styling-components/less.mdx (100%)
rename {src/routes => old pages}/guides/styling-components/macaron.mdx (100%)
rename {src/routes => old pages}/guides/styling-components/sass.mdx (100%)
rename {src/routes => old pages}/guides/styling-components/tailwind-v3.mdx (100%)
rename {src/routes => old pages}/guides/styling-components/tailwind.mdx (100%)
rename {src/routes => old pages}/guides/styling-components/uno.mdx (100%)
rename {src/routes => old pages}/guides/styling-your-components.mdx (100%)
rename {src/routes => old pages}/guides/testing.mdx (100%)
rename {src/routes => old pages}/quick-start.mdx (100%)
create mode 100644 src/routes/advanced/data.json
create mode 100644 src/routes/components/data.json
create mode 100644 src/routes/control-flow/data.json
create mode 100644 src/routes/getting-started/counter.mdx
create mode 100644 src/routes/getting-started/data.json
create mode 100644 src/routes/getting-started/quick-start.mdx
create mode 100644 src/routes/getting-started/todo.mdx
create mode 100644 src/routes/intro.mdx
create mode 100644 src/routes/reactivity/data.json
create mode 100644 src/routes/reactivity/effects.mdx
create mode 100644 src/routes/reactivity/how-to/async-data.mdx
create mode 100644 src/routes/reactivity/how-to/data.json
create mode 100644 src/routes/reactivity/how-to/debug-reactivity.mdx
create mode 100644 src/routes/reactivity/how-to/derived-signals.mdx
create mode 100644 src/routes/reactivity/memos.mdx
create mode 100644 src/routes/reactivity/overview.mdx
create mode 100644 src/routes/reactivity/resources.mdx
create mode 100644 src/routes/reactivity/signals.mdx
create mode 100644 src/routes/reactivity/stores.mdx
create mode 100644 src/routes/rendering/data.json
diff --git a/src/routes/advanced-concepts/data.json b/old pages/advanced-concepts/data.json
similarity index 100%
rename from src/routes/advanced-concepts/data.json
rename to old pages/advanced-concepts/data.json
diff --git a/src/routes/advanced-concepts/fine-grained-reactivity.mdx b/old pages/advanced-concepts/fine-grained-reactivity.mdx
similarity index 100%
rename from src/routes/advanced-concepts/fine-grained-reactivity.mdx
rename to old pages/advanced-concepts/fine-grained-reactivity.mdx
diff --git a/src/routes/concepts/components/basics.mdx b/old pages/concepts/components/basics.mdx
similarity index 100%
rename from src/routes/concepts/components/basics.mdx
rename to old pages/concepts/components/basics.mdx
diff --git a/src/routes/concepts/components/class-style.mdx b/old pages/concepts/components/class-style.mdx
similarity index 100%
rename from src/routes/concepts/components/class-style.mdx
rename to old pages/concepts/components/class-style.mdx
diff --git a/src/routes/concepts/components/data.json b/old pages/concepts/components/data.json
similarity index 100%
rename from src/routes/concepts/components/data.json
rename to old pages/concepts/components/data.json
diff --git a/src/routes/concepts/components/event-handlers.mdx b/old pages/concepts/components/event-handlers.mdx
similarity index 100%
rename from src/routes/concepts/components/event-handlers.mdx
rename to old pages/concepts/components/event-handlers.mdx
diff --git a/src/routes/concepts/components/props.mdx b/old pages/concepts/components/props.mdx
similarity index 100%
rename from src/routes/concepts/components/props.mdx
rename to old pages/concepts/components/props.mdx
diff --git a/src/routes/concepts/context.mdx b/old pages/concepts/context.mdx
similarity index 100%
rename from src/routes/concepts/context.mdx
rename to old pages/concepts/context.mdx
diff --git a/src/routes/concepts/control-flow/conditional-rendering.mdx b/old pages/concepts/control-flow/conditional-rendering.mdx
similarity index 100%
rename from src/routes/concepts/control-flow/conditional-rendering.mdx
rename to old pages/concepts/control-flow/conditional-rendering.mdx
diff --git a/src/routes/concepts/control-flow/data.json b/old pages/concepts/control-flow/data.json
similarity index 100%
rename from src/routes/concepts/control-flow/data.json
rename to old pages/concepts/control-flow/data.json
diff --git a/src/routes/concepts/control-flow/dynamic.mdx b/old pages/concepts/control-flow/dynamic.mdx
similarity index 100%
rename from src/routes/concepts/control-flow/dynamic.mdx
rename to old pages/concepts/control-flow/dynamic.mdx
diff --git a/src/routes/concepts/control-flow/error-boundary.mdx b/old pages/concepts/control-flow/error-boundary.mdx
similarity index 100%
rename from src/routes/concepts/control-flow/error-boundary.mdx
rename to old pages/concepts/control-flow/error-boundary.mdx
diff --git a/src/routes/concepts/control-flow/list-rendering.mdx b/old pages/concepts/control-flow/list-rendering.mdx
similarity index 100%
rename from src/routes/concepts/control-flow/list-rendering.mdx
rename to old pages/concepts/control-flow/list-rendering.mdx
diff --git a/src/routes/concepts/control-flow/portal.mdx b/old pages/concepts/control-flow/portal.mdx
similarity index 100%
rename from src/routes/concepts/control-flow/portal.mdx
rename to old pages/concepts/control-flow/portal.mdx
diff --git a/src/routes/concepts/data.json b/old pages/concepts/data.json
similarity index 100%
rename from src/routes/concepts/data.json
rename to old pages/concepts/data.json
diff --git a/src/routes/concepts/derived-values/data.json b/old pages/concepts/derived-values/data.json
similarity index 100%
rename from src/routes/concepts/derived-values/data.json
rename to old pages/concepts/derived-values/data.json
diff --git a/src/routes/concepts/derived-values/derived-signals.mdx b/old pages/concepts/derived-values/derived-signals.mdx
similarity index 100%
rename from src/routes/concepts/derived-values/derived-signals.mdx
rename to old pages/concepts/derived-values/derived-signals.mdx
diff --git a/src/routes/concepts/derived-values/memos.mdx b/old pages/concepts/derived-values/memos.mdx
similarity index 100%
rename from src/routes/concepts/derived-values/memos.mdx
rename to old pages/concepts/derived-values/memos.mdx
diff --git a/src/routes/concepts/effects.mdx b/old pages/concepts/effects.mdx
similarity index 100%
rename from src/routes/concepts/effects.mdx
rename to old pages/concepts/effects.mdx
diff --git a/src/routes/concepts/intro-to-reactivity.mdx b/old pages/concepts/intro-to-reactivity.mdx
similarity index 100%
rename from src/routes/concepts/intro-to-reactivity.mdx
rename to old pages/concepts/intro-to-reactivity.mdx
diff --git a/src/routes/concepts/refs.mdx b/old pages/concepts/refs.mdx
similarity index 100%
rename from src/routes/concepts/refs.mdx
rename to old pages/concepts/refs.mdx
diff --git a/src/routes/concepts/signals.mdx b/old pages/concepts/signals.mdx
similarity index 100%
rename from src/routes/concepts/signals.mdx
rename to old pages/concepts/signals.mdx
diff --git a/src/routes/concepts/stores.mdx b/old pages/concepts/stores.mdx
similarity index 100%
rename from src/routes/concepts/stores.mdx
rename to old pages/concepts/stores.mdx
diff --git a/src/routes/concepts/understanding-jsx.mdx b/old pages/concepts/understanding-jsx.mdx
similarity index 100%
rename from src/routes/concepts/understanding-jsx.mdx
rename to old pages/concepts/understanding-jsx.mdx
diff --git a/src/routes/configuration/data.json b/old pages/configuration/data.json
similarity index 100%
rename from src/routes/configuration/data.json
rename to old pages/configuration/data.json
diff --git a/src/routes/configuration/environment-variables.mdx b/old pages/configuration/environment-variables.mdx
similarity index 100%
rename from src/routes/configuration/environment-variables.mdx
rename to old pages/configuration/environment-variables.mdx
diff --git a/src/routes/configuration/typescript.mdx b/old pages/configuration/typescript.mdx
similarity index 100%
rename from src/routes/configuration/typescript.mdx
rename to old pages/configuration/typescript.mdx
diff --git a/src/routes/guides/complex-state-management.mdx b/old pages/guides/complex-state-management.mdx
similarity index 100%
rename from src/routes/guides/complex-state-management.mdx
rename to old pages/guides/complex-state-management.mdx
diff --git a/old pages/guides/data.json b/old pages/guides/data.json
new file mode 100644
index 000000000..364f3f925
--- /dev/null
+++ b/old pages/guides/data.json
@@ -0,0 +1,14 @@
+{
+ "title": "Guides",
+ "pages": [
+ "styling-your-components.mdx",
+ "styling-components",
+ "state-management.mdx",
+ "routing-and-navigation.mdx",
+ "complex-state-management.mdx",
+ "fetching-data.mdx",
+ "testing.mdx",
+ "deploying-your-app.mdx",
+ "deployment-options"
+ ]
+}
diff --git a/src/routes/guides/deploying-your-app.mdx b/old pages/guides/deploying-your-app.mdx
similarity index 100%
rename from src/routes/guides/deploying-your-app.mdx
rename to old pages/guides/deploying-your-app.mdx
diff --git a/src/routes/guides/deployment-options/aws-via-flightcontrol.mdx b/old pages/guides/deployment-options/aws-via-flightcontrol.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/aws-via-flightcontrol.mdx
rename to old pages/guides/deployment-options/aws-via-flightcontrol.mdx
diff --git a/src/routes/guides/deployment-options/aws-via-sst.mdx b/old pages/guides/deployment-options/aws-via-sst.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/aws-via-sst.mdx
rename to old pages/guides/deployment-options/aws-via-sst.mdx
diff --git a/src/routes/guides/deployment-options/cloudflare.mdx b/old pages/guides/deployment-options/cloudflare.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/cloudflare.mdx
rename to old pages/guides/deployment-options/cloudflare.mdx
diff --git a/src/routes/guides/deployment-options/data.json b/old pages/guides/deployment-options/data.json
similarity index 100%
rename from src/routes/guides/deployment-options/data.json
rename to old pages/guides/deployment-options/data.json
diff --git a/src/routes/guides/deployment-options/firebase.mdx b/old pages/guides/deployment-options/firebase.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/firebase.mdx
rename to old pages/guides/deployment-options/firebase.mdx
diff --git a/src/routes/guides/deployment-options/netlify.mdx b/old pages/guides/deployment-options/netlify.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/netlify.mdx
rename to old pages/guides/deployment-options/netlify.mdx
diff --git a/src/routes/guides/deployment-options/railway.mdx b/old pages/guides/deployment-options/railway.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/railway.mdx
rename to old pages/guides/deployment-options/railway.mdx
diff --git a/src/routes/guides/deployment-options/stormkit.mdx b/old pages/guides/deployment-options/stormkit.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/stormkit.mdx
rename to old pages/guides/deployment-options/stormkit.mdx
diff --git a/src/routes/guides/deployment-options/vercel.mdx b/old pages/guides/deployment-options/vercel.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/vercel.mdx
rename to old pages/guides/deployment-options/vercel.mdx
diff --git a/src/routes/guides/deployment-options/zerops.mdx b/old pages/guides/deployment-options/zerops.mdx
similarity index 100%
rename from src/routes/guides/deployment-options/zerops.mdx
rename to old pages/guides/deployment-options/zerops.mdx
diff --git a/src/routes/guides/fetching-data.mdx b/old pages/guides/fetching-data.mdx
similarity index 100%
rename from src/routes/guides/fetching-data.mdx
rename to old pages/guides/fetching-data.mdx
diff --git a/src/routes/guides/routing-and-navigation.mdx b/old pages/guides/routing-and-navigation.mdx
similarity index 100%
rename from src/routes/guides/routing-and-navigation.mdx
rename to old pages/guides/routing-and-navigation.mdx
diff --git a/src/routes/guides/state-management.mdx b/old pages/guides/state-management.mdx
similarity index 100%
rename from src/routes/guides/state-management.mdx
rename to old pages/guides/state-management.mdx
diff --git a/src/routes/guides/styling-components/css-modules.mdx b/old pages/guides/styling-components/css-modules.mdx
similarity index 100%
rename from src/routes/guides/styling-components/css-modules.mdx
rename to old pages/guides/styling-components/css-modules.mdx
diff --git a/src/routes/guides/styling-components/data.json b/old pages/guides/styling-components/data.json
similarity index 100%
rename from src/routes/guides/styling-components/data.json
rename to old pages/guides/styling-components/data.json
diff --git a/src/routes/guides/styling-components/less.mdx b/old pages/guides/styling-components/less.mdx
similarity index 100%
rename from src/routes/guides/styling-components/less.mdx
rename to old pages/guides/styling-components/less.mdx
diff --git a/src/routes/guides/styling-components/macaron.mdx b/old pages/guides/styling-components/macaron.mdx
similarity index 100%
rename from src/routes/guides/styling-components/macaron.mdx
rename to old pages/guides/styling-components/macaron.mdx
diff --git a/src/routes/guides/styling-components/sass.mdx b/old pages/guides/styling-components/sass.mdx
similarity index 100%
rename from src/routes/guides/styling-components/sass.mdx
rename to old pages/guides/styling-components/sass.mdx
diff --git a/src/routes/guides/styling-components/tailwind-v3.mdx b/old pages/guides/styling-components/tailwind-v3.mdx
similarity index 100%
rename from src/routes/guides/styling-components/tailwind-v3.mdx
rename to old pages/guides/styling-components/tailwind-v3.mdx
diff --git a/src/routes/guides/styling-components/tailwind.mdx b/old pages/guides/styling-components/tailwind.mdx
similarity index 100%
rename from src/routes/guides/styling-components/tailwind.mdx
rename to old pages/guides/styling-components/tailwind.mdx
diff --git a/src/routes/guides/styling-components/uno.mdx b/old pages/guides/styling-components/uno.mdx
similarity index 100%
rename from src/routes/guides/styling-components/uno.mdx
rename to old pages/guides/styling-components/uno.mdx
diff --git a/src/routes/guides/styling-your-components.mdx b/old pages/guides/styling-your-components.mdx
similarity index 100%
rename from src/routes/guides/styling-your-components.mdx
rename to old pages/guides/styling-your-components.mdx
diff --git a/src/routes/guides/testing.mdx b/old pages/guides/testing.mdx
similarity index 100%
rename from src/routes/guides/testing.mdx
rename to old pages/guides/testing.mdx
diff --git a/src/routes/quick-start.mdx b/old pages/quick-start.mdx
similarity index 100%
rename from src/routes/quick-start.mdx
rename to old pages/quick-start.mdx
diff --git a/package.json b/package.json
index 238a4b94d..00e10cf87 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "solid-docs-next",
- "version": "1.0.0",
+ "version": "2.0.0",
"private": true,
"description": "Docs for Solid",
"type": "module",
diff --git a/src/routes/advanced/data.json b/src/routes/advanced/data.json
new file mode 100644
index 000000000..89c57710b
--- /dev/null
+++ b/src/routes/advanced/data.json
@@ -0,0 +1,4 @@
+{
+ "title": "Advanced Concepts",
+ "pages": []
+}
diff --git a/src/routes/components/data.json b/src/routes/components/data.json
new file mode 100644
index 000000000..f675b706b
--- /dev/null
+++ b/src/routes/components/data.json
@@ -0,0 +1,4 @@
+{
+ "title": "Components",
+ "pages": []
+}
diff --git a/src/routes/control-flow/data.json b/src/routes/control-flow/data.json
new file mode 100644
index 000000000..91d5713a5
--- /dev/null
+++ b/src/routes/control-flow/data.json
@@ -0,0 +1,4 @@
+{
+ "title": "Control Flow",
+ "pages": []
+}
diff --git a/src/routes/data.json b/src/routes/data.json
index 5c04652ac..5091d9eaa 100644
--- a/src/routes/data.json
+++ b/src/routes/data.json
@@ -2,10 +2,13 @@
"title": "root",
"pages": [
"index.mdx",
- "quick-start.mdx",
- "concepts",
- "advanced-concepts",
- "guides",
- "configuration"
+ "intro.mdx",
+ "getting-started",
+ "reactivity",
+ "components",
+ "control-flow",
+ "rendering",
+ "advanced",
+ "guides"
]
}
diff --git a/src/routes/getting-started/counter.mdx b/src/routes/getting-started/counter.mdx
new file mode 100644
index 000000000..ee8d28182
--- /dev/null
+++ b/src/routes/getting-started/counter.mdx
@@ -0,0 +1,12 @@
+---
+title: "Counter Tutorial"
+order: 2
+---
+
+[TODO]
+
+1. Open your newly scaffolded project in your code editor of choice.
+2. Create a new file called `Counter.jsx` in the `src/components` directory.
+3. In `Counter.tsx`, use Solid's `createSignal` to create a reactive counter state.
+4. Export the `Counter` component and import it into your main application file (e.g., `src/App.jsx`).
+5. Use the `Counter` component in your application and test its functionality.
\ No newline at end of file
diff --git a/src/routes/getting-started/data.json b/src/routes/getting-started/data.json
new file mode 100644
index 000000000..4b2a8a548
--- /dev/null
+++ b/src/routes/getting-started/data.json
@@ -0,0 +1,4 @@
+{
+ "title": "Getting Started",
+ "pages": ["quick-start.mdx", "counter.mdx", "todo.mdx"]
+}
diff --git a/src/routes/getting-started/quick-start.mdx b/src/routes/getting-started/quick-start.mdx
new file mode 100644
index 000000000..4e5a93110
--- /dev/null
+++ b/src/routes/getting-started/quick-start.mdx
@@ -0,0 +1,26 @@
+---
+title: Quick Start Guide
+order: 1
+---
+
+The fastest way to try Solid is to create a new project and run it locally.
+In just a few minutes, you’ll have a working Solid app running in your browser.
+
+## Solid in your Browser
+
+If you're looking to experiment with Solid without setting up a local environment, open the [Solid Playground](https://playground.solidjs.com/) in your browser.
+
+If you prefer a more complete development setup, you can use the StackBlitz [Javascript](https://stackblitz.com/github/solidjs/templates/tree/master/js) or [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) templates.
+
+## Create a New Project
+
+:::note[Before You Begin]
+Make sure you have a recent version of your prefer JavaScript runtime installed, such as [Node.js](https://nodejs.org/en), [Bun](https://bun.sh/), or [Deno](https://deno.com/).
+:::
+
+[TODO]
+
+- Navigate to directory and run command
+- CLI will take you through options
+- Once you've selected your options, the CLI will prompt you to install the dependencies and start the development server
+- Open browser and navigate to the provided local URL to see your new Solid app in action!
\ No newline at end of file
diff --git a/src/routes/getting-started/todo.mdx b/src/routes/getting-started/todo.mdx
new file mode 100644
index 000000000..4e031d3d1
--- /dev/null
+++ b/src/routes/getting-started/todo.mdx
@@ -0,0 +1,15 @@
+---
+title: Todo Tutorial
+order: 3
+---
+
+[TODO]
+
+1. Open your newly scaffolded project in your code editor of choice.
+
+- Signal to track all tasks
+- Function to add a new task
+- Function to remove a task
+- Function to toggle task completion
+- Show number of completed tasks
+- Show number of tasks
\ No newline at end of file
diff --git a/src/routes/guides/data.json b/src/routes/guides/data.json
index 364f3f925..88ddc06cb 100644
--- a/src/routes/guides/data.json
+++ b/src/routes/guides/data.json
@@ -1,14 +1,4 @@
{
"title": "Guides",
- "pages": [
- "styling-your-components.mdx",
- "styling-components",
- "state-management.mdx",
- "routing-and-navigation.mdx",
- "complex-state-management.mdx",
- "fetching-data.mdx",
- "testing.mdx",
- "deploying-your-app.mdx",
- "deployment-options"
- ]
+ "pages": []
}
diff --git a/src/routes/index.mdx b/src/routes/index.mdx
index bc137a50e..2be7028b9 100644
--- a/src/routes/index.mdx
+++ b/src/routes/index.mdx
@@ -3,6 +3,8 @@ title: Overview
mainNavExclude: true
---
+[TODO: Convert to landing page. Move any relevant info into Solid Info]
+
# Overview
Solid is a modern JavaScript framework designed to build responsive and high-performing user interfaces (UI).
diff --git a/src/routes/intro.mdx b/src/routes/intro.mdx
new file mode 100644
index 000000000..1809b9ecf
--- /dev/null
+++ b/src/routes/intro.mdx
@@ -0,0 +1,35 @@
+---
+title: Intro to Solid
+order: 1
+---
+
+[TODO:
+- Input on what should be included in a Solid intro
+- Answer questions such as: (maybe)
+ - What are the key features of Solid?
+ - Why use
+ - What are the benefits of using Solid?
+ - Ecosystem
+]
+
+Solid is a modern JavaScript framework designed to build responsive and high-performing user interfaces.
+It prioritizes a simple, yet predictable, developer experience, making it a great choice for developers of all skill levels.
+
+## What is Solid?
+
+As a JavaScript framework, Solid embraces reactivity and fine-grained updates.
+What this means is that Solid can efficiently update the user interface by only re-rendering the parts of the UI that have changed, rather than the entire page.
+
+Traditionally, when a change occurs, the entire page would need to reload to display the updated information.
+With Solid's fine-grained reactive system, updates are only applied to the parts of the page that need to be updated.
+This decreases work and can result in faster load times as well as a smoother user experience overall.
+
+## The Mental Model
+
+[TODO: Simple explanation of the mental model behind Solid]
+
+## Where to Go Next
+
+- [Quick Start Guide](https://solidjs.com/docs/getting-started)
+- [Reactivity Overview](/concepts/reactivity/)
+- [Component Overview](/concepts/components/)
\ No newline at end of file
diff --git a/src/routes/reactivity/data.json b/src/routes/reactivity/data.json
new file mode 100644
index 000000000..cf237240a
--- /dev/null
+++ b/src/routes/reactivity/data.json
@@ -0,0 +1,12 @@
+{
+ "title": "Reactivity",
+ "pages": [
+ "overview.mdx",
+ "signals.mdx",
+ "memos.mdx",
+ "effects.mdx",
+ "stores.mdx",
+ "resources.mdx",
+ "how-to"
+ ]
+}
diff --git a/src/routes/reactivity/effects.mdx b/src/routes/reactivity/effects.mdx
new file mode 100644
index 000000000..64f626609
--- /dev/null
+++ b/src/routes/reactivity/effects.mdx
@@ -0,0 +1,12 @@
+---
+title: "Effects"
+order: 4
+---
+
+[TODO:
+Concept page for Effects
+- What are Effects
+- How to use them
+- When to use Effects
+- Move relevant sections to ref and vice versa
+]
\ No newline at end of file
diff --git a/src/routes/reactivity/how-to/async-data.mdx b/src/routes/reactivity/how-to/async-data.mdx
new file mode 100644
index 000000000..f8ba4a246
--- /dev/null
+++ b/src/routes/reactivity/how-to/async-data.mdx
@@ -0,0 +1,8 @@
+---
+title: "Async Data"
+order: 2
+---
+
+[TODO:
+How to work with async Data
+]
\ No newline at end of file
diff --git a/src/routes/reactivity/how-to/data.json b/src/routes/reactivity/how-to/data.json
new file mode 100644
index 000000000..53d08c540
--- /dev/null
+++ b/src/routes/reactivity/how-to/data.json
@@ -0,0 +1,4 @@
+{
+ "title": "How To",
+ "pages": ["derived-signals.mdx", "async-data.mdx", "debug-reactivity.mdx"]
+}
diff --git a/src/routes/reactivity/how-to/debug-reactivity.mdx b/src/routes/reactivity/how-to/debug-reactivity.mdx
new file mode 100644
index 000000000..28ad0f70b
--- /dev/null
+++ b/src/routes/reactivity/how-to/debug-reactivity.mdx
@@ -0,0 +1,4 @@
+---
+title: "Debugging Reactivity"
+order: 3
+---
diff --git a/src/routes/reactivity/how-to/derived-signals.mdx b/src/routes/reactivity/how-to/derived-signals.mdx
new file mode 100644
index 000000000..59dd72745
--- /dev/null
+++ b/src/routes/reactivity/how-to/derived-signals.mdx
@@ -0,0 +1,11 @@
+---
+title: "Derived Signals"
+order: 1
+---
+
+[TODO:
+How to create derived signals
+- when to use
+- how to use
+- examples
+]
\ No newline at end of file
diff --git a/src/routes/reactivity/memos.mdx b/src/routes/reactivity/memos.mdx
new file mode 100644
index 000000000..bdaf190ab
--- /dev/null
+++ b/src/routes/reactivity/memos.mdx
@@ -0,0 +1,11 @@
+---
+title: "Memos"
+order: 3
+---
+
+[TODO:
+Concept page on Memos
+- Improve on existing page
+- Move relevant sections to reference and vice versa
+- Link out to how-to for derived signals where appropriate
+]
\ No newline at end of file
diff --git a/src/routes/reactivity/overview.mdx b/src/routes/reactivity/overview.mdx
new file mode 100644
index 000000000..725a2186c
--- /dev/null
+++ b/src/routes/reactivity/overview.mdx
@@ -0,0 +1,74 @@
+---
+title: "Overview"
+order: 1
+---
+
+[TODO: Review]
+
+:::note
+While this guide can be helpful for understanding reactive systems, it does use some Solid-specific terminology and concepts.
+:::
+
+Reactivity is what powers the interactivity of Solid apps.
+This programming paradigm refers to a system's ability to respond to changes in data, or state, automatically and efficiently.
+Solid is built with reactivity at the core of its design, assisting applications with staying up-to-date with its underlying data.
+
+## The Importance of Reactivity
+
+Reactivity is what keeps the user interface (UI) in sync with the underlying application state.
+When the state changes, the UI is automatically updated, reducing the need for manual updates.
+
+In addition, reactivity enables real-time updates, allowing applications to reflect changes instantly without requiring a full page refresh.
+This helps with creating more responsive and interactive user experiences.
+
+As an example, when building a Counter, you can use the reactive primitives provided by Solid to create a counter.
+Once the counter is set up, whenever the count changes, the UI will automatically update to reflect the new count:
+
+```tsx
+function Counter() {
+ const [count, setCount] = createSignal(0);
+ const increment = () => setCount((prev) => prev + 1);
+
+ return (
+
+ Count: {count()}{" "}
+ {/* Only `count()` is updated when the button is clicked. */}
+
+
+ );
+}
+```
+
+## Reactive Principles
+
+### Signals
+
+Signals serve as the core elements within a reactive system.
+They play a crucial role in tracking and managing state changes, allowing the UI to respond automatically when the underlying data changes.
+They are responsible for storing and managing data, as well as triggering updates across the system.
+
+Signals are able to achieve this reactivity through the use of:
+
+- **Getters**: A function responsible for retrieving the current value of a signal.
+When called within a reactive context, it will give access to the current value of the signal.
+- **Setters**: This function is responsible for updating the value of a signal.
+To trigger reactivity, setters notify the system that the signal's value has changed, prompting anything that depends on the signal to re-evaluate and update accordingly.
+
+
+
+### Subscribers
+
+Subscribers refer to other reactive contexts or components that depend on the value of a signal.
+These automated responders keep the system up-to-date by re-evaluating and updating whenever the signal's value changes.
+
+Subscribers work based on two main actions:
+- **Observation**: The core function of a subscriber is to observe signals.
+This keeps the subscriber informed about any changes to the signal(s) they're tracking.
+- **Respond**: Once the signal has updated and the subscriber is notified, it triggers a re-evaluation of the dependent computations or UI updates.
+
+[TODO: Some kind of image / code block??]
\ No newline at end of file
diff --git a/src/routes/reactivity/resources.mdx b/src/routes/reactivity/resources.mdx
new file mode 100644
index 000000000..143db8236
--- /dev/null
+++ b/src/routes/reactivity/resources.mdx
@@ -0,0 +1,8 @@
+---
+title: "Resources"
+order: 6
+---
+
+[TODO:
+Concept page on Resource
+]
\ No newline at end of file
diff --git a/src/routes/reactivity/signals.mdx b/src/routes/reactivity/signals.mdx
new file mode 100644
index 000000000..701839712
--- /dev/null
+++ b/src/routes/reactivity/signals.mdx
@@ -0,0 +1,10 @@
+---
+title: "Signals"
+order: 2
+---
+
+[TODO:
+Concept page on signals
+- Any complex parts should be moved to reference section
+- Move any concept bits from reference section into here
+]
\ No newline at end of file
diff --git a/src/routes/reactivity/stores.mdx b/src/routes/reactivity/stores.mdx
new file mode 100644
index 000000000..eb8a33bb3
--- /dev/null
+++ b/src/routes/reactivity/stores.mdx
@@ -0,0 +1,4 @@
+---
+title: "Stores"
+order: 5
+---
diff --git a/src/routes/rendering/data.json b/src/routes/rendering/data.json
new file mode 100644
index 000000000..1fbb9d7ea
--- /dev/null
+++ b/src/routes/rendering/data.json
@@ -0,0 +1,4 @@
+{
+ "title": "Rendering",
+ "pages": []
+}
From 780750c92b01bdc91aa0b6c16822f2826df46ef8 Mon Sep 17 00:00:00 2001
From: Amir Hossein Hashemi <87268103+amirhhashemi@users.noreply.github.com>
Date: Tue, 26 Aug 2025 19:48:39 +0330
Subject: [PATCH 02/37] Improve data fetching docs (#1179)
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
Co-authored-by: Sarah
---
src/middleware/legacy-routes-redirect.ts | 2 +
src/routes/solid-router/concepts/actions.mdx | 470 ++++++++++++++----
src/routes/solid-router/concepts/data.json | 3 +-
.../solid-router/data-fetching/data.json | 4 +
.../data-fetching/how-to/data.json | 4 +
.../handle-error-and-loading-states.mdx | 29 ++
.../data-fetching/how-to/preload-data.mdx | 54 ++
.../solid-router/data-fetching/queries.mdx | 81 +++
.../data-fetching/revalidation.mdx | 60 +++
.../solid-router/data-fetching/streaming.mdx | 90 ++++
src/routes/solid-router/data.json | 1 +
.../reference/data-apis/action.mdx | 243 ++++-----
.../data-apis/create-async-store.mdx | 126 ++++-
.../reference/data-apis/create-async.mdx | 139 ++++--
.../reference/data-apis/query.mdx | 153 +++---
.../reference/data-apis/use-action.mdx | 48 +-
.../reference/data-apis/use-submission.mdx | 231 ++++-----
.../reference/data-apis/use-submissions.mdx | 281 +++++------
.../reference/preload-functions/preload.mdx | 108 ++--
.../data-fetching.mdx | 43 ++
.../data-loading.mdx | 157 ------
.../data-mutation.mdx | 104 ++++
.../building-your-application/data.json | 3 +-
.../solid-start/guides/data-fetching.mdx | 27 +-
.../solid-start/guides/data-mutation.mdx | 8 +-
.../reference/server/use-server.mdx | 8 +-
26 files changed, 1593 insertions(+), 884 deletions(-)
create mode 100644 src/routes/solid-router/data-fetching/data.json
create mode 100644 src/routes/solid-router/data-fetching/how-to/data.json
create mode 100644 src/routes/solid-router/data-fetching/how-to/handle-error-and-loading-states.mdx
create mode 100644 src/routes/solid-router/data-fetching/how-to/preload-data.mdx
create mode 100644 src/routes/solid-router/data-fetching/queries.mdx
create mode 100644 src/routes/solid-router/data-fetching/revalidation.mdx
create mode 100644 src/routes/solid-router/data-fetching/streaming.mdx
create mode 100644 src/routes/solid-start/building-your-application/data-fetching.mdx
delete mode 100644 src/routes/solid-start/building-your-application/data-loading.mdx
create mode 100644 src/routes/solid-start/building-your-application/data-mutation.mdx
diff --git a/src/middleware/legacy-routes-redirect.ts b/src/middleware/legacy-routes-redirect.ts
index fdf371f9b..647d1b38b 100644
--- a/src/middleware/legacy-routes-redirect.ts
+++ b/src/middleware/legacy-routes-redirect.ts
@@ -180,6 +180,8 @@ const LEGACY_ROUTES = {
"/solid-router/reference/response-helpers/revalidate":
"/solid-router/reference/data-apis/revalidate",
+
+ "/solid-start/guides/data-loading": "/solid-start/guides/data-fetching",
} as const;
function isLegacyRoute(path: string): path is keyof typeof LEGACY_ROUTES {
diff --git a/src/routes/solid-router/concepts/actions.mdx b/src/routes/solid-router/concepts/actions.mdx
index 53a96da9c..3d59eb63b 100644
--- a/src/routes/solid-router/concepts/actions.mdx
+++ b/src/routes/solid-router/concepts/actions.mdx
@@ -2,151 +2,445 @@
title: "Actions"
---
-When developing applications, it is common to need to communicate new information to the server based on user interactions.
-Actions are Solid Router’s solution to this problem.
+Many user interactions in an application involve changing data on the server.
+These **mutations** can be challenging to manage, as they require updates to the application's state and proper error handling.
+Actions simplify managing data mutations.
-## What are actions?
+Actions provide several benefits:
-Actions are asynchronous processing functions that allow you to submit data to your server and receive a response.
-They are isomorphic, meaning they can run either on the server or the client, depending on what is needed.
-This flexibility makes actions a powerful tool for managing and tracking data submissions.
+- **Integrated state management:**
+ Solid Router automatically tracks the execution state of an action, simplifying reactive UI feedback.
+- **Automatic data revalidation:**
+ After an action successfully completes, Solid Router revalidates relevant [`queries`](/solid-router/concepts/queries), ensuring the UI reflects the latest data.
+- **Progressive enhancement:**
+ When used with HTML forms, actions enable functionality even if JavaScript is not yet loaded.
-### How actions work
+## Defining actions
-Actions represent the server-side part of an [HTML form](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form).
-They handle submissions through POST requests, allowing you to easily use HTML forms to send data.
+Actions are defined by wrapping the data-mutation logic with the [`action` function](/solid-router/reference/data-apis/action).
-When a user performs an action, such as submitting a form, the data is sent to the server for processing via an action.
+```tsx
+import { action } from "@solidjs/router";
+
+const createTicketAction = action(async (subject: string) => {
+ const response = await fetch("https://my-api.com/support/tickets", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ subject }),
+ });
+
+ if (!response.ok) {
+ const errorData = await response.json();
+ return { ok: false, message: errorData.message };
+ }
+
+ return { ok: true };
+}, "createTicket");
+```
+
+In this example, an action is defined that creates a support ticket using a remote API.
+
+## Using actions
+
+Actions can be triggered in two ways: using a HTML [`
+ );
+}
```
-In this example, the `echo` action simulates a fetch call with a 1 second delay before logging the message to the console.
-The `echo` action will act as a backend, however, it can be substituted for any API provided it can be run on the client.
-Typically, route actions are used with some sort of solution like fetch or GraphQL.
+In this example, when the form is submitted, `submitFeedbackAction` will be triggered with the `FormData` containing the form values.
+
+:::tip[Uploading files]
+If a form that includes file inputs, the `
+```
-:::tip
-In [SolidStart](/solid-start) apps, it's recommended to use the [`"use server"`](/solid-start/reference/server/use-server) directive to leverage server-side functionality.
:::
-### Using actions
+#### Passing additional arguments
-To use the action, you can call it from within a component using [`useAction`](/solid-router/reference/data-apis/use-action).
-This returns a function that can be called with the necessary arguments to trigger the action.
+Sometimes, an action needs data that isn't part of the form's inputs.
+These additional arguments can be passed using the `with` method.
-```tsx del={1} ins={2,9-13}
+The `with` method creates a new action that wraps around the original action.
+When this new action is triggered, it forwards the arguments specified in the `with` method to the original action, followed by the `FormData` object.
+
+```tsx
import { action } from "@solidjs/router";
+
+const updateProductAction = action(
+ async (productId: string, formData: FormData) => {
+ // ... Sends the updated fields to the server.
+
+ return { ok: true };
+ },
+ "updateProduct"
+);
+
+function EditProductForm(props: { productId: string }) {
+ return (
+
+ );
+}
+```
+
+In this example, `updateProductAction` receives `productId` (passed via `with`), and then the `formData` from the form.
+
+### With the `useAction` primitive
+
+For scenarios where a `
+ );
+}
+```
- return
{echoing.result}
;
+In this example, the form's submit button is disabled while `submission.pending` is `true`.
+
+:::tip
+To track multiple submissions for a single action, such as in a multi-file uploader interface, the [`useSubmissions` primitive](/solid-router/reference/data-apis/use-submissions) can be used.
+:::
+
+## Handling errors
+
+An action can fail for various reasons.
+A robust application must handle these failures gracefully.
+Solid Router provides two mechanisms for an action to signal failure: throwing an `Error` or returning a value.
+
+Throwing an `Error` is a valid way to signal failure.
+Solid Router will catch the thrown error and make it available in the `submission.error` property.
+However, this approach has some drawbacks.
+The `submission.error` property is typed as `any`, which undermines type safety in the consuming component.
+It is also difficult to convey structured error information, such as validation messages for multiple form fields, using a simple `Error` instance.
+
+For these reasons, the recommended practice is to always `return` a descriptive object from an action to represent its outcome.
+The returned object is available in the `submission.result` property, which will be fully typed.
+This makes handling different outcomes in the UI simple and safe.
+
+```tsx
+import { Show } from "solid-js";
+import { action, useSubmission } from "@solidjs/router";
+
+const verifyTwoFactorAction = action(async (formData: FormData) => {
+ const code = formData.get("code")?.toString();
+
+ if (!code || code.length !== 6) {
+ return {
+ ok: false,
+ errors: { code: "Enter the 6-digit code from the authenticator app." },
+ };
+ }
+
+ // ... Verifies the code with the server and handles potential errors.
+
+ return { ok: true };
+}, "verifyTwoFactor");
+
+function TwoFactorForm() {
+ const submission = useSubmission(verifyTwoFactorAction);
+
+ const errors = () => {
+ const result = submission.result;
+ if (result && !result.ok) {
+ return result.errors;
+ }
+ };
+
+ return (
+
+ );
+}
+```
+
+In this example, the `errors` derived signal inspects `submission.result` to check for failures.
+If an `errors` object is found, its properties are used to conditionally render error messages next to the relevant form fields.
+
+:::caution[Always return a value]
+It is important that an action consistently returns a value from all of its possible code paths.
+Because, if an action returns `undefined` or `null`, Solid Router removes that submission from its internal list upon completion.
+This can lead to unexpected behavior.
+
+For example, consider an action that returns an error object on failure but returns nothing on success.
+If the action fails once, `useSubmission` will correctly report the error.
+However, if a subsequent submission succeeds, it will be removed from the list, and `useSubmission` will continue to report the previous stale error state.
+To prevent this, ensure every code path in an action returns a value, such as `{ ok: true }` to indicate a successful outcome.
+:::
+
+## Automatic data revalidation
+
+After server data changes, the application's can become stale.
+To solve this, Solid Router automatically revalidates all [queries](/solid-router/concepts/queries) used in the same page after a successful action.
+This ensures any component using that data is automatically updated with the freshest information.
+
+For example, if a page displays a list of registered devices and includes a form to register a new one, the list will automatically update after the form is submitted.
+
+```tsx
+import { For } from "solid-js";
+import { query, action, createAsync } from "@solidjs/router";
+
+const getDevicesQuery = query(async () => {
+ // ... Fetches the list of registered devices.
+}, "devices");
+
+const registerDeviceAction = action(async (formData: FormData) => {
+ // ... Registers a new device on the server.
+}, "registerDevice");
+
+function DevicesPage() {
+ // This query will automatically revalidate after registerDeviceAction completes.
+ const devices = createAsync(() => getDevicesQuery());
+
+ return (
+
+
Registered devices
+ {(device) =>
{device.name}
}
+
+
Register new device
+
+
+ );
}
```
-Using `useSubmission` leaves the implementation details of how you trigger `echo` up to you.
-When handling user inputs, for example, it is better to use a `form` for a multitude of reasons.
+While this automatic behavior is convenient for most cases, more fine-grained control may be needed.
+The next section explains how to customize or even disable this behavior for specific actions.
-## Using forms to submit data
+## Managing navigation and revalidation
-When submitting data with actions, it is recommended to use HTML forms.
-These forms can be used prior to JavaScript loading, which creates instantly interactive applications.
-This also inherently provides accessibility benefits, saving the time of designing a custom UI library that may not have these benefits.
+While automatic revalidation is powerful, more control is often needed.
+It may be desirable to redirect the user to a different page, prevent revalidation entirely, or revalidate a specific set of queries.
+This is where response helpers come in.
-When using forms to submit actions, the first argument passed to your action function is an instance of [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData).
-To use actions with forms, pass the action to the `action` property of your form.
-This creates progressively enhanced forms that work even when JavaScript is disabled.
+Response helpers are functions that create special [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects.
+When an action returns or throws one of these responses, Solid Router intercepts it and performs a specific task.
-If you do not return a `Response` from your action, the user will stay on the same page and responses will be re-triggered.
-Using a `redirect` can tell the browser to navigate to a new page.
+### Redirecting
+To navigate the user to a new page after an action completes, the [`redirect` helper](/solid-router/reference/response-helpers/redirect) can be used.
+It can also be used to revalidate specific queries upon redirection, which is useful for updating data that is displayed on the new page.
```tsx
import { action, redirect } from "@solidjs/router";
+import { useSession } from "vinxi/http";
+
+const logoutAction = action(async () => {
+ "use server";
+ const session = await useSession({
+ password: process.env.SESSION_SECRET as string,
+ name: "session",
+ });
+
+ if (session.data.sessionId) {
+ await session.clear();
+ await db.session.delete({ id: sessionId });
+ }
+
+ throw redirect("/");
+}, "logout");
+```
+
+In this example, after a successful login, the `redirect` helper is used to navigate to the dashboard.
+It also revalidates the "session" query to ensure the UI reflects the user's authenticated state.
+
+### Customizing revalidation
-const isAdmin = action(async (formData: FormData) => {
- await new Promise((resolve, reject) => setTimeout(resolve, 1000));
+To override the default revalidation behavior, the [`reload`](/solid-router/reference/response-helpers/reload) and [`json`](/solid-router/reference/response-helpers/json) helpers can be used.
- const username = formData.get("username");
+- `reload` is used when only revalidation needs to be customized.
+- `json` is used when revalidation needs to be controlled _and_ data needs to be returned from the action.
- if (username === "admin") throw redirect("/admin");
- return new Error("Invalid username");
+Both helpers accept a `revalidate` option, which takes an array of query keys to revalidate.
+If an empty array (`[]`) is provided, revalidation is prevented altogether.
+
+```tsx
+import { action, reload, json } from "@solidjs/router";
+
+// Example 1: Revalidating a specific query
+const savePreferencesAction = action(async () => {
+ // ... Saves the user preferences.
+
+ // Only revalidate the 'userPreferences' query
+ throw reload({ revalidate: ["userPreferences"] });
});
-export function MyComponent() {
+// Example 2: Disabling revalidation and returning data
+const logActivityAction = action(async () => {
+ // ... Logs the activity to the server.
- return (
-
- );
-}
+ // Return without revalidating any queries
+ return json({ ok: true }, { revalidate: [] });
+});
```
-**Note:** If you are uploading files make sure you include `enctype="multipart/form-data"` to your `
}>
+ Loading news...}>
+
+ {(item) =>
{item.headline}
}
+
+
+
+ );
+}
+```
diff --git a/src/routes/solid-router/data-fetching/how-to/preload-data.mdx b/src/routes/solid-router/data-fetching/how-to/preload-data.mdx
new file mode 100644
index 000000000..39215abe6
--- /dev/null
+++ b/src/routes/solid-router/data-fetching/how-to/preload-data.mdx
@@ -0,0 +1,54 @@
+---
+title: "Preload data"
+---
+
+Preloading data improves perceived performance by fetching the data for an upcoming page before the user navigates to it.
+
+Solid Router initiates preloading in two scenarios:
+
+- When a user indicates intent to navigate to the page (e.g., by hovering over a link).
+- When the route's component is rendering.
+
+This ensures data fetching starts as early as possible, often making data ready once the component renders.
+
+Preloading is configured using the [`preload`](/solid-router/reference/preload-functions/preload) prop on a [`Route`](/solid-router/reference/components/route).
+This prop accepts a function that calls one or more queries.
+When triggered, the queries execute and their results are stored in a short-lived internal cache.
+Once the user navigates and the destination route’s component renders, any `createAsync` calls within the page will consume the preloaded data.
+Thanks to the [deduplication mechanism](#deduplication), no redundant network requests are made.
+
+```tsx {18-20,27}
+import { Show } from "solid-js";
+import { Route, query, createAsync } from "@solidjs/router";
+
+const getProductQuery = query(async (id: string) => {
+ // ... Fetches product details for the given ID.
+}, "product");
+
+function ProductDetails(props) {
+ const product = createAsync(() => getProductQuery(props.params.id));
+
+ return (
+
+
{product().name}
+
+ );
+}
+
+function preloadProduct({ params }: { params: { id: string } }) {
+ getProductQuery(params.id);
+}
+
+function Routes() {
+ return (
+
+ );
+}
+```
+
+In this example, hovering a link to `/products/:id` triggers `preloadProduct`.
+When the `ProductDetails` component renders, its `createAsync` call will instantly resolve with the preloaded data.
diff --git a/src/routes/solid-router/data-fetching/queries.mdx b/src/routes/solid-router/data-fetching/queries.mdx
new file mode 100644
index 000000000..0f43335a6
--- /dev/null
+++ b/src/routes/solid-router/data-fetching/queries.mdx
@@ -0,0 +1,81 @@
+---
+title: "Queries"
+---
+
+Queries are the core building blocks for data fetching in Solid Router.
+They provide an elegant solution for managing data fetching.
+
+## Defining queries
+
+They are defined using the [`query` function](/solid-router/reference/data-apis/query).
+It wraps the data-fetching logic and extends it with powerful capabilities like [request deduplication](#deduplication) and [automatic revalidation](#revalidation).
+
+The `query` function takes two parameters: a **fetcher** and a **name**.
+
+- The **fetcher** is an asynchronous function that fetches data from any source, such as a remote API.
+- The **name** is a unique string used to identify the query.
+ When a query is called, Solid Router uses this name and the arguments passed to the query to create a unique key, which is used for the internal deduplication mechanism.
+
+```tsx
+import { query } from "@solidjs/router";
+
+const getUserProfileQuery = query(async (userId: string) => {
+ const response = await fetch(
+ `https://api.example.com/users/${encodeURIComponent(userId)}`
+ );
+ const json = await response.json();
+
+ if (!response.ok) {
+ throw new Error(json?.message ?? "Failed to load user profile.");
+ }
+
+ return json;
+}, "userProfile");
+```
+
+In this example, the defined query fetches a user's profile from an API.
+If the request fails, the fetcher will throw an error that will be caught by the nearest [``](/reference/components/error-boundary) in the component tree.
+
+## Using queries in components
+
+Defining a query does not by itself fetch any data.
+To access its data, the query can be used with the [`createAsync` primitive](/solid-router/reference/data-apis/create-async).
+`createAsync` takes an asynchronous function, such as a query, and returns a signal that tracks its result.
+
+```tsx
+import { For, Show } from "solid-js";
+import { query, createAsync } from "@solidjs/router";
+
+const getArticlesQuery = query(async () => {
+ // ... Fetches a list of articles from an API.
+}, "articles");
+
+function Articles() {
+ const articles = createAsync(() => getArticlesQuery());
+
+ return (
+
+ {(article) =>
{article.title}
}
+
+ );
+}
+```
+
+In this example, `createAsync` is used to call the query.
+Once the query completes, `articles` holds the result, which is then rendered.
+
+:::tip
+When working with complex data types, such as arrays or deeply nested objects, the [`createAsyncStore` primitive](/solid-router/reference/data-apis/create-async-store) offers a more ergonomic and performant solution.
+It works like `createAsync`, but returns a [store](/concepts/stores) for easier state management..
+:::
+
+## Deduplication
+
+A key feature of queries is their ability to deduplicate requests, preventing redundant data fetching in quick succession.
+
+One common use case is preloading: when a user hovers over a link, the application can begin preloading the data for the destination page.
+If the user then clicks the link, the query has already been completed, and the data is available instantly without triggering another network request.
+This mechanism is fundamental to the performance of Solid Router applications.
+
+Deduplication also applies when multiple components on the same page use the same query.
+As long as at least one component is actively using the query, Solid Router will reuse the cached result instead of refetching the data.
diff --git a/src/routes/solid-router/data-fetching/revalidation.mdx b/src/routes/solid-router/data-fetching/revalidation.mdx
new file mode 100644
index 000000000..3ee773fdf
--- /dev/null
+++ b/src/routes/solid-router/data-fetching/revalidation.mdx
@@ -0,0 +1,60 @@
+---
+title: "Revalidation"
+---
+
+Since server data can change, Solid Router provides mechanisms to revalidate queries and keep the UI up to date.
+
+The most common case is **automatic revalidation**.
+After an [action](/solid-router/concepts/actions) completes successfully, Solid Router automatically revalidates all active queries on the page.
+For more details, see the [actions documentation](/solid-router/concepts/actions#automatic-data-revalidation).
+
+For more fine-grained control, you can trigger revalidation manually with the [`revalidate` function](/solid-router/reference/data-apis/revalidate).
+It accepts a query key (or an array of keys) to target specific queries.
+Each query exposes two properties for this: `key` and `keyFor`.
+
+- `query.key` is the base key for a query and targets all of its instances.
+ Using this key will revalidate all data fetched by that query, regardless of the arguments provided.
+- `query.keyFor(arguments)` generates a key for a specific set of arguments, allowing you to target and revalidate only that particular query.
+
+```tsx
+import { For } from "solid-js";
+import { query, createAsync, revalidate } from "@solidjs/router";
+
+const getProjectsQuery = query(async () => {
+ // ... Fetches a list of projects.
+}, "projects");
+
+const getProjectTasksQuery = query(async (projectId: string) => {
+ // ... Fetches a list of tasks for a project.
+}, "projectTasks");
+
+function Projects() {
+ const projects = createAsync(() => getProjectsQuery());
+
+ function refetchAllTasks() {
+ revalidate(getProjectTasksQuery.key);
+ }
+
+ return (
+
+ );
+}
+```
diff --git a/src/routes/solid-router/data-fetching/streaming.mdx b/src/routes/solid-router/data-fetching/streaming.mdx
new file mode 100644
index 000000000..42fa45f41
--- /dev/null
+++ b/src/routes/solid-router/data-fetching/streaming.mdx
@@ -0,0 +1,90 @@
+---
+title: "Streaming"
+---
+
+In traditional server-rendered applications, the server must fetch all data before rendering and sending the page to the browser.
+If some queries are slow, this delays the initial load.
+**Streaming** solves this by sending the page’s HTML shell immediately and progressively streaming data-dependent sections as they become ready.
+
+When a query is accessed during a server-side render, Solid suspends the UI until the data resolves.
+By default, this suspension affects the entire page.
+
+To control this behavior, you can use suspense boundaries - regions of the component tree defined by a [`` component](/reference/components/suspense).
+It isolates asynchronous behavior to a specific section of the page.
+
+Content inside the boundary is managed by Solid’s concurrency system: if it isn’t ready, the boundary’s fallback UI is shown while the rest of the page renders and streams immediately.
+Once the data resolves, the server streams the final HTML for that section, replacing the fallback and letting users see and interact with most of the page much sooner.
+
+```tsx
+import { Suspense, For } from "solid-js";
+import { query, createAsync } from "@solidjs/router";
+
+const getAccountStatsQuery = query(async () => {
+ // ... Fetches account statistics.
+}, "accountStats");
+
+const getRecentTransactionsQuery = query(async () => {
+ // ... Fetches a list of recent transactions.
+}, "recentTransactions");
+
+function Dashboard() {
+ const stats = createAsync(() => getAccountStatsQuery());
+ const transactions = createAsync(() => getRecentTransactionsQuery());
+
+ return (
+
+ );
+}
+```
+
+For example, each `` component creates its own independent boundary.
+The server can stream the heading `
Dashboard
` immediately, while the `stats` and `transactions` are handled separately.
+If the `transactions` query is slow, only its boundary will display a fallback, while `stats` will render as soon as its data is ready.
+
+## When to disable streaming
+
+While streaming is powerful, there are cases where it is better to wait for the data to load on the server.
+In these situations, you can use the `deferStream` option in `createAsync`.
+
+When `deferStream` is set to `true`, the server waits for the query to resolve before sending the initial HTML.
+
+A common reason to disable streaming is for Search Engine Optimization (SEO).
+Some search engine crawlers may not wait for streamed content to load.
+If critical data, such as a page title or meta description, affects SEO, it should be included in the initial server response.
+
+```tsx
+import { query, createAsync } from "@solidjs/router";
+
+const getArticleQuery = query(async () => {
+ // ... Fetches an article.
+}, "article");
+
+function ArticleHeader() {
+ const article = createAsync(() => getArticleQuery(), {
+ deferStream: true,
+ });
+
+ return
{article()?.title}
;
+}
+```
diff --git a/src/routes/solid-router/data.json b/src/routes/solid-router/data.json
index a141ae4d4..e60a784f2 100644
--- a/src/routes/solid-router/data.json
+++ b/src/routes/solid-router/data.json
@@ -5,6 +5,7 @@
"getting-started",
"concepts",
"rendering-modes",
+ "data-fetching",
"advanced-concepts",
"guides"
]
diff --git a/src/routes/solid-router/reference/data-apis/action.mdx b/src/routes/solid-router/reference/data-apis/action.mdx
index 8f3a5e666..7847080fc 100644
--- a/src/routes/solid-router/reference/data-apis/action.mdx
+++ b/src/routes/solid-router/reference/data-apis/action.mdx
@@ -2,196 +2,139 @@
title: action
---
-Actions are data mutations that can trigger invalidations and further routing.
-A list of prebuilt response helpers can be found below.
+The `action` function wraps an asynchronous function and returns an [action](/solid-router/concepts/actions).
-```jsx
-import { action, revalidate, redirect } from "@solidjs/router"
+When an action is triggered, it creates a submission object that tracks its execution status.
+This state can be accessed with the [`useSubmission`](/solid-router/reference/data-apis/use-submission) and [`useSubmissions`](/solid-router/reference/data-apis/use-submissions) primitives.
-// anywhere
-const myAction = action(async (data) => {
- await doMutation(data);
- throw redirect("/", { revalidate: getUser.keyFor(data.id) }); // throw a response to do a redirect
-});
-
-// in component
-
+After an action completed successfully, all queries active in the same page are revalidated, unless revalidation is configured using [response helpers](/solid-router/concepts/actions#managing-navigation-and-revalidation).
-//or
-
+## Import
+```tsx
+import { action } from "@solidjs/router";
```
-Actions only work with **post** requests.
-This means forms require `method="post"`.
-
-A `with` method can be used when typed data is required.
-This removes the need to use `FormData` or other additional hidden fields.
-The `with` method works similar to [`bind`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_objects/Function/bind), which applies the arguments in order.
-
-Without `with`:
-
-```jsx
-const deleteTodo = action(async (formData: FormData) => {
- const id = Number(formData.get("id"))
- await api.deleteTodo(id)
-})
-
-
+- **Type:** `(...args: T) => Promise`
+- **Required:** Yes
-```
+An asynchronous function that performs the action's logic.
+When the action is used with a [`
` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/form), the function receives a [`FormData` object](https://developer.mozilla.org/en-US/docs/Web/API/FormData) as its first parameter.
-:::tip
-In [SolidStart](/solid-start) apps, it's recommended to use the [`"use server"`](/solid-start/reference/server/use-server) directive to leverage server-side caching.
-:::
+### `options`
-## Notes of `
` implementation and SSR
+- **Type:** `string | { name?: string; onComplete?: (s: Submission) => void }`
+- **Required**: No
-This requires stable references because a string can only be serialized as an attribute, and it is crucial for consistency across SSR. where these references must align.
-The solution is to provide a unique name.
+A unique string used to identify the action in Server-Side Rendering (SSR) environments.
+This is required when using the action with a `
` element.
-```jsx
-const myAction = action(async (args) => {}, "my-action");
-```
+Alternatively, a configuration object can be passed with the following properties.
-## `useAction`
+#### `name`
-Instead of forms, actions can directly be wrapped in a `useAction` primitive.
-This is how router context is created.
+- **Type:** `string`
+- **Required:** No
-```jsx
-// in component
-const submit = useAction(myAction);
-submit(...args);
+The unique string to identify the action in SSR environments.
+Required for `
` usage.
-```
+#### `onComplete` (optional):
-The outside of a form context can use custom data instead of `formData`.
-These helpers preserve types.
+- **Type:** `(s: Submission) => void`
+- **Required:** No
-However, even when used with server functions, such as with [SolidStart](https://start.solidjs.com/getting-started/what-is-solidstart), this requires client-side JavaScript and is not progressively enhanceable like forms are.
+A function that runs after the action completes.
+It receives a submission object as its parameter.
-## `useSubmission`/`useSubmissions`
+## Return value
-These functions are used when incorporating optimistic updates during ongoing actions.
-They provide either a singular Submission (the latest one), or a collection of Submissions that match, with an optional filtering function.
+`action` returns an action with the following properties.
-```jsx
-type Submission = {
- input: T;
- result: U;
- error: any;
- pending: boolean
- clear: () => {}
- retry: () => {}
-}
+### `with`
-const submissions = useSubmissions(action, (input) => filter(input));
-const submission = useSubmission(action, (input) => filter(input));
+A method that wraps the original action and returns a new one.
+When this new action is triggered, the arguments passed to `with` are forwarded to the original action.
+If this new action is used with a `
`, the `FormData` object is passed as the last parameter, after any other forwarded parameters.
-```
-
-## Revalidate cached functions
+## Examples
-### Revalidate all (default)
-By default all cached functions will be revalidated wether the action does not return or return a "normal" response.
+### Form submission
-```jsx
+```tsx
+import { action } from "@solidjs/router";
-const deleteTodo = action(async (formData: FormData) => {
- const id = Number(formData.get("id"))
- await api.deleteTodo(id)
- // ...
- return new Response("success", { status: 200 });
-})
-```
-
-### Revalidate specific cached keys
-
-By returning a response with solid-router's `json`, `reload` or `redirect` helpers you can pass a key / keys to the revalidate prop as the second argument of the json response helper.
-You can either pass as `string` directly or use the cached functions `key` or `keyFor` props.
-
-```jsx
-import { action, json, reload, redirect } from "@solidjs/router"
-
-const deleteTodo = action(async (formData: FormData) => {
- const id = Number(formData.get("id"))
- await api.deleteTodo(id)
- return json(
- { deleted: id },
- { revalidate: ["getAllTodos", getTodos.key, getTodoByID.keyFor(id)]}
- )
-
- //or
- return reload({ revalidate: ["getAllTodos", getTodos.key, getTodoByID.keyFor(id)]})
-
- //or
- return redirect("/", { revalidate: ["getAllTodos", getTodos.key, getTodoByID.keyFor(id)]})
-
-})
+const addTodoAction = action(async (formData: FormData) => {
+ // Adds a new todo to the server.
+}, "addTodo");
+function TodoForm() {
+ return (
+
+
+
+
+ );
+}
```
-## Prevent revalidation
-To opt out of any revalidation you can pass any `string` to revalidate which is not a key of any cached function.
-
-```jsx
-const deleteTodo = action(async (formData: FormData) => {
- const id = Number(formData.get("id"))
- await api.deleteTodo(id)
- // returns a `json` without revalidating the action.
- return json(`deleted ${id}`,{ revalidate: "nothing" })
+### Passing additional arguments
- // or reload the route without revalidating the request.
- return reload({ revalidate: "nothing" })
+```tsx
+import { action } from "@solidjs/router";
- // or redirect without revalidating
- return redirect("/", { revalidate: "nothing" })
-})
+const addTodoAction = action(async (userId: number, formData: FormData) => {
+ // ... Adds a new todo for a specific user.
+}, "addTodo");
+function TodoForm() {
+ const userId = 1;
+ return (
+
+
+
+
+ );
+}
```
-### Revalidate without action
+### Triggering actions programmatically
-Cached functions can also be revalidated by the `revalidate` helper.
+```tsx
+import { action, useAction } from "@solidjs/router";
-```jsx
-revalidate([getTodos.key, getTodoByID.keyFor(id)])
+const markDoneAction = action(async (id: string) => {
+ // ... Marks a todo as done on the server.
+});
-```
+function NotificationItem(props: { id: string }) {
+ const markDone = useAction(markDoneAction);
-This is also great if you want to set your own "refresh" interval e.g. poll data every 30 seconds.
-
-```jsx
-export default function TodoLayout(){
-
- const todos = createAsync(() => getTodos())
-
- onMount(() => {
- //30 second polling
- const interval = setInterval(() => revalidate(getTodos.key),1000 * 30)
- onCleanup(() => clearInterval(interval))
- })
-
- // ...
+ return ;
}
-
```
diff --git a/src/routes/solid-router/reference/data-apis/create-async-store.mdx b/src/routes/solid-router/reference/data-apis/create-async-store.mdx
index a1659422c..caa015890 100644
--- a/src/routes/solid-router/reference/data-apis/create-async-store.mdx
+++ b/src/routes/solid-router/reference/data-apis/create-async-store.mdx
@@ -2,8 +2,128 @@
title: createAsyncStore
---
-Similar to [createAsync](/solid-router/reference/data-apis/create-async) except it uses a deeply reactive store. Perfect for applying fine-grained changes to large model data that updates.
+The `createAsyncStore` primitive manages asynchronous data fetching by tracking the result of a promise-returning function in a [store](/concepts/stores).
-```jsx
-const todos = createAsyncStore(() => getTodos());
+The main difference from [createAsync](/solid-router/reference/data-apis/create-async) is its use of reconciliation: when new data arrives, it intelligently merges with the existing store, updating only changed fields while preserving unchanged state.
+
+## Import
+
+```tsx
+import { createAsyncStore } from "@solidjs/router";
+```
+
+## Type
+
+```tsx
+function createAsyncStore(
+ fn: (prev: T) => Promise,
+ options: {
+ name?: string;
+ initialValue: T;
+ deferStream?: boolean;
+ reconcile?: ReconcileOptions;
+ }
+): AccessorWithLatest;
+
+function createAsyncStore(
+ fn: (prev: T | undefined) => Promise,
+ options?: {
+ name?: string;
+ initialValue?: T;
+ deferStream?: boolean;
+ reconcile?: ReconcileOptions;
+ }
+): AccessorWithLatest;
+```
+
+## Parameters
+
+### `fetcher`
+
+- **Type:** `(prev: T | undefined) => Promise`
+- **Required:** Yes
+
+An asynchronous function or a function that returns a `Promise`.
+The resolved value of this `Promise` is what `createAsyncStore` tracks.
+This function is reactive and will automatically re-execute if any of its dependencies change.
+
+### `options`
+
+- **Type:** `{ name?: string; initialValue?: T; deferStream?: boolean; reconcile?: ReconcileOptions; }`
+- **Required:** No
+
+An object for configuring the primitive.
+It has the following properties.
+
+#### `name`
+
+- **Type:** `string`
+- **Required:** No
+
+A name for the resource, used for identification in debugging tools like [Solid Debugger](https://github.com/thetarnav/solid-devtools).
+
+#### `initialValue`
+
+- **Type:** `T`
+- **Required:** No
+
+The initial value of the returned store before the fetcher resolves.
+
+#### `deferStream`
+
+- **Type:** `boolean`
+- **Required:** No
+
+If `true`, [streaming](/solid-router/concepts/queries#streaming) will be deferred until the resource has resolved.
+
+#### `reconcile`
+
+- **Type:** `ReconcileOptions`
+- **Required:** No
+
+[Options](/reference/store-utilities/reconcile#options) passed directly to the `reconcile` function.
+It controls how new data is merged with the existing store.
+
+## Return value
+
+`createAsyncStore` returns a derived signal that contains the resolved value of the fetcher as a store.
+
+While the fetcher is executing for the first time, unless an `initialValue` is specified, the store's value is `undefined`.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { For, createSignal } from "solid-js";
+import { createAsyncStore, query } from "@solidjs/router";
+
+const getNotificationsQuery = query(async (unreadOnly: boolean) => {
+ // ... Fetches the list of notifications from the server.
+}, "notifications");
+
+function Notifications() {
+ const [unreadOnly, setUnreadOnly] = createSignal(false);
+ const notifications = createAsyncStore(() =>
+ getNotificationsQuery(unreadOnly())
+ );
+
+ return (
+
+
+
+
+ {(notification) => (
+
+
{notification.message}
+
{notification.user.name}
+
+ )}
+
+
+
+ );
+}
```
diff --git a/src/routes/solid-router/reference/data-apis/create-async.mdx b/src/routes/solid-router/reference/data-apis/create-async.mdx
index c8b7b833d..59823bdc7 100644
--- a/src/routes/solid-router/reference/data-apis/create-async.mdx
+++ b/src/routes/solid-router/reference/data-apis/create-async.mdx
@@ -2,42 +2,125 @@
title: createAsync
---
-An asynchronous primitive with a function that tracks similar to `createMemo`.
-`createAsync` expects a promise back that is then turned into a Signal.
-Reading it before it is ready causes Suspense/Transitions to trigger.
+The `createAsync` primitive manages asynchronous data fetching by tracking the result of a promise-returning function.
-:::caution
- Using `query` in `createResource` directly will not work since the fetcher is
- not reactive. This means that it will not invalidate properly.
+:::note
+`createAsync` is currently a thin wrapper over `createResource`.
+While `createResource` offers similar functionality, **`createAsync` is the recommended primitive for most asynchronous data fetching**.
+It is intended to be the standard async primitive in a future Solid 2.0 release.
:::
-This is light wrapper over [`createResource`](/reference/basic-reactivity/create-resource) which serves as a stand-in for a future primitive being brought to Solid core in 2.0.
-It is recommended that `createAsync` be used in favor of `createResource` specially when in a **SolidStart** app because `createAsync` works better in conjunction with the [cache](/solid-router/reference/data-apis/cache) helper.
+## Import
+```tsx
+import { createAsync } from "@solidjs/router";
+```
+## Type
-```tsx title="component.tsx" {6,10}
-import { createAsync } from "@solidjs/router";
-import { Suspense } from "solid-js";
-import { getUser } from "./api";
+```tsx
+function createAsync(
+ fn: (prev: T) => Promise,
+ options: {
+ name?: string;
+ initialValue: T;
+ deferStream?: boolean;
+ }
+): AccessorWithLatest;
-export function Component () => {
- const user = createAsync(() => getUser(params.id));
+function createAsync(
+ fn: (prev: T | undefined) => Promise,
+ options?: {
+ name?: string;
+ initialValue?: T;
+ deferStream?: boolean;
+ }
+): AccessorWithLatest;
+```
- return (
-
-
{user()}
-
- );
+## Parameters
+
+### `fetcher`
+
+- **Type:** `(prev: T | undefined) => Promise`
+- **Required:** Yes
+
+An asynchronous function or a function that returns a `Promise`.
+The resolved value of this `Promise` is what `createAsync` tracks.
+This function is reactive and will automatically re-execute if any of its dependencies change.
+
+### `options`
+
+- **Type:** `{ name?: string; initialValue?: T; deferStream?: boolean; }`
+- **Required:** No
+
+An object for configuring the primitive.
+It has the following properties:
+
+#### `name`
+
+- **Type:** `string`
+- **Required:** No
+
+A name for the resource, used for identification in debugging tools like [Solid Debugger](https://github.com/thetarnav/solid-devtools).
+
+#### `initialValue`
+
+- **Type:** `T`
+- **Required:** No
+
+The initial value of the returned signal before the fetcher finishes executing.
+
+#### `deferStream`
+
+- **Type:** `boolean`
+- **Required:** No
+
+If `true`, [streaming](/solid-router/concepts/queries#streaming) will be deferred until the fetcher finishes executing.
+
+## Return value
+
+`createAsync` returns a derived signal that contains the resolved value of the fetcher.
+
+While the fetcher is executing for the first time, unless an `initialValue` is specified, the signal's value is `undefined`.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { createAsync, query } from "@solidjs/router";
+
+const getUserQuery = query(async (id: string) => {
+ // ... Fetches the user from the server.
+}, "user");
+
+function UserProfile() {
+ const user = createAsync(() => getUserQuery());
+
+ return
{user()?.name}
;
+}
```
-## Options
+### Handling loading and errors
+
+```tsx
+import { Suspense, ErrorBoundary, For } from "solid-js";
+import { createAsync, query } from "@solidjs/router";
+
+const getUserQuery = query(async (id: string) => {
+ // ... Fetches the user from the server.
+}, "user");
-| Name | Type | Default | Description |
-| ------------ | ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| name | `string` | `undefined` | A name for the resource. This is used for debugging purposes. |
-| deferStream | `boolean` | `false` | If true, Solid will wait for the resource to resolve before flushing the stream. |
-| initialValue | `any` | `undefined` | The initial value of the resource. |
-| onHydrated | `function` | `undefined` | A callback that is called when the resource is hydrated. |
-| ssrLoadFrom | `"server" \| "initial"` | `"server"` | The source of the initial value for SSR. If set to `"initial"`, the resource will use the `initialValue` option instead of the value returned by the fetcher. |
-| storage | `function` | `createSignal` | A function that returns a signal. This can be used to create a custom storage for the resource. This is still experimental
+function UserProfile() {
+ const user = createAsync(() => getUserQuery());
+
+ return (
+ Could not fetch user data.}>
+ Loading user...}>
+
{user()!.name}
+
+
+ );
+}
+```
diff --git a/src/routes/solid-router/reference/data-apis/query.mdx b/src/routes/solid-router/reference/data-apis/query.mdx
index eab7749ba..09c75eef5 100644
--- a/src/routes/solid-router/reference/data-apis/query.mdx
+++ b/src/routes/solid-router/reference/data-apis/query.mdx
@@ -2,118 +2,87 @@
title: query
---
-`query` is a [higher-order function](https://en.wikipedia.org/wiki/Higher-order_function) designed to create a new function with the same signature as the function passed to it.
-When this newly created function is called for the first time with a specific set of arguments, the original function is run, and its return value is stored in a cache and returned to the caller of the created function.
-The next time the created function is called with the same arguments (as long as the cache is still valid), it will return the cached value instead of re-executing the original function.
-
-:::note
-`query` can be defined anywhere and then used inside your components with [`createAsync`](/solid-router/reference/data-apis/create-async).
-
-However, using `query` directly in [`createResource`](/reference/basic-reactivity/create-resource) will not work since the fetcher is not reactive and will not invalidate properly.
-
-:::
-
-## Usage
-
-```js
-const getUser = query(
- (id, options = {}) =>
- fetch(`/api/users/${id}?summary=${options.summary || false}`).then((r) =>
- r.json()
- ),
- "usersById"
-);
-
-getUser(123); // Causes a GET request to /api/users/123?summary=false
-getUser(123); // Does not cause a GET request
-getUser(123, { summary: true }); // Causes a GET request to /api/users/123?summary=true
-setTimeout(() => getUser(123, { summary: true }), 999000); // Eventually causes another GET request to /api/users/123?summary=true
+The `query` function wraps an asynchronous function (the fetcher) and returns a query.
+
+The primary purpose of a query is to prevent redundant data fetching.
+When a query is called, a key is generated from its name and arguments.
+This key is used to internally cache the result of the fetcher.
+If a query with the same key is called, the cached result is used in these scenarios:
+
+- **For preloading:**
+ After a route's data is preloaded, a subsequent call to the same query within a 5-second window uses the preloaded data.
+- **For active subscriptions:**
+ When a query is actively being used by a component (e.g., via [`createAsync`](/solid-router/reference/data-apis/create-async)), its data is reused without expiration.
+- **On native history navigation:**
+ When navigating with the browser's back or forward buttons, the data is reused instead of being re-fetched.
+- **For server-side deduplication:**
+ Within a single server-side rendering (SSR) request, repeated calls to the same query reuse the same value.
+- **During client hydration:**
+ If SSR has provided data for a key, that data is used immediately on the client without a new network request.
+
+## Import
+
+```tsx
+import { query } from "@solidjs/router";
```
-### With preload functions
-
-Using it with a [preload function](/solid-router/reference/preload-functions/preload):
-
-```js
-import { lazy } from "solid-js";
-import { Route } from "@solidjs/router";
-import { getUser } from ... // the cache function
+## Type
-const User = lazy(() => import("./pages/users/[id].js"));
-
-// preload function
-function preloadUser({params, location}) {
- void getUser(params.id)
-}
-
-// Pass it in the route definition
-;
+```tsx
+function query any>(
+ fn: T,
+ name: string
+): CachedFunction;
```
-### Inside a route's component
-
-Using it inside a route's component:
-
-```jsx
-// pages/users/[id].js
-import { getUser } from ... // the cache function
+## Parameters
-export default function User(props) {
- const user = createAsync(() => getUser(props.params.id));
- return
{user().name}
;
-}
-```
+### `fetcher`
-## Query Function Capabilities
+- **Type:** `T extends (...args: any) => any`
+- **Required:** Yes
-`query` accomplishes the following:
+An asynchronous function that handles the logic for fetching data.
+All arguments passed to this function must be JSON-serializable.
-1. Deduping on the server for the lifetime of the request.
-2. It fills a preload cache in the browser - this lasts 5 seconds.
- When a route is preloaded on hover or when preload is called when entering a route it will make sure to dedupe calls.
-3. A reactive refetch mechanism based on key.
- This prevents routes that are not new from retriggering on action revalidation.
-4. Serve as a back/forward cache for browser navigation for up to 5 minutes.
- Any user based navigation or link click bypasses this cache.
- Revalidation or new fetch updates the cache.
+### `name`
-## Query Keys
+- **Type:** `string`
+- **Required:** Yes
-To ensure that the query keys are consistent and unique, arguments are deterministically serialized using `JSON.stringify`.
-Before serialization, key/value pairs in objects are sorted so that the order of properties does not affect the serialization.
-For instance, both `{ name: 'Ryan', awesome: true }` and `{ awesome: true, name: 'Ryan' }` will serialize to the same string so that they produce the same query key.
+A string used as a namespace for the query.
+Solid Router combines this with the query's arguments to generate a unique key for deduplication.
## Return value
-The return value is a `CachedFunction`, a function that has the same signature as the function you passed to `query`.
-This cached function stores the return value using the query key.
-Under most circumstances, this temporarily prevents the passed function from running with the same arguments, even if the created function is called repeatedly.
+`query` returns a new function with the same call signature as the fetcher.
+This returned function has the following properties attached to it:
-## Arguments
+### `key`
-| argument | type | description |
-| -------- | ----------------------- | ------------------------------------------------------------------------- |
-| `fn` | `(...args: any) => any` | A function whose return value you'd like to be cached. |
-| `name`\* | string | Any arbitrary string that you'd like to use as the rest of the query key. |
+The base key for the query, derived from its name.
-\*Since the internal cache is shared by all the functions using `query`, the string should be unique for each function passed to `query`.
-If the same key is used with multiple functions, one function might return the cached result of the other.
+### `keyFor`
-## Methods
+A function that takes the same arguments as the fetcher and returns a string representing a specific key for that set of arguments.
-### `.key` and `.keyFor`
+## Example
-Query functions provide `.key` and `.keyFor`, are useful when retrieving the keys used in cases involving invalidation:
+### Basic usage
-```ts
-let id = 5;
-getUser.key; // returns "users"
-getUser.keyFor(id); // returns "users[5]"
-```
+```tsx
+import { query } from "@solidjs/router";
-### `revalidate`
+const getUserProfileQuery = query(async (userId: string) => {
+ const response = await fetch(
+ `https://api.example.com/users/${encodeURIComponent(userId)}`
+ );
+ const json = await response.json();
-The `query` can be revalidated using the `revalidate` method or the `revalidate` keys that are set on the response from the actions.
-If the entire key is passed, it will invalidate all entries for the cache (ie. `users` in the example above).
-If only a single entry needs to be invalidated, `keyFor` is provided.
-To revalidate everything in the cache, pass `undefined` as the key.
+ if (!response.ok) {
+ throw new Error(json?.message ?? "Failed to load user profile.");
+ }
+
+ return json;
+}, "userProfile");
+```
diff --git a/src/routes/solid-router/reference/data-apis/use-action.mdx b/src/routes/solid-router/reference/data-apis/use-action.mdx
index 91d8a5e80..68e117b4b 100644
--- a/src/routes/solid-router/reference/data-apis/use-action.mdx
+++ b/src/routes/solid-router/reference/data-apis/use-action.mdx
@@ -2,26 +2,50 @@
title: useAction
---
-`useAction` allows an [`action`](/solid-router/reference/data-apis/action) to be invoked programmatically.
+The `useAction` primitive returns a function that triggers an [action](/solid-router/concepts/actions) when called.
+
+`useAction` requires client-side JavaScript and is not progressively enhanceable.
+
+## Import
```tsx
import { useAction } from "@solidjs/router";
-import { updateNameAction } from "./actions";
+```
-const updateName = useAction(updateNameAction);
+## Type
-const result = updateName("John Wick");
+```tsx
+function useAction, U, V>(
+ action: Action
+): (...args: Parameters>) => Promise>;
```
-:::note
-`useAction` requires client-side JavaScript and is not progressively enhanceable.
-:::
-
## Parameters
-- `action`: The action to be invoked.
+### `action`
+
+- **Type:** `Action`
+- **Required:** Yes
-## Returns
+The action to be triggered.
-`useAction` returns a function that invokes the action.
-It shares the same signature as the action itself.
+## Return value
+
+`useAction` returns a function that triggers the action.
+It takes the same parameters as the action handler and returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves with the action's result.
+
+## Example
+
+```tsx
+import { action, useAction } from "@solidjs/router";
+
+const likePostAction = action(async (id: string) => {
+ // ... Likes a post on the server.
+});
+
+function LikeButton(props: { postId: string }) {
+ const likePost = useAction(likePostAction);
+
+ return ;
+}
+```
diff --git a/src/routes/solid-router/reference/data-apis/use-submission.mdx b/src/routes/solid-router/reference/data-apis/use-submission.mdx
index 7153e664c..acd2f82e9 100644
--- a/src/routes/solid-router/reference/data-apis/use-submission.mdx
+++ b/src/routes/solid-router/reference/data-apis/use-submission.mdx
@@ -2,160 +2,127 @@
title: useSubmission
---
-This helper is used to handle form submissions and can provide optimistic updates while actions are in flight as well as pending state feedback.
-This method will return a single (latest) value while its sibling, [`useSubmissions`](/solid-router/reference/data-apis/use-submissions), will return all values submitted while the component is active. With an optional second parameter for a filter function.
+The `useSubmission` primitive returns the state of the _most recent_ submission for a given [action](/solid-router/concepts/actions).
-It's important to note that `useSubmission` requires the form method to be **post** otherwise it will trigger a browser navigation and will not work.
+## Import
-```tsx title="component.tsx" {4,8}
+```tsx
import { useSubmission } from "@solidjs/router";
+```
-function Component() {
- const submission = useSubmission(postNameAction);
-
- return (
-
-
-
-
- )
-}
+## Type
+
+```tsx
+function useSubmission, U, V>(
+ fn: Action,
+ filter?: (input: V) => boolean
+): Submission> | SubmissionStub;
```
-:::note
-Learn more about actions in the [`action`](/solid-router/reference/data-apis/action) docs.
-:::
+## Parameters
-## Filtering Submissions
+### `action`
-As an optional second parameter, the `useSubmission` helper can receive a filter function to only return the submission that matches the condition.
-The filter receives the submitted dated as a parameter and should return a boolean value.
-E.g.: action below will only submit if the name is "solid".
+- **Type:** `Action`
+- **Required:** Yes
-```tsx title="component.tsx" {4-8}
-import { useSubmission } from "@solidjs/router";
+The action to track.
-function Component() {
- const submission = useSubmission(postNameAction, ([formData]) => {
- const name = formData.get("name") ?? "";
-
- return name === "solid";
- });
-
- return (
-
-
-
-
- )
-}
-```
+### `filter`
-## Optimistic Updates
+- **Type:** `(input: V) => boolean`
+- **Required:** No
-When the form is submitted, the `submission` object will be updated with the new value and the `pending` property will be set to `true`.
-This allows you to provide feedback to the user that the action is in progress.
-Once the action is complete, the `pending` property will be set to `false` and the `result` property will be updated with final value.
+A function that filters submissions.
+It is executed for each submission in the order of creation.
+It receives an array of the action's inputs as a parameter and must return `true` to select the submission or `false` otherwise.
+The first submission that passes the filter is returned by `useSubmission`.
-```tsx tab title="TypeScript" {6,10-12}
-// component.tsx
-import { Show } from "solid-js";
-import { useSubmission } from "@solidjs/router";
+## Return value
-function Component() {
- const submission = useSubmission(postNameAction);
-
- return (
- <>
-
- {(name) =>
Optimistic: {name() as string}
}
-
-
-
- {(name) =>
Result: {name()}
}
-
-
-
-
-
-
- >
- )
-}
-```
+`useSubmission` returns a reactive object with the following properties:
-```tsx tab title="JavaScript" {6,10-12}
-// component.jsx
-import { Show } from "solid-js";
-import { useSubmission } from "@solidjs/router";
+### `input`
-function Component() {
- const submission = useSubmission(postNameAction);
-
- return (
- <>
-
- {(name) =>
Optimistic: {name()}
}
-
-
-
- {(name) =>
Result: {name()}
}
-
-
-
-
-
-
- >
- )
-}
-```
+A reactive value representing the input data of the action.
+
+### `result`
-## Error Handling
+A reactive value representing the successful return value of the action.
-If the action fails, the `submission` object will be updated with the error and the `pending` property will be set to `false`.
-This allows you to provide feedback to the user that the action has failed. Additionally, the return type of `useSubmission` will have a new key `error` that will contain the error object thrown by the submission handler.
+### `error`
-At this stage, you can also use the `retry()` method to attempt the action again or the `clear()` to wipe the filled data in the platform.
+A reactive value representing any error thrown by the action.
-```tsx title="component.tsx" {12-18}
+### `pending`
+
+A reactive boolean indicating if the action is currently running.
+
+### `clear`
+
+A function to clear the submission's state.
+
+### `retry`
+
+A function to re-execute the submission with the same input.
+
+## Examples
+
+### Basic usage
+
+```tsx
import { Show } from "solid-js";
+import { action, useSubmission } from "@solidjs/router";
+
+const addTodoAction = action(async (formData: FormData) => {
+ const name = formData.get("name")?.toString();
+
+ if (!name || name.length <= 2) {
+ return { ok: false, message: "Name must be larger than 2 characters." };
+ }
+
+ // ... Sends the todo data to the server.
+
+ return { ok: true };
+}, "addTodo");
+
+function AddTodoForm() {
+ const submission = useSubmission(addTodoAction);
+
+ return (
+
;
}
```
diff --git a/src/routes/solid-router/reference/data-apis/use-submissions.mdx b/src/routes/solid-router/reference/data-apis/use-submissions.mdx
index c03ac618c..5a1899755 100644
--- a/src/routes/solid-router/reference/data-apis/use-submissions.mdx
+++ b/src/routes/solid-router/reference/data-apis/use-submissions.mdx
@@ -2,189 +2,146 @@
title: useSubmissions
---
-This helper is used to handle form submissions and can provide optimistic updates while actions are in flight as well as pending state feedback.
-This method will return an iterable of all submitted actions while its component is mounted. With an optional second parameter for a filter function.
+The `useSubmissions` primitive returns the state of all submissions for a given [action](/solid-router/concepts/actions).
-:::tip
-If you only care for the latest submission, you can use the [`useSubmission`](/solid-router/reference/data-apis/use-submission) helper.
-:::
+## Import
-It's important to note that it requires the form method to be **post** otherwise it will trigger a browser navigation and will not work.
-
-In the example below, the `useSubmissions` helper is used to retain a list of all submission results to that action while also giving feedback on the pending state of the current in-flight submission.
-
-```tsx title="component.tsx" {4,9-20, 23}
+```tsx
import { useSubmissions } from "@solidjs/router";
+```
-function Component() {
- const submissions = useSubmissions(postNameAction);
-
- return (
-
- )
-}
+## Type
+
+```tsx
+function useSubmissions, U, V>(
+ fn: Action,
+ filter?: (input: V) => boolean
+): Submission>[] & {
+ pending: boolean;
+};
```
-:::note
-To trigger a submission, [actions](https://docs.solidjs.com/) can be used.
-:::
+## Parameters
-## Filtering Submissions
+### `action`
-As an optional second parameter, the `useSubmissions` helper can receive a filter function to only return the submission that matches the condition.
-The filter receives the submitted dated as a parameter and should return a boolean value.
-E.g.: action below will only submit if the name is "solid".
+- **Type:** `Action`
+- **Required:** Yes
-```tsx title="component.tsx" {4-8}
-import { useSubmissions } from "@solidjs/router";
+The action to track.
-function Component() {
- const submissions = useSubmissions(postNameAction, ([formData]) => {
- const name = formData.get("name") ?? "";
-
- return name === "solid";
- });
-
- return (
-
- )
-}
-```
+### `filter`
-## Optimistic Updates
+- **Type:** `(input: V) => boolean`
+- **Required:** No
-When the form is submitted, the `submission` object will be updated with the new value and the `pending` property will be set to `true`.
-This allows you to provide feedback to the user that the action is in progress.
-Once the action is complete, the `pending` property will be set to `false` and the `result` property will be updated with final value.
+A function that filters submissions.
+It is executed for each submission in the order of creation.
+It receives an array of the action's inputs as a parameter and must return `true` to select the submission or `false` otherwise.
-```tsx tab title="TypeScript" {6,13-20}
-// component.tsx
-import { Show } from "solid-js";
-import { useSubmissions } from "@solidjs/router";
+## Return value
-function Component() {
- const submissions = useSubmissions(postNameAction);
-
- return (
-
- )
-}
-```
+The reactive input data of the action.
+
+### `result`
-## Error Handling
+A reactive value representing the successful return value of the action.
-If the action fails, the `submission` object will be updated with the error and the `pending` property will be set to `false`.
-This allows you to provide feedback to the user that the action has failed. Additionally, the return type of `useSubmission` will have a new key `error` that will contain the error object thrown by the submission handler.
+### `error`
+
+A reactive value for any error thrown by the action.
+
+### `pending`
+
+A reactive boolean indicating if the action is currently running.
+
+### `clear`
+
+A function to clear the submission's state.
+
+### `retry`
+
+A function to re-execute the submission with the same input.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { For, Show } from "solid-js";
+import { action, useSubmissions } from "@solidjs/router";
+
+const addTodoAction = action(async (formData: FormData) => {
+ // ... Sends the todo data to the server.
+}, "addTodo");
+
+function AddTodoForm() {
+ const submissions = useSubmissions(addTodoAction);
+
+ return (
+
+ );
+}
+```
-At this stage, you can also use the `retry()` method to attempt the action again or the `clear()` to wipe the filled data in the platform.
+### Filtering submissions
-```tsx title="component.tsx" {12-18}
-import { Show } from "solid-js";
+```tsx
import { useSubmissions } from "@solidjs/router";
-function Component() {
- const submissions = useSubmissions(postNameAction);
-
- return (
-
-
-
- {([attempt, data]) => (
-
-
-
Backend {attempt}: {data.error.message}
-
-
-
-
- )}
-
-
-
-
-
- )
+const addTodoAction = action(async (formData: FormData) => {
+ // ... Sends the todo data to the server.
+}, "addTodo");
+
+function FailedTodos() {
+ const failedSubmissions = useSubmissions(
+ addTodoAction,
+ ([formData]: [FormData]) => {
+ // Filters for submissions that failed a client-side validation
+ const name = formData.get("name")?.toString() ?? "";
+ return name.length <= 2;
+ }
+ );
+
+ return (
+
+ );
}
```
diff --git a/src/routes/solid-router/reference/preload-functions/preload.mdx b/src/routes/solid-router/reference/preload-functions/preload.mdx
index 71f27bc60..cf21d504b 100644
--- a/src/routes/solid-router/reference/preload-functions/preload.mdx
+++ b/src/routes/solid-router/reference/preload-functions/preload.mdx
@@ -1,46 +1,92 @@
---
-title: Preload
+title: preload
---
-With smart caches waterfalls are still possible with view logic and with lazy loaded code.
-With preload functions, fetching the data parallel to loading the route is possible to allow use of the data as soon as possible.
-The preload function can be called when the Route is loaded or eagerly when links are hovered.
+The `preload` function is a property on a route definition that initiates data fetching before a user navigates to the route.
-As its only argument, the preload function is passed an object that can be used to access route information:
+`preload` runs in two separate phases:
-```js
-import { lazy } from "solid-js";
+- **Preload phase:**
+ Triggered by user intent (e.g., hovering over a link), the function is called to initiate data fetching.
+- **Rendering phase:**
+ Triggered by actual navigation, the function is called a second time to provide the fetched data to the component.
+
+## Import
+
+```tsx
import { Route } from "@solidjs/router";
+```
-const User = lazy(() => import("./pages/users/[id].js"));
+## Type
-// preload function
-function preloadUser({ params, location }) {
- // do preloading
-}
+```tsx
+type RoutePreloadFunc = (args: RoutePreloadFuncArgs) => T;
-// Pass it in the route definition
-;
+interface RoutePreloadFuncArgs {
+ params: Params;
+ location: Location;
+ intent: "initial" | "native" | "navigate" | "preload";
+}
```
-| key | type | description |
-| -------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| params | object | The route parameters (same value as calling [`useParams()`](/solid-router/reference/primitives/use-params) inside the route component) |
-| location | `{ pathname, search, hash, query, state, key}` | An object that used to get more information about the path (corresponds to [`useLocation()`](/solid-router/reference/primitives/use-location)) |
-| intent | `"initial", "navigate", "native", "preload"` | Indicates why this function is being called.
"initial" - the route is being initially shown (ie page load)
"native" - navigate originated from the browser (eg back/forward)
"navigate" - navigate originated from the router (eg call to navigate or anchor clicked)
"preload" - not navigating, just preloading (eg link hover)
|
+## Parameters
-A common pattern is to export the preload function and data wrappers that correspond to a route in a dedicated `route.data.js` file.
-This imports the data functions without loading anything else.
+### `params`
-```js
-import { lazy } from "solid-js";
-import { Route } from "@solidjs/router";
-import preloadUser from "./pages/users/[id].data.js";
-const User = lazy(() => import("/pages/users/[id].js"));
+- **Type:** `Params`
-// In the Route definition
-;
-```
+An object containing the parameters for the matched route.
+It corresponds to the value returned by the [`useParams` primitive](/solid-router/reference/primitives/use-params).
+
+### `location`
+
+- **Type:** `Location`
+
+The router's location object for the destination URL.
+It corresponds to the value returned by the [`useLocation` primitive](/solid-router/reference/primitives/use-location).
+
+### `intent`
+
+- **Type:** `"initial" | "native" | "navigate" | "preload"`
+
+A string indicating the context in which the function is called.
+
+- `"preload"`:
+ The function is running to initiate data fetching.
+- `"navigate"`:
+ The function is running during navigation to the route.
+- `"initial"`:
+ The function is running for the first route on page load.
-The return value of the `preload` function is passed to the page component when called at anytime other than `preload`.
-This initializes things in there, or alternatively the following new `Data APIs` can be used.
+## Return value
+
+The value returned by `preload` is passed to the route's component as the `data` prop.
+
+- In the **preload phase** (`intent: "preload"`), the return value is **ignored**.
+- In the **rendering phase** (`intent: "navigate"` or `"initial"`), the return value is **captured** and provided to the component.
+
+## Examples
+
+```tsx
+import { Route, query, createAsync } from "@solidjs/router";
+
+const getProductQuery = query(async (id: string) => {
+ // ... Fetches a product from the server.
+}, "product");
+
+function ProductPage(props) {
+ const product = createAsync(() => getProductQuery(props.params.id));
+
+ return
{product()?.title}
;
+}
+
+function preloadData({ params }) {
+ getProductQuery(params.id);
+}
+
+function ProductRoutes() {
+ return (
+
+ );
+}
+```
diff --git a/src/routes/solid-start/building-your-application/data-fetching.mdx b/src/routes/solid-start/building-your-application/data-fetching.mdx
new file mode 100644
index 000000000..6204a6bb4
--- /dev/null
+++ b/src/routes/solid-start/building-your-application/data-fetching.mdx
@@ -0,0 +1,43 @@
+---
+title: "Data fetching"
+---
+
+Fetching data from a remote API or database is a core task for most applications.
+[Solid](/) and [Solid Router](/solid-router) provide foundational tools like the [`createResource` primitive](/guides/fetching-data) and [queries](/solid-router/concepts/queries) to manage asynchronous data.
+
+SolidStart builds on these capabilities, extending them to provide a comprehensive solution for data fetching in a full-stack environment.
+
+This page assumes you are familiar with the fundamental concepts of Solid and Solid Router.
+If you are a beginner, we highly recommend starting with the [queries documentation](/solid-router/concepts/queries).
+You can also find many practical examples in the [data fetching how-to guide](/solid-start/guides/data-fetching).
+
+## Server functions and queries
+
+Server functions provide a way to write functions that run exclusively on the server.
+This makes it safe to fetch data directly from a database without relying on a separate API endpoint.
+
+Server functions integrate seamlessly with queries, as they can be used as the fetcher for a query.
+
+```tsx
+import { query, redirect } from "@solidjs/router";
+import { useSession } from "vinxi/http";
+import { db } from "./db";
+
+const getCurrentUserQuery = query(async (id: string) => {
+ "use server";
+ const session = await useSession({
+ password: process.env.SESSION_SECRET as string,
+ name: "session",
+ });
+
+ if (session.data.userId) {
+ return await db.users.get({ id: session.data.userId });
+ } else {
+ throw redirect("/login");
+ }
+}, "currentUser");
+```
+
+In this example, the `getCurrentUserQuery` retrieves the session data, and if an authenticated user exists, it gets their information from the database and returns it.
+Otherwise, it redirects the user to the login page.
+All of these operations are performed completely on the server regardless of how the query is called.
diff --git a/src/routes/solid-start/building-your-application/data-loading.mdx b/src/routes/solid-start/building-your-application/data-loading.mdx
deleted file mode 100644
index 32445361e..000000000
--- a/src/routes/solid-start/building-your-application/data-loading.mdx
+++ /dev/null
@@ -1,157 +0,0 @@
----
-title: "Data loading"
----
-
-SolidStart aims to make it easy to load data from your data sources to keep your UI updated with your data.
-For most of your data requirements, routes will likely be used to decide what data to load.
-SolidStart includes nested routing to help structure your application's UI in a hierarchical way, so that you can share layouts.
-
-## Data loading on the client
-
-Solid provides a way to load data from your data sources using the [`createResource` primitive](/reference/basic-reactivity/create-resource).
-It takes an async function and returns a [signal](/reference/basic-reactivity/create-signal) from it.
-`createResource` integrates with [`Suspense`](/reference/components/suspense) and [`ErrorBoundary`](/reference/components/error-boundary) to help manage lifecycle and error states.
-
-```tsx tab title="TypeScript" {7-10}
-// src/routes/users.tsx
-import { For, createResource } from "solid-js";
-
-type User = { name: string; house: string };
-
-export default function Page() {
- const [users] = createResource(async () => {
- const response = await fetch("https://example.com/users");
- return (await response.json()) as User[];
- });
-
- return {(user) =>
};
-}
-```
-
-When fetching inside components, you can encounter unnecessary waterfalls, especially when nested under lazy loaded sections.
-To solve this, it is recommended to hoist the data fetching to the top of the component tree or, when in [SolidStart](/solid-start), use the server to fetch data in a non-blocking way.
-For the example below we will be using the data in APIs in [`solid-router`](/solid-router)
-
-Using some of the features of `solid-router`, we can create a cache for our data:
-
-```tsx tab title="TypeScript" {7, 10, 13}
-// /routes/users.tsx
-import { For } from "solid-js";
-import { createAsync, query } from "@solidjs/router";
-
-type User = { name: string; email: string };
-
-const getUsers = query(async () => {
- const response = await fetch("https://example.com/users");
- return (await response.json()) as User[];
-}, "users");
-
-export const route = {
- preload: () => getUsers(),
-};
-
-export default function Page() {
- const users = createAsync(() => getUsers());
-
- return {(user) =>
};
-}
-```
-
-With this method, however, there are some caveats to be aware of:
-
-1. The [`preload`](/solid-router/reference/preload-functions/preload) function is called **once** per route, which is the first time the user comes to that route.
- Following that, the fine-grained resources that remain alive synchronize with state/url changes to refetch data when needed.
- If the data needs a refresh, the [`refetch`](/guides/fetching-data#refetch) function returned in the `createResource` can be used.
-2. Before the route is rendered, the `preload` function is called.
- It does not share the same `context` as the route.
- The context tree that is exposed to the `preload` function is anything above the `Page` component.
-3. On both the server and the client, the `preload` function is called.
- The resources can avoid refetching if they serialized their data in the server render.
- The server-side render will only wait for the resources to fetch and serialize if the resource signals are accessed under a `Suspense` boundary.
-
-### Data loading always on the server
-
-An advantage of being a full-stack JavaScript framework is that it is easy to write data loading code that can run both on the server and client.
-SolidStart offers a way to do that and more.
-Through the `"use server"` comment you can tell the bundler to create an RPC and not include the code in the clients bundle.
-This lets you write code that only runs on the server without needing to create an API route for it.
-For example, it could be database access or internal APIs, or when you sit within your function and need to use your server.
-
-```tsx tab title="TypeScript" {8}
-// /routes/users.tsx
-import { For } from "solid-js";
-import { createAsync, query } from "@solidjs/router";
-
-type User = { name: string; email: string };
-
-const getUsers = query(async () => {
- "use server";
- return store.users.list();
-}, "users");
-
-export const route = {
- preload: () => getUsers(),
-};
-
-export default function Page() {
- const users = createAsync(() => getUsers());
-
- return {(user) =>
};
-}
-```
diff --git a/src/routes/solid-start/building-your-application/data-mutation.mdx b/src/routes/solid-start/building-your-application/data-mutation.mdx
new file mode 100644
index 000000000..2692c4dfc
--- /dev/null
+++ b/src/routes/solid-start/building-your-application/data-mutation.mdx
@@ -0,0 +1,104 @@
+---
+title: "Data mutation"
+---
+
+Mutating data on a server is a common task in most applications.
+[Solid Router](/solid-router) provides [actions](/solid-router/concepts/actions) to manage data mutations effectively.
+
+SolidStart builds upon the capabilities of actions, extending their scope to provide a comprehensive, full-stack solution for data mutations.
+
+This page does not cover the foundational concepts from Solid Router.
+If you are a beginner, we highly recommend starting with the [actions documentation](/solid-router/concepts/actions).
+You can also find many practical examples in the [data mutation how-to guide](/solid-start/guides/data-mutation).
+
+## Server functions and actions
+
+Server functions allow an action to run exclusively on the server.
+This enables performing sensitive operations—such as writing to a database or working with sessions—directly within the action.
+
+```tsx
+import { action, redirect } from "@solidjs/router";
+import { useSession } from "vinxi/http";
+import { db } from "./db";
+
+const logoutAction = action(async () => {
+ "use server";
+ const session = await useSession({
+ password: process.env.SESSION_SECRET as string,
+ name: "session",
+ });
+
+ if (session.data.sessionId) {
+ await session.clear();
+ await db.session.delete({ id: sessionId });
+ }
+
+ throw redirect("/");
+}, "logout");
+```
+
+In this example, the entire `logoutAction` runs on the server.
+It safely accesses the session to retrieve the `sessionId` and performs a database deletion without exposing this logic to the client.
+The `redirect` then navigates the user back to the home page.
+
+## Single-flight mutations
+
+When a piece of data changes on the server, the new data needs to be fetched so the UI doesn't fall out of sync.
+Traditionally, this is done in two separate HTTP requests: one to update the data, and a second to fetch the new data.
+
+Single-flight mutations are a unique feature of SolidStart that handles this pattern in a single request.
+This is enabled when two requirements are met:
+
+1. The action that updates the data must execute on the server using server functions.
+2. The data that the action updated must be preloaded.
+ If the action performs a redirect, preloading needs to happen on the destination page.
+
+```tsx title="src/routes/products/[id].tsx"
+import {
+ action,
+ query,
+ createAsync,
+ type RouteDefinition,
+ type RouteSectionProps,
+} from "@solidjs/router";
+import { db } from "./db";
+
+const updateProductAction = action(async (id: string, formData: FormData) => {
+ "use server";
+ const name = formData.get("name")?.toString();
+ await db.products.update(id, { name });
+}, "updateProduct");
+
+const getProductQuery = query(async (id: string) => {
+ "use server";
+ return await db.products.get(id);
+}, "product");
+
+export const route = {
+ preload: ({ params }) => getProductQuery(params.id as string),
+} satisfies RouteDefinition;
+
+export default function ProductDetail(props: RouteSectionProps) {
+ const product = createAsync(() => getProductQuery(props.params.id as string));
+
+ return (
+
+
Current name: {props.data.product?.name}
+
+
+
+
+
+ );
+}
+```
+
+In this example, `updateProductAction` updates the product within a server function, and `getProductQuery` is responsible for fetching the product data.
+Note that `getProductQuery` is preloaded on the route.
+
+When a user submits the form, a single POST request is sent to the server.
+After the action completes, `getProductQuery` is automatically revalidated.
+Because it's preloaded, SolidStart can trigger the revalidation on the server and stream the result back to the client in the same response.
diff --git a/src/routes/solid-start/building-your-application/data.json b/src/routes/solid-start/building-your-application/data.json
index 2da1baa8d..7d5641d01 100644
--- a/src/routes/solid-start/building-your-application/data.json
+++ b/src/routes/solid-start/building-your-application/data.json
@@ -4,7 +4,8 @@
"routing.mdx",
"api-routes.mdx",
"css-and-styling.mdx",
- "data-loading.mdx",
+ "data-fetching.mdx",
+ "data-mutation.mdx",
"head-and-metadata.mdx",
"route-prerendering.mdx",
"static-assets.mdx"
diff --git a/src/routes/solid-start/guides/data-fetching.mdx b/src/routes/solid-start/guides/data-fetching.mdx
index 5a1a4c38a..6707b6d95 100644
--- a/src/routes/solid-start/guides/data-fetching.mdx
+++ b/src/routes/solid-start/guides/data-fetching.mdx
@@ -2,17 +2,9 @@
title: "Data fetching"
---
-SolidStart is built on top of [Solid](/) and uses [Solid Router](/solid-router) by default.
-This means you can leverage their respective data-fetching primitives within SolidStart.
-Since SolidStart itself provides minimal data-fetching APIs, most functionality comes from Solid and Solid Router.
+This guide provides practical examples of common data-fetching tasks in SolidStart.
-This guide provides practical examples of common data-fetching tasks using these primitives.
-
-:::note
-For detailed API information, refer to the [Solid](/) and [Solid Router](/solid-router) documentation.
-:::
-
-Here's a simple example:
+Here's an example showing how to create a [`query`](/solid-router/concepts/queries) and access its data with the [`createAsync` primitive](/solid-router/reference/data-apis/create-async):
```tsx tab title="TypeScript"
// src/routes/index.tsx
@@ -54,12 +46,9 @@ export default function Page() {
}
```
-In this example, a [`query`](/solid-router/reference/data-apis/query) is created.
-In order to access it's data within the component, the [`createAsync`](/solid-router/reference/data-apis/create-async) primitive was used.
-
## Showing loading UI
-To show a loading UI during data-fetching:
+To show a loading UI during data fetching:
1. Import [`Suspense`](/reference/components/suspense) from `solid-js`.
2. Wrap your data rendering in ``, and use the `fallback` prop to show a component during data fetching.
@@ -110,7 +99,7 @@ export default function Page() {
## Handling errors
-To show a fallback UI if the data-fetching fails:
+To show a fallback UI if the data fetching fails:
1. Import [`ErrorBoundary`](/reference/components/error-boundary) from `solid-js`.
2. Wrap the data rendering in ``, and use the `fallback` prop to show a component if an error occurs.
@@ -165,7 +154,7 @@ export default function Page() {
## Preloading data
-Data fetching can be optimized during user navigation by preloading the data:
+To preload data before a route renders:
1. Export a `route` object with a [`preload`](/solid-router/reference/preload-functions/preload) function.
2. Run your query inside the `preload` function.
@@ -225,7 +214,7 @@ export default function Page() {
## Passing parameters to queries
-When creating a query that accepts parameters, define your query function to take any number of arguments:
+When creating a query that accepts parameters, define your query function to take any number of parameters:
```tsx tab title="TypeScript" {5} {11} {16}
// src/routes/posts/[id]/index.tsx
@@ -283,7 +272,7 @@ export default function Page() {
## Using a database or an ORM
-To safely interact with your database or ORM in a query, ensure it's server-only by adding [`"use server"`](/solid-start/reference/server/use-server) as the first line of your query:
+To safely interact with your database or ORM in a query, use a [server function](/solid-start/reference/server/use-server):
```tsx tab title="TypeScript" {7-8}
// src/routes/index.tsx
@@ -388,5 +377,5 @@ export default function Page() {
See the [`createResource`](/reference/basic-reactivity/create-resource) API reference for more information.
:::note[Advanced Data Handling]
-For advanced features like automatic background re-fetching or infinite queries, you can use [Tanstack Query](https://tanstack.com/query/latest/docs/framework/solid/overview).
+For advanced features like automatic background re-fetching or infinite queries, you can use [TanStack Query](https://tanstack.com/query/latest/docs/framework/solid/overview).
:::
diff --git a/src/routes/solid-start/guides/data-mutation.mdx b/src/routes/solid-start/guides/data-mutation.mdx
index abcc75f27..e2bcced15 100644
--- a/src/routes/solid-start/guides/data-mutation.mdx
+++ b/src/routes/solid-start/guides/data-mutation.mdx
@@ -12,7 +12,7 @@ To handle [`
`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/f
See the [Action API reference](/solid-router/reference/data-apis/action#notes-of-form-implementation-and-ssr) for more information.
2. Pass the action to the `
` element using the `action` prop.
3. Ensure the `
` element uses the `post` method for submission.
-4. Use the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) object in the action to extract field data using the navite `FormData` methods.
+4. Use the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) object in the action to extract field data using the native `FormData` methods.
```tsx tab title="TypeScript" {4-10} {14}
// src/routes/index.tsx
@@ -486,12 +486,12 @@ export default function Page() {
}
```
-## Invoking an action programmatically
+## Triggering an action programmatically
-To programmatically invoke an action:
+To programmatically trigger an action:
1. Import [`useAction`](/solid-router/reference/data-apis/use-action) from `@solidjs/router`.
-2. Call `useAction` with your action, and use the returned function to invoke the action.
+2. Call `useAction` with your action, and use the returned function to trigger the action.
```tsx tab title="TypeScript" {14} {18}
// src/routes/index.tsx
diff --git a/src/routes/solid-start/reference/server/use-server.mdx b/src/routes/solid-start/reference/server/use-server.mdx
index 87dbad035..6c4cc6d33 100644
--- a/src/routes/solid-start/reference/server/use-server.mdx
+++ b/src/routes/solid-start/reference/server/use-server.mdx
@@ -44,7 +44,7 @@ In both examples, the `logHello` function will only show in the server console,
## Usage with Data APIs
-Server functions can be used for fetching data and performing actions on the server.
+Server functions can be used for fetching data and performing actions on the server.
The following examples show how to use server functions alongside solid-router's data APIs.
```tsx {3}
@@ -61,12 +61,12 @@ const updateUser = action(async (id, data) => {
```
-When `getUser` or `updateUser` are invoked on the client, an http request will be made to the server, which calls the corresponding server function.
+When `getUser` or `updateUser` are triggered on the client, an http request will be made to the server, which calls the corresponding server function.
## Single-flight mutations
-In the above example, when the `updateUser` action is called, a redirect is thrown on the server.
-Solid Start can handle this redirect on the server instead of propagating it to the client.
+In the above example, when the `updateUser` action is called, a redirect is thrown on the server.
+Solid Start can handle this redirect on the server instead of propagating it to the client.
The data for the redirected page is fetched and streamed to the client in the same http request as the `updateUser` action, rather than the client requiring a separate http request for the redirected page.
## Serialization
From 20cf242155dc7dfb2298ab4cc33dd15ef558ef1b Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Wed, 27 Aug 2025 21:36:48 -0700
Subject: [PATCH 03/37] quick start
---
src/routes/getting-started/quick-start.mdx | 71 +++++++++++++++++++---
1 file changed, 64 insertions(+), 7 deletions(-)
diff --git a/src/routes/getting-started/quick-start.mdx b/src/routes/getting-started/quick-start.mdx
index 4e5a93110..8c0038ce1 100644
--- a/src/routes/getting-started/quick-start.mdx
+++ b/src/routes/getting-started/quick-start.mdx
@@ -1,5 +1,5 @@
---
-title: Quick Start Guide
+title: Quick Start
order: 1
---
@@ -15,12 +15,69 @@ If you prefer a more complete development setup, you can use the StackBlitz [Jav
## Create a New Project
:::note[Before You Begin]
-Make sure you have a recent version of your prefer JavaScript runtime installed, such as [Node.js](https://nodejs.org/en), [Bun](https://bun.sh/), or [Deno](https://deno.com/).
+Make sure you have a recent version of your preferred JavaScript runtime installed, such as [Node.js](https://nodejs.org/en), [Bun](https://bun.sh/), or [Deno](https://deno.com/).
:::
-[TODO]
+To create a new Solid project, follow these steps:
-- Navigate to directory and run command
-- CLI will take you through options
-- Once you've selected your options, the CLI will prompt you to install the dependencies and start the development server
-- Open browser and navigate to the provided local URL to see your new Solid app in action!
\ No newline at end of file
+1. **Open your terminal and navigate to the directory** where you want to create your project.
+
+2. **Run the following command:**
+
+```package-create
+solid
+```
+
+3. **Follow the CLI prompts** to select your project name, template (JavaScript or TypeScript), and other options.
+
+```sh
+◆ Project Name
+|
+
+◆ Is this a SolidStart project?
+| ● Yes / ○ No
+
+◆ Which template would you like to use?
+│ ● ts
+│ ○ ts-vitest
+│ ○ ts-uvu
+│ ○ ts-unocss
+│ ○ ts-tailwindcss
+
+◆ Use TypeScript?
+│ ● Yes / ○ No
+```
+
+4. **Follow the instructions to install the dependencies and start the development server:**
+
+```sh title="npm" tab="package-manager"
+cd solid-project
+npm install
+npm run dev
+```
+
+```sh title="pnpm" tab="package-manager"
+cd solid-project
+pnpm install
+pnpm dev
+```
+
+```sh title="yarn" tab="package-manager"
+cd solid-project
+yarn install
+yarn dev
+```
+
+```sh title="bun" tab="package-manager"
+cd solid-project
+bun install
+bun run dev
+```
+
+```sh title="deno" tab="package-manager"
+cd solid-project
+deno install
+deno run dev
+```
+
+6. **Open your browser and go to the local URL** provided in the terminal to see your new Solid app in action!
\ No newline at end of file
From a67220a0a4fbeb9b70d9f62734c9ef7403365fbd Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Thu, 28 Aug 2025 13:14:38 -0700
Subject: [PATCH 04/37] update titles and reactivity basics page
---
src/routes/components/data.json | 2 +-
src/routes/components/intro.mdx | 10 ++++
src/routes/reactivity/basics.mdx | 88 +++++++++++++++++++++++++++++
src/routes/reactivity/data.json | 2 +-
src/routes/reactivity/effects.mdx | 2 +-
src/routes/reactivity/memos.mdx | 2 +-
src/routes/reactivity/overview.mdx | 74 ------------------------
src/routes/reactivity/resources.mdx | 2 +-
src/routes/reactivity/signals.mdx | 76 +++++++++++++++++++++++--
src/routes/reactivity/stores.mdx | 2 +-
10 files changed, 175 insertions(+), 85 deletions(-)
create mode 100644 src/routes/components/intro.mdx
create mode 100644 src/routes/reactivity/basics.mdx
delete mode 100644 src/routes/reactivity/overview.mdx
diff --git a/src/routes/components/data.json b/src/routes/components/data.json
index f675b706b..12b3976db 100644
--- a/src/routes/components/data.json
+++ b/src/routes/components/data.json
@@ -1,4 +1,4 @@
{
"title": "Components",
- "pages": []
+ "pages": ["intro.md"]
}
diff --git a/src/routes/components/intro.mdx b/src/routes/components/intro.mdx
new file mode 100644
index 000000000..cdd8bd041
--- /dev/null
+++ b/src/routes/components/intro.mdx
@@ -0,0 +1,10 @@
+---
+title: "Intro to Components"
+order: 1
+---
+
+[TODO]
+
+## Component lifecycle
+
+[TODO]
\ No newline at end of file
diff --git a/src/routes/reactivity/basics.mdx b/src/routes/reactivity/basics.mdx
new file mode 100644
index 000000000..17d223d9b
--- /dev/null
+++ b/src/routes/reactivity/basics.mdx
@@ -0,0 +1,88 @@
+---
+title: "Reactivity Basics"
+order: 1
+---
+
+
+Reactivity is the foundation of Solid.
+It’s the programming model where **changes in data automatically update the parts of your app that depend on it**.
+
+Solid’s approach is **fine-grained**: instead of re-rendering entire components, only the exact parts of the DOM that depend on a value update. This makes applications efficient and responsive, even as they grow.
+
+## Core Principles of Reactivity
+
+Solid’s reactivity is built on three key ideas: **signals, subscribers, and tracking scopes**.
+Together, these create a system where updates are precise, automatic, and efficient.
+
+### Signals: Reactive Values
+
+A **signal** is a reactive value container.
+They consist of 2 parts:
+- **Getter** → reads the current value.
+- **Setter** → updates the value and notifies dependents.
+
+```tsx
+const [count, setCount] = createSignal(0);
+
+console.log(count()); // 0
+setCount(1);
+console.log(count()); // 1
+```
+
+Signals can hold any type of value:
+- primitives (string, number, boolean)
+- objects and arrays
+- application state (user, theme, current page)
+
+Learn more in the [Signals page](/reactivity/signals).
+
+### Subscribers: Reactive Consumers
+
+If signals are the **source of truth**, subscribers are the **reactive consumers**.
+
+A subscriber is any function or construct that reads a signal inside a tracking scope and automatically re-runs whenever it changes.
+This is what makes Solid’s reactivity *fine-grained*: only the subscribers that depend on a signal update, not the entire component.
+
+How subscribers work:
+1. **Observation** → subscriber runs and reads signals.
+2. **Dependency tracking** → those signals register the subscriber.
+3. **Response** → when a signal changes, the subscriber re-runs.
+
+### Tracking Scopes: Connecting Signals & Subscribers
+
+A **tracking scope** is the environment where Solid records which signals are being used.
+When a signal is read within a tracking scope, it registers the current subscriber as a dependency.
+Once that signal changes, it will notify the subscriber to re-run and update accordingly.
+
+Tracking scopes within Solid include:
+- Component render functions (JSX return values)
+- Reactive computations (e.g., `createMemo`)
+- Effects (e.g., `createEffect`)
+
+Example of a tracking vs non-tracking scope:
+
+```tsx
+import { createSignal } from "solid-js";
+
+function Counter() {
+ const [count, setCount] = createSignal(0);
+
+ console.log(count()) // ❌ Not tracked — runs once
+
+ return (
+
+ );
+}
+```
+
+Tracking scopes are what enable **precise DOM updates**: only parts of the UI that depend on signals re-run, not the entire component.
+You can learn more about [component lifecycles in the Intro to Components page](/components/intro).
+
+
+## Related pages
+- [Signals](/reactivity/signals)
+- [Reactive Side Effects](/reactivity/effects)
+- [Introduction to Components](/components/intro)
diff --git a/src/routes/reactivity/data.json b/src/routes/reactivity/data.json
index cf237240a..5cdfeb89b 100644
--- a/src/routes/reactivity/data.json
+++ b/src/routes/reactivity/data.json
@@ -1,7 +1,7 @@
{
"title": "Reactivity",
"pages": [
- "overview.mdx",
+ "basics.mdx",
"signals.mdx",
"memos.mdx",
"effects.mdx",
diff --git a/src/routes/reactivity/effects.mdx b/src/routes/reactivity/effects.mdx
index 64f626609..1086c53e9 100644
--- a/src/routes/reactivity/effects.mdx
+++ b/src/routes/reactivity/effects.mdx
@@ -1,5 +1,5 @@
---
-title: "Effects"
+title: "Derived Reactive Values"
order: 4
---
diff --git a/src/routes/reactivity/memos.mdx b/src/routes/reactivity/memos.mdx
index bdaf190ab..6f07f36bb 100644
--- a/src/routes/reactivity/memos.mdx
+++ b/src/routes/reactivity/memos.mdx
@@ -1,5 +1,5 @@
---
-title: "Memos"
+title: "Memoized Computations"
order: 3
---
diff --git a/src/routes/reactivity/overview.mdx b/src/routes/reactivity/overview.mdx
deleted file mode 100644
index 725a2186c..000000000
--- a/src/routes/reactivity/overview.mdx
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: "Overview"
-order: 1
----
-
-[TODO: Review]
-
-:::note
-While this guide can be helpful for understanding reactive systems, it does use some Solid-specific terminology and concepts.
-:::
-
-Reactivity is what powers the interactivity of Solid apps.
-This programming paradigm refers to a system's ability to respond to changes in data, or state, automatically and efficiently.
-Solid is built with reactivity at the core of its design, assisting applications with staying up-to-date with its underlying data.
-
-## The Importance of Reactivity
-
-Reactivity is what keeps the user interface (UI) in sync with the underlying application state.
-When the state changes, the UI is automatically updated, reducing the need for manual updates.
-
-In addition, reactivity enables real-time updates, allowing applications to reflect changes instantly without requiring a full page refresh.
-This helps with creating more responsive and interactive user experiences.
-
-As an example, when building a Counter, you can use the reactive primitives provided by Solid to create a counter.
-Once the counter is set up, whenever the count changes, the UI will automatically update to reflect the new count:
-
-```tsx
-function Counter() {
- const [count, setCount] = createSignal(0);
- const increment = () => setCount((prev) => prev + 1);
-
- return (
-
- Count: {count()}{" "}
- {/* Only `count()` is updated when the button is clicked. */}
-
-
- );
-}
-```
-
-## Reactive Principles
-
-### Signals
-
-Signals serve as the core elements within a reactive system.
-They play a crucial role in tracking and managing state changes, allowing the UI to respond automatically when the underlying data changes.
-They are responsible for storing and managing data, as well as triggering updates across the system.
-
-Signals are able to achieve this reactivity through the use of:
-
-- **Getters**: A function responsible for retrieving the current value of a signal.
-When called within a reactive context, it will give access to the current value of the signal.
-- **Setters**: This function is responsible for updating the value of a signal.
-To trigger reactivity, setters notify the system that the signal's value has changed, prompting anything that depends on the signal to re-evaluate and update accordingly.
-
-
-
-### Subscribers
-
-Subscribers refer to other reactive contexts or components that depend on the value of a signal.
-These automated responders keep the system up-to-date by re-evaluating and updating whenever the signal's value changes.
-
-Subscribers work based on two main actions:
-- **Observation**: The core function of a subscriber is to observe signals.
-This keeps the subscriber informed about any changes to the signal(s) they're tracking.
-- **Respond**: Once the signal has updated and the subscriber is notified, it triggers a re-evaluation of the dependent computations or UI updates.
-
-[TODO: Some kind of image / code block??]
\ No newline at end of file
diff --git a/src/routes/reactivity/resources.mdx b/src/routes/reactivity/resources.mdx
index 143db8236..16342dad1 100644
--- a/src/routes/reactivity/resources.mdx
+++ b/src/routes/reactivity/resources.mdx
@@ -1,5 +1,5 @@
---
-title: "Resources"
+title: "Handling Async Data"
order: 6
---
diff --git a/src/routes/reactivity/signals.mdx b/src/routes/reactivity/signals.mdx
index 701839712..6a5eab9d4 100644
--- a/src/routes/reactivity/signals.mdx
+++ b/src/routes/reactivity/signals.mdx
@@ -3,8 +3,74 @@ title: "Signals"
order: 2
---
-[TODO:
-Concept page on signals
-- Any complex parts should be moved to reference section
-- Move any concept bits from reference section into here
-]
\ No newline at end of file
+Signals are the **primary way to manage state** in a Solid application.
+They store values, notify dependents when those values change, and form the [foundation of reactivity](/reactivity/overview).
+
+You can use signals for any kind of state:
+- simple values (strings, numbers)
+- complex values (objects, arrays)
+- application state (current user, theme, page, etc.)
+
+## What is a Signal?
+
+A **signal** is a reactive value container.
+- It holds a value.
+- It provides a **getter** to read the value.
+- It provides a **setter** to update the value.
+- When the value changes, any reactive computations that depend on it are updated automatically.
+
+They can be thought of as a **reactive variable**.
+
+## Create a Signal
+
+
+Use [`createSignal`](/reference/basic-reactivity/create-signal) from `solid-js`:
+
+```tsx
+import { createSignal } from "solid-js";
+
+const [count, setCount] = createSignal(0);
+// ^ getter ^ setter
+```
+
+:::note
+The [getter, setter] syntax uses [array destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment)().
+:::
+
+
+## Read a Signal's Value
+
+To read the current value of a signal, simply call the getter function:
+
+```tsx
+console.log(count()); // 0
+```
+
+## Update a Signal's Value
+
+To update the value of a signal, call the setter function with the new value:
+
+```tsx
+setCount(1);
+console.log(count()); // 1
+```
+
+## Reactivity in Action
+
+Signals are **reactive**: when used inside a tracking scope, they automatically notify dependents when updated.
+
+```tsx
+function Counter() {
+ const [count, setCount] = createSignal(0);
+ const increment = () => setCount(prev => prev + 1);
+
+ return (
+
+ );
+}
+```
+
+:::
diff --git a/src/routes/reactivity/stores.mdx b/src/routes/reactivity/stores.mdx
index eb8a33bb3..c8c7e9151 100644
--- a/src/routes/reactivity/stores.mdx
+++ b/src/routes/reactivity/stores.mdx
@@ -1,4 +1,4 @@
---
-title: "Stores"
+title: "Reactive State Management"
order: 5
---
From 2d97093fd73772078875c2d83ed0ce3c64ca2f3f Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Thu, 28 Aug 2025 13:20:58 -0700
Subject: [PATCH 05/37] focused signals page
---
old pages/concepts/signals.mdx | 54 +++++++++++++++++++---------------
1 file changed, 30 insertions(+), 24 deletions(-)
diff --git a/old pages/concepts/signals.mdx b/old pages/concepts/signals.mdx
index aa59b6515..71662e63a 100644
--- a/old pages/concepts/signals.mdx
+++ b/old pages/concepts/signals.mdx
@@ -3,39 +3,45 @@ title: Signals
order: 2
---
-Signals are the primary means of [managing state](/concepts/intro-to-reactivity#state-management) in your Solid application.
-They provide a way to store and update values, and are the foundation of [reactivity](/concepts/intro-to-reactivity) in Solid.
+Signals are the **core primitive for state** in Solid.
+They provide a way to store a value, read it, and update it.
+When a signal changes, anything that depends on it will update automatically.
-Signals can be used to represent any kind of state in your application, such as the current user, the current page, or the current theme.
-This can be any value, including primitive values such as strings and numbers, or complex values such as objects and arrays.
+Signals can represent any kind of state in your application:
+- simple values like numbers or strings
+- complex values like objects or arrays
+- application state such as the current user, theme, or page
+
+For an overview of how signals fit into Solid’s reactive model, see [Reactivity Basics](/reactivity/basics).
## Creating a signal
-You can create a signal by calling the [`createSignal`](/reference/basic-reactivity/create-signal) function, which is imported from `solid-js`.
-This function takes an initial value as an argument, and returns a pair of functions: a **getter** function, and a **setter** function.
+Use [`createSignal`](/reference/basic-reactivity/create-signal) from `solid-js` to create a signal.
+It returns a pair of functions:
+- a **getter** to read the value
+- a **setter** to update the value
```jsx
import { createSignal } from "solid-js";
const [count, setCount] = createSignal(0);
-// ^ getter ^ setter
+// ^ getter ^ setter
```
- :::note
- The syntax using `[` and `]` is called [array destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment).
+:::note
+The syntax using `[` and `]` is called [array destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment).
This lets you extract values from the array.
In the context of `createSignal`, the first value is the getter function, and the second value is the setter function.
-
:::
## Accessing values
The getter function returned by `createSignal` is used to access the value of the signal.
-You call this function with no arguments to get the current value of the signal:
+Call the getter function with no arguments to read the current value:
```jsx
-console.log(count()); // output: 0
+console.log(count()); // 0
```
## Updating values
@@ -46,7 +52,7 @@ This function takes an argument that represents the new value of the signal:
```jsx
setCount(count() + 1);
-console.log(count()); // output: 1
+console.log(count()); // 1
```
The setter function can also take a function that passes the previous value.
@@ -54,14 +60,13 @@ The setter function can also take a function that passes the previous value.
```jsx
setCount((prevCount) => prevCount + 1);
-console.log(count()); // output: 1
+console.log(count()); // 1
```
## Reactivity
-Signals are reactive, which means that they automatically update when their value changes.
-When a signal is called within a [tracking scope](/concepts/intro-to-reactivity#tracking-changes), the signal adds the dependency to a list of subscribers.
-Once a signal's value changes, it notifies all of its dependencies of the change so they can re-evaluate their values and update accordingly.
+Signals are **reactive**, which means that they automatically update when their value changes.
+For example, using a signal inside JSX automatically makes the DOM update when the signal changes:
```jsx
function Counter() {
@@ -79,12 +84,13 @@ function Counter() {
}
```
-:::note
-A tracking scope can be created by [`createEffect`](/reference/basic-reactivity/create-effect) or [`createMemo`](/reference/basic-reactivity/create-memo), which are other Solid primitives.
-
-Both functions subscribe to the signals accessed within them, establishing a dependency relationship.
-Once this relationship is established, the function is notified whenever the signal changes.
+To learn how signals connect to effects and tracking scopes, see:
+- [Reactive Side Effects](/reactivity/effects)
+- [Memoized Computations](/reactivity/memo)
-:::
+## Related Pages
-To learn more about how to use Signals in your application, visit our [state management guide](/guides/state-management).
+- [Reactivity Basics](/reactivity/basics)
+- [Reactive Side Effects](/reactivity/effects)
+- [Memoized Computations](/reactivity/memo)
+- [Introduction to Components](/components/intro)
From ce0da5c9650edbb7e8fa4cda742ad4bbbc98d994 Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Thu, 28 Aug 2025 14:01:30 -0700
Subject: [PATCH 06/37] understanding JSX page
---
src/routes/components/data.json | 2 +-
src/routes/components/how-to/data.json | 4 +
.../components/how-to/event-listeners.mdx | 4 +
src/routes/components/how-to/styling.mdx | 4 +
src/routes/getting-started/counter.mdx | 12 --
.../getting-started/understanding-jsx.mdx | 149 ++++++++++++++++++
6 files changed, 162 insertions(+), 13 deletions(-)
create mode 100644 src/routes/components/how-to/data.json
create mode 100644 src/routes/components/how-to/event-listeners.mdx
create mode 100644 src/routes/components/how-to/styling.mdx
delete mode 100644 src/routes/getting-started/counter.mdx
create mode 100644 src/routes/getting-started/understanding-jsx.mdx
diff --git a/src/routes/components/data.json b/src/routes/components/data.json
index 12b3976db..d4bf1d89b 100644
--- a/src/routes/components/data.json
+++ b/src/routes/components/data.json
@@ -1,4 +1,4 @@
{
"title": "Components",
- "pages": ["intro.md"]
+ "pages": ["intro.md", "how-to"]
}
diff --git a/src/routes/components/how-to/data.json b/src/routes/components/how-to/data.json
new file mode 100644
index 000000000..994008934
--- /dev/null
+++ b/src/routes/components/how-to/data.json
@@ -0,0 +1,4 @@
+{
+ "title": "How-to",
+ "pages": ["event-listeners.mdx", "styling.mdx"]
+}
diff --git a/src/routes/components/how-to/event-listeners.mdx b/src/routes/components/how-to/event-listeners.mdx
new file mode 100644
index 000000000..db41d97a4
--- /dev/null
+++ b/src/routes/components/how-to/event-listeners.mdx
@@ -0,0 +1,4 @@
+---
+title: "Using Event Listeners"
+---
+
diff --git a/src/routes/components/how-to/styling.mdx b/src/routes/components/how-to/styling.mdx
new file mode 100644
index 000000000..0953ba88e
--- /dev/null
+++ b/src/routes/components/how-to/styling.mdx
@@ -0,0 +1,4 @@
+---
+title: "Styling Components"
+---
+
diff --git a/src/routes/getting-started/counter.mdx b/src/routes/getting-started/counter.mdx
deleted file mode 100644
index ee8d28182..000000000
--- a/src/routes/getting-started/counter.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: "Counter Tutorial"
-order: 2
----
-
-[TODO]
-
-1. Open your newly scaffolded project in your code editor of choice.
-2. Create a new file called `Counter.jsx` in the `src/components` directory.
-3. In `Counter.tsx`, use Solid's `createSignal` to create a reactive counter state.
-4. Export the `Counter` component and import it into your main application file (e.g., `src/App.jsx`).
-5. Use the `Counter` component in your application and test its functionality.
\ No newline at end of file
diff --git a/src/routes/getting-started/understanding-jsx.mdx b/src/routes/getting-started/understanding-jsx.mdx
new file mode 100644
index 000000000..0d0031d3f
--- /dev/null
+++ b/src/routes/getting-started/understanding-jsx.mdx
@@ -0,0 +1,149 @@
+---
+title: "Understanding JSX"
+order: 2
+---
+
+Solid's JSX is a JavaScript extension that lets you write **HTML-like syntax inside JavaScript**.
+It keeps your rendering logic and markup together, making components easier to read and maintain.
+
+## How Solid uses JSX
+
+Solid was designed to align closely with HTML standards.
+
+```tsx
+const element =
I'm JSX!!
+```
+
+Unlike some other frameworks, Solid compiles JSX directly to real DOM nodes.
+This means:
+- JSX expressions map closely to HTML.
+- You can use variables and functions inline using curly braces `{}`.
+- Only the parts of the DOM that depend on reactive state update.
+This avoids the whole component re-rendering, improving performance.
+
+```tsx
+const component = () => {
+ const animal = { breed: "cat", name: "Midnight" }
+
+ return (
+
+ I have a {animal.breed} named {animal.name}.
+
+ )
+}
+```
+
+## Solid's JSX Rules
+
+### 1. Return a Single Root Element
+
+Each component must return a single root element.
+Since JSX maintains the familiar tree-like structure of HTML, having a single root element helps keep the hierarchy clear.
+If you need multiple top-level elements, wrap them in a `
`, ``, or use a fragment `<>...>`.
+
+```tsx
+function App() {
+ return (
+
+
Hello World!
+
Welcome to JSX in Solid.
+
+ )
+}
+```
+
+```advanced
+JSX in Solid compiles into structured HTML.
+Static elements are optimized once, while dynamic ones get special markers so Solid can update them efficiently.
+Requiring a single root element keeps the hierarchy consistent and easier to update.
+```
+
+
+### 2. Close All Tags
+
+All tags must be properly closed.
+This includes self-closing tags like ``, ``, and ` `.
+
+```tsx
+// Correct
+
+
+// Incorrect
+
+```
+
+### 3. Properties vs Attributes
+
+In Solid's JSX, you can use both HTML attributes and JSX properties (props) to define element behavior and appearance.
+
+#### HTML attributes
+
+Solid's JSX blends HTML attributes with JavaScript expressions.
+
+- **HTML attributes** → work similar to regular HTML, but you can use JavaScript expressions inside curly braces `{}`.
+- **Event listeners** → Solid's JSX allows you to add event listeners using camelCase (e.g., `onClick`, `onChange`) or all lowercase (e.g., `onclick`, `onchange`).
+- **Inline styles** → You can apply styles directly using the `style` attribute with a JavaScript object.
+
+```tsx
+
+
+
+```
+
+You can also use JavaScript expressions to set attribute values dynamically:
+
+```tsx
+const isActive = true;
+
+
+```
+
+For more information on:
+- [Using Event Listeners](/components/how-to/event-listeners)
+- [Styling Components](/components/how-to/styling)
+
+#### JSX Properties (Props)
+
+JSX properties (or props) are how you pass data and event handlers to components in Solid.
+They work similarly to HTML attributes but can accept JavaScript expressions.
+
+In this example, the `name` prop is passed to the `Greeting` component, which uses it within its JSX:
+
+```tsx
+function App() {
+ return (
+
+
+
+
+ );
+}
+
+function Greeting(props) {
+ return
Hello, {props.name}!
;
+}
+```
+
+The core concepts of JSX properties in Solid include:
+- **Static props**: Directly integrated into the HTML by cloning the template and using them as attributes.
+- **Dynamic props**: Rely on state, allowing content or properties to change in response to user interactions or other events.
+An example is changing the style of an element based on a signal (`value={value()}`).
+- **Data transfer**: Props can be used to fill components with data from resources, such as API responses or context providers.
+This allows for components to update reactively when the underlying data changes.
+
+:::note
+In JSX, expressions are applied in the order they appear.
+This works for most elements, but some (i.e. ``) require attributes in a specific order.
+When order matters, make sure to define expressions in the sequence the element expects.
+:::
+
+## Related Pages
+- [Using Event Listeners](/components/how-to/event-listeners)
+- [Styling Components](/components/how-to/styling)
+- [Passing Data with Props](/components/props)
From a96251c0d92d7883ecaed802cc4b578187ee6ab4 Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Fri, 29 Aug 2025 20:38:41 -0700
Subject: [PATCH 07/37] new files
---
old pages/concepts/intro-to-reactivity.mdx | 248 ---------------------
old pages/concepts/signals.mdx | 96 --------
old pages/concepts/understanding-jsx.mdx | 129 -----------
old pages/quick-start.mdx | 80 -------
src/routes/components/data.json | 2 +-
src/routes/getting-started/data.json | 2 +-
6 files changed, 2 insertions(+), 555 deletions(-)
delete mode 100644 old pages/concepts/intro-to-reactivity.mdx
delete mode 100644 old pages/concepts/signals.mdx
delete mode 100644 old pages/concepts/understanding-jsx.mdx
delete mode 100644 old pages/quick-start.mdx
diff --git a/old pages/concepts/intro-to-reactivity.mdx b/old pages/concepts/intro-to-reactivity.mdx
deleted file mode 100644
index 5b885169d..000000000
--- a/old pages/concepts/intro-to-reactivity.mdx
+++ /dev/null
@@ -1,248 +0,0 @@
----
-title: "Intro to reactivity"
-order: 1
----
-
-**Note**: While this guide is useful for understanding reactive systems, it does use some Solid-specific terminology.
-
-Reactivity powers the interactivity in Solid applications.
-This programming paradigm refers to a system's ability to respond to changes in data or state automatically.
-With Solid, reactivity is the basis of its design, ensuring applications stay up-to-date with their underlying data.
-
-## Importance of reactivity
-
-1. Reactivity keeps the user interface (UI) and state in sync, which reduces the need for manual updates.
-
-2. Real-time updates create a more responsive and interactive user experience.
-
-```jsx
-function Counter() {
- const [count, setCount] = createSignal(0);
- const increment = () => setCount((prev) => prev + 1);
-
- return (
-
- Count: {count()}{" "}
- {/* Only `count()` is updated when the button is clicked. */}
-
-
- );
-}
-```
-
-This `Counter` function sets up a button that, when clicked, calls the `increment` function to increase the `count` by one.
-This updates just the number displayed _without_ refreshing the entire component.
-
-
-
-## Reactive principles
-
-### Signals
-
-Signals serve as core elements in reactive systems, playing an important role in data management and system responsiveness.
-They are responsible for storing and managing data, as well as triggering updates across the system.
-This is done through the use of getters and setters.
-
-```jsx
-const [count, setCount] = createSignal(0);
-// ^ getter ^ setter
-```
-
-
-
-- **Getter**: A function responsible for accessing the current value of the signal.
- You call a getter to access the data stored in a signal within a component.
-
-- **Setter**:
- The function used to modify a signal's value.
- To trigger reactive updates across an application, you call a setter to update the value of a signal.
-
-```js
-console.log(count()); // `count()` is a getter that returns the current value of `count`, which is `0`.
-
-setCount(1); // the setter, `setCount`, updates the value of `count`.
-
-console.log(count()); // the updated value of `count` is now `1`.
-```
-
-### Subscribers
-
-Subscribers are the other core element in reactive systems.
-They are responsible for tracking changes in signals and updating the system accordingly.
-They are automated responders that keep the system up-to-date with the latest data changes.
-
-Subscribers work based on two main actions:
-
-- **Observation**: At their core, subscribers observe signals.
- This keeps the subscriber primed to pick up on any changes to the signal they are tracking.
-- **Response**: When a signal changes, the subscriber is notified.
- This triggers the subscriber to respond to the change in the signal.
- This can involve tasks like updating the UI or calling external functions.
-
-```jsx
-function Counter() {
- const [count, setCount] = createSignal(0);
- const increment = () => setCount((prev) => prev + 1);
-
- createEffect(() => {
- console.log(count());
- });
- // the `createEffect` will trigger the console log every time `count` changes.
-}
-```
-
-## State management
-
-State management is the process of managing the state of an application.
-This involves storing and updating data, as well as responding to the changes in it.
-
-With Solid, state management is handled through signals and subscribers.
-Signals are used to store and update data, while subscribers are used to respond to changes in the data.
-
-### Tracking changes
-
-Tracking changes involves monitoring any updates to the data and responding accordingly.
-This is done through the use of subscribers.
-
-When a signal is not accessed within a tracking scope, an update to the signal will not trigger an update.
-This happens because if a signal is not being tracked, it is not able to notify any subscribers of the change.
-
-```jsx
-const [count, setCount] = createSignal(0);
-
-console.log("Count:", count());
-
-setCount(1);
-
-// Output: Count: 0
-
-// `count` is not being tracked, so the console log will not update when `count` changes.
-```
-
-Since initialization is a **one-time event**, if a signal is accessed _outside of a tracking scope_, it will not be tracked.
-To track a signal, it must be accessed within the scope of a subscriber.
-Reactive primitives, such as [effects](/concepts/effects), can be used to create subscribers.
-
-```jsx
-const [count, setCount] = createSignal(0);
-
-createEffect(() => {
- console.log("Count:", count());
-});
-
-setCount(1);
-
-// Output: Count: 0
-// Count: 1
-```
-
-### Updating the UI
-
-The UI of a Solid application is built using [JSX](/concepts/understanding-jsx).
-JSX creates a tracking scope behind the scenes, which allows signals to be tracked within the return statement of a component.
-
-```jsx
-function Counter() {
- const [count, setCount] = createSignal(0);
- const increment = () => setCount((prev) => prev + 1);
-
- return (
-
- Count: {count()}{" "}
- {/* ✅ will update when `count()` changes. */}
-
-
- );
-}
-```
-
-Components, much like other functions, will only run _once_.
-This means that if a signal is accessed outside of the return statement, it will run on initialization, but any updates to the signal will not trigger an update.
-
-```jsx
-function Counter() {
- const [count, setCount] = createSignal(0);
- const increment = () => setCount((prev) => prev + 1);
-
- console.log("Count:", count()); // ❌ not tracked - only runs once during initialization.
-
- createEffect(() => {
- console.log(count()); // ✅ will update whenever `count()` changes.
- });
-
- return (
-
- );
-}
-```
-
-To learn more about managing state in Solid, visit the [guide on state management](/guides/state-management).
-
-## Synchronous vs. asynchronous
-
-Reactive systems are designed to respond to changes in data.
-These responses can be immediate or delayed, depending on the nature of the system.
-Often, the choice between these two depends on the requirements of the application and the nature of the tasks involved.
-
-### Synchronous reactivity
-
-[Synchronous](https://developer.mozilla.org/en-US/docs/Glossary/Synchronous) reactivity is Solid's default reactivity mode, where a system responds to changes in a direct and linear fashion.
-When a signal changes, any corresponding subscribers are immediately updated in an ordered manner.
-
-With synchronous reactivity, the system is able to respond to changes in a predictable manner.
-This is useful in scenarios where the order of updates is important.
-For example, if a subscriber depends on another signal, it is important that the subscriber is updated after the signal it depends on.
-
-```jsx
-const [count, setCount] = createSignal(0);
-const [double, setDouble] = createSignal(0);
-
-createEffect(() => {
- setDouble(count() * 2);
-});
-```
-
-In this example, the `double` signal will always be updated after `count` due to synchronous reactivity.
-This ensures that `double` is always up-to-date with the latest value of `count`.
-
-### Asynchronous reactivity
-
-[Asynchronous](https://developer.mozilla.org/en-US/docs/Glossary/Asynchronous) reactivity is when a system responds to changes in a delayed or non-linear fashion.
-When a signal changes, the corresponding subscribers are not immediately updated.
-Instead, the system waits for a specific event or task to complete before updating the subscribers.
-
-This is important in scenarios where subscribers depend on multiple signals.
-In these cases, updating one signal before another could result in data inconsistency.
-For example, if a subscriber depends on two signals, it is important that the subscriber is updated after both signals have been updated.
-Rather, the system waits for both signals to be updated before updating the subscriber.
-
-**Note:** When asynchronous reactivity is present, it is important to ensure that the system is able to handle the delay in updates.
-[`batch`](/reference/reactive-utilities/batch) can be used to delay an update so the subscriber runs after each signal has been updated.
-
-## Key concepts
-
-- Signals are the core elements of a reactive system.
- They are responsible for storing and managing data.
-- Signals are both readable and writeable because of getters and setters.
-- Subscribers are automated responders that track changes in signals and update the system accordingly.
-- Signals and subscribers work together to ensure that the system is kept up-to-date with the latest data changes.
-- A reactive system is built on the principles of data-driven reactivity.
- This means that the system's reactivity is driven by the data it is built on.
-- Reactive systems can be synchronous or asynchronous.
-
-If you want to dive deeper, visit the [guide on fine-grained reactivity](/advanced-concepts/fine-grained-reactivity).
diff --git a/old pages/concepts/signals.mdx b/old pages/concepts/signals.mdx
deleted file mode 100644
index 71662e63a..000000000
--- a/old pages/concepts/signals.mdx
+++ /dev/null
@@ -1,96 +0,0 @@
----
-title: Signals
-order: 2
----
-
-Signals are the **core primitive for state** in Solid.
-They provide a way to store a value, read it, and update it.
-When a signal changes, anything that depends on it will update automatically.
-
-Signals can represent any kind of state in your application:
-- simple values like numbers or strings
-- complex values like objects or arrays
-- application state such as the current user, theme, or page
-
-For an overview of how signals fit into Solid’s reactive model, see [Reactivity Basics](/reactivity/basics).
-
-## Creating a signal
-
-Use [`createSignal`](/reference/basic-reactivity/create-signal) from `solid-js` to create a signal.
-It returns a pair of functions:
-- a **getter** to read the value
-- a **setter** to update the value
-
-```jsx
-import { createSignal } from "solid-js";
-
-const [count, setCount] = createSignal(0);
-// ^ getter ^ setter
-```
-
-:::note
-The syntax using `[` and `]` is called [array destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment).
-
-This lets you extract values from the array.
-In the context of `createSignal`, the first value is the getter function, and the second value is the setter function.
-:::
-
-## Accessing values
-
-The getter function returned by `createSignal` is used to access the value of the signal.
-Call the getter function with no arguments to read the current value:
-
-```jsx
-console.log(count()); // 0
-```
-
-## Updating values
-
-The setter function returned by `createSignal` is used to update the value of the signal.
-This function takes an argument that represents the new value of the signal:
-
-```jsx
-setCount(count() + 1);
-
-console.log(count()); // 1
-```
-
-The setter function can also take a function that passes the previous value.
-
-```jsx
-setCount((prevCount) => prevCount + 1);
-
-console.log(count()); // 1
-```
-
-## Reactivity
-
-Signals are **reactive**, which means that they automatically update when their value changes.
-For example, using a signal inside JSX automatically makes the DOM update when the signal changes:
-
-```jsx
-function Counter() {
- const [count, setCount] = createSignal(0);
- const increment = () => setCount((prev) => prev + 1);
-
- return (
-
- );
-}
-```
-
-To learn how signals connect to effects and tracking scopes, see:
-- [Reactive Side Effects](/reactivity/effects)
-- [Memoized Computations](/reactivity/memo)
-
-## Related Pages
-
-- [Reactivity Basics](/reactivity/basics)
-- [Reactive Side Effects](/reactivity/effects)
-- [Memoized Computations](/reactivity/memo)
-- [Introduction to Components](/components/intro)
diff --git a/old pages/concepts/understanding-jsx.mdx b/old pages/concepts/understanding-jsx.mdx
deleted file mode 100644
index 8dea79978..000000000
--- a/old pages/concepts/understanding-jsx.mdx
+++ /dev/null
@@ -1,129 +0,0 @@
----
-title: Understanding JSX
-order: 2
----
-
-JSX is an extension for JavaScript.
-It allows you to write HTML-like code inside your JavaScript file which keeps your rendering logic and content in the same place.
-This provides a concise and readable way to create and represent components.
-
-## How Solid uses JSX
-
-Solid was designed to align closely with HTML standards.
-
-```jsx
-const element =
I'm JSX!!
-```
-
-It offers a distinct advantage, however: to copy/paste solutions from resources like Stack Overflow; and to allow direct usage of templates from design tools.
-Solid sets itself apart by using JSX immediately as it returns [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction) elements.
-This lets you use dynamic expressions within your HTML by allowing variables and functions to be references with the use of curly braces (`{ }`):
-
-```jsx
-const Component = () => {
- const animal = { breed: "cat", name: "Midnight" }
-
- return (
-
- I have a {animal.breed} named {animal.name}!
-
- )
-}
-```
-
-This means JavaScript content can be rendered on web pages based on an application's state or logic.
-
-Additionally, Solid's [reactive](/concepts/intro-to-reactivity) system introduces [fine-grained reactivity](/advanced-concepts/fine-grained-reactivity) with JSX.
-This updates only the necessary parts of the DOM when changes occur in the underlying state.
-
-## Using JSX in Solid
-
-### Return a single root element
-
-Where HTML lets you have disconnected tags at the top level, JSX requires that a component to return a single root element.
-
-:::advanced
-When working with JSX, parts of your code are translated into structured HTML that is placed at the start of the file.
-Static elements are processed differently from dynamic ones, which might change based on data or user actions.
-For dynamic elements, special markers are added for better handling during rendering.
-
-Having a single root creates a consistent and manageable hierarchy to optimize rendering and updates.
-:::
-
-JSX maintains the familiar nested, tree-like structure found in HTML.
-As a result, parent-child relationships between elements become easier to follow.
-
-### Close all tags
-
-Self-closing tags are a must in JSX.
-Unlike in HTML, where elements like ``, ``, or ` ` don't require explicit closure, JSX requires consistent self-closing tags.
-This helps to avoid potential rendering issues.
-
-```jsx
-
-```
-
-### Properties vs. attributes
-
-HTML attributes and JSX properties may seem similar, but they serve different purposes and behave differently.
-Both offer ways to specify configurations or pass information.
-However, HTML is used for standard web content and JSX creates Solid's component logic.
-
-#### HTML attributes
-
-[HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes) are values set directly on HTML elements.
-They provide additional information about an element to guide its initial behavior and state.
-These attributes are often translated into properties on DOM objects once the browser parses the HTML.
-
-In JSX files, HTML attributes are used much like regular HTML, with a few key differences due to the blend of HTML and JavaScript:
-
-- Event listeners such as `onClick` can be in camelCase or lowercase.
- (**Note:** When using ESLint, you will get a warning if you use lowercase.)
-- In cases where you can dynamically specify a value, you can replace the `"` and `"` with curly braces (`{ }`):
-
-```jsx
-
-```
-
- :::note
- If you wish to pass objects in JSX, such as with inline styling, you will have to use double curly braces (`{{ }}`).
-
-```jsx
-
-```
-:::
-
-### JSX properties (props)
-
-JSX properties, commonly known as "props," help with the passing of data and configurations to components within an application.
-They connect the component with the data it requires, for seamless data flows and dynamic interactions.
-
-#### Core concepts
-
-- **Static props**:
- In Solid's JSX, static props are integrated directly into the HTML by cloning the template and using them as attributes.
-
- - **Dynamic props**:
- Dynamic props rely on state, allowing the content or properties to be dynamic.
- An example is changing the style of an element in response to interactions within an application.
- This can be expressed in the form of signals (`value={value()}`).
-
-- **Data transfer**:
- Props are also used to fill components with data that comes from resources, like [`createResource`](/reference/basic-reactivity/create-resource) calls.
- This results in components that react in real-time to data changes.
-
-:::note
-Expressions, whether fixed or dynamic, get applied *in the order defined within the JSX*.
-This works for a wide range of DOM elements, but will not work with elements that require attributes to be defined in a special order, such as input types with `type='range'`.
-
-When order influences an element's behavior, users must define the expressions in the order that the element is expected.
-:::
-
-For how to use props effectively in Solid, explore the [props page](/concepts/components/props).
diff --git a/old pages/quick-start.mdx b/old pages/quick-start.mdx
deleted file mode 100644
index c04a9c7b5..000000000
--- a/old pages/quick-start.mdx
+++ /dev/null
@@ -1,80 +0,0 @@
----
-title: Quick start
----
-
-## Try Solid online
-
-To experiment with Solid directly in your browser, head over to our [interactive playground](https://playground.solidjs.com/).
-Prefer a full development setup? You can set up a complete environment using StackBlitz.
-Start with the [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) or [JavaScript](https://stackblitz.com/github/solidjs/templates/tree/master/js) templates.
-
-## Create a Solid project
-
-:::note[Prerequisites]
-
-- Familiarity with the command line.
-- A recent version of [Node.js](https://nodejs.org/en), [Bun](https://bun.sh/), or [Deno](https://deno.com/).
- The latest LTS version is recommended.
-
-:::
-
-To create a new Solid application, navigate to the directory where you want to create your project and run the following command:
-
-```package-create
-solid
-```
-
-This command installs and runs [create-solid](https://github.com/solidjs-community/solid-cli/tree/main/packages/create-solid), the official project scaffolding tool for Solid.
-The CLI will guide you through a series of prompts, allowing you to choose options such as [starter templates](https://github.com/solidjs/templates), TypeScript support, and whether to include [Solid's full-stack framework, SolidStart](/solid-start):
-
-```shell
-◆ Project Name
-|
-
-◆ Is this a SolidStart project?
-| ● Yes / ○ No
-
-◆ Which template would you like to use?
-│ ● ts
-│ ○ ts-vitest
-│ ○ ts-uvu
-│ ○ ts-unocss
-│ ○ ts-tailwindcss
-
-◆ Use TypeScript?
-│ ● Yes / ○ No
-```
-
-Once the project is created, follow the instructions to install the dependencies and start the development server:
-
-```sh title="npm" tab="package-manager"
-│ cd solid-project
-│ npm install
-│ npm run dev
-```
-
-```sh title="pnpm" tab="package-manager"
-│ cd solid-project
-│ pnpm install
-│ pnpm dev
-```
-
-```sh title="yarn" tab="package-manager"
-│ cd solid-project
-│ yarn install
-│ yarn dev
-```
-
-```sh title="bun" tab="package-manager"
-│ cd solid-project
-│ bun install
-│ bun run dev
-```
-
-```sh title="deno" tab="package-manager"
-│ cd solid-project
-│ deno install
-│ deno run dev
-```
-
-You should now have your Solid project running!
diff --git a/src/routes/components/data.json b/src/routes/components/data.json
index d4bf1d89b..7c6ff1f78 100644
--- a/src/routes/components/data.json
+++ b/src/routes/components/data.json
@@ -1,4 +1,4 @@
{
"title": "Components",
- "pages": ["intro.md", "how-to"]
+ "pages": ["intro.mdx", "how-to"]
}
diff --git a/src/routes/getting-started/data.json b/src/routes/getting-started/data.json
index 4b2a8a548..5790f74ec 100644
--- a/src/routes/getting-started/data.json
+++ b/src/routes/getting-started/data.json
@@ -1,4 +1,4 @@
{
"title": "Getting Started",
- "pages": ["quick-start.mdx", "counter.mdx", "todo.mdx"]
+ "pages": ["quick-start.mdx", "understanding-jsx.mdx", "todo.mdx"]
}
From ca815ce7ba567b54edc1d1477542cfac61f3b904 Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Sat, 30 Aug 2025 20:59:22 -0700
Subject: [PATCH 08/37] workign on new pages
---
src/routes/components/basics.mdx | 110 +++++++++++++++++++++++++++++++
src/routes/components/props.mdx | 4 ++
2 files changed, 114 insertions(+)
create mode 100644 src/routes/components/basics.mdx
create mode 100644 src/routes/components/props.mdx
diff --git a/src/routes/components/basics.mdx b/src/routes/components/basics.mdx
new file mode 100644
index 000000000..ee0d47f8b
--- /dev/null
+++ b/src/routes/components/basics.mdx
@@ -0,0 +1,110 @@
+---
+title: "Basics of Components"
+order: 1
+---
+
+Components are the **fundamental building blocks** of Solid applications.
+A component is a **JavaScript function that returns JSX**.
+This allows you to create encapsulated pieces of UI that can manage their own state and behavior.
+
+## Your First Component
+
+A component starts as a plain JavaScript function, defined by either a function declaration or an arrow function:
+
+```tsx
+// Greeting.jsx
+export function Greeting() {
+ return
Hello, Solid!
;
+}
+
+export const Greeting = () => {
+ return
Hello, Solid!
;
+};
+```
+
+These functions can be used in other components by importing them and using their names like HTML tags:
+
+```tsx
+// App.tsx
+import { Greeting } from './Greeting';
+
+function App() {
+ return (
+
+
+
+ );
+}
+```
+
+### Passing Props
+
+Props, short for properties, let you pass data from a parent component to a child component.
+They are passed as attributes on the component tag and received as an object in the component function.
+
+```tsx
+//Greeting.tsx
+export function Greeting(props) {
+ return
+ );
+}
+```
+
+To learn more about props, see the next section: [Passing Data with Props](/components/props).
+
+### Composing Components
+
+Components can be composed together to build more complex UIs.
+You can use one component inside another, passing props as needed.
+
+```tsx
+// App.tsx
+import { Greeting } from './Greeting';
+
+function App() {
+ return (
+
+
+
+
+ );
+}
+```
+
+## Component lifecycles
+
+Components in Solid have a lifecycle that includes mounting, updating, and unmounting phases.
+
+1. **Mounting**: When the component is being created and inserted into the DOM.
+It occurs once in the component's lifecycle.
+2. **Updating**: The component's state or props change, causing it to re-render. Solid optimizes updates to ensure minimal re-rendering.
+3. **Unmounting**: The component is removed from the DOM.
+Cleanup tasks, such as cancelling network requests or removing event listeners, should be performed here.
+
+There are certain lifecycle helpers available in Solid to manage these phases more easily, such as `onMount`, `onCleanup`, and `createEffect`.
+
+```tsx
+import { onMount, onCleanup } from "solid-js";
+
+function Timer() {
+ let interval;
+
+ onMount(() => {
+ interval = setInterval(() => console.log("tick"), 1000);
+ });
+
+ onCleanup(() => clearInterval(interval));
+
+ return
Timer running...
;
+}
+```
\ No newline at end of file
diff --git a/src/routes/components/props.mdx b/src/routes/components/props.mdx
new file mode 100644
index 000000000..63dcb64de
--- /dev/null
+++ b/src/routes/components/props.mdx
@@ -0,0 +1,4 @@
+---
+title: "Passing Data with Props"
+order: 2
+---
\ No newline at end of file
From daf1c5c591b72c98960f5526068ed03bff671137 Mon Sep 17 00:00:00 2001
From: Sarah
Date: Wed, 3 Sep 2025 12:40:57 -0700
Subject: [PATCH 09/37] Update src/routes/getting-started/quick-start.mdx
Co-authored-by: Amir Hossein Hashemi <87268103+amirhhashemi@users.noreply.github.com>
---
src/routes/getting-started/quick-start.mdx | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/src/routes/getting-started/quick-start.mdx b/src/routes/getting-started/quick-start.mdx
index 8c0038ce1..37cee243a 100644
--- a/src/routes/getting-started/quick-start.mdx
+++ b/src/routes/getting-started/quick-start.mdx
@@ -10,7 +10,7 @@ In just a few minutes, you’ll have a working Solid app running in your browser
If you're looking to experiment with Solid without setting up a local environment, open the [Solid Playground](https://playground.solidjs.com/) in your browser.
-If you prefer a more complete development setup, you can use the StackBlitz [Javascript](https://stackblitz.com/github/solidjs/templates/tree/master/js) or [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) templates.
+If you prefer a more complete development setup, you can use the StackBlitz [JavaScript](https://stackblitz.com/github/solidjs/templates/tree/master/js) or [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) templates.
## Create a New Project
From a55927a2292bc326d629433aaebb2bf76fbabf47 Mon Sep 17 00:00:00 2001
From: Sarah
Date: Wed, 3 Sep 2025 12:48:35 -0700
Subject: [PATCH 10/37] Apply suggestions from code review
Co-authored-by: Amir Hossein Hashemi <87268103+amirhhashemi@users.noreply.github.com>
---
src/routes/getting-started/quick-start.mdx | 20 ++++++++++---------
.../getting-started/understanding-jsx.mdx | 12 +++++++----
src/routes/reactivity/basics.mdx | 20 +++++++++++--------
src/routes/reactivity/signals.mdx | 9 +++------
4 files changed, 34 insertions(+), 27 deletions(-)
diff --git a/src/routes/getting-started/quick-start.mdx b/src/routes/getting-started/quick-start.mdx
index 37cee243a..a77884414 100644
--- a/src/routes/getting-started/quick-start.mdx
+++ b/src/routes/getting-started/quick-start.mdx
@@ -6,7 +6,7 @@ order: 1
The fastest way to try Solid is to create a new project and run it locally.
In just a few minutes, you’ll have a working Solid app running in your browser.
-## Solid in your Browser
+## Solid in Your Browser
If you're looking to experiment with Solid without setting up a local environment, open the [Solid Playground](https://playground.solidjs.com/) in your browser.
@@ -31,21 +31,23 @@ solid
3. **Follow the CLI prompts** to select your project name, template (JavaScript or TypeScript), and other options.
```sh
-◆ Project Name
-|
+◆ Project Name
+│ solid-project
-◆ Is this a SolidStart project?
-| ● Yes / ○ No
+◆ What type of project would you like to create?
+│ ○ SolidStart
+│ ● SolidJS + Vite
+│ ○ Library
-◆ Which template would you like to use?
+◆ Use Typescript?
+│ ● Yes / ○ No
+
+◆ Which template would you like to use?
│ ● ts
│ ○ ts-vitest
│ ○ ts-uvu
│ ○ ts-unocss
│ ○ ts-tailwindcss
-
-◆ Use TypeScript?
-│ ● Yes / ○ No
```
4. **Follow the instructions to install the dependencies and start the development server:**
diff --git a/src/routes/getting-started/understanding-jsx.mdx b/src/routes/getting-started/understanding-jsx.mdx
index 0d0031d3f..4c16b32e7 100644
--- a/src/routes/getting-started/understanding-jsx.mdx
+++ b/src/routes/getting-started/understanding-jsx.mdx
@@ -16,10 +16,10 @@ const element =
I'm JSX!!
Unlike some other frameworks, Solid compiles JSX directly to real DOM nodes.
This means:
+
- JSX expressions map closely to HTML.
- You can use variables and functions inline using curly braces `{}`.
- Only the parts of the DOM that depend on reactive state update.
-This avoids the whole component re-rendering, improving performance.
```tsx
const component = () => {
@@ -105,6 +105,7 @@ const isActive = true;
```
For more information on:
+
- [Using Event Listeners](/components/how-to/event-listeners)
- [Styling Components](/components/how-to/styling)
@@ -131,10 +132,12 @@ function Greeting(props) {
```
The core concepts of JSX properties in Solid include:
-- **Static props**: Directly integrated into the HTML by cloning the template and using them as attributes.
-- **Dynamic props**: Rely on state, allowing content or properties to change in response to user interactions or other events.
+
+- **Static props:** Directly integrated into the HTML by cloning the template and using them as attributes.
+- **Dynamic props:** Rely on state, allowing content or properties to change in response to user interactions or other events.
An example is changing the style of an element based on a signal (`value={value()}`).
-- **Data transfer**: Props can be used to fill components with data from resources, such as API responses or context providers.
+- **Data transfer:** Props can be used to fill components with data from resources, such as API responses or context providers.
+
This allows for components to update reactively when the underlying data changes.
:::note
@@ -144,6 +147,7 @@ When order matters, make sure to define expressions in the sequence the element
:::
## Related Pages
+
- [Using Event Listeners](/components/how-to/event-listeners)
- [Styling Components](/components/how-to/styling)
- [Passing Data with Props](/components/props)
diff --git a/src/routes/reactivity/basics.mdx b/src/routes/reactivity/basics.mdx
index 17d223d9b..7c44d28ef 100644
--- a/src/routes/reactivity/basics.mdx
+++ b/src/routes/reactivity/basics.mdx
@@ -7,7 +7,8 @@ order: 1
Reactivity is the foundation of Solid.
It’s the programming model where **changes in data automatically update the parts of your app that depend on it**.
-Solid’s approach is **fine-grained**: instead of re-rendering entire components, only the exact parts of the DOM that depend on a value update. This makes applications efficient and responsive, even as they grow.
+Solid’s approach is **fine-grained**: only the exact parts of the DOM that depend on a value update.
+This makes applications efficient and responsive, even as they grow.
## Core Principles of Reactivity
@@ -18,6 +19,7 @@ Together, these create a system where updates are precise, automatic, and effici
A **signal** is a reactive value container.
They consist of 2 parts:
+
- **Getter** → reads the current value.
- **Setter** → updates the value and notifies dependents.
@@ -30,9 +32,9 @@ console.log(count()); // 1
```
Signals can hold any type of value:
-- primitives (string, number, boolean)
-- objects and arrays
-- application state (user, theme, current page)
+
+- Primitives (string, number, boolean).
+- Objects and arrays.
Learn more in the [Signals page](/reactivity/signals).
@@ -41,9 +43,10 @@ Learn more in the [Signals page](/reactivity/signals).
If signals are the **source of truth**, subscribers are the **reactive consumers**.
A subscriber is any function or construct that reads a signal inside a tracking scope and automatically re-runs whenever it changes.
-This is what makes Solid’s reactivity *fine-grained*: only the subscribers that depend on a signal update, not the entire component.
+This is what makes Solid’s reactivity *fine-grained*: only the subscribers that depend on a signal update.
How subscribers work:
+
1. **Observation** → subscriber runs and reads signals.
2. **Dependency tracking** → those signals register the subscriber.
3. **Response** → when a signal changes, the subscriber re-runs.
@@ -55,8 +58,9 @@ When a signal is read within a tracking scope, it registers the current subscrib
Once that signal changes, it will notify the subscriber to re-run and update accordingly.
Tracking scopes within Solid include:
-- Component render functions (JSX return values)
-- Reactive computations (e.g., `createMemo`)
+
+- Component render functions (JSX return values).
+- Reactive computations (e.g., `createMemo`).
- Effects (e.g., `createEffect`)
Example of a tracking vs non-tracking scope:
@@ -78,7 +82,7 @@ function Counter() {
}
```
-Tracking scopes are what enable **precise DOM updates**: only parts of the UI that depend on signals re-run, not the entire component.
+Tracking scopes are what enable **precise DOM updates**: only parts of the UI that depend on signals re-run.
You can learn more about [component lifecycles in the Intro to Components page](/components/intro).
diff --git a/src/routes/reactivity/signals.mdx b/src/routes/reactivity/signals.mdx
index 6a5eab9d4..e19c1e3c3 100644
--- a/src/routes/reactivity/signals.mdx
+++ b/src/routes/reactivity/signals.mdx
@@ -13,11 +13,9 @@ You can use signals for any kind of state:
## What is a Signal?
-A **signal** is a reactive value container.
-- It holds a value.
-- It provides a **getter** to read the value.
-- It provides a **setter** to update the value.
-- When the value changes, any reactive computations that depend on it are updated automatically.
+A **signal** is a reactive value container.
+It holds a value and provides a **getter** to read the value and a **setter** to update it.
+When the value changes, it automatically triggers updates in any dependent computations.
They can be thought of as a **reactive variable**.
@@ -73,4 +71,3 @@ function Counter() {
}
```
-:::
From 0f5f21b683d8078006a8ee0e9c4b1c5e400c540a Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Wed, 17 Sep 2025 11:21:31 -0700
Subject: [PATCH 11/37] effects
---
src/routes/getting-started/data.json | 2 +-
.../{quick-start.mdx => installation.mdx} | 2 +-
src/routes/intro.mdx | 4 +-
src/routes/reactivity/basics.mdx | 10 +-
src/routes/reactivity/data.json | 2 +-
.../{memos.mdx => derived-state.mdx} | 2 +-
src/routes/reactivity/effects.mdx | 169 +++++++++++++++++-
7 files changed, 172 insertions(+), 19 deletions(-)
rename src/routes/getting-started/{quick-start.mdx => installation.mdx} (99%)
rename src/routes/reactivity/{memos.mdx => derived-state.mdx} (85%)
diff --git a/src/routes/getting-started/data.json b/src/routes/getting-started/data.json
index 5790f74ec..5f04d10c2 100644
--- a/src/routes/getting-started/data.json
+++ b/src/routes/getting-started/data.json
@@ -1,4 +1,4 @@
{
"title": "Getting Started",
- "pages": ["quick-start.mdx", "understanding-jsx.mdx", "todo.mdx"]
+ "pages": ["installation.mdx", "understanding-jsx.mdx", "todo.mdx"]
}
diff --git a/src/routes/getting-started/quick-start.mdx b/src/routes/getting-started/installation.mdx
similarity index 99%
rename from src/routes/getting-started/quick-start.mdx
rename to src/routes/getting-started/installation.mdx
index a77884414..8e8f4fee3 100644
--- a/src/routes/getting-started/quick-start.mdx
+++ b/src/routes/getting-started/installation.mdx
@@ -1,5 +1,5 @@
---
-title: Quick Start
+title: Installation
order: 1
---
diff --git a/src/routes/intro.mdx b/src/routes/intro.mdx
index 1809b9ecf..e7944c791 100644
--- a/src/routes/intro.mdx
+++ b/src/routes/intro.mdx
@@ -24,11 +24,11 @@ Traditionally, when a change occurs, the entire page would need to reload to dis
With Solid's fine-grained reactive system, updates are only applied to the parts of the page that need to be updated.
This decreases work and can result in faster load times as well as a smoother user experience overall.
-## The Mental Model
+## The mental model
[TODO: Simple explanation of the mental model behind Solid]
-## Where to Go Next
+## Where to go next
- [Quick Start Guide](https://solidjs.com/docs/getting-started)
- [Reactivity Overview](/concepts/reactivity/)
diff --git a/src/routes/reactivity/basics.mdx b/src/routes/reactivity/basics.mdx
index 7c44d28ef..36df5c5fa 100644
--- a/src/routes/reactivity/basics.mdx
+++ b/src/routes/reactivity/basics.mdx
@@ -10,12 +10,12 @@ It’s the programming model where **changes in data automatically update the pa
Solid’s approach is **fine-grained**: only the exact parts of the DOM that depend on a value update.
This makes applications efficient and responsive, even as they grow.
-## Core Principles of Reactivity
+## Core principles of reactivity
Solid’s reactivity is built on three key ideas: **signals, subscribers, and tracking scopes**.
Together, these create a system where updates are precise, automatic, and efficient.
-### Signals: Reactive Values
+### Signals: Reactive values
A **signal** is a reactive value container.
They consist of 2 parts:
@@ -38,7 +38,7 @@ Signals can hold any type of value:
Learn more in the [Signals page](/reactivity/signals).
-### Subscribers: Reactive Consumers
+### Subscribers: Reactive consumers
If signals are the **source of truth**, subscribers are the **reactive consumers**.
@@ -51,7 +51,7 @@ How subscribers work:
2. **Dependency tracking** → those signals register the subscriber.
3. **Response** → when a signal changes, the subscriber re-runs.
-### Tracking Scopes: Connecting Signals & Subscribers
+### Tracking Scopes: Connecting signals & subscribers
A **tracking scope** is the environment where Solid records which signals are being used.
When a signal is read within a tracking scope, it registers the current subscriber as a dependency.
@@ -88,5 +88,5 @@ You can learn more about [component lifecycles in the Intro to Components page](
## Related pages
- [Signals](/reactivity/signals)
-- [Reactive Side Effects](/reactivity/effects)
+- [Effects](/reactivity/effects)
- [Introduction to Components](/components/intro)
diff --git a/src/routes/reactivity/data.json b/src/routes/reactivity/data.json
index 5cdfeb89b..7eacc5dcb 100644
--- a/src/routes/reactivity/data.json
+++ b/src/routes/reactivity/data.json
@@ -3,7 +3,7 @@
"pages": [
"basics.mdx",
"signals.mdx",
- "memos.mdx",
+ "derived-state.mdx",
"effects.mdx",
"stores.mdx",
"resources.mdx",
diff --git a/src/routes/reactivity/memos.mdx b/src/routes/reactivity/derived-state.mdx
similarity index 85%
rename from src/routes/reactivity/memos.mdx
rename to src/routes/reactivity/derived-state.mdx
index 6f07f36bb..d0f749336 100644
--- a/src/routes/reactivity/memos.mdx
+++ b/src/routes/reactivity/derived-state.mdx
@@ -1,5 +1,5 @@
---
-title: "Memoized Computations"
+title: "Derived State"
order: 3
---
diff --git a/src/routes/reactivity/effects.mdx b/src/routes/reactivity/effects.mdx
index 1086c53e9..17936e4d9 100644
--- a/src/routes/reactivity/effects.mdx
+++ b/src/routes/reactivity/effects.mdx
@@ -1,12 +1,165 @@
---
-title: "Derived Reactive Values"
+title: "Effects"
order: 4
---
-[TODO:
-Concept page for Effects
-- What are Effects
-- How to use them
-- When to use Effects
-- Move relevant sections to ref and vice versa
-]
\ No newline at end of file
+Effects are reactive functions that run when the values they depend on change.
+They’re the main way to manage side effects that occur outside an application's scope, such as:
+- DOM manipulation
+- Data fetching
+- Subscriptions
+
+## What are Effects?
+
+An effect is a reactive function that **runs automatically whenever the values it depends on change**.
+
+Unlike [signals](/basics/signals) (which store state) or [memos](/basics/derived-state) (which derive state), effects connect your reactive data to the outside world.
+They are used for running code that has side effects, meaning it interacts with or modifies something beyond Solid's reactive graph, such as:
+
+- updating or interacting with the DOM
+- logging values
+- fetching or subscribing to external data
+- setting up or cleaning up resources
+
+Effects run **once when created** to establish its subscriptions, then **again whenever its dependencies change**.
+
+## Creating an Effect
+
+You create an effect using the `createEffect` function.
+It takes a **callback function** as its first argument, which contains the code you want to run reactively.
+
+```tsx
+import { createSignal, createEffect } from "solid-js";
+
+function Counter() {
+ const [count, setCount] = createSignal(0);
+
+ createEffect(() => {
+ console.log(`Count is: ${count()}`);
+ });
+
+ return (
+
+ );
+}
+```
+
+In this example, the effect logs the current value of `count` to the console.
+The effect runs once when created, logging `Count is: 0`, and will run again whenever `count` changes, in this case when the button is clicked.
+
+## Lifecycle of an Effect
+
+An effect goes through a predictable cycle every time it's created and re-runs:
+
+### 1. **Initialization**
+
+When you call `createEffect`, the effect is immediately scheduled to run **once**.
+This first run happens **after the current render phase** finishes, or after the component function returns its JSX.
+This ensures that the DOM is already created and refs are assigned, allowing you to safely interact with the DOM.
+
+```tsx
+createEffect(() => console.log("Initial run"));
+console.log("Hello");
+
+// Output:
+// Hello
+// Initial run
+```
+
+### 2. **Dependency tracking**
+
+During its first run, the effect records every reactive value it accesses (such as signals or memos).
+It becomes subscribed to those values, which are now its **dependencies**.
+From then on, the effect automatically re‑runs whenever any of its dependencies change.
+
+```tsx
+const [count, setCount] = createSignal(0);
+
+createEffect(() => {
+ console.log(`Count: ${count()}`);
+});
+
+// Count: 0 runs immediately
+// every setCount(...) re‑runs the effect
+```
+
+### 3. **Reactive Updates**
+
+Whenever *any* dependency changes, the effects is scheduled to run again.
+This happens **after the current synchronous code completes**, ensuring that all changes are batched together.
+This means that if the dependencies change multiple times in quick succession, the effect will only run *once* after all changes are made:
+
+```tsx
+const [count, setCount] = createSignal(0);
+const [name, setName] = createSignal("Solid");
+
+createEffect(() => {
+ console.log(`Count: ${count()}, Name: ${name()}`);
+});
+
+setCount(1);
+setName("SolidJS");
+```
+
+In this example, the effect will only log `Count: 1, Name: SolidJS` once, after all changes have been made.
+
+### Lifecycle functions
+
+Effects are reactive and run whenever their dependencies change, but sometimes finer control is needed.
+Solid provides lifecycle functions to manage when code runs and how it gets cleaned up.
+
+These functions are especially useful for:
+- Running a side effect **only once** when the component mounts
+- Cleaning up resources, event listeners, or other side effects when the component unmounts
+
+#### `onMount`
+
+The [`onMount`](TODO) function allows you to run code **once** when the component is first added to the DOM.
+Unlike effects, `onMount` does **not track dependencies**.
+It will execute the callback once, and never again.
+
+```tsx
+import { onMount, createSignal, createEffect } from "solid-js";
+
+function Component() {
+ const [data, setData] = createSignal(null);
+
+ createEffect(() => {
+ // Still runs reactively whenever `data` changes
+ console.log("Data:", data());
+ });
+
+ onMount(async () => {
+ // Runs only once when the component is mounted
+ const res = await fetch("/api/data");
+ setData(await res.json());
+ });
+
+ return
...
;
+}
+```
+
+#### `onCleanup`
+
+Use [`onCleanup`](TODO) to **dispose of resources** before a component unmounts, or before an effect re-runs.
+This will prevent memory leaks and ensure that any subscriptions or event listeners are properly removed.
+
+```tsx
+import { createSignal, onCleanup } from "solid-js";
+
+function App() {
+ const [count, setCount] = createSignal(0);
+
+ const timer = setInterval(() => setCount(c => c + 1), 1000);
+
+ onCleanup(() => {
+ // Runs when the component unmounts
+ clearInterval(timer);
+ });
+
+ return
+ Count: {count()}{" "}
+ {/* Only `count()` is updated when the button is clicked. */}
+
+
+ );
+}
+```
+
+This `Counter` function sets up a button that, when clicked, calls the `increment` function to increase the `count` by one.
+This updates just the number displayed _without_ refreshing the entire component.
+
+
+
+## Reactive principles
+
+### Signals
+
+Signals serve as core elements in reactive systems, playing an important role in data management and system responsiveness.
+They are responsible for storing and managing data, as well as triggering updates across the system.
+This is done through the use of getters and setters.
+
+```jsx
+const [count, setCount] = createSignal(0);
+// ^ getter ^ setter
+```
+
+
+
+- **Getter**: A function responsible for accessing the current value of the signal.
+ You call a getter to access the data stored in a signal within a component.
+
+- **Setter**:
+ The function used to modify a signal's value.
+ To trigger reactive updates across an application, you call a setter to update the value of a signal.
+
+```js
+console.log(count()); // `count()` is a getter that returns the current value of `count`, which is `0`.
+
+setCount(1); // the setter, `setCount`, updates the value of `count`.
+
+console.log(count()); // the updated value of `count` is now `1`.
+```
+
+### Subscribers
+
+Subscribers are the other core element in reactive systems.
+They are responsible for tracking changes in signals and updating the system accordingly.
+They are automated responders that keep the system up-to-date with the latest data changes.
+
+Subscribers work based on two main actions:
+
+- **Observation**: At their core, subscribers observe signals.
+ This keeps the subscriber primed to pick up on any changes to the signal they are tracking.
+- **Response**: When a signal changes, the subscriber is notified.
+ This triggers the subscriber to respond to the change in the signal.
+ This can involve tasks like updating the UI or calling external functions.
+
+```jsx
+function Counter() {
+ const [count, setCount] = createSignal(0);
+ const increment = () => setCount((prev) => prev + 1);
+
+ createEffect(() => {
+ console.log(count());
+ });
+ // the `createEffect` will trigger the console log every time `count` changes.
+}
+```
+
+## State management
+
+State management is the process of managing the state of an application.
+This involves storing and updating data, as well as responding to the changes in it.
+
+With Solid, state management is handled through signals and subscribers.
+Signals are used to store and update data, while subscribers are used to respond to changes in the data.
+
+### Tracking changes
+
+Tracking changes involves monitoring any updates to the data and responding accordingly.
+This is done through the use of subscribers.
+
+When a signal is not accessed within a tracking scope, an update to the signal will not trigger an update.
+This happens because if a signal is not being tracked, it is not able to notify any subscribers of the change.
+
+```jsx
+const [count, setCount] = createSignal(0);
+
+console.log("Count:", count());
+
+setCount(1);
+
+// Output: Count: 0
+
+// `count` is not being tracked, so the console log will not update when `count` changes.
+```
+
+Since initialization is a **one-time event**, if a signal is accessed _outside of a tracking scope_, it will not be tracked.
+To track a signal, it must be accessed within the scope of a subscriber.
+Reactive primitives, such as [effects](/concepts/effects), can be used to create subscribers.
+
+```jsx
+const [count, setCount] = createSignal(0);
+
+createEffect(() => {
+ console.log("Count:", count());
+});
+
+setCount(1);
+
+// Output: Count: 0
+// Count: 1
+```
+
+### Updating the UI
+
+The UI of a Solid application is built using [JSX](/concepts/understanding-jsx).
+JSX creates a tracking scope behind the scenes, which allows signals to be tracked within the return statement of a component.
+
+```jsx
+function Counter() {
+ const [count, setCount] = createSignal(0);
+ const increment = () => setCount((prev) => prev + 1);
+
+ return (
+
+ Count: {count()}{" "}
+ {/* ✅ will update when `count()` changes. */}
+
+
+ );
+}
+```
+
+Components, much like other functions, will only run _once_.
+This means that if a signal is accessed outside of the return statement, it will run on initialization, but any updates to the signal will not trigger an update.
+
+```jsx
+function Counter() {
+ const [count, setCount] = createSignal(0);
+ const increment = () => setCount((prev) => prev + 1);
+
+ console.log("Count:", count()); // ❌ not tracked - only runs once during initialization.
+
+ createEffect(() => {
+ console.log(count()); // ✅ will update whenever `count()` changes.
+ });
+
+ return (
+
+ );
+}
+```
+
+To learn more about managing state in Solid, visit the [guide on state management](/guides/state-management).
+
+## Synchronous vs. asynchronous
+
+Reactive systems are designed to respond to changes in data.
+These responses can be immediate or delayed, depending on the nature of the system.
+Often, the choice between these two depends on the requirements of the application and the nature of the tasks involved.
+
+### Synchronous reactivity
+
+[Synchronous](https://developer.mozilla.org/en-US/docs/Glossary/Synchronous) reactivity is Solid's default reactivity mode, where a system responds to changes in a direct and linear fashion.
+When a signal changes, any corresponding subscribers are immediately updated in an ordered manner.
+
+With synchronous reactivity, the system is able to respond to changes in a predictable manner.
+This is useful in scenarios where the order of updates is important.
+For example, if a subscriber depends on another signal, it is important that the subscriber is updated after the signal it depends on.
+
+```jsx
+const [count, setCount] = createSignal(0);
+const [double, setDouble] = createSignal(0);
+
+createEffect(() => {
+ setDouble(count() * 2);
+});
+```
+
+In this example, the `double` signal will always be updated after `count` due to synchronous reactivity.
+This ensures that `double` is always up-to-date with the latest value of `count`.
+
+### Asynchronous reactivity
+
+[Asynchronous](https://developer.mozilla.org/en-US/docs/Glossary/Asynchronous) reactivity is when a system responds to changes in a delayed or non-linear fashion.
+When a signal changes, the corresponding subscribers are not immediately updated.
+Instead, the system waits for a specific event or task to complete before updating the subscribers.
+
+This is important in scenarios where subscribers depend on multiple signals.
+In these cases, updating one signal before another could result in data inconsistency.
+For example, if a subscriber depends on two signals, it is important that the subscriber is updated after both signals have been updated.
+Rather, the system waits for both signals to be updated before updating the subscriber.
+
+**Note:** When asynchronous reactivity is present, it is important to ensure that the system is able to handle the delay in updates.
+[`batch`](/reference/reactive-utilities/batch) can be used to delay an update so the subscriber runs after each signal has been updated.
+
+## Key concepts
+
+- Signals are the core elements of a reactive system.
+ They are responsible for storing and managing data.
+- Signals are both readable and writeable because of getters and setters.
+- Subscribers are automated responders that track changes in signals and update the system accordingly.
+- Signals and subscribers work together to ensure that the system is kept up-to-date with the latest data changes.
+- A reactive system is built on the principles of data-driven reactivity.
+ This means that the system's reactivity is driven by the data it is built on.
+- Reactive systems can be synchronous or asynchronous.
+
+If you want to dive deeper, visit the [guide on fine-grained reactivity](/advanced-concepts/fine-grained-reactivity).
diff --git a/old pages/concepts/signals.mdx b/old pages/concepts/signals.mdx
new file mode 100644
index 000000000..aa59b6515
--- /dev/null
+++ b/old pages/concepts/signals.mdx
@@ -0,0 +1,90 @@
+---
+title: Signals
+order: 2
+---
+
+Signals are the primary means of [managing state](/concepts/intro-to-reactivity#state-management) in your Solid application.
+They provide a way to store and update values, and are the foundation of [reactivity](/concepts/intro-to-reactivity) in Solid.
+
+Signals can be used to represent any kind of state in your application, such as the current user, the current page, or the current theme.
+This can be any value, including primitive values such as strings and numbers, or complex values such as objects and arrays.
+
+## Creating a signal
+
+You can create a signal by calling the [`createSignal`](/reference/basic-reactivity/create-signal) function, which is imported from `solid-js`.
+This function takes an initial value as an argument, and returns a pair of functions: a **getter** function, and a **setter** function.
+
+```jsx
+import { createSignal } from "solid-js";
+
+const [count, setCount] = createSignal(0);
+// ^ getter ^ setter
+```
+
+ :::note
+ The syntax using `[` and `]` is called [array destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment).
+
+This lets you extract values from the array.
+In the context of `createSignal`, the first value is the getter function, and the second value is the setter function.
+
+:::
+
+## Accessing values
+
+The getter function returned by `createSignal` is used to access the value of the signal.
+You call this function with no arguments to get the current value of the signal:
+
+```jsx
+console.log(count()); // output: 0
+```
+
+## Updating values
+
+The setter function returned by `createSignal` is used to update the value of the signal.
+This function takes an argument that represents the new value of the signal:
+
+```jsx
+setCount(count() + 1);
+
+console.log(count()); // output: 1
+```
+
+The setter function can also take a function that passes the previous value.
+
+```jsx
+setCount((prevCount) => prevCount + 1);
+
+console.log(count()); // output: 1
+```
+
+## Reactivity
+
+Signals are reactive, which means that they automatically update when their value changes.
+When a signal is called within a [tracking scope](/concepts/intro-to-reactivity#tracking-changes), the signal adds the dependency to a list of subscribers.
+Once a signal's value changes, it notifies all of its dependencies of the change so they can re-evaluate their values and update accordingly.
+
+```jsx
+function Counter() {
+ const [count, setCount] = createSignal(0);
+ const increment = () => setCount((prev) => prev + 1);
+
+ return (
+
+ );
+}
+```
+
+:::note
+A tracking scope can be created by [`createEffect`](/reference/basic-reactivity/create-effect) or [`createMemo`](/reference/basic-reactivity/create-memo), which are other Solid primitives.
+
+Both functions subscribe to the signals accessed within them, establishing a dependency relationship.
+Once this relationship is established, the function is notified whenever the signal changes.
+
+:::
+
+To learn more about how to use Signals in your application, visit our [state management guide](/guides/state-management).
diff --git a/old pages/concepts/understanding-jsx.mdx b/old pages/concepts/understanding-jsx.mdx
new file mode 100644
index 000000000..8dea79978
--- /dev/null
+++ b/old pages/concepts/understanding-jsx.mdx
@@ -0,0 +1,129 @@
+---
+title: Understanding JSX
+order: 2
+---
+
+JSX is an extension for JavaScript.
+It allows you to write HTML-like code inside your JavaScript file which keeps your rendering logic and content in the same place.
+This provides a concise and readable way to create and represent components.
+
+## How Solid uses JSX
+
+Solid was designed to align closely with HTML standards.
+
+```jsx
+const element =
I'm JSX!!
+```
+
+It offers a distinct advantage, however: to copy/paste solutions from resources like Stack Overflow; and to allow direct usage of templates from design tools.
+Solid sets itself apart by using JSX immediately as it returns [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction) elements.
+This lets you use dynamic expressions within your HTML by allowing variables and functions to be references with the use of curly braces (`{ }`):
+
+```jsx
+const Component = () => {
+ const animal = { breed: "cat", name: "Midnight" }
+
+ return (
+
+ I have a {animal.breed} named {animal.name}!
+
+ )
+}
+```
+
+This means JavaScript content can be rendered on web pages based on an application's state or logic.
+
+Additionally, Solid's [reactive](/concepts/intro-to-reactivity) system introduces [fine-grained reactivity](/advanced-concepts/fine-grained-reactivity) with JSX.
+This updates only the necessary parts of the DOM when changes occur in the underlying state.
+
+## Using JSX in Solid
+
+### Return a single root element
+
+Where HTML lets you have disconnected tags at the top level, JSX requires that a component to return a single root element.
+
+:::advanced
+When working with JSX, parts of your code are translated into structured HTML that is placed at the start of the file.
+Static elements are processed differently from dynamic ones, which might change based on data or user actions.
+For dynamic elements, special markers are added for better handling during rendering.
+
+Having a single root creates a consistent and manageable hierarchy to optimize rendering and updates.
+:::
+
+JSX maintains the familiar nested, tree-like structure found in HTML.
+As a result, parent-child relationships between elements become easier to follow.
+
+### Close all tags
+
+Self-closing tags are a must in JSX.
+Unlike in HTML, where elements like ``, ``, or ` ` don't require explicit closure, JSX requires consistent self-closing tags.
+This helps to avoid potential rendering issues.
+
+```jsx
+
+```
+
+### Properties vs. attributes
+
+HTML attributes and JSX properties may seem similar, but they serve different purposes and behave differently.
+Both offer ways to specify configurations or pass information.
+However, HTML is used for standard web content and JSX creates Solid's component logic.
+
+#### HTML attributes
+
+[HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes) are values set directly on HTML elements.
+They provide additional information about an element to guide its initial behavior and state.
+These attributes are often translated into properties on DOM objects once the browser parses the HTML.
+
+In JSX files, HTML attributes are used much like regular HTML, with a few key differences due to the blend of HTML and JavaScript:
+
+- Event listeners such as `onClick` can be in camelCase or lowercase.
+ (**Note:** When using ESLint, you will get a warning if you use lowercase.)
+- In cases where you can dynamically specify a value, you can replace the `"` and `"` with curly braces (`{ }`):
+
+```jsx
+
+```
+
+ :::note
+ If you wish to pass objects in JSX, such as with inline styling, you will have to use double curly braces (`{{ }}`).
+
+```jsx
+
+```
+:::
+
+### JSX properties (props)
+
+JSX properties, commonly known as "props," help with the passing of data and configurations to components within an application.
+They connect the component with the data it requires, for seamless data flows and dynamic interactions.
+
+#### Core concepts
+
+- **Static props**:
+ In Solid's JSX, static props are integrated directly into the HTML by cloning the template and using them as attributes.
+
+ - **Dynamic props**:
+ Dynamic props rely on state, allowing the content or properties to be dynamic.
+ An example is changing the style of an element in response to interactions within an application.
+ This can be expressed in the form of signals (`value={value()}`).
+
+- **Data transfer**:
+ Props are also used to fill components with data that comes from resources, like [`createResource`](/reference/basic-reactivity/create-resource) calls.
+ This results in components that react in real-time to data changes.
+
+:::note
+Expressions, whether fixed or dynamic, get applied *in the order defined within the JSX*.
+This works for a wide range of DOM elements, but will not work with elements that require attributes to be defined in a special order, such as input types with `type='range'`.
+
+When order influences an element's behavior, users must define the expressions in the order that the element is expected.
+:::
+
+For how to use props effectively in Solid, explore the [props page](/concepts/components/props).
diff --git a/old pages/quick-start.mdx b/old pages/quick-start.mdx
new file mode 100644
index 000000000..c04a9c7b5
--- /dev/null
+++ b/old pages/quick-start.mdx
@@ -0,0 +1,80 @@
+---
+title: Quick start
+---
+
+## Try Solid online
+
+To experiment with Solid directly in your browser, head over to our [interactive playground](https://playground.solidjs.com/).
+Prefer a full development setup? You can set up a complete environment using StackBlitz.
+Start with the [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) or [JavaScript](https://stackblitz.com/github/solidjs/templates/tree/master/js) templates.
+
+## Create a Solid project
+
+:::note[Prerequisites]
+
+- Familiarity with the command line.
+- A recent version of [Node.js](https://nodejs.org/en), [Bun](https://bun.sh/), or [Deno](https://deno.com/).
+ The latest LTS version is recommended.
+
+:::
+
+To create a new Solid application, navigate to the directory where you want to create your project and run the following command:
+
+```package-create
+solid
+```
+
+This command installs and runs [create-solid](https://github.com/solidjs-community/solid-cli/tree/main/packages/create-solid), the official project scaffolding tool for Solid.
+The CLI will guide you through a series of prompts, allowing you to choose options such as [starter templates](https://github.com/solidjs/templates), TypeScript support, and whether to include [Solid's full-stack framework, SolidStart](/solid-start):
+
+```shell
+◆ Project Name
+|
+
+◆ Is this a SolidStart project?
+| ● Yes / ○ No
+
+◆ Which template would you like to use?
+│ ● ts
+│ ○ ts-vitest
+│ ○ ts-uvu
+│ ○ ts-unocss
+│ ○ ts-tailwindcss
+
+◆ Use TypeScript?
+│ ● Yes / ○ No
+```
+
+Once the project is created, follow the instructions to install the dependencies and start the development server:
+
+```sh title="npm" tab="package-manager"
+│ cd solid-project
+│ npm install
+│ npm run dev
+```
+
+```sh title="pnpm" tab="package-manager"
+│ cd solid-project
+│ pnpm install
+│ pnpm dev
+```
+
+```sh title="yarn" tab="package-manager"
+│ cd solid-project
+│ yarn install
+│ yarn dev
+```
+
+```sh title="bun" tab="package-manager"
+│ cd solid-project
+│ bun install
+│ bun run dev
+```
+
+```sh title="deno" tab="package-manager"
+│ cd solid-project
+│ deno install
+│ deno run dev
+```
+
+You should now have your Solid project running!
diff --git a/src/routes/getting-started/counter.mdx b/src/routes/getting-started/counter.mdx
new file mode 100644
index 000000000..ee8d28182
--- /dev/null
+++ b/src/routes/getting-started/counter.mdx
@@ -0,0 +1,12 @@
+---
+title: "Counter Tutorial"
+order: 2
+---
+
+[TODO]
+
+1. Open your newly scaffolded project in your code editor of choice.
+2. Create a new file called `Counter.jsx` in the `src/components` directory.
+3. In `Counter.tsx`, use Solid's `createSignal` to create a reactive counter state.
+4. Export the `Counter` component and import it into your main application file (e.g., `src/App.jsx`).
+5. Use the `Counter` component in your application and test its functionality.
\ No newline at end of file
diff --git a/src/routes/getting-started/quick-start.mdx b/src/routes/getting-started/quick-start.mdx
new file mode 100644
index 000000000..4e5a93110
--- /dev/null
+++ b/src/routes/getting-started/quick-start.mdx
@@ -0,0 +1,26 @@
+---
+title: Quick Start Guide
+order: 1
+---
+
+The fastest way to try Solid is to create a new project and run it locally.
+In just a few minutes, you’ll have a working Solid app running in your browser.
+
+## Solid in your Browser
+
+If you're looking to experiment with Solid without setting up a local environment, open the [Solid Playground](https://playground.solidjs.com/) in your browser.
+
+If you prefer a more complete development setup, you can use the StackBlitz [Javascript](https://stackblitz.com/github/solidjs/templates/tree/master/js) or [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) templates.
+
+## Create a New Project
+
+:::note[Before You Begin]
+Make sure you have a recent version of your prefer JavaScript runtime installed, such as [Node.js](https://nodejs.org/en), [Bun](https://bun.sh/), or [Deno](https://deno.com/).
+:::
+
+[TODO]
+
+- Navigate to directory and run command
+- CLI will take you through options
+- Once you've selected your options, the CLI will prompt you to install the dependencies and start the development server
+- Open browser and navigate to the provided local URL to see your new Solid app in action!
\ No newline at end of file
diff --git a/src/routes/reactivity/memos.mdx b/src/routes/reactivity/memos.mdx
new file mode 100644
index 000000000..bdaf190ab
--- /dev/null
+++ b/src/routes/reactivity/memos.mdx
@@ -0,0 +1,11 @@
+---
+title: "Memos"
+order: 3
+---
+
+[TODO:
+Concept page on Memos
+- Improve on existing page
+- Move relevant sections to reference and vice versa
+- Link out to how-to for derived signals where appropriate
+]
\ No newline at end of file
diff --git a/src/routes/reactivity/overview.mdx b/src/routes/reactivity/overview.mdx
new file mode 100644
index 000000000..725a2186c
--- /dev/null
+++ b/src/routes/reactivity/overview.mdx
@@ -0,0 +1,74 @@
+---
+title: "Overview"
+order: 1
+---
+
+[TODO: Review]
+
+:::note
+While this guide can be helpful for understanding reactive systems, it does use some Solid-specific terminology and concepts.
+:::
+
+Reactivity is what powers the interactivity of Solid apps.
+This programming paradigm refers to a system's ability to respond to changes in data, or state, automatically and efficiently.
+Solid is built with reactivity at the core of its design, assisting applications with staying up-to-date with its underlying data.
+
+## The Importance of Reactivity
+
+Reactivity is what keeps the user interface (UI) in sync with the underlying application state.
+When the state changes, the UI is automatically updated, reducing the need for manual updates.
+
+In addition, reactivity enables real-time updates, allowing applications to reflect changes instantly without requiring a full page refresh.
+This helps with creating more responsive and interactive user experiences.
+
+As an example, when building a Counter, you can use the reactive primitives provided by Solid to create a counter.
+Once the counter is set up, whenever the count changes, the UI will automatically update to reflect the new count:
+
+```tsx
+function Counter() {
+ const [count, setCount] = createSignal(0);
+ const increment = () => setCount((prev) => prev + 1);
+
+ return (
+
+ Count: {count()}{" "}
+ {/* Only `count()` is updated when the button is clicked. */}
+
+
+ );
+}
+```
+
+## Reactive Principles
+
+### Signals
+
+Signals serve as the core elements within a reactive system.
+They play a crucial role in tracking and managing state changes, allowing the UI to respond automatically when the underlying data changes.
+They are responsible for storing and managing data, as well as triggering updates across the system.
+
+Signals are able to achieve this reactivity through the use of:
+
+- **Getters**: A function responsible for retrieving the current value of a signal.
+When called within a reactive context, it will give access to the current value of the signal.
+- **Setters**: This function is responsible for updating the value of a signal.
+To trigger reactivity, setters notify the system that the signal's value has changed, prompting anything that depends on the signal to re-evaluate and update accordingly.
+
+
+
+### Subscribers
+
+Subscribers refer to other reactive contexts or components that depend on the value of a signal.
+These automated responders keep the system up-to-date by re-evaluating and updating whenever the signal's value changes.
+
+Subscribers work based on two main actions:
+- **Observation**: The core function of a subscriber is to observe signals.
+This keeps the subscriber informed about any changes to the signal(s) they're tracking.
+- **Respond**: Once the signal has updated and the subscriber is notified, it triggers a re-evaluation of the dependent computations or UI updates.
+
+[TODO: Some kind of image / code block??]
\ No newline at end of file
diff --git a/src/routes/reactivity/stores.mdx b/src/routes/reactivity/stores.mdx
index c8c7e9151..eb8a33bb3 100644
--- a/src/routes/reactivity/stores.mdx
+++ b/src/routes/reactivity/stores.mdx
@@ -1,4 +1,4 @@
---
-title: "Reactive State Management"
+title: "Stores"
order: 5
---
From 8e9c161b71b7fc2634bc49628fbe87b086523631 Mon Sep 17 00:00:00 2001
From: LadyBluenotes
Date: Wed, 17 Sep 2025 11:56:39 -0700
Subject: [PATCH 29/37] fix broken jsx
---
old pages/concepts/understanding-jsx.mdx | 20 +++++++++++--------
src/routes/getting-started/counter.mdx | 12 -----------
.../getting-started/understanding-jsx.mdx | 11 +++++-----
src/routes/reactivity/basics.mdx | 6 +++---
src/routes/solid-router/concepts/data.json | 1 -
5 files changed, 20 insertions(+), 30 deletions(-)
delete mode 100644 src/routes/getting-started/counter.mdx
diff --git a/old pages/concepts/understanding-jsx.mdx b/old pages/concepts/understanding-jsx.mdx
index 8dea79978..6609b4c12 100644
--- a/old pages/concepts/understanding-jsx.mdx
+++ b/old pages/concepts/understanding-jsx.mdx
@@ -11,7 +11,7 @@ This provides a concise and readable way to create and represent components.
Solid was designed to align closely with HTML standards.
-```jsx
+```tsx
const element =
I'm JSX!!
```
@@ -19,7 +19,7 @@ It offers a distinct advantage, however: to copy/paste solutions from resources
Solid sets itself apart by using JSX immediately as it returns [DOM](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Introduction) elements.
This lets you use dynamic expressions within your HTML by allowing variables and functions to be references with the use of curly braces (`{ }`):
-```jsx
+```tsx
const Component = () => {
const animal = { breed: "cat", name: "Midnight" }
@@ -42,7 +42,7 @@ This updates only the necessary parts of the DOM when changes occur in the under
Where HTML lets you have disconnected tags at the top level, JSX requires that a component to return a single root element.
-:::advanced
+:::note
When working with JSX, parts of your code are translated into structured HTML that is placed at the start of the file.
Static elements are processed differently from dynamic ones, which might change based on data or user actions.
For dynamic elements, special markers are added for better handling during rendering.
@@ -59,7 +59,7 @@ Self-closing tags are a must in JSX.
Unlike in HTML, where elements like ``, ``, or ` ` don't require explicit closure, JSX requires consistent self-closing tags.
This helps to avoid potential rendering issues.
-```jsx
+```tsx
```
@@ -81,16 +81,17 @@ In JSX files, HTML attributes are used much like regular HTML, with a few key di
(**Note:** When using ESLint, you will get a warning if you use lowercase.)
- In cases where you can dynamically specify a value, you can replace the `"` and `"` with curly braces (`{ }`):
-```jsx
+```tsx
```
- :::note
- If you wish to pass objects in JSX, such as with inline styling, you will have to use double curly braces (`{{ }}`).
+:::note
+
+If you wish to pass objects in JSX, such as with inline styling, you will have to use double curly braces (`{{ }}`).
-```jsx
+```tsx