`, or use a fragment `<>...`.
+
+```tsx
+function App() {
+ return (
+
+
Hello World!
+
Welcome to JSX in Solid.
+
+ Click me!
+
+
+
+ Styled Button
+
+```
+
+You can also use JavaScript expressions to set attribute values dynamically:
+
+```tsx
+const isActive = true;
+
+
+ Click me!
+
+```
+
+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. `
-
- Learn the basics of Solid through this interactive tutorial.
-
-
- Start your first project with a template that fits your needs.
-
-
- Explore the Solid ecosystem and find useful tools and libraries.
-
-
- Help improve Solid by contributing to the documentation.
-
-
-
-_Find our API documentation under the **Reference** tab_
-
-Join the [Solid community on Discord](https://discord.com/invite/solidjs) to share your projects or get help from our community!
-
-
-
- Learn the basics of Solid through this interactive tutorial.
-
-
- Start your first project with a template that fits your needs.
-
-
- Explore the Solid ecosystem and find useful tools and libraries.
-
-
- Help improve Solid by contributing to the documentation.
-
-
-
-_Find our API documentation under the **Reference** tab_
-
-Join the [Solid community on Discord](https://discord.com/invite/solidjs) to share your projects or get help from our community!
-
-
+
Count: {count()}
{/* ✅ tracked automatically - re-runs on update */}
+
setCount(count() + 1)}>Increment
+
setCount(count() + 1)}>
+ Increment
+
+ );
+}
+```
+
+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()}
;
+}
+```
+
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..f6351bcd0
--- /dev/null
+++ b/src/routes/reactivity/overview.mdx
@@ -0,0 +1,69 @@
+---
+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. */}
+
+ Increment
+
+
+ );
+}
+```
+
+## 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..16342dad1
--- /dev/null
+++ b/src/routes/reactivity/resources.mdx
@@ -0,0 +1,8 @@
+---
+title: "Handling Async Data"
+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..e19c1e3c3
--- /dev/null
+++ b/src/routes/reactivity/signals.mdx
@@ -0,0 +1,73 @@
+---
+title: "Signals"
+order: 2
+---
+
+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 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**.
+
+## 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 (
+
+ Count: {count()} {/* Updates when `count` changes */}
+ Increment
+
+ );
+}
+```
+
diff --git a/src/routes/reactivity/stores.mdx b/src/routes/reactivity/stores.mdx
new file mode 100644
index 000000000..5a5384762
--- /dev/null
+++ b/src/routes/reactivity/stores.mdx
@@ -0,0 +1,100 @@
+---
+title: "Stores"
+order: 5
+---
+
+Stores are a state management primitive in Solid that provide a convenient, centralized way to handle structured data.
+Unlike signals, which are best suited for primitive values, stores are better for managing complex data structures like objects and arrays:
+
+- They provide fine-grained reactivity, meaning only the parts of the store that are accessed will trigger updates when they change.
+- They support **nested reactivity,** so you can track and update deeply nested properties without losing reactivity.
+- They make working with complex state easier while avoiding duplication or unnecessary recomputation.
+
+Stores are built on top of Solid's reactive system, leveraging [JavaScript's proxies](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) to track property access and changes.
+
+## Creating a Store
+
+To create a store, you can use the `createStore` function from the `solid-js/store` package.
+This function takes an initial value and returns a tuple containing the store and a setter function to update it.
+
+```tsx
+import { createStore } from "solid-js/store"
+
+// Initialize store
+const [store, setStore] = createStore({
+ userCount: 3,
+ users: [
+ {
+ id: 0,
+ username: "felix909",
+ location: "England",
+ loggedIn: false,
+ },
+ {
+ id: 1,
+ username: "tracy634",
+ location: "Canada",
+ loggedIn: true,
+ },
+ {
+ id: 2,
+ username: "johny123",
+ location: "India",
+ loggedIn: true,
+ },
+ ],
+})
+```
+
+## Accessing store values
+
+Unlike signals, which are functions that need to be called to get their values, stores can be accessed directly like regular objects or arrays.
+
+```tsx
+console.log(store.userCount) // 3
+```
+
+Inside a tracking scope, store properties can be accessed directly, and any changes to those properties will trigger updates to the scope.
+
+:::note
+
+Stores create signals **lazily**.
+This means that a property only becomes reactive once accessed inside a tracking scope.
+:::
+
+```tsx
+const App = () => {
+ const [mySignal, setMySignal] = createSignal("This is a signal.")
+ const [store, setStore] = createStore({
+ userCount: 3,
+ users: [
+ {
+ id: 0,
+ username: "felix909",
+ location: "England",
+ loggedIn: false,
+ },
+ {
+ id: 1,
+ username: "tracy634",
+ location: "Canada",
+ loggedIn: true,
+ },
+ {
+ id: 2,
+ username: "johny123",
+ location: "India",
+ loggedIn: true,
+ },
+ ],
+ })
+ return (
+
+
Hello, {store.users[0].username} {/* Accessing a store value */}
+ {mySignal()} {/* Accessing a signal */}
+
+ )
+}
+```
+
+##
\ No newline at end of file
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": []
+}
diff --git a/src/routes/solid-router/concepts/actions.mdx b/src/routes/solid-router/concepts/actions.mdx
index 26fba9b4b..0bf425e48 100644
--- a/src/routes/solid-router/concepts/actions.mdx
+++ b/src/routes/solid-router/concepts/actions.mdx
@@ -13,151 +13,445 @@ tags:
version: '1.0'
---
-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
+
+
```
@@ -93,16 +93,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