Welcome to Counter App

- ) + ); } ``` @@ -179,12 +183,12 @@ export function CounterProvider(props) { count, { increment() { - setCount(prev => prev + 1); + setCount((prev) => prev + 1); }, decrement() { - setCount(prev => prev - 1); - } - } + setCount((prev) => prev - 1); + }, + }, ]; return ( @@ -194,7 +198,9 @@ export function CounterProvider(props) { ); } -export function useCounter() { return useContext(CounterContext); } +export function useCounter() { + return useContext(CounterContext); +} ``` ```tsx tab title="Child.jsx" @@ -205,13 +211,13 @@ export function Child(props) { const [count, { increment, decrement }] = useCounter(); return ( - <> -

{count()}

I'm JSX!!

I have a {animal.breed} named {animal.name}!

New in v1.9.0

{} + interface CustomEvents extends Pick< + HTMLElementEventMap, + "mousemove" | "pointermove" + > {} } } ``` diff --git a/src/routes/guides/complex-state-management.mdx b/src/routes/guides/complex-state-management.mdx index 068ab6e76..ee5aed88a 100644 --- a/src/routes/guides/complex-state-management.mdx +++ b/src/routes/guides/complex-state-management.mdx @@ -1,6 +1,20 @@ --- title: Complex state management order: 5 +use_cases: >- + scaling applications, multiple components, backend communication, state + synchronization, prop drilling, shared state +tags: + - stores + - state + - context + - scaling + - components + - management +version: "1.0" +description: >- + Master complex state management in Solid using stores and context to build + scalable, maintainable applications efficiently. --- As applications grow and start to involve many components, more intricate user interactions, and possibly communication with backend services, you may find that staying organized with more [basic state management methods](/guides/state-management) can become difficult to maintain. @@ -8,25 +22,27 @@ As applications grow and start to involve many components, more intricate user i Consider this example: ```jsx -import { For, createSignal, Show, createMemo } from "solid-js" +import { For, createSignal, Show, createMemo } from "solid-js"; const App = () => { - const [tasks, setTasks] = createSignal([]) - const [numberOfTasks, setNumberOfTasks] = createSignal(tasks.length) - const completedTasks = createMemo(() => tasks().filter((task) => task.completed)) - let input + const [tasks, setTasks] = createSignal([]); + const [numberOfTasks, setNumberOfTasks] = createSignal(tasks.length); + const completedTasks = createMemo(() => + tasks().filter((task) => task.completed) + ); + let input; const addTask = (text) => { - setTasks([...tasks(), { id: tasks().length, text, completed: false }]) - setNumberOfTasks(numberOfTasks() + 1) - } + setTasks([...tasks(), { id: tasks().length, text, completed: false }]); + setNumberOfTasks(numberOfTasks() + 1); + }; const toggleTask = (id) => { setTasks( tasks().map((task) => task.id !== id ? task : { ...task, completed: !task.completed } ) - ) - } + ); + }; return ( <> @@ -36,9 +52,9 @@ const App = () => {

My Task List for Today

You have {state.numberOfTasks} task(s) for today!

{(task) => { - const { id, text } = task + const { id, text } = task; return (

{ /> {text}

- ) + ); }}

{/* Your components */}

``` + 4. Navigate to the root of your app (where zerops.yml is located) and run the following command in Terminal to trigger the deploy: + ```bash zcli push ``` diff --git a/src/routes/guides/fetching-data.mdx b/src/routes/guides/fetching-data.mdx index 8bf0f9e24..c07b8fa1c 100644 --- a/src/routes/guides/fetching-data.mdx +++ b/src/routes/guides/fetching-data.mdx @@ -1,6 +1,21 @@ --- title: Fetching data order: 3 +use_cases: >- + api calls, async data loading, server communication, external data fetching, + loading states, error handling +tags: + - data + - fetching + - async + - api + - createresource + - suspense + - loading +version: "1.0" +description: >- + Master data fetching in Solid with createResource for async operations, + loading states, error handling, and Suspense boundaries. --- For most modern web applications, data fetching is a common task. @@ -23,11 +38,12 @@ These properties can be used to conditionally render JSX based on the current re The fetcher function that is created makes a call to get a user, which is then passed in as an argument to `createResource`. The signal returned from the `createResource` provides the properties that can assist with conditional rendering based on the current reactive state: -* `state`: The current status of the operation (`unresolved`, `pending`, `ready`, `refreshing`, or `errored`). -* `loading`: Indicates that the operation is currently in progress via a `boolean`. -* `error`: If the operation fails for any reason, this property will contain information about this error. -It may be a string with an error message, or an object with more detailed information. -* `latest`: The most recent data or result returned from the operation. + +- `state`: The current status of the operation (`unresolved`, `pending`, `ready`, `refreshing`, or `errored`). +- `loading`: Indicates that the operation is currently in progress via a `boolean`. +- `error`: If the operation fails for any reason, this property will contain information about this error. + It may be a string with an error message, or an object with more detailed information. +- `latest`: The most recent data or result returned from the operation. When there is a change in the source signal, an internal fetch process is triggered to retrieve new data based on this change. @@ -35,35 +51,35 @@ When there is a change in the source signal, an internal fetch process is trigge import { createSignal, createResource, Switch, Match, Show } from "solid-js"; const fetchUser = async (id) => { - const response = await fetch(`https://swapi.dev/api/people/${id}/`); - return response.json(); -} + const response = await fetch(`https://swapi.dev/api/people/${id}/`); + return response.json(); +}; function App() { - const [userId, setUserId] = createSignal(); - const [user] = createResource(userId, fetchUser); - - return ( -

- setUserId(e.currentTarget.value)} - /> - -

- - - - Error: {user.error} - - -

{JSON.stringify(user())}

- - -

- ); + const [userId, setUserId] = createSignal(); + const [user] = createResource(userId, fetchUser); + + return ( +

+ setUserId(e.currentTarget.value)} + /> + +

+ + + + Error: {user.error} + + +

{JSON.stringify(user())}

+ + +

+ ); } ``` @@ -77,12 +93,11 @@ However, if there's an error while fetching, the `user.error` block becomes `tru :::tip If you anticipate errors, you may want to wrap `createResource` in an [ErrorBoundary](/reference/components/error-boundary). - + ::: In addition to the `error` property, the `loading` property offers a way to display a loading state to the user during the fetch operation. - ## Calling multiple async events Although you can use `createResource` independently, Solid provides an alternative method for synchronizing the display of multiple asynchronous events. @@ -90,37 +105,43 @@ Although you can use `createResource` independently, Solid provides an alternati It allows you to display a fallback placeholder while waiting for all asynchronous events to resolve, preventing the display of partially loaded content: ```jsx -import { createSignal, createResource, Switch, Match, Suspense } from "solid-js"; +import { + createSignal, + createResource, + Switch, + Match, + Suspense, +} from "solid-js"; const fetchUser = async (id) => { - const response = await fetch(`https://swapi.dev/api/people/${id}/`); - return response.json(); -} + const response = await fetch(`https://swapi.dev/api/people/${id}/`); + return response.json(); +}; function App() { - const [userId, setUserId] = createSignal(); - const [user] = createResource(userId, fetchUser); - - return ( -

- setUserId(e.currentTarget.value)} - /> - Loading...

}> - - - Error: {user.error.message} - - -

{JSON.stringify(user())}

- - - -

Hello, world!

diff --git a/src/routes/guides/styling-components/tailwind-v3.mdx b/src/routes/guides/styling-components/tailwind-v3.mdx index 3ae214d9a..c6d3b82f9 100644 --- a/src/routes/guides/styling-components/tailwind-v3.mdx +++ b/src/routes/guides/styling-components/tailwind-v3.mdx @@ -2,6 +2,20 @@ title: Tailwind CSS v3 order: 7 mainNavExclude: true +use_cases: >- + utility-first css, rapid prototyping, responsive design, consistent styling, + atomic css classes +tags: + - styling + - tailwind + - utility-css + - responsive + - postcss + - atomic-css +version: "1.0" +description: >- + Set up Tailwind CSS v3 in Solid apps for utility-first styling, rapid + development, and consistent responsive design patterns. --- [Tailwind CSS v3](https://v3.tailwindcss.com/) is an on-demand utility CSS library that integrates seamlessly with Solid as a built-in PostCSS plugin. @@ -10,7 +24,6 @@ mainNavExclude: true 1. Install Tailwind CSS as a development dependency: - ```package-install-dev tailwindcss@3 postcss autoprefixer ``` @@ -76,8 +89,8 @@ Update your components to use Tailwind's utility classes: /* src/components/Card.jsx */ function Card() { return ( -

Hello, world!

diff --git a/src/routes/guides/styling-components/tailwind.mdx b/src/routes/guides/styling-components/tailwind.mdx index 5bee79841..6b2aa004d 100644 --- a/src/routes/guides/styling-components/tailwind.mdx +++ b/src/routes/guides/styling-components/tailwind.mdx @@ -2,6 +2,20 @@ title: Tailwind CSS order: 5 mainNavExclude: true +use_cases: >- + styling components, utility classes, rapid ui development, responsive design, + production builds +tags: + - styling + - css + - tailwind + - postcss + - utilities + - design +version: "1.0" +description: >- + Set up Tailwind CSS v4 in your Solid app for utility-first styling. Configure + PostCSS, import styles, and build responsive UIs efficiently. --- :::note @@ -24,8 +38,8 @@ tailwindcss @tailwindcss/postcss postcss export default { plugins: { "@tailwindcss/postcss": {}, - } -} + }, +}; ``` For a deeper dive into configuration, you can check out the [Tailwind Official Documentation](https://tailwindcss.com/docs/configuration). @@ -38,7 +52,6 @@ Add an `@import` to your `src/index.css` file that imports Tailwind CSS. @import "tailwindcss"; ``` - ## Import your CSS file Import your `index.css` file into the root `index.jsx` or `index.tsx` file: @@ -67,8 +80,8 @@ Update your components to use Tailwind's utility classes: /* src/components/Card.jsx */ function Card() { return ( -

Hello, world!

diff --git a/src/routes/guides/styling-components/uno.mdx b/src/routes/guides/styling-components/uno.mdx index e79499cc3..98a33c03d 100644 --- a/src/routes/guides/styling-components/uno.mdx +++ b/src/routes/guides/styling-components/uno.mdx @@ -2,6 +2,19 @@ title: UnoCSS order: 6 mainNavExclude: true +use_cases: >- + styling components, utility css, on-demand styles, vite integration, atomic + css +tags: + - styling + - css + - unocss + - vite + - utilities +version: "1.0" +description: >- + Integrate UnoCSS with Solid for on-demand utility CSS. Configure Vite plugin, + import styles, and create efficient atomic CSS designs quickly. --- [UnoCSS](https://unocss.dev/) is an on-demand utility CSS library that integrates seamlessly with Solid as a Vite plugin. diff --git a/src/routes/guides/styling-your-components.mdx b/src/routes/guides/styling-your-components.mdx index 611acbf3f..3b541c046 100644 --- a/src/routes/guides/styling-your-components.mdx +++ b/src/routes/guides/styling-your-components.mdx @@ -1,6 +1,19 @@ --- title: Styling your components order: 1 +use_cases: >- + styling components, choosing css solutions, css frameworks, preprocessors, + css-in-js +tags: + - styling + - css + - preprocessors + - css-in-js + - frameworks +version: "1.0" +description: >- + Explore Solid's flexible styling options: CSS preprocessors, CSS Modules, + CSS-in-JS, and utility frameworks for component styling needs. --- Solid provides flexible and versatile ways to style your components. diff --git a/src/routes/guides/testing.mdx b/src/routes/guides/testing.mdx index 5452f276b..06bd88b8a 100644 --- a/src/routes/guides/testing.mdx +++ b/src/routes/guides/testing.mdx @@ -1,6 +1,19 @@ --- title: Testing order: 6 +use_cases: >- + testing components, unit tests, integration tests, user interactions, test + coverage, quality assurance +tags: + - testing + - vitest + - components + - unit-tests + - quality +version: "1.0" +description: >- + Test Solid apps with Vitest and Testing Library. Write component tests, + simulate user interactions, and ensure code quality effectively. --- Testing your Solid applications is important to inspiring confidence in your codebase through preventing regressions. @@ -15,7 +28,6 @@ Testing your Solid applications is important to inspiring confidence in your cod - [`@testing-library/user-event`](https://testing-library.com/docs/user-event/intro) - used to simulate user events that are closer to reality - [`@testing-library/jest-dom`](https://testing-library.com/docs/ecosystem-jest-dom) - augments expect with helpful matchers - ### Adding testing packages The recommended testing framework for Solid applications is [vitest](https://vitest.dev). @@ -56,15 +68,15 @@ If using TypeScript, add `@testing-library/jest-dom` to `tsconfig.json#compilerO When using [SolidStart](/solid-start), create a `vitest.config.ts` file: ```ts title="vitest.config.ts" -import solid from "vite-plugin-solid" -import { defineConfig } from "vitest/config" +import solid from "vite-plugin-solid"; +import { defineConfig } from "vitest/config"; export default defineConfig({ - plugins: [solid()], - resolve: { - conditions: ["development", "browser"], - }, -}) + plugins: [solid()], + resolve: { + conditions: ["development", "browser"], + }, +}); ``` ## Writing tests @@ -81,31 +93,27 @@ To write tests for your components, create a `[name].test.tsx` file. The purpose of this file is to describe the intended behavior from a user's perspective in the form of unit tests: ```jsx tab title="Counter.test.jsx" -import { test, expect } from "vitest" -import { render } from "@solidjs/testing-library" -import userEvent from "@testing-library/user-event" -import { Counter } from "./Counter" +import { test, expect } from "vitest"; +import { render } from "@solidjs/testing-library"; +import userEvent from "@testing-library/user-event"; +import { Counter } from "./Counter"; -const user = userEvent.setup() +const user = userEvent.setup(); test("increments value", async () => { - const { getByRole } = render(() => ) - const counter = getByRole('button') - expect(counter).toHaveTextContent("1") - await user.click(counter) - expect(counter).toHaveTextContent("2") -}) + const { getByRole } = render(() => ); + const counter = getByRole("button"); + expect(counter).toHaveTextContent("1"); + await user.click(counter); + expect(counter).toHaveTextContent("2"); +}); ``` ```jsx tab title="Counter.jsx" export const Counter = () => { - const [count, setCount] = createSignal(1); - return ( - - ); -} + const [count, setCount] = createSignal(1); + return ; +}; ``` In the `test.jsx` file, [the `render` call from `@solidjs/testing-library`](https://testing-library.com/docs/solid-testing-library/api#render) is used to render the component and supply the props and context. @@ -137,30 +145,31 @@ environment 880ms, prepare 212ms) #### Rendering the component -The `render` function from `@solidjs/testing-library` creates the testing environment within the `test.tsx` file. +The `render` function from `@solidjs/testing-library` creates the testing environment within the `test.tsx` file. It sets up the container, rendering the component within it, and automatically registers it for clean-up after a successful test. Additionally, it manages wrapping the component in contexts as well as setting up a router. ```tsx frame="none" const renderResult = render( - () => , // @solidjs/testing-library requires a function - { // all options are optional - container, // manually set up your own container, will not be handled - baseElement, // parent of container in case it is not supplied - queries, // manually set up custom queries - hydrate, // set to `true` to use hydration - wrapper, // reusable wrapper component to supply context - location, // sets up a router pointed to the location if provided - } -) + () => , // @solidjs/testing-library requires a function + { + // all options are optional + container, // manually set up your own container, will not be handled + baseElement, // parent of container in case it is not supplied + queries, // manually set up custom queries + hydrate, // set to `true` to use hydration + wrapper, // reusable wrapper component to supply context + location, // sets up a router pointed to the location if provided + } +); const { - asFragment, // function returning the contents of the container - baseElement, // the parent of the container - container, // the container in which the component is rendered - debug, // a function giving some helpful debugging output - unmount, // manually removing the component from the container - ...queries, // functions to select elements from the container -} = renderResult + asFragment, // function returning the contents of the container + baseElement, // the parent of the container + container, // the container in which the component is rendered + debug, // a function giving some helpful debugging output + unmount, // manually removing the component from the container + ...queries // functions to select elements from the container +} = renderResult; ``` ##### Using the right queries @@ -181,7 +190,7 @@ The prefixes (`get`, `query`, and `find`) and the middle portion (`By` and `AllB - **getAllBy**: synchronous, throws if not found, returns array of matches - **queryBy**: synchronous, null if not found, error if more than 1 matches - **queryAllBy**: synchronous, returns array of zero or more matches -- **findBy**: asynchronous, rejected if not found within 1000ms or more than 1 matches, resolves wth element if found +- **findBy**: asynchronous, rejected if not found within 1000ms or more than 1 matches, resolves with element if found - **findAllBy**: asynchronous, rejected if not found within 1000ms, resolves with array of one or more element(s) By default, queries should start with `get...`. @@ -190,7 +199,7 @@ If there are multiple elements matching the same query, `getAllBy...` should be There are two exceptions when you should **not** start with `get...`: 1. If the `location` option is used or the component is based on resources, the router will be lazy-loaded; in this case, the first query after rendering needs to be `find...` -2. When testing something that is *not* rendered, you will need to find something that will be rendered at the same time; after that, use `queryAllBy...` to test if the result is an empty array (`[]`). +2. When testing something that is _not_ rendered, you will need to find something that will be rendered at the same time; after that, use `queryAllBy...` to test if the result is an empty array (`[]`). The query's suffix (Role, LabelText, ...) depends on the characteristics of the element you want to select. If possible, try to select for accessible attributes (roughly in the following order): @@ -202,7 +211,7 @@ If possible, try to select for accessible attributes (roughly in the following o - **DisplayValue**: form elements showing the given value (e.g. select elements) - **AltText**: images with alt text - **Title**: HTML elements with the `title` attribute or SVGs with the `` tag containing the given text -- **TestId**: queries by the `data-testid` attribute; a different data attribute can be setup via `configure({testIdAttribute: 'data-my-test-attribute'})`; TestId-queries are *not accessible*, so use them only as a last resort. +- **TestId**: queries by the `data-testid` attribute; a different data attribute can be setup via `configure({testIdAttribute: 'data-my-test-attribute'})`; TestId-queries are _not accessible_, so use them only as a last resort. For more information, check the [testing-library documentation](https://testing-library.com/docs/queries/about). @@ -211,29 +220,33 @@ For more information, check the [testing-library documentation](https://testing- Solid allows components to break through the DOM tree structure using [`<Portal>`](/reference/components/portal). This mechanism will still work in testing, so the content of the portals will break out of the testing container. In order to test this content, make sure to use the `screen` export to query the contents: ```jsx tab title="Toast.test.jsx" -import { test, expect } from "vitest" -import { render, screen } from "@solidjs/testing-library" -import { Toast } from "./Toast" +import { test, expect } from "vitest"; +import { render, screen } from "@solidjs/testing-library"; +import { Toast } from "./Toast"; test("increments value", async () => { - render(() => <Toast><p>This is a toast</p></Toast>) - const toast = screen.getByRole("log") - expect(toast).toHaveTextContent("This is a toast") -}) + render(() => ( + <Toast> + <p>This is a toast</p> + </Toast> + )); + const toast = screen.getByRole("log"); + expect(toast).toHaveTextContent("This is a toast"); +}); ``` ```jsx tab title="Toast.jsx" import { Portal } from "solid-js/web"; export const Toast = (props) => { - return ( - <Portal> - <div class="toast" role={props.role ?? "log"}> - {props.children} - </div> - </Portal> - ); -} + return ( + <Portal> + <div class="toast" role={props.role ?? "log"}> + {props.children} + </div> + </Portal> + ); +}; ``` #### Testing in context @@ -241,15 +254,15 @@ export const Toast = (props) => { If a component relies on some context, to wrap it use the `wrapper` option: ```tsx title="Context.test.tsx" -import { test, expect } from "vitest" -import { render } from "@solidjs/testing-library" -import { DataContext, DataConsumer } from "./Data" +import { test, expect } from "vitest"; +import { render } from "@solidjs/testing-library"; +import { DataContext, DataConsumer } from "./Data"; -const wrapper = (props) => <DataContext value="test" {...props} /> +const wrapper = (props) => <DataContext value="test" {...props} />; test("receives data from context", () => { - const { getByText } = render(() => <DataConsumer />, { wrapper }) - expect(getByText("test")).toBeInTheDocument() + const { getByText } = render(() => <DataConsumer />, { wrapper }); + expect(getByText("test")).toBeInTheDocument(); }); ``` @@ -257,8 +270,9 @@ Wrappers can be re-used if they are created externally. For wrappers with different values, a higher-order component creating the required wrappers can make the tests more concise: ```tsx -const createWrapper = (value) => (props) => - <DataContext value={value} {...props}/> +const createWrapper = (value) => (props) => ( + <DataContext value={value} {...props} /> +); ``` :::note[Using multiple providers] @@ -272,10 +286,10 @@ Since the `<Router>` component is lazily loaded, the first query after rendering ```tsx const { findByText } = render( - () => <Route path="/article/:id" component={Article} />, - { location: "/article/12345" } + () => <Route path="/article/:id" component={Article} />, + { location: "/article/12345" } ); -expect(await findByText("Article 12345")).toBeInTheDocument() +expect(await findByText("Article 12345")).toBeInTheDocument(); ``` #### Interacting with components @@ -289,7 +303,6 @@ For example, this means that a `click` event from the user would be accompanied The most convenient events to test are typically `click`, `keyboard` and `pointer` (to simulate touch events). To dive deeper into these events, you can learn about them in the [`user-event` documentation](https://testing-library.com/docs/user-event/intro). - ##### Using timers If you require a fake timer and want to use `vi.useFakeTimers()` in your tests, it must set it up with an `advanceTimers` option: @@ -325,7 +338,7 @@ describe("pre-login: sign-in", () => { `vitest` comes with the `expect` function to facilitate assertions that works like: ```tsx frame="none" -expect(subject)[assertion](value) +expect(subject)[assertion](value); ``` The command supports assertions like `toBe` (reference comparison) and `toEqual` (value comparison) out of the box. @@ -338,25 +351,23 @@ For testing inside the DOM, the package `@testing-library/jest-dom` augments it - [`.toHaveAccessibleDescription(description)`](https://github.com/testing-library/jest-dom?tab=readme-ov-file#tohaveaccessibledescription) - checks accessible description - and a [lot more](https://github.com/testing-library/jest-dom?tab=readme-ov-file#custom-matchers). - ### Directive testing [Directives](/reference/jsx-attributes/use) are reusable behaviors for elements. They receive the HTML element they are bound to as their first and an accessor of the directive prop as their second argument. To make testing them more concise, [`@solidjs/testing-library` has a `renderDirective`](https://testing-library.com/docs/solid-testing-library/api#renderdirective) function: - ```ts frame="none" const renderResult = renderDirective(directive, { - initialValue, // value initially added to the argument signal - targetElement, // opt. node name or element used as target for the directive - ...renderOptions, // see render options -}) + initialValue, // value initially added to the argument signal + targetElement, // opt. node name or element used as target for the directive + ...renderOptions, // see render options +}); const { - arg, // getter for the directive's argument - setArg, // setter for the directive's argument - ...renderResults, // see render results -} = renderResult + arg, // getter for the directive's argument + setArg, // setter for the directive's argument + ...renderResults // see render results +} = renderResult; ``` In `...renderResults`, the container will contain the `targetElement`, which defaults to a `<div>`. @@ -365,31 +376,31 @@ This, along with the ability to modify the `arg` signal, are helpful when testin If, for example, you have a directive that handles the [Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API), you can test it like this: ```ts tab title="fullscreen.test.ts" -import { test, expect, vi } from "vitest" -import { renderDirective } from "@solidjs/testing-library" -import { createFullScreen } from "./fullscreen" +import { test, expect, vi } from "vitest"; +import { renderDirective } from "@solidjs/testing-library"; +import { createFullScreen } from "./fullscreen"; test("toggles fullscreen", () => { - const targetElement = document.createElement("div") - const fs = vi.spyOn(targetElement, "fullscreen") - const [setArg, container] = renderDirective(createFullScreen, false) - setArg(true) - expect(fs).toHaveBeenCalled() -}) + const targetElement = document.createElement("div"); + const fs = vi.spyOn(targetElement, "fullscreen"); + const [setArg, container] = renderDirective(createFullScreen, false); + setArg(true); + expect(fs).toHaveBeenCalled(); +}); ``` ```ts tab title="fullscreen.ts" -import { Accessor } from "solid-js" +import { Accessor } from "solid-js"; export const fullscreen = (ref: HTMLElement, active: Accessor<boolean>) => - createEffect(() => { - const isActive = document.fullscreenElement === ref - if (active() && !isActive) { - ref.requestFullScreen().catch(() => {}) - } else if (!active() && isActive) { - document.exitFullScreen() - } - }) + createEffect(() => { + const isActive = document.fullscreenElement === ref; + if (active() && !isActive) { + ref.requestFullScreen().catch(() => {}); + } else if (!active() && isActive) { + document.exitFullScreen(); + } + }); ``` ### Primitive testing @@ -400,32 +411,31 @@ To avoid this, there is a [`renderHook` utility](https://testing-library.com/doc ```ts frame="none" const renderResult = renderHook(hook, { - initialProps, // an array with arguments being supplied to the hook - wrapper, // same as the wrapper optionss for `render` -}) + initialProps, // an array with arguments being supplied to the hook + wrapper, // same as the wrapper optionss for `render` +}); const { - result, // return value of the hook (mutable, destructuring fixes it) - cleanup, // manually remove the traces of the test from the DOM - owner, // the owner running the hook to use with `runWithOwner()` -} = renderResult + result, // return value of the hook (mutable, destructuring fixes it) + cleanup, // manually remove the traces of the test from the DOM + owner, // the owner running the hook to use with `runWithOwner()` +} = renderResult; ``` A primitive that manages the state of a counter could be tested like this: ```ts frame="none" -import { test, expect } from "vitest" -import { renderHook } from "@solidjs/testing-library" -import { createCounter } from "./counter" +import { test, expect } from "vitest"; +import { renderHook } from "@solidjs/testing-library"; +import { createCounter } from "./counter"; test("increments count", () => { - const { result } = renderHook(createCounter) - expect(result.count).toBe(0) - result.increment() - expect(result.count).toBe(1) -}) + const { result } = renderHook(createCounter); + expect(result.count).toBe(0); + result.increment(); + expect(result.count).toBe(1); +}); ``` - ### Testing effects Since effects may happen asynchronously, it can be difficult to test them. @@ -436,19 +446,19 @@ Any errors that would hit the next boundary are used to reject the returned prom An example test using `testEffect` may look like this: ```ts frame="none" -const [value, setValue] = createSignal(0) -return testEffect(done => - createEffect((run: number = 0) => { - if (run === 0) { - expect(value()).toBe(0) - setValue(1) - } else if (run === 1) { - expect(value()).toBe(1) - done() - } - return run + 1 - }) -) +const [value, setValue] = createSignal(0); +return testEffect((done) => + createEffect((run: number = 0) => { + if (run === 0) { + expect(value()).toBe(0); + setValue(1); + } else if (run === 1) { + expect(value()).toBe(1); + done(); + } + return run + 1; + }) +); ``` ### Benchmarks @@ -457,40 +467,51 @@ While Solid offers performance simplified, it is good to validate if that promis Vitest offers an experimental `bench` function to run benchmarks and compare the results inside the same `describe` block; for example if you had a `<List>` flow component similar to `<For>`, you could benchmark it like this: - ```jsx title="list.bench.jsx" -describe('list rendering', () => { - const ITEMS = 1000 - const renderedFor = new Set() - const listFor = Array.from({ length: ITEMS }, (_, i) => i) - bench('For', () => new Promise((resolve) => { - const ItemFor = (props) => { - onMount(() => { - renderedFor.add(props.number) - if (renderedFor.size === ITEMS) { resolve() } - }) - return <span>{props.number}</span> - } - render(() => <For each={listFor}> - {(item) => <ItemFor number={item} />} - </For>) - })) - - const renderedList = new Set() - const listList = Array.from({ length: ITEMS }, (_, i) => i) - bench('List', () => new Promise((resolve) => { - const ItemList = (props) => { - onMount(() => { - renderedList.add(props.number) - if (renderedList.size === ITEMS) { resolve() } - }) - return <span>{props.number}</span> - } - render(() => <List each={listList}> - {(item) => <ItemList number={item} />} - </List>) - })) -}) +describe("list rendering", () => { + const ITEMS = 1000; + const renderedFor = new Set(); + const listFor = Array.from({ length: ITEMS }, (_, i) => i); + bench( + "For", + () => + new Promise((resolve) => { + const ItemFor = (props) => { + onMount(() => { + renderedFor.add(props.number); + if (renderedFor.size === ITEMS) { + resolve(); + } + }); + return <span>{props.number}</span>; + }; + render(() => ( + <For each={listFor}>{(item) => <ItemFor number={item} />}</For> + )); + }) + ); + + const renderedList = new Set(); + const listList = Array.from({ length: ITEMS }, (_, i) => i); + bench( + "List", + () => + new Promise((resolve) => { + const ItemList = (props) => { + onMount(() => { + renderedList.add(props.number); + if (renderedList.size === ITEMS) { + resolve(); + } + }); + return <span>{props.number}</span>; + }; + render(() => ( + <List each={listList}>{(item) => <ItemList number={item} />}</List> + )); + }) + ); +}); ``` Running `[npm|pnpm|yarn] test bench` will then execute the benchmark function: @@ -513,7 +534,6 @@ Running `[npm|pnpm|yarn] test bench` will then execute the benchmark function: Please keep in mind that it is very difficult to create meaningful benchmarks. The numbers should always be taken with a grain of salt, but can still indicate performance degradations if compared between versions. - ### Test coverage While coverage numbers can be misleading, they are used by many projects as a rough measurement of code quality. @@ -525,7 +545,6 @@ Vitest supports coverage collection. To use it, it needs an extra package: Also, you need to [set up vitest's coverage feature](https://vitest.dev/guide/coverage.html). - ### Integration/E2E testing Some issues can only be found once the code is running in the environment it is supposed to run in. diff --git a/src/routes/index.mdx b/src/routes/index.mdx index bc137a50e..57da3f848 100644 --- a/src/routes/index.mdx +++ b/src/routes/index.mdx @@ -1,6 +1,21 @@ --- -title: Overview +title: Solid Docs +nav_title: Overview +titleTemplate: ":title" mainNavExclude: true +use_cases: >- + getting started, learning solid, understanding framework, first project, + introduction +tags: + - introduction + - overview + - getting-started + - basics + - framework +version: "1.0" +description: >- + Solid is a reactive JavaScript framework for building fast, efficient UIs. + Learn about fine-grained reactivity and modern web development. --- # Overview @@ -36,7 +51,7 @@ This combination of features makes it a great choice to build responsive and hig ## Quick links -<div class="flex flex-col md:grid md:grid-cols-2 md:grid-rows-2 gap-3"> +<div class="flex flex-col gap-3 md:grid md:grid-cols-2 md:grid-rows-2"> <QuickLinks title="Tutorial" href="https://www.solidjs.com/tutorial/introduction_basics" diff --git a/src/routes/pt-br/index.mdx b/src/routes/pt-br/index.mdx deleted file mode 100644 index 04694517e..000000000 --- a/src/routes/pt-br/index.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Sumário -mainNavExclude: true ---- - -# Sumário - -Solid is a modern JavaScript framework designed to build responsive and high-performing user interfaces (UI). -It prioritizes a simple and predictable development 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. - -Reactivity, in programming, refers to an applications' ability to respond to changes in data or user interactions. - -Traditionally, when a change occurs, the entire web page would need to reload to display the updated information. -In contrast, when using a fine-grained reactive system, updates are only applied to the parts of the page that need to be updated. - -Solid adopts the concept of fine-grained reactivity, updating only when the data the application depends on changes. -This decreases work and can result in faster load times and a smoother user experience overall. - -## Advantages of using Solid - -- **Performant**: Fine-grained reactivity allows Solid to update only what has changed, resulting in faster load times and smoother performance overall. - -- **Powerful**: Using less memory and processing power, Solid is capable of creating complex applications without compromising on functionality. - This also gives developers the flexibility over how and when updates happen. - -- **Pragmatic**: Rather than sticking to rigid structures or methods, Solid provides the freedom to choose the strategies and practices that work best for you. - -- **Productive**: Regardless of experience level, Solid's clear and predictable API makes developers' work simpler and more efficient. - -Solid aims to strike a balance between speed, efficiency, power, and flexibility, all while providing a developer-friendly environment. -This combination of features makes it a great choice to build responsive and high-performing UIs. - -## Quick links - -<div class="flex flex-col md:grid md:grid-cols-2 md:grid-rows-2 gap-3"> - <QuickLinks - title="Tutorial" - href="https://www.solidjs.com/tutorial/introduction_basics" - icon="learn" - > - Learn the basics of Solid through this interactive tutorial. - </QuickLinks> - <QuickLinks - title="Templates" - href="https://github.com/solidjs/templates" - icon="template" - > - Start your first project with a template that fits your needs. - </QuickLinks> - <QuickLinks - title="Ecosystem" - href="https://www.solidjs.com/ecosystem" - icon="community" - > - Explore the Solid ecosystem and find useful tools and libraries. - </QuickLinks> - <QuickLinks - title="Contribute" - href="https://github.com/solidjs/solid-docs-next" - icon="learn" - > - Help improve Solid by contributing to the documentation. - </QuickLinks> -</div> - -_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! - -<EditPageLink /> -<PageIssueLink /> diff --git a/src/routes/pt-br/quick-start.mdx b/src/routes/pt-br/quick-start.mdx deleted file mode 100644 index 17eaf23fe..000000000 --- a/src/routes/pt-br/quick-start.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Começo rápido ---- - -## Solid playgrounds - -Experimente Solid in your browser by visiting our [interactive playground](https://playground.solidjs.com/). - -Additionally, we offer a [JavaScript](https://stackblitz.com/github/solidjs/templates/tree/master/js) and [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) Stackblitz starters, which provide a web-based development environment to get you started. - -## Creating a Solid application - -:::note[Prerequisites] - - - Familiarity with the command line - - Install [Node.js](https://nodejs.org/en) - -::: - -Solid offers convenient project templates that can help kickstart your development. -To get an application running, follow the steps below based on the language you prefer to use. - -### For JavaScript projects - -1. Run the following command in your terminal to get the JavaScript starter template: - -```bash frame="none" -npx degit solidjs/templates/js my-app -``` - -2. Navigate to your application's directory: - -```bash frame="none" -cd my-app -``` - -3. Install the necessary dependencies: - -```package-install-local -``` - -4. Run the application: - -```bash frame="none" -npm run dev -``` - -This will start the development server. -Now, you can open your browser and navigate to `localhost:3000` to see your application running. - -### For TypeScript projects - -1. To use a TypeScript template, run the following command in your terminal: - -```bash frame="none" -npx degit solidjs/templates/ts my-app -``` - -2. Navigate to your application's directory: - -```bash frame="none" -cd my-app -``` - -3. Install the necessary dependencies: - -```package-install-local -``` - -4. Run the application: - -```bash frame="none" -npm run dev -``` - -This will start the development server. -Now, you can open your browser and navigate to `localhost:3000` to see your application running. - -### Explore more templates - -Solid offers a variety of Vite templates to streamline your development process. -These resources are available on [GitHub](https://github.com/solidjs/templates). diff --git a/src/routes/pt-br/solid-router/index.mdx b/src/routes/pt-br/solid-router/index.mdx deleted file mode 100644 index 52656a5ab..000000000 --- a/src/routes/pt-br/solid-router/index.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Sumário -mainNavExclude: true ---- - -# Roteador - -Solid is a modern JavaScript framework designed to build responsive and high-performing user interfaces (UI). -It prioritizes a simple and predictable development 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. - -Reactivity, in programming, refers to an applications' ability to respond to changes in data or user interactions. - -Traditionally, when a change occurs, the entire web page would need to reload to display the updated information. -In contrast, when using a fine-grained reactive system, updates are only applied to the parts of the page that need to be updated. - -Solid adopts the concept of fine-grained reactivity, updating only when the data the application depends on changes. -This decreases work and can result in faster load times and a smoother user experience overall. - -## Advantages of using Solid - -- **Performant**: Fine-grained reactivity allows Solid to update only what has changed, resulting in faster load times and smoother performance overall. - -- **Powerful**: Using less memory and processing power, Solid is capable of creating complex applications without compromising on functionality. - This also gives developers the flexibility over how and when updates happen. - -- **Pragmatic**: Rather than sticking to rigid structures or methods, Solid provides the freedom to choose the strategies and practices that work best for you. - -- **Productive**: Regardless of experience level, Solid's clear and predictable API makes developers' work simpler and more efficient. - -Solid aims to strike a balance between speed, efficiency, power, and flexibility, all while providing a developer-friendly environment. -This combination of features makes it a great choice to build responsive and high-performing UIs. - -## Quick links - -<div class="flex flex-col md:grid md:grid-cols-2 md:grid-rows-2 gap-3"> - <QuickLinks - title="Tutorial" - href="https://www.solidjs.com/tutorial/introduction_basics" - icon="learn" - > - Learn the basics of Solid through this interactive tutorial. - </QuickLinks> - <QuickLinks - title="Templates" - href="https://github.com/solidjs/templates" - icon="template" - > - Start your first project with a template that fits your needs. - </QuickLinks> - <QuickLinks - title="Ecosystem" - href="https://www.solidjs.com/ecosystem" - icon="community" - > - Explore the Solid ecosystem and find useful tools and libraries. - </QuickLinks> - <QuickLinks - title="Contribute" - href="https://github.com/solidjs/solid-docs-next" - icon="learn" - > - Help improve Solid by contributing to the documentation. - </QuickLinks> -</div> - -_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! - -<EditPageLink /> -<PageIssueLink /> diff --git a/src/routes/pt-br/solid-router/quick-start.mdx b/src/routes/pt-br/solid-router/quick-start.mdx deleted file mode 100644 index 17eaf23fe..000000000 --- a/src/routes/pt-br/solid-router/quick-start.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Começo rápido ---- - -## Solid playgrounds - -Experimente Solid in your browser by visiting our [interactive playground](https://playground.solidjs.com/). - -Additionally, we offer a [JavaScript](https://stackblitz.com/github/solidjs/templates/tree/master/js) and [TypeScript](https://stackblitz.com/github/solidjs/templates/tree/master/ts) Stackblitz starters, which provide a web-based development environment to get you started. - -## Creating a Solid application - -:::note[Prerequisites] - - - Familiarity with the command line - - Install [Node.js](https://nodejs.org/en) - -::: - -Solid offers convenient project templates that can help kickstart your development. -To get an application running, follow the steps below based on the language you prefer to use. - -### For JavaScript projects - -1. Run the following command in your terminal to get the JavaScript starter template: - -```bash frame="none" -npx degit solidjs/templates/js my-app -``` - -2. Navigate to your application's directory: - -```bash frame="none" -cd my-app -``` - -3. Install the necessary dependencies: - -```package-install-local -``` - -4. Run the application: - -```bash frame="none" -npm run dev -``` - -This will start the development server. -Now, you can open your browser and navigate to `localhost:3000` to see your application running. - -### For TypeScript projects - -1. To use a TypeScript template, run the following command in your terminal: - -```bash frame="none" -npx degit solidjs/templates/ts my-app -``` - -2. Navigate to your application's directory: - -```bash frame="none" -cd my-app -``` - -3. Install the necessary dependencies: - -```package-install-local -``` - -4. Run the application: - -```bash frame="none" -npm run dev -``` - -This will start the development server. -Now, you can open your browser and navigate to `localhost:3000` to see your application running. - -### Explore more templates - -Solid offers a variety of Vite templates to streamline your development process. -These resources are available on [GitHub](https://github.com/solidjs/templates). diff --git a/src/routes/quick-start.mdx b/src/routes/quick-start.mdx index c04a9c7b5..33df4c74d 100644 --- a/src/routes/quick-start.mdx +++ b/src/routes/quick-start.mdx @@ -1,5 +1,18 @@ --- title: Quick start +use_cases: >- + starting new project, project setup, first app, development environment, + templates +tags: + - quickstart + - setup + - templates + - getting-started + - playground +version: "1.0" +description: >- + Start building with Solid quickly. Try the playground, create projects with + templates, and get your first Solid app running in minutes. --- ## Try Solid online diff --git a/src/routes/reference/basic-reactivity/create-effect.mdx b/src/routes/reference/basic-reactivity/create-effect.mdx index d93501967..84ee13f12 100644 --- a/src/routes/reference/basic-reactivity/create-effect.mdx +++ b/src/routes/reference/basic-reactivity/create-effect.mdx @@ -1,104 +1,174 @@ --- title: createEffect +use_cases: >- + dom manipulation, side effects, manual dom updates, vanilla js integration, + cleanup operations, logging changes +tags: + - effects + - dom + - side-effects + - reactivity + - lifecycle + - cleanup +version: "1.0" +description: >- + Learn how to use createEffect to run side effects when reactive dependencies + change. Perfect for DOM manipulation and external library integration. --- -```tsx -import { createEffect } from "solid-js" +The `createEffect` primitive creates a reactive computation. +It automatically tracks reactive values, such as [signals](/concepts/signals), accessed within the provided function. +This function will re-run whenever any of its dependencies change. -function createEffect<T>(fn: (v: T) => T, value?: T): void +## Execution Timing -``` +### Initial Run -Effects are a general way to make arbitrary code ("side effects") run whenever dependencies change, e.g., to modify the DOM manually. -`createEffect` creates a new computation that runs the given function in a tracking scope, thus automatically tracking its dependencies, and automatically reruns the function whenever the dependencies update. +- The initial run of effects is **scheduled to occur after the current rendering phase completes**. +- It runs after all synchronous code in a component has finished and DOM elements have been created, but **before the browser paints them on the screen**. +- **[Refs](/concepts/refs) are set** before the first run, even though DOM nodes may not yet be attached to the main document tree. + This is relevant when using the [`children`](/reference/component-apis/children) helper. -For example: +### Subsequent Runs -```tsx -const [a, setA] = createSignal(initialValue) +- After the initial run, the effect **re-runs whenever any tracked dependency changes**. +- When multiple dependencies change within the same batch, the effect **runs once per batch**. +- The **order of runs** among multiple effects is **not guaranteed**. +- Effects always run **after** all pure computations (such as [memos](/concepts/derived-values/memos)) within the same update cycle. -// effect that depends on signal `a` -createEffect(() => doSideEffect(a())) -``` +### Server-Side Rendering -The effect will run whenever `a` changes value. +- Effects **never run during SSR**. +- Effects also **do not run during the initial client hydration**. -The effect will also run once, immediately after it is created, to initialize the DOM to the correct state. This is called the "mounting" phase. -However, we recommend using `onMount` instead, which is a more explicit way to express this. +## Import -The effect callback can return a value, which will be passed as the `prev` argument to the next invocation of the effect. -This is useful for memoizing values that are expensive to compute. For example: +```ts +import { createEffect } from "solid-js"; +``` -```tsx -const [a, setA] = createSignal(initialValue) - -// effect that depends on signal `a` -createEffect((prevSum) => { - // do something with `a` and `prevSum` - const sum = a() + b() - if (sum !== prevSum) console.log("sum changed to", sum) - return sum -}, 0) -// ^ the initial value of the effect is 0 +## Type + +```ts +function createEffect<Next>( + fn: EffectFunction<undefined | NoInfer<Next>, Next> +): void; +function createEffect<Next, Init = Next>( + fn: EffectFunction<Init | Next, Next>, + value: Init, + options?: { name?: string } +): void; +function createEffect<Next, Init>( + fn: EffectFunction<Init | Next, Next>, + value?: Init, + options?: { name?: string } +): void; ``` -Effects are meant primarily for side effects that read but don't write to the reactive system: it's best to avoid setting signals in effects, which without care can cause additional rendering or even infinite effect loops. Instead, prefer using [createMemo](/reference/basic-reactivity/create-memo) to compute new values that depend on other reactive values, so the reactive system knows what depends on what, and can optimize accordingly. -If you do end up setting a signal within an effect, computations subscribed to that signal will be executed only once the effect completes; see [`batch`](/reference/reactive-utilities/batch) for more detail. +## Parameters -The first execution of the effect function is not immediate; it's scheduled to run after the current rendering phase (e.g., after calling the function passed to [render](/reference/rendering/render), [createRoot](/reference/reactive-utilities/create-root), or [runWithOwner](/reference/reactive-utilities/run-with-owner)). -If you want to wait for the first execution to occur, use [queueMicrotask](https://developer.mozilla.org/en-US/docs/Web/API/queueMicrotask) (which runs before the browser renders the DOM) or `await Promise.resolve()` or `setTimeout(..., 0)` (which runs after browser rendering). +### `fn` -```tsx -// assume this code is in a component function, so is part of a rendering phase -const [count, setCount] = createSignal(0) - -// this effect prints count at the beginning and when it changes -createEffect(() => console.log("count =", count())) -// effect won't run yet -console.log("hello") -setCount(1) // effect still won't run yet -setCount(2) // effect still won't run yet - -queueMicrotask(() => { - // now `count = 2` will print - console.log("microtask") - setCount(3) // immediately prints `count = 3` - console.log("goodbye") -}) - -// --- overall output: --- -// hello -// count = 2 -// microtask -// count = 3 -// goodbye -``` +- **Type:** `EffectFunction<undefined | NoInfer<Next> | EffectFunction<Init | Next, Next>` +- **Required:** Yes + +A function to be executed as the effect. + +It receives the value returned from the previous run, or the initial `value` during the first run. +The value returned by `fn` is passed to the next run. + +### `value` + +- **Type:** `Init` +- **Required:** No -This delay in first execution is useful because it means an effect defined in a component scope runs after the JSX returned by the component gets added to the DOM. -In particular, [refs](/reference/jsx-attributes/ref) will already be set. -Thus you can use an effect to manipulate the DOM manually, call vanilla JS libraries, or other side effects. +The initial value passed to `fn` during its first run. -Note that the first run of the effect still runs before the browser renders the DOM to the screen (similar to React's `useLayoutEffect`). -If you need to wait until after rendering (e.g., to measure the rendering), you can use `await Promise.resolve()` (or `Promise.resolve().then(...)`), but note that subsequent use of reactive state (such as signals) will not trigger the effect to rerun, as tracking is not possible after an async function uses `await`. -Thus you should use all dependencies before the promise. +### `options` -If you'd rather an effect run immediately even for its first run, use [createRenderEffect](/reference/secondary-primitives/create-render-effect) or [createComputed](/reference/secondary-primitives/create-computed). +- **Type:** `{ name?: string }` +- **Required:** No + +An optional configuration object with the following properties: + +#### `name` + +- **Type:** `string` +- **Required:** No + +A name for the effect, which can be useful for identification in debugging tools like the [Solid Debugger](https://github.com/thetarnav/solid-devtools). + +## Return value + +`createEffect` does not return a value. + +## Examples + +### Basic Usage + +```tsx +import { createSignal, createEffect } from "solid-js"; + +function Counter() { + const [count, setCount] = createSignal(0); + + // Every time count changes, this effect re-runs. + createEffect(() => { + console.log("Count incremented! New value: ", count()); + }); + + return ( + <div> + <p>Count: {count()}</p> + <button onClick={() => setCount((prev) => prev + 1)}>Increment</button> + </div> + ); +} +``` -You can clean up your side effects in between executions of the effect function by calling [onCleanup](/reference/lifecycle/on-cleanup) inside the effect function. -Such a cleanup function gets called both in between effect executions and when the effect gets disposed (e.g., the containing component unmounts). -For example: +### Execution Timing ```tsx -// listen to event dynamically given by eventName signal -createEffect(() => { - const event = eventName() - const callback = (e) => console.log(e) - ref.addEventListener(event, callback) - onCleanup(() => ref.removeEventListener(event, callback)) -}) +import { createSignal, createEffect, createRenderEffect } from "solid-js"; + +function Counter() { + const [count, setCount] = createSignal(0); + + // This is part of the component's synchronous execution. + console.log("Hello from counter"); + + // This effect is scheduled to run after the initial render is complete. + createEffect(() => { + console.log("Effect:", count()); + }); + + // By contrast, a render effect runs synchronously during the render phase. + createRenderEffect(() => { + console.log("Render effect:", count()); + }); + + // Setting a signal during the render phase re-runs render effects, but not effects, which are + // still scheduled. + setCount(1); + + // A microtask is scheduled to run after the current synchronous code (the render phase) finishes. + queueMicrotask(() => { + // Now that rendering is complete, signal updates will trigger effects immediately. + setCount(2); + }); +} + +// Output: +// Hello from counter +// Render effect: 0 +// Render effect: 1 +// Effect: 1 +// Render effect: 2 +// Effect: 2 ``` -## Arguments +## Related -- `fn` - The function to run in a tracking scope. It can return a value, which will be passed as the `prev` argument to the next invocation of the effect. -- `value` - The initial value of the effect. This is useful for memoizing values that are expensive to compute. +- [`createRenderEffect`](/reference/secondary-primitives/create-render-effect) +- [`onCleanup`](/reference/lifecycle/on-cleanup) +- [`onMount`](/reference/lifecycle/on-mount) diff --git a/src/routes/reference/basic-reactivity/create-memo.mdx b/src/routes/reference/basic-reactivity/create-memo.mdx index 58f21b140..5a6836155 100644 --- a/src/routes/reference/basic-reactivity/create-memo.mdx +++ b/src/routes/reference/basic-reactivity/create-memo.mdx @@ -1,72 +1,217 @@ --- title: createMemo +use_cases: >- + expensive computations, derived values, performance optimization, caching + calculations, preventing duplicate work +tags: + - memoization + - performance + - optimization + - derived-state + - caching + - reactivity +version: "1.0" +description: >- + Use createMemo to efficiently compute and cache derived values. Prevent + expensive recalculations and optimize your Solid.js application's performance. --- -Memos let you efficiently use a derived value in many reactive computations. -`createMemo` creates a readonly reactive value equal to the return value of the given function and makes sure that function only gets executed when its dependencies change. +The `createMemo` function creates a read-only signal that derives its value from other reactive values. +The calculated value is memoized: the calculation runs only when dependencies change, and is reused when the value is read. +When a dependency changes, the calculation re-executes. +If the new result is equal to the previous result (according to the [`equals`](#equals) option), the memo suppresses downstream updates. -```tsx -import { createMemo } from "solid-js" +## Import + +```ts +import { createMemo } from "solid-js"; +``` + +## Type +```ts function createMemo<T>( fn: (v: T) => T, value?: T, - options?: { equals?: false | ((prev: T, next: T) => boolean) } -): () => T - + options?: { equals?: false | ((prev: T, next: T) => boolean); name?: string } +): () => T; ``` -Here's an example of how createMemo can be used: +## Parameters -```ts -const value = createMemo(() => computeExpensiveValue(a(), b())) +### `fn` -//read the value -value() -``` +- **Type:** `(v: T) => T` +- **Required:** Yes -In Solid, you often don't need to wrap functions in memos; you can alternatively just define and call a regular function to get similar reactive behavior. -The main difference is when you call the function in multiple reactive settings. -In this case, when the function's dependencies update, the function will get called multiple times unless it is wrapped in createMemo. -For example: +The function that calculates the memo's value. -```tsx -const user = createMemo(() => searchForUser(username())) -// compare with: const user = () => searchForUser(username()); -return ( - <ul> - <li>Your name is {user()?.name}</li> - <li> - Your email is <code>{user()?.email}</code> - </li> - </ul> -) -``` +It receives the value returned from the previous execution as its argument. +On the first execution, it receives the `value` parameter (if provided) or `undefined`. + +This function should be pure (it should not modify other reactive values). + +### `value` + +- **Type:** `T` +- **Required:** No + +The initial value passed to `fn` on its first execution. + +### `options` + +- **Type:** `{ equals?: false | ((prev: T, next: T) => boolean); name?: string }` +- **Required:** No -When the username signal updates, searchForUser will get called just once. -If the returned user actually changed, the user memo updates, and then both list items will update automatically. +An optional configuration object with the following properties: -If we had instead defined user as a plain function `() => searchForUser(username())`, then `searchForUser` would have been called twice, once when updating each list item. +#### `equals` -Another key difference is that a memo can shield dependents from updating when the memo's dependencies change but the resulting memo value doesn't. -Like [createSignal](/reference/basic-reactivity/create-signal), the derived signal made by `createMemo` updates (and triggers dependents to rerun) only when the value returned by the memo function actually changes from the previous value, according to JavaScript's `===` operator. -Alternatively, you can pass an options object with `equals` set to false to always update the memo when its dependencies change, or you can pass your own `equals` function for testing equality. +- **Type:** `false | ((prev: T, next: T) => boolean)` +- **Required:** No -The memo function is called with an argument equal to the value returned from the previous execution of the memo function, or, on the first call, equal to the optional second argument to `createMemo`. -This is useful for reducing computations, such as: +A function that runs after each execution of `fn` to determine if the memo value has changed. +It receives the previous and the new value. +If it returns `true`, the values are considered equal and the memo does not trigger downstream updates. + +If set to `false` (instead of a function), the memo triggers updates whenever it re-executes, even if the value is unchanged. + +Defaults to a function that compares values using strict equality (`===`). + +#### `name` + +- **Type:** `string` +- **Required:** No + +A debug name for the memo. +It is used for identification in debugging tools like the [Solid Debugger](https://github.com/thetarnav/solid-devtools). + +## Return value + +- **Type:** `() => T` + +`createMemo` returns a read-only accessor function. +Calling this function returns the current memoized value. + +## Examples + +### Basic usage + +```tsx +import { createSignal, createMemo, For } from "solid-js"; + +const NAMES = ["Alice Smith", "Bob Jones", "Charlie Day", "David Lee"]; + +function FilterList() { + const [query, setQuery] = createSignal(""); + + // The function executes immediately to calculate the initial value. + // It re-executes only when the `query` signal changes. + const filteredNames = createMemo(() => { + console.log("Calculating list..."); + return NAMES.filter((name) => { + return name.toLowerCase().includes(query().toLowerCase()); + }); + }); + + return ( + <div> + <input + value={query()} + onInput={(e) => setQuery(e.currentTarget.value)} + placeholder="Search..." + /> + + {/* Accessing the memo. If dependencies haven't changed, returns cached value. */} + <div>Count: {filteredNames().length}</div> + + <ul> + {/* Accessing the memo again does not trigger re-execution. */} + <For each={filteredNames()}>{(name) => <li>{name}</li>}</For> + </ul> + </div> + ); +} +``` + +### Custom equality check ```tsx -// track the sum of all values taken on by input() as it updates -const sum = createMemo((prev) => input() + prev, 0) +import { createSignal, createMemo, createEffect } from "solid-js"; + +function DateNormalizer() { + const [dateString, setDateString] = createSignal("2024-05-10"); + + const dateObject = createMemo( + () => { + return new Date(dateString()); + }, + undefined, + { + // Overrides the default strict equality check (===). + // If this returns true, observers (like the Effect below) are NOT notified. + equals: (prev, next) => { + return prev.getTime() === next.getTime(); + }, + } + ); + + createEffect(() => { + // This effect runs only when the numeric time value changes, + // ignoring new Date object references. + console.log("Date changed to:", dateObject().toISOString()); + }); + + return ( + <div> + <input + value={dateString()} + onInput={(e) => setDateString(e.currentTarget.value)} + /> + {/* Setting the same date string creates a new Date object, + but `equals` prevents the update propagation. */} + <button onClick={() => setDateString("2024-05-10")}> + Reset to the same date + </button> + </div> + ); +} ``` -The memo function should not change other signals by calling setters (it should be "pure"). -This enables Solid to optimize the execution order of memo updates according to their dependency graph, so that all memos can update at most once in response to a dependency change. +### Accessing previous value + +```tsx +import { createSignal, createMemo } from "solid-js"; + +function TrendTracker() { + const [count, setCount] = createSignal(0); + + const trend = createMemo( + // The first argument `prev` is the return value of the previous execution. + (prev) => { + const current = count(); + if (current === prev.value) return { value: current, label: "Same" }; + return { + value: current, + label: current > prev.value ? "Up" : "Down", + }; + }, + // The second argument provides the initial value for `prev`. + { value: 0, label: "Same" } + ); + + return ( + <div> + <div>Current: {trend().value}</div> + <div>Direction: {trend().label}</div> + + <button onClick={() => setCount((c) => c + 1)}>Increment</button> + <button onClick={() => setCount((c) => c - 1)}>Decrement</button> + </div> + ); +} +``` -## Options and arguments +## Related -| Name | Type | Description | -| :------ | :------------------------------------------------------ | :------------------------------------------------------------- | -| fn | `(v: T) => T` | The function to memoize. | -| value | `T` | The initial value of the memo. | -| options | `{ equals?: false \| ((prev: T, next: T) => boolean) }` | An optional object with an `equals` function to test equality. | +- [`createComputed`](/reference/secondary-primitives/create-computed) diff --git a/src/routes/reference/basic-reactivity/create-resource.mdx b/src/routes/reference/basic-reactivity/create-resource.mdx index c53db92e3..1b293cf4e 100644 --- a/src/routes/reference/basic-reactivity/create-resource.mdx +++ b/src/routes/reference/basic-reactivity/create-resource.mdx @@ -1,207 +1,271 @@ --- title: createResource +use_cases: >- + data fetching, api calls, async operations, loading states, error handling, + server data, suspense boundaries +tags: + - async + - fetching + - api + - suspense + - loading + - error-handling + - ssr +version: "1.0" +description: >- + Fetch async data with createResource. Handles loading states, errors, and + integrates with Suspense for seamless data fetching in Solid.js applications. --- -`createResource` takes an asynchronous fetcher function and returns a signal that is updated with the resulting data when the fetcher completes. +Creates a reactive resource that manages asynchronous data fetching and loading states, automatically tracking dependencies and providing a simple interface for reading, refreshing, and error handling. +It integrates with Solid's reactivity system and Suspense boundaries. -There are two ways to use `createResource`: you can pass the fetcher function as the sole argument, or you can additionally pass a source signal as the first argument. -The source signal will retrigger the fetcher whenever it changes, and its value will be passed to the fetcher. +## Import -```tsx -const [data, { mutate, refetch }] = createResource(fetchData) +```typescript +import { createResource } from "solid-js"; ``` -```tsx -const [data, { mutate, refetch }] = createResource(source, fetchData) +## Type + +```typescript +// Without source +function createResource<T, R = unknown>( + fetcher: ResourceFetcher<true, T, R>, + options?: ResourceOptions<T> +): ResourceReturn<T, R>; + +// With source +function createResource<T, S, R = unknown>( + source: ResourceSource<S>, + fetcher: ResourceFetcher<S, T, R>, + options?: ResourceOptions<T, S> +): ResourceReturn<T, R>; ``` -In these snippets, the fetcher is the function `fetchData`, and `data()` is undefined until `fetchData` finishes resolving. -In the first case, `fetchData` will be called immediately. -In the second, `fetchData` will be called as soon as `source` has any value other than false, null, or undefined. -It will be called again whenever the value of `source` changes, and that value will always be passed to `fetchData` as its first argument. - -You can call `mutate` to directly update the `data` signal (it works like any other signal setter). -You can also call refetch to rerun the fetcher directly, and pass an optional argument to provide additional info to the fetcher e.g `refetch(info)`. - -`data` works like a normal signal getter: use `data()` to read the last returned value of `fetchData`. -But it also has extra reactive properties: - -- `data.loading`: whether the fetcher has been called but not returned. -- `data.error`: if the request has errored out. - `createResource`: provides an `Error` object for `data.error`. It will show even if the fetcher throws something else. - - - Fetcher throws an `Error` instance, `data.error` will be that instance. - - If the fetcher throws a string, `data.error.message` will contain that string. - - When the fetcher throws a value that is neither an `Error` nor a string, that value will be available as `data.error.cause`. - -- As of **v1.4.0**, `data.latest` returns the last value received and will not trigger [Suspense](/reference/components/suspense) or [transitions](#TODO); if no value has been returned yet, `data.latest` will act the same as `data()`. - This can be useful if you want to show the out-of-date data while the new data is loading. - -`loading`, `error`, and `latest` are reactive getters and can be tracked. - -## The fetcher - -The `fetcher` is the async function that you provide to `createResource` to actually fetch the data. -It is passed two arguments: the value of the source signal (if provided), and an info object with two properties: `value` and `refetching`. -The `value` property tells you the previously fetched value. -The `refetching` property is true if the `fetcher` was triggered using the refetch function and false otherwise. -If the `refetch` function was called with an argument (`refetch(info)`), refetching is set to that argument. - -```tsx -async function fetchData(source, { value, refetching }) { - // Fetch the data and return a value. - //`source` tells you the current value of the source signal; - //`value` tells you the last returned value of the fetcher; - //`refetching` is true when the fetcher is triggered by calling `refetch()`, - // or equal to the optional data passed: `refetch(info)` +### Related types + +```typescript +type ResourceReturn<T, R = unknown> = [Resource<T>, ResourceActions<T, R>]; + +type Resource<T> = { + (): T | undefined; + state: "unresolved" | "pending" | "ready" | "refreshing" | "errored"; + loading: boolean; + error: any; + latest: T | undefined; +}; + +type ResourceActions<T, R = unknown> = { + mutate: (value: T | undefined) => T | undefined; + refetch: (info?: R) => Promise<T> | T | undefined; +}; + +type ResourceSource<S> = + | S + | false + | null + | undefined + | (() => S | false | null | undefined); + +type ResourceFetcher<S, T, R = unknown> = ( + source: S, + info: { value: T | undefined; refetching: R | boolean } +) => T | Promise<T>; + +interface ResourceOptions<T, S = unknown> { + initialValue?: T; + name?: string; + deferStream?: boolean; + ssrLoadFrom?: "initial" | "server"; + storage?: ( + init: T | undefined + ) => [Accessor<T | undefined>, Setter<T | undefined>]; + onHydrated?: (k: S | undefined, info: { value: T | undefined }) => void; } +``` + +## Parameters + +### `source` + +- **Type:** `ResourceSource<S>` +- **Default:** `undefined` + +Reactive data source evaluated before the fetcher runs. +When the value is `undefined`, `null`, or `false`, the fetcher is not called. +Otherwise the current value is passed as the first fetcher argument. +Each change triggers the fetcher again. + +### `fetcher` + +- **Type:** `ResourceFetcher<S, T, R>` + +Function that receives the source value (or `true` if no source), the current resource info, and returns a value or Promise. + +### `options` + +- **Type:** `ResourceOptions<T, S>` +- **Default:** `{}` + +Configuration options for the resource. + +#### `initialValue` + +- **Type:** `T` +- **Default:** `undefined` + +Initial value for the resource. +When provided, the resource starts in "ready" state and the type excludes `undefined`. + +#### `name` + +- **Type:** `string` +- **Default:** `undefined` + +A name for debugging purposes in development mode. + +#### `deferStream` + +- **Type:** `boolean` +- **Default:** `false` -const [data, { mutate, refetch }] = createResource(getQuery, fetchData) +Controls streaming behavior during server-side rendering. -// read value -data() +#### `ssrLoadFrom` -// check if loading -data.loading +- **Type:** `"initial" | "server"` +- **Default:** `"server"` -// check if errored -data.error +Determines how the resource loads during SSR hydration. -// directly set value without creating promise -mutate(optimisticValue) +- "server": Uses the server-fetched value during hydration. +- "initial": Re-fetches on the client after hydration. -// refetch the last request explicitly -refetch() +#### `storage` +- **Type:** `(init: T | undefined) => [Accessor<T | undefined>, Setter<T | undefined>]` +- **Default:** `createSignal` + +Custom storage function for the resource value, useful for persistence or custom state management. + +#### `onHydrated` + +- **Type:** `(k: S | undefined, info: { value: T | undefined }) => void` +- **Default:** `undefined` + +Callback fired when the resource hydrates on the client side. + +## Return value + +- **Type:** `[Resource<T>, ResourceActions<T, R>]` + +Returns a tuple containing the resource accessor and resource actions. + +### `Resource` + +```typescript +type Resource<T> = { + (): T | undefined; + state: "unresolved" | "pending" | "ready" | "refreshing" | "errored"; + loading: boolean; + error: any; + latest: T | undefined; +}; +``` + +- `state`: Current state of the resource. + See the table below for state descriptions. +- `loading`: Indicates if the resource is currently loading. +- `error`: Error information if the resource failed to load. +- `latest`: The latest value of the resource. + +| State | Description | Loading | Error | Latest | +| ------------ | --------------------------------------- | ------- | ----------- | ----------- | +| `unresolved` | Initial state, not yet fetched | `false` | `undefined` | `undefined` | +| `pending` | Fetching in progress | `true` | `undefined` | `undefined` | +| `ready` | Successfully fetched | `false` | `undefined` | `T` | +| `refreshing` | Refetching while keeping previous value | `true` | `undefined` | `T` | +| `errored` | Fetching failed | `false` | `any` | `undefined` | + +### `ResourceActions` + +```typescript +type ResourceActions<T, R = unknown> = { + mutate: (value: T | undefined) => T | undefined; + refetch: (info?: R) => Promise<T> | T | undefined; +}; ``` -## Version 1.4.0 and Later +- `mutate`: Function to manually overwrite the resource value without calling the fetcher. + Allows you to optimistically update the resource value locally, without making a network request. +- `refetch`: Function to re-run the fetcher without changing the source. + If a parameter is provided to `refetch`, it will be passed to the fetcher's `refetching` property. -#### v1.4.0 +## Examples -If you're using `renderToStream`, you can tell Solid to wait for a resource before flushing the stream using the `deferStream` option: +### Basic usage -```tsx -// fetches a user and streams content as soon as possible -const [user] = createResource(() => params.id, fetchUser) +```typescript +const [data] = createResource(async () => { + const response = await fetch("/api/data"); + return response.json(); +}); -// fetches a user but only streams content after this resource has loaded -const [user] = createResource(() => params.id, fetchUser, { - deferStream: true, -}) +// Access data +console.log(data()); // undefined initially, then fetched data +console.log(data.loading); // true during fetch +console.log(data.state); // "pending" → "ready" ``` -#### v1.5.0 +### With source + +```typescript +const [userId, setUserId] = createSignal(1); + +const [user] = createResource(userId, async (id) => { + const response = await fetch(`/api/users/${id}`); + return response.json(); +}); + +// Automatically refetches when userId changes +setUserId(2); +``` -1. We've added a new state field which covers a more detailed view of the Resource state beyond `loading` and `error`. -You can now check whether a Resource is `unresolved`, `pending`, `ready`, `refreshing`, or `errored`. +### With actions -| State | Value resolved | Loading | Has error | -| ------------ | -------------- | ------- | --------- | -| `unresolved` | No | No | No | -| `pending` | No | Yes | No | -| `ready` | Yes | No | No | -| `refreshing` | Yes | Yes | No | -| `errored` | No | No | Yes | +```typescript +const [posts, { refetch, mutate }] = createResource(fetchPosts); -2. When server-rendering resources, especially when embedding Solid in other systems that fetch data before rendering, you might want to initialize the resource with this prefetched value instead of fetching again and having the resource serialize it in its own state. -You can use the new `ssrLoadFrom` option for this. -Instead of using the default `server` value, you can pass `initial` and the resource will use `initialValue` as if it were the result of the first fetch for both SSR and hydration. +// Manual refetch +await refetch(); -```tsx -const [data, { mutate, refetch }] = createResource(() => params.id, fetchUser, { - initialValue: preloadedData, - ssrLoadFrom: "initial", -}) +// Optimistic update +mutate((posts) => [...posts, newPost]); ``` -3. Resources can be set with custom defined storage with the same signature as a Signal by using the storage option. -For example using a custom reconciling store could be done this way: - -```tsx -function createDeepSignal<T>(value: T): Signal<T> { - const [store, setStore] = createStore({ - value, - }) - return [ - () => store.value, - (v: T) => { - const unwrapped = unwrap(store.value) - typeof v === "function" && (v = v(unwrapped)) - setStore("value", reconcile(v)) - return store.value - }, - ] as Signal<T> -} +### Error handling + +```typescript +const [data] = createResource(async () => { + const response = await fetch('/api/data'); + if (!response.ok) throw new Error('Failed to fetch'); + return response.json(); +}); -const [resource] = createResource(fetcher, { - storage: createDeepSignal, -}) +// In JSX +<ErrorBoundary fallback={<div>Error loading data</div>}> + <div>{data()?.title}</div> +</ErrorBoundary> ``` -This option is still experimental and may change in the future. - -## Options - -The `createResource` function takes an optional third argument, an options object. The options are: - -| 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 | - -## Note for TypeScript users - -The function and type definitions for `createResource` are as follows: - -```tsx -import { createResource } from "solid-js" -import type { ResourceReturn, ResourceOptions } from "solid-js" - -type ResourceReturn<T> = [ - { - (): T | undefined - state: "unresolved" | "pending" | "ready" | "refreshing" | "errored" - loading: boolean - error: any - latest: T | undefined - }, - { - mutate: (v: T | undefined) => T | undefined - refetch: (info: unknown) => Promise<T> | T - } -] - -type ResourceOptions<T, S = unknown> = { - initialValue?: T - name?: string - deferStream?: boolean - ssrLoadFrom?: "initial" | "server" - storage?: ( - init: T | undefined - ) => [Accessor<T | undefined>, Setter<T | undefined>] - onHydrated?: (k: S | undefined, info: { value: T | undefined }) => void -} +### With initial value -function createResource<T, U = true>( - fetcher: ( - k: U, - info: { value: T | undefined; refetching: boolean | unknown } - ) => T | Promise<T>, - options?: ResourceOptions<T, U> -): ResourceReturn<T> - -function createResource<T, U>( - source: U | false | null | (() => U | false | null), - fetcher: ( - k: U, - info: { value: T | undefined; refetching: boolean | unknown } - ) => T | Promise<T>, - options?: ResourceOptions<T, U> -): ResourceReturn<T> +```typescript +const [user] = createResource(() => fetchUser(), { + initialValue: { name: "Loading...", id: 0 }, +}); +// user() is never undefined +console.log(user().name); // "Loading..." initially ``` diff --git a/src/routes/reference/basic-reactivity/create-signal.mdx b/src/routes/reference/basic-reactivity/create-signal.mdx index 6a56a40ef..79abb1f99 100644 --- a/src/routes/reference/basic-reactivity/create-signal.mdx +++ b/src/routes/reference/basic-reactivity/create-signal.mdx @@ -1,148 +1,122 @@ --- title: createSignal +use_cases: >- + state management, reactive values, component state, form inputs, counters, + toggles, any reactive data +tags: + - signals + - state + - reactivity + - core + - primitives +version: "1.0" +description: >- + Create reactive state with createSignal, Solid's fundamental primitive. Track + values that change over time and automatically update your UI when they do. --- -Signals are the most basic reactive primitive. -They track a single value (which can be a value of any type) that changes over time. +Creates a reactive state primitive consisting of a getter (accessor) and a setter function that forms the foundation of Solid's reactivity system. +Signals use a pull-based reactivity model where tracking subscriptions (reads) is lightweight, while updates (writes) trigger dependency tracking and effect re-execution, making them optimized for frequent reads and infrequent writes. -```tsx -import { createSignal } from "solid-js" - -function createSignal<T>( - initialValue: T, - options?: { - equals?: false | ((prev: T, next: T) => boolean) - name?: string - internal?: boolean - } -): [get: () => T, set: (v: T) => T] - -// available types for return value of createSignal: -import type { Signal, Accessor, Setter } from "solid-js" -type Signal<T> = [get: Accessor<T>, set: Setter<T>] -type Accessor<T> = () => T -type Setter<T> = (v: T | ((prev?: T) => T)) => T +## Import +```typescript +import { createSignal } from "solid-js"; ``` -The Signal's value starts out equal to the passed first argument `initialValue` (or undefined if there are no arguments). -The `createSignal` function returns a pair of functions as a two-element array: a getter (or accessor) and a setter. -In typical use, you would destructure this array into a named Signal like so: +## Type signature -```tsx -const [count, setCount] = createSignal(0) -const [ready, setReady] = createSignal(false) -``` +```typescript +function createSignal<T>(): Signal<T | undefined>; +function createSignal<T>(value: T, options?: SignalOptions<T>): Signal<T>; -Calling the getter (e.g., `count()` or `ready()`) returns the current value of the Signal. +type Signal<T> = [get: Accessor<T>, set: Setter<T>]; -Crucial to automatic dependency tracking, calling the getter within a tracking scope causes the calling function to depend on this Signal, so that function will rerun if the Signal gets updated. +type Accessor<T> = () => T; -Calling the setter (e.g., `setCount(nextCount)` or `setReady(nextReady)`) sets the Signal's value and updates the Signal (triggering dependents to rerun) if the value actually changed (see details below). -The setter takes either the new value for the signal or a function that maps the previous value of the signal to a new value as its only argument. -The updated value is also returned by the setter. As an example: +type Setter<T> = { + <U extends T>(value: Exclude<U, Function> | ((prev: T) => U)): U; + <U extends T>(value: (prev: T) => U): U; + <U extends T>(value: Exclude<U, Function>): U; + <U extends T>(value: Exclude<U, Function> | ((prev: T) => U)): U; +}; -```tsx -// read signal's current value, and -// depend on signal if in a tracking scope -// (but nonreactive outside of a tracking scope): -const currentCount = count() +interface SignalOptions<T> { + name?: string; + equals?: false | ((prev: T, next: T) => boolean); + internal?: boolean; +} +``` -// or wrap any computation with a function, -// and this function can be used in a tracking scope: -const doubledCount = () => 2 * count() +## Parameters -// or build a tracking scope and depend on signal: -const countDisplay = <div>{count()}</div> +### `value` -// write signal by providing a value: -setReady(true) +- **Type:** `T` +- **Default:** `undefined` -// write signal by providing a function setter: -const newCount = setCount((prev) => prev + 1) +The initial value for the signal. +If no initial value is provided, the signal's type is automatically extended with `undefined`. -``` +### `options` -:::note - If you want to store a function in a Signal you must use the function form: +- **Type:** `SignalOptions<T>` +- **Default:** `undefined` - ```tsx - setValue(() => myFunction); - ``` +Configuration object for the signal. - However, functions are not treated specially as the `initialValue` argument to `createSignal`, so you can pass a - function initial value as is: +#### `name` - ```tsx - const [func, setFunc] = createSignal(myFunction); - ``` +- **Type:** `string` +- **Default:** `undefined` -::: +A name for the signal used by debugging tools like [Solid devtools](https://github.com/thetarnav/solid-devtools). +It works only in development mode and is removed from the production bundle. -## Options +#### `equals` -| Name | Type | Default | Description | -| ---------- | ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `equals` | `false \| ((prev: T, next: T) => boolean)` | `===` | A function that determines whether the Signal's value has changed. If the function returns true, the Signal's value will not be updated and dependents will not rerun. If the function returns false, the Signal's value will be updated and dependents will rerun. | -| `name` | `string` | | A name for the Signal. This is useful for debugging. | -| `internal` | `boolean` | `false` | If true, the Signal will not be accessible in the devtools. | +- **Type:** `false | ((prev: T, next: T) => boolean)` +- **Default:** `false` -### `equals` +A custom comparison function to determine when the signal should update. +By default, signals use reference equality (`===`) to compare previous and next values. +When set to `false`, the signal will always update regardless of value equality, which is useful for creating signals that trigger manual updates in the reactive system. -The `equals` option can be used to customize the equality check used to determine whether the Signal's value has changed. -By default, the equality check is a strict equality check (`===`). -If you want to use a different equality check, you can pass a custom function as the `equals` option. -The custom function will be called with the previous and next values of the Signal as arguments. -If the function returns true, the Signal's value will not be updated and dependents will not rerun. -If the function returns false, the Signal's value will be updated and dependents will rerun. +When providing a custom function, it should be pure and return `true` if the values are equal (no update needed) or `false` if they differ (trigger update). +Impure functions can create unexpected side effects and performance issues. -```tsx -const [count, setCount] = createSignal(0, { - equals: (prev, next) => prev === next, -}) -``` +#### `internal` -Here are some examples of this option in use: +- **Type:** `boolean` +- **Default:** `false` -```tsx -// use { equals: false } to allow modifying object in-place; -// normally this wouldn't be seen as an update because the -// object has the same identity before and after change -const [object, setObject] = createSignal({ count: 0 }, { equals: false }) -setObject((current) => { - current.count += 1 - current.updated = new Date() - return current -}) - -// use { equals: false } to create a signal that acts as a trigger without storing a value: -const [depend, rerun] = createSignal(undefined, { equals: false }) -// now calling depend() in a tracking scope -// makes that scope rerun whenever rerun() gets called - -// define equality based on string length: -const [myString, setMyString] = createSignal("string", { - equals: (newVal, oldVal) => newVal.length === oldVal.length, -}) - -setMyString("string") // considered equal to the last value and won't cause updates -setMyString("stranger") // considered different and will cause updates -``` +Marks the signal as internal, preventing it from appearing in development tools. +This is primarily used by Solid's internal systems. -### `name` +## Return value -The `name` option can be used to give the Signal a name. -This is useful for debugging. The name will be displayed in the devtools. +- **Type:** `Signal<T>` -```tsx -const [count, setCount] = createSignal(0, { name: "count" }) -``` +Returns a tuple `[getter, setter]` where: + +- **getter**: An accessor function that returns the current value and tracks dependencies when called within a reactive context +- **setter**: A function that updates the signal's value and notifies all dependent computations -### `internal` +## Examples -The `internal` option can be used to hide the Signal from the devtools. -This is useful for Signals that are used internally by a component and should not be exposed to the user. +### Basic usage ```tsx -const [count, setCount] = createSignal(0, { internal: true }) +import { createSignal } from "solid-js"; + +function Counter() { + const [count, setCount] = createSignal(0); + + return ( + <div> + <button onClick={() => setCount(count() + 1)}>+</button> + <span>{count()}</span> + </div> + ); +} ``` diff --git a/src/routes/reference/component-apis/children.mdx b/src/routes/reference/component-apis/children.mdx index 2d001fb0c..c0a081ccb 100644 --- a/src/routes/reference/component-apis/children.mdx +++ b/src/routes/reference/component-apis/children.mdx @@ -1,65 +1,105 @@ --- title: children +use_cases: >- + resolving component children, normalizing JSX children, slot-like helpers, + interacting with child content in library components +tags: + - components + - children + - jsx + - utilities +version: "1.0" +description: >- + Resolve a component's `children` prop into a stable accessor. --- -```tsx -import { children } from "solid-js"; -import type { JSX, ResolvedChildren } from "solid-js"; +`children` resolves a component's `children` prop and returns a stable accessor for the resolved result. -function children(fn: () => JSX.Element): () => ResolvedChildren +## Import +```ts +import { children } from "solid-js"; ``` -The `children` helper is used for more complex interactions with props. -When you're not just passing children to another component using `props.children` once in JSX, you should use `children`. -Props are normally passed in via a getter for `props.children` in this manner: +## Type -```tsx -const resolved = children(() => props.children) +```ts +type ResolvedJSXElement = Exclude<JSX.Element, JSX.ArrayElement>; +type ResolvedChildren = ResolvedJSXElement | ResolvedJSXElement[]; + +function children(fn: Accessor<JSX.Element>): Accessor<ResolvedChildren> & { + toArray: () => ResolvedJSXElement[]; +}; ``` -The return value is a [memo](/reference/basic-reactivity/create-memo) evaluating to the resolved children, which updates whenever the children change. -Using this memo instead of accessing `props.children` directly has some important advantages in some scenarios. -The underlying issue is that, when you specify component children via JSX, Solid automatically defines `props.children` as a property getter, so that the children are created (in particular, DOM is created) whenever `props.children` gets accessed. +## Parameters + +### `fn` + +- **Type:** `() => JSX.Element` +- **Required:** Yes + +Accessor that returns the component's `children` value. -Two particular consequences: +## Return value -1. If you access `props.children` multiple times, the children (and associated DOM) get created multiple times. -This is useful if you want the DOM to be duplicated (as DOM nodes can appear in only one parent element), but in many cases it creates redundant DOM nodes. -If you instead call `resolved()` multiple times, you re-use the same children. +- **Type:** `Accessor<ResolvedChildren> & { toArray: () => ResolvedJSXElement[] }` -2. If you access `props.children` outside of a tracking scope (e.g., in an event handler), then you create children that will never be cleaned up. -If you instead call `resolved()`, you re-use the already resolved children. -You also guarantee that the children are tracked in the current component, as opposed to another tracking scope such as another component. +Returns an accessor for the resolved children. +The accessor also exposes `toArray()`. -In addition, the `children` helper "resolves" children by calling argumentless functions and flattening arrays of arrays into an array. -For example, a child specified with JSX like `{signal() * 2}` gets wrapped into a getter function `() => count() * 2` in `props.children`, but gets evaluated to an actual number in resolved, properly depending on a count signal. +## Behavior -If the given `props.children` is not an array (which occurs when the JSX tag has a single child), then the `children` helper will not normalize it into an array. -This is useful behavior e.g. when the intention is to pass a single function as a child, which can be detected via `typeof resolved() === 'function'`. -If you want to normalize to an array, the returned memo has a `toArray` method _(new in 1.5)_. +- The returned accessor memoizes the resolved children, so repeated reads use the resolved result instead of recreating the child structure. +- `children` resolves nested arrays, fragments, and zero-argument child accessors from `props.children`. +- `toArray()` returns the resolved children as an array. It returns `[]` when the resolved value is `null` or `undefined`. -In most cases, you don't need (and in some cases, don't want) to use the `children` helper if you're just passing `props.children` on to another component or element via JSX: +## Examples + +### Basic usage ```tsx -const Wrapper = (props) => { - return <div>{props.children}</div> +function Wrapper(props) { + const resolved = children(() => props.children); + + return <div>{resolved()}</div>; +} + +function Example() { + return ( + <Wrapper> + <span>First</span> + <span>Second</span> + </Wrapper> + ); } ``` -An important aspect of the `children` helper is that it forces the children to be created and resolved, as it accesses `props.children` immediately. -This can be undesirable for conditional rendering, e.g., when using the children within a [`<Show>`](/reference/components/show) component. -For example, the following code always evaluates the children: +### Flatten children into an array ```tsx -const resolved = children(() => props.children) +function List(props) { + const resolved = children(() => props.children); + + return ( + <ul> + {resolved.toArray().map((child) => ( + <li>{child}</li> + ))} + </ul> + ); +} -return <Show when={visible()}>{resolved()}</Show> +function Example() { + return ( + <List> + <span>Alpha</span> + <span>Beta</span> + </List> + ); +} ``` -To evaluate the children only when `<Show>` would render them, you can push the call to children inside a component or a function within `<Show>`, which only evaluates its children when `when` condition is true. -Another nice workaround is to pass `props.children` to the children helper only when you actually want to evaluate the children: +## Related -```tsx -const resolved = children(() => visible() && props.children) -``` +- [Props](/concepts/components/props) diff --git a/src/routes/reference/component-apis/create-context.mdx b/src/routes/reference/component-apis/create-context.mdx index fb1634575..c6fa4e8be 100644 --- a/src/routes/reference/component-apis/create-context.mdx +++ b/src/routes/reference/component-apis/create-context.mdx @@ -1,103 +1,112 @@ --- title: createContext order: 5 +use_cases: >- + prop drilling, global state, theme providers, user authentication, app-wide + settings, dependency injection +tags: + - context + - providers + - global-state + - props + - dependency-injection +version: "1.0" +description: >- + Create a context object with a `Provider` component and a default value. --- +`createContext` creates a context object. +The returned object contains a `Provider` component and an optional `defaultValue`; [`useContext`](/reference/component-apis/use-context) reads the nearest matching provider value. -Context provides a form of dependency injection in Solid. -It is used to save from needing to pass data as props through intermediate components (aka **prop drilling**). -This function creates a new context object that can be used with [useContext](/reference/component-apis/use-context) and offers the Provider control flow. -The default value is used when no Provider is found above in the hierarchy. +## Import -## Usage +```ts +import { createContext } from "solid-js"; +``` + +## Type + +```ts +interface Context<T> { + id: symbol; + Provider: (props: { value: T; children: any }) => any; + defaultValue: T; +} -To avoid reinstatiating a new context when Hot-Module Replacement (HMR) occurs, it is recommended to use `createContext` in its own module (file). +function createContext<T>( + defaultValue?: undefined, + options?: { name?: string } +): Context<T | undefined>; -:::danger[Hot-Module Replacement] -When using HMR, the context is lost when the module is reloaded. -Which will cause an error to be thrown as `useContext` will try to access it while it is still reloading. -::: +function createContext<T>( + defaultValue: T, + options?: { name?: string } +): Context<T>; +``` +## Parameters -For example: +### `defaultValue` -```ts title="/context/counter.ts" -import { createContext } from "solid-js"; +- **Type:** `T` -export const INITIAL_COUNT = 0; +Default value returned by [`useContext`](/reference/component-apis/use-context) when no matching provider is found. -const INITIAL_STORE_SETTER = { - increment: () => {}, - decrement: () => {} -}; +### `options` -export const CounterContext = createContext([ - { count: INITIAL_COUNT }, - INITIAL_STORE_SETTER -]); -``` +#### `name` -With the context created in its own module, you can use to instantiate the context provider. - -```ts title="/context/counter-component.tsx" -import { createStore } from 'solid-js/store'; -import { CounterContext, INITIAL_COUNT } from "./counter.ts"; - -export function CounterProvider(props) { - const [value, setValue] = createStore({ count: props.initialCount || INITIAL_COUNT }) - - const counter = [ - value, - { - increment() { - setValue("count", currentCount => currentCount + 1) - }, - decrement() { - setValue("count", currentCount => currentCount - 1) - }, - }, - ] - - return ( - <CounterContext.Provider value={counter}> - {props.children} - </CounterContext.Provider> - ) -} -``` +- **Type:** `string` + +Debug name used by development tooling. -A few imporant notes on how to pass data through the context API: +## Return value -- The value passed to provider is passed to `useContext` as is. -- Wrapping as a reactive expression will not work. -- You should pass in Signals and Stores directly instead of accessing them in the JSX. +- **Type:** `Context<T>` or `Context<T | undefined>` -To learn how to consume the context, see the [useContext](/reference/component-apis/use-context) documentation and the [Context concepts entry](/concepts/context). +Returns a context object containing `id`, `Provider`, and `defaultValue`. -## Default Values +## Behavior -`createContext()` takes an optional "default value" as an argument. -If `useContext` is called and there is no corresponding context provider above it in the component hierarchy, then the value passed as `defaultValue` is returned. +- `Context.Provider` passes its `value` prop to descendant calls to [`useContext`](/reference/component-apis/use-context). +- `useContext` reads the nearest matching provider in the current owner tree. +- If no matching provider is found, `useContext` returns `defaultValue` when one was supplied, or `undefined` otherwise. -However, if no `defaultValue` was passed, then `undefined` is returned in this case. -Also, `defaultValue` (or `undefined`) is returned if `useContext` is called inside an event callback, as it is then outside of the component hierarchy. +## Notes -This has implications for TS. -If no `defaultValue` is passed, then it is possible that `useContext()` will return `undefined`, and the types reflect this. +- During Hot Module Replacement (HMR), recreating a context in a reloaded module creates a new context object. +- If provider and consumer modules are temporarily out of sync during reload, `useContext` can read a different context object and return the default value or `undefined`. +- Defining the context in its own module keeps the exported context object stable across imports. -Another (used in the example in the previous section) is provide a default value to `createContext()`. -In that case, `useContext()` will always return a value, and therefore TS will not complain either. -The pitfall with this approach is that if you _unintentionally_ use `useContext` outside of a provider, it may not be immediately apparent, because the context is still providing a valid value. -Therefore, if you expect to always use `useContext` within a provider, it is best to use the error based approach described above. +## Examples -## Type signature +### Create a context with a default value ```ts -interface Context<T> { - id: symbol - Provider: (props: { value: T; children: any }) => any - defaultValue: T -} +import { createContext } from "solid-js"; + +type Theme = "light" | "dark"; -function createContext<T>(defaultValue?: T): Context<T | undefined> +const ThemeContext = createContext<Theme>("light"); ``` + +### Create a provider + +```tsx +import { createContext } from "solid-js"; + +const CounterContext = createContext<{ count: number }>(); + +function CounterProvider(props) { + return ( + <CounterContext.Provider value={{ count: 1 }}> + {props.children} + </CounterContext.Provider> + ); +} +``` + +## Related + +- [`useContext`](/reference/component-apis/use-context) +- [Context](/concepts/context) diff --git a/src/routes/reference/component-apis/create-unique-id.mdx b/src/routes/reference/component-apis/create-unique-id.mdx index 65088f374..a2de7d756 100644 --- a/src/routes/reference/component-apis/create-unique-id.mdx +++ b/src/routes/reference/component-apis/create-unique-id.mdx @@ -1,18 +1,77 @@ --- title: createUniqueId +use_cases: >- + form elements, accessibility, aria labels, ssr compatibility, html id + generation, unique identifiers +tags: + - ids + - accessibility + - ssr + - forms + - utilities +version: "1.0" +description: >- + Generate a unique string for the current render or hydration context. --- -```ts -import { createUniqueId } from "solid-js" +`createUniqueId` generates a unique string for the current render or hydration context. +During hydration, matching server and client call order produces matching IDs. + +`createUniqueId` does _not_ generate a cryptographically secure ID and is not suitable for security-sensitive data. +Additionally, it should not be used in scenarios that require uniqueness across a distributed system. + +:::note +`createUniqueId` relies on a counter-based mechanism to generate IDs. +It must be called the same number of times on both the server and client. -function createUniqueId(): string +Calling `createUniqueId` only on the server or only on the client, such as when using [`isServer`](/reference/rendering/is-server) or [`<NoHydration>`](/reference/components/no-hydration), may lead to hydration errors. +::: +## Import + +```ts +import { createUniqueId } from "solid-js"; ``` -A universal id generator that is stable across server/browser. +## Type ```ts -const id = createUniqueId() +function createUniqueId(): string; ``` -**Note:** on the server this only works under hydratable components. +## Parameters + +This function does not take any parameters. + +## Returns + +`createUniqueId` returns a unique `string` that is stable across server and client renders. + +## Behavior + +- During hydration, IDs come from the current hydration context, so matching call order produces matching server and client IDs. +- Outside hydration context, client-side IDs use a local counter and are unique only within the current Solid runtime instance. + +## Examples + +### Basic Usage + +```tsx +import { createUniqueId } from "solid-js"; + +type InputProps = { + id?: string; + label: string; +}; + +function Input(props: InputProps) { + const inputId = props.id ?? createUniqueId(); + + return ( + <> + <label for={inputId}>{props.label}</label> + <input id={inputId} /> + </> + ); +} +``` diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx index d6b714433..970d510fd 100644 --- a/src/routes/reference/component-apis/lazy.mdx +++ b/src/routes/reference/component-apis/lazy.mdx @@ -1,25 +1,109 @@ --- title: lazy +use_cases: >- + code splitting, performance optimization, reducing bundle size, dynamic + imports, route-based splitting, lazy loading +tags: + - lazy-loading + - code-splitting + - performance + - suspense + - optimization + - imports +version: "1.0" +description: >- + Create a component that loads its module lazily from a dynamic import. --- -```ts -import { lazy } from "solid-js" -import type { Component } from "solid-js" +`lazy` wraps a dynamic import and returns a component that loads its module on demand. +The returned component accepts the same props as the loaded component and exposes `preload()`. + +## Import +```tsx +import { lazy } from "solid-js"; +``` + +## Type + +```ts function lazy<T extends Component<any>>( fn: () => Promise<{ default: T }> -): T & { preload: () => Promise<T> } +): T & { preload: () => Promise<{ default: T }> }; ``` -Used to lazy load components to allow for code splitting. -Components are not loaded until rendered. -Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. -Lazy components trigger `<Suspense>` +## Parameters + +### `fn` + +- **Type:** `() => Promise<{ default: T }>` +- **Required:** Yes + +Dynamic import that resolves to the component module, exposing the component as the `default` export. + +## Return value + +- **Type:** `T & { preload: () => Promise<{ default: T }> }` + +Returns a renderable component compatible with `T`. +The returned component also exposes `preload()`. + +`preload()` starts loading the module without rendering the component and returns the resolved module. + +## Behavior + +- Rendering a lazy component starts loading its module if it has not already been loaded. +- Inside a [`<Suspense>`](/reference/components/suspense) boundary, the boundary shows its fallback while the module is loading. +- Without a suspense boundary, the lazy component renders an empty string until the module resolves. +- `preload()` starts the same module request without rendering the component. + +## Examples + +### Basic usage ```tsx -// wrap import +import { lazy, Suspense } from "solid-js"; + const ComponentA = lazy(() => import("./ComponentA")); -// use in JSX -<ComponentA title={props.title} /> +function App(props: { title: string }) { + return ( + <Suspense fallback={<p>Loading...</p>}> + <ComponentA title={props.title} /> + </Suspense> + ); +} +``` + +### Preloading nested lazy components + +```tsx +import { createSignal, lazy, Show, Suspense } from "solid-js"; + +const Nested = lazy(() => import("./Nested")); + +const ComponentWithPreload = () => { + const [showNested, setShowNested] = createSignal(false); + + return ( + <div> + <button + onMouseEnter={() => Nested.preload()} + onClick={() => setShowNested(true)} + > + Preload Nested Component + </button> + <Show when={showNested()}> + <Suspense fallback={<p>Loading nested component...</p>}> + <Nested /> + </Suspense> + </Show> + </div> + ); +}; ``` + +## Related + +- [`Suspense`](/reference/components/suspense) +- [Router preloading guide](/solid-router/advanced-concepts/preloading) diff --git a/src/routes/reference/component-apis/use-context.mdx b/src/routes/reference/component-apis/use-context.mdx index e4eb55068..0f9be9aeb 100644 --- a/src/routes/reference/component-apis/use-context.mdx +++ b/src/routes/reference/component-apis/use-context.mdx @@ -1,38 +1,99 @@ --- title: useContext +use_cases: >- + consuming context, accessing global state, avoiding prop drilling, theme + access, auth state, shared data +tags: + - context + - providers + - global-state + - hooks + - consumption +version: "1.0" +description: >- + Read the current value of a context object created by `createContext`. --- -Used to grab context within a context provider scope to allow for deep passing of props without having to pass them through each Component function. -It's therefore used in conjunction with [`createContext`](/reference/component-apis/create-context) to consume the data from a Provider scope and thus avoid passing data through intermediate components (prop drilling). +`useContext` reads the nearest provider value for a context object in the current owner tree. + +## Import ```ts -const [state, { increment, decrement }] = useContext(CounterContext) +import { useContext } from "solid-js"; ``` -## Recommended usage +## Type -It is often a good idea to wrap `useContext` in a function like so: +```ts +interface Context<T> { + id: symbol; + Provider: (props: { value: T; children: any }) => any; + defaultValue: T; +} -```ts title="/context/counter-component.tsx" -function useCounterContext() { - const context = useContext(CounterContext) +function useContext<T>(context: Context<T>): T; +``` - if (!context) { - throw new Error("useCounterContext: cannot find a CounterContext") - } +## Parameters + +### `context` + +- **Type:** `Context<T>` +- **Required:** Yes + +Context object created by [`createContext`](/reference/component-apis/create-context). + +## Return value + +- **Type:** `T` + +Returns the value provided by the nearest matching `Context.Provider`. +If the context was created without a default value, `T` can include `undefined`. +If no provider is found, it returns the context's default value or `undefined`. + +## Behavior + +- `useContext` reads the nearest matching provider in the current owner tree. +- If no matching provider is found, it returns the default value from [`createContext`](/reference/component-apis/create-context), or `undefined` when no default value was supplied. +- A provider value of `undefined` is treated the same as a missing provider and returns the default value or `undefined`. - return context +## Examples + +### Read a context value + +```tsx +import { createContext, useContext } from "solid-js"; + +const CounterContext = createContext<number>(0); + +function CounterValue() { + const value = useContext(CounterContext); + + return <span>{value}</span>; } ``` -See the API reference of [createContext](/reference/component-apis/create-context) the API on how to generate a Provider scope. -And check the [Context concepts](/concepts/context) for more information on how to architecture your contexts. +### Throw when a provider is missing -## Type signature +This example checks for `undefined` when the context was created without a default value. ```ts -import { type Context } from "solid-js" +import { createContext, useContext } from "solid-js"; + +const CounterContext = createContext<number>(); + +function useCounterContext() { + const context = useContext(CounterContext); + + if (context === undefined) { + throw new Error("CounterContext is missing"); + } + + return context; +} +``` -function useContext<T>(context: Context<T>): T +## Related -``` \ No newline at end of file +- [`createContext`](/reference/component-apis/create-context) +- [Context](/concepts/context) diff --git a/src/routes/reference/components/create-dynamic.mdx b/src/routes/reference/components/create-dynamic.mdx new file mode 100644 index 000000000..9f6c63749 --- /dev/null +++ b/src/routes/reference/components/create-dynamic.mdx @@ -0,0 +1,92 @@ +--- +title: createDynamic +use_cases: >- + dynamic components, runtime component selection, polymorphic components, + lower-level rendering helpers, library components +tags: + - dynamic + - components + - jsx + - polymorphic + - rendering +version: "1.0" +description: >- + Render a component or intrinsic element selected at runtime from an accessor. +--- + +`createDynamic` renders the value returned by its `component` accessor as either a custom component or an intrinsic element. + +## Import + +```ts +import { createDynamic } from "solid-js/web"; +``` + +## Type + +```ts +type ValidComponent = + | keyof JSX.IntrinsicElements + | ((props: any) => JSX.Element); + +function createDynamic<T extends ValidComponent>( + component: () => T | undefined, + props: ComponentProps<T> +): JSX.Element; +``` + +## Parameters + +### `component` + +- **Type:** `() => T | undefined` + +Accessor that returns the component or intrinsic element to render. + +### `props` + +- **Type:** props accepted by the rendered component or element + +Props passed to the rendered component or element. + +## Return value + +- **Type:** `JSX.Element` + +Returns the rendered component or element. + +## Behavior + +- If `component()` is `undefined`, nothing is rendered. + +## Example + +```tsx +import { createSignal } from "solid-js"; + +const views = { + red: (props: { label: string }) => ( + <p style={{ color: "red" }}>{props.label}</p> + ), + blue: (props: { label: string }) => ( + <p style={{ color: "blue" }}>{props.label}</p> + ), +}; + +function App() { + const [selected, setSelected] = createSignal<keyof typeof views>("red"); + + return ( + <> + <button onClick={() => setSelected("red")}>Red</button> + <button onClick={() => setSelected("blue")}>Blue</button> + + {createDynamic(() => views[selected()], { label: "Selected view" })} + </> + ); +} +``` + +## Related + +- [`<Dynamic>`](/reference/components/dynamic) diff --git a/src/routes/reference/components/data.json b/src/routes/reference/components/data.json index 716b071e6..18de882d2 100644 --- a/src/routes/reference/components/data.json +++ b/src/routes/reference/components/data.json @@ -1,6 +1,7 @@ { "title": "Components", "pages": [ + "create-dynamic.mdx", "dynamic.mdx", "error-boundary.mdx", "for.mdx", diff --git a/src/routes/reference/components/dynamic.mdx b/src/routes/reference/components/dynamic.mdx index d21959508..0b56f0d51 100644 --- a/src/routes/reference/components/dynamic.mdx +++ b/src/routes/reference/components/dynamic.mdx @@ -1,32 +1,96 @@ --- title: <Dynamic> order: 5 +use_cases: >- + dynamic components, runtime component selection, polymorphic components, + rendering custom components or intrinsic elements +tags: + - dynamic + - components + - jsx + - polymorphic + - rendering +version: "1.0" +description: >- + Render a component or intrinsic element selected at runtime. --- -This component lets you insert an arbitrary Component or tag and passes the props through to it. +`<Dynamic>` renders the value of its `component` prop as either a custom component or an intrinsic element. -```tsx -import { Dynamic } from "solid-js/web" -import type { JSX } from "solid-js" - -function Dynamic<T>( - props: T & { - children?: any - component?: Component<T> | string | keyof JSX.IntrinsicElements - } -): () => JSX.Element +## Import + +```ts +import { Dynamic } from "solid-js/web"; ``` -Here's an example of how you can use it: +## Type -```tsx -<Dynamic component={MyComponent} someProp={state.something} /> +```ts +type ValidComponent = + | keyof JSX.IntrinsicElements + | ((props: any) => JSX.Element); + +type DynamicProps<T extends ValidComponent, P = ComponentProps<T>> = { + [K in keyof P]: P[K]; +} & { + component: T | undefined; +}; + +function Dynamic<T extends ValidComponent>(props: DynamicProps<T>): JSX.Element; ``` ## Props -| Name | Type | Description | -| :---------- | :---------------------------------------------------------- | :---------------------------------------- | -| `component` | `Component<T>` \| `string` \| `keyof JSX.IntrinsicElements` | The component to render. | -| `children` | `any` | The children to pass to the component. | -| `...` | `T` | Any other props to pass to the component. | +### `component` + +- **Type:** `T | undefined` + +Component or intrinsic element to render. + +### remaining props + +- **Type:** props accepted by the rendered component or element + +Props forwarded to the rendered value of `component`. + +## Return value + +- **Type:** `JSX.Element` + +Returns the rendered component or element. + +## Behavior + +- When `component` is `undefined`, nothing is rendered. + +## Example + +```tsx +import { createSignal } from "solid-js"; + +const views = { + red: (props: { label: string }) => ( + <p style={{ color: "red" }}>{props.label}</p> + ), + blue: (props: { label: string }) => ( + <p style={{ color: "blue" }}>{props.label}</p> + ), +}; + +function App() { + const [selected, setSelected] = createSignal<keyof typeof views>("red"); + + return ( + <> + <button onClick={() => setSelected("red")}>Red</button> + <button onClick={() => setSelected("blue")}>Blue</button> + + <Dynamic component={views[selected()]} label="Selected view" /> + </> + ); +} +``` + +## Related + +- [`createDynamic`](/reference/components/create-dynamic) diff --git a/src/routes/reference/components/error-boundary.mdx b/src/routes/reference/components/error-boundary.mdx index bcdae26a3..d91e14120 100644 --- a/src/routes/reference/components/error-boundary.mdx +++ b/src/routes/reference/components/error-boundary.mdx @@ -1,54 +1,85 @@ --- title: <ErrorBoundary> order: 5 +use_cases: >- + error handling, rendering fallbacks, preventing subtree crashes, recovering + from render errors +tags: + - error-handling + - components + - fallback + - stability +version: "1.0" +description: >- + Catch errors thrown while rendering or updating a subtree and render fallback + content. --- -The `<ErrorBoundary>` component catches errors that occur during the rendering or updating of its children and shows a fallback UI instead. -This includes: +`<ErrorBoundary>` catches errors thrown while rendering or updating its children. -- Errors that occur while rendering JSX. -- Errors that occur within `createEffect`, `createMemo`, and other state management primitives. -- Errors that occur within `createResource` and other asynchronous state management or data-fetching primitives. +## Import -However, errors occurring outside the rendering process are **not** captured by error boundaries. -For instance: +```ts +import { ErrorBoundary } from "solid-js"; +``` -- Errors that occur inside event handlers. -- Errors that occur after a `setTimeout`. +## Type + +```ts +function ErrorBoundary(props: { + fallback: JSX.Element | ((err: any, reset: () => void) => JSX.Element); + children: JSX.Element; +}): JSX.Element; +``` ## Props ### `fallback` -**Type**: `JSX.Element | ((err: any, reset: () => void) => JSX.Element)` +- **Type:** `JSX.Element | ((err: any, reset: () => void) => JSX.Element)` + +Fallback content. Function fallbacks receive the caught error and a reset function. + +### `children` + +- **Type:** `JSX.Element` + +Subtree wrapped by the boundary. -`fallback` provides content to display when an error occurs. -If a function is passed, it receives two parameters: +## Return value -- `err`: The caught error object. -- `reset`: A function that forces the `<ErrorBoundary>` to re-render its children and clear the error state. +- **Type:** `JSX.Element` -If there's an error within the `fallback` itself, however, it is not caught by the same `<ErrorBoundary>`. -Instead, it will bubble up to any parent error boundaries. +Returns the rendered children or fallback content. -## Example +## Behavior + +- `<ErrorBoundary>` catches errors thrown while rendering JSX and while updating reactive computations in its subtree, including reactive async primitives when they surface through the same rendering or update flow. +- Errors thrown from event handlers or from callbacks scheduled outside Solid's rendering and update flow are not caught by the boundary. +- Function fallbacks receive `reset`, which clears the current error state and re-renders the children. +- Errors thrown by the fallback itself can be caught by a parent error boundary. + +## Examples + +### Basic usage ```tsx -import { ErrorBoundary } from "solid-js"; -import { ErrorProne } from "./components"; - -function Example() { - return ( - <ErrorBoundary - fallback={(error, reset) => ( - <div> - <p>{error.message}</p> - <button onClick={reset}>Try Again</button> - </div> - )} - > - <ErrorProne /> - </ErrorBoundary> - ); +function ErrorProne() { + throw new Error("Broken"); } + +<ErrorBoundary + fallback={(error, reset) => ( + <div> + <p>{String(error)}</p> + <button onClick={reset}>Try Again</button> + </div> + )} +> + <ErrorProne /> +</ErrorBoundary>; ``` + +## Related + +- [`catchError`](/reference/reactive-utilities/catch-error) diff --git a/src/routes/reference/components/for.mdx b/src/routes/reference/components/for.mdx index a02434702..75ec4f86a 100644 --- a/src/routes/reference/components/for.mdx +++ b/src/routes/reference/components/for.mdx @@ -1,51 +1,100 @@ --- title: <For> order: 5 +use_cases: >- + rendering lists, dynamic arrays, data iteration, collections, tables, + repeating elements +tags: + - lists + - iteration + - components + - arrays + - rendering + - performance +version: "1.0" +description: >- + Render a list by item identity with a child function that receives the item + and an index accessor. --- -The `<For>` component is used to render a list of items. It is similar to the `.map()` function in JavaScript. +`<For>` renders a list by item identity. + +## Import ```ts -import { For } from "solid-js" -import type { JSX } from "solid-js" - -function For<T, U extends JSX.Element>(props: { - each: readonly T[] - fallback?: JSX.Element - children: (item: T, index: () => number) => U -}): () => U[] +import { For } from "solid-js"; ``` -A referentially keyed loop with efficient updating of only changed items. The callback takes the current item as the first argument: +## Type -```jsx -<For each={state.list} fallback={<div>Loading...</div>}> - {(item) => <div>{item}</div>} -</For> +```ts +type Accessor<T> = () => T; + +function For<T extends readonly any[], U extends JSX.Element>(props: { + each: T | undefined | null | false; + fallback?: JSX.Element; + children: (item: T[number], index: Accessor<number>) => U; +}): JSX.Element; ``` -The `each` prop can also be a function that returns a list. This is useful for creating a loop that depends on a state value: +## Props + +### `each` + +- **Type:** `T | undefined | null | false` + +Source list. + +### `fallback` + +- **Type:** `JSX.Element` + +Content rendered when `each` is an empty array, `undefined`, `null`, or `false`. + +### `children` -```jsx -<For each={stateSignal()}>{(item) => <div>{item}</div>}</For> +- **Type:** `(item: T[number], index: Accessor<number>) => U` + +Child function. It receives the current item and an index accessor. + +## Return value + +- **Type:** `JSX.Element` + +## Behavior + +- `<For>` maps items by value identity. +- If the same item value appears at a new position, its rendered node can be moved instead of recreated. +- The `index` argument is an accessor. +- `<For>` uses [`mapArray`](/reference/reactive-utilities/map-array) internally. + +## Examples + +### Basic usage + +```tsx +const items = ["A", "B", "C"]; + +<For each={items} fallback={<div>No items</div>}> + {(item) => <div>{item}</div>} +</For>; ``` -The optional second argument is an index signal: +### Access the index + +```tsx +const items = ["A", "B", "C"]; -```jsx -<For each={state.list} fallback={<div>Loading...</div>}> +<For each={items}> {(item, index) => ( <div> #{index()} {item} </div> )} -</For> +</For>; ``` -## Props +## Related -| Name | Type | Description | -| :--------- | :------------------------------------ | :--------------------------------------------------------------- | -| `each` | `readonly T[]` | The list of items to render. | -| `fallback` | `JSX.Element` | A fallback element to render while the list is loading. | -| `children` | `(item: T, index: () => number) => U` | A callback that returns a JSX element for each item in the list. | +- [`<Index>`](/reference/components/index-component) +- [`mapArray`](/reference/reactive-utilities/map-array) diff --git a/src/routes/reference/components/index-component.mdx b/src/routes/reference/components/index-component.mdx index f3f6b6427..3a1fb7030 100644 --- a/src/routes/reference/components/index-component.mdx +++ b/src/routes/reference/components/index-component.mdx @@ -1,61 +1,100 @@ --- title: <Index> +use_cases: >- + non-keyed lists, index-based rendering, fixed positions, changing values, + simple lists +tags: + - lists + - iteration + - components + - arrays + - index +version: "1.0" +description: >- + Render a list by index with a child function that receives an item accessor + and a numeric index. --- -Non-keyed list iteration (rendered nodes are keyed to an array index). This is useful when there is no conceptual key, like if the data consists of primitives and it is the index that is fixed rather than the value. +`<Index>` renders a list by index. + +## Import ```ts -import { Index } from "solid-js" -import type { JSX } from "solid-js" - -function Index<T, U extends JSX.Element>(props: { - each: readonly T[]; - fallback?: JSX.Element; - children: (item: () => T, index: number) => U; -}): () => U[]; +import { Index } from "solid-js"; ``` -A super simple implementation of this component might look like this: +## Type -```tsx -function Index<T, U extends JSX.Element>(props: { - each: readonly T[]; - fallback?: JSX.Element; - children: (item: () => T, index: number) => U; -}) { - return () => { - const [items, setItems] = createSignal(props.each); - return props.each.map((_, i) => props.children(() => items()[i], i)); - }; -} +```ts +type Accessor<T> = () => T; + +function Index<T extends readonly any[], U extends JSX.Element>(props: { + each: T | undefined | null | false; + fallback?: JSX.Element; + children: (item: Accessor<T[number]>, index: number) => U; +}): JSX.Element; ``` -Here's a look at the implementation of the `Index` component in Solid: +## Props + +### `each` + +- **Type:** `T | undefined | null | false` + +Source list. + +### `fallback` + +- **Type:** `JSX.Element` + +Content rendered when `each` is an empty array, `undefined`, `null`, or `false`. + +### `children` + +- **Type:** `(item: Accessor<T[number]>, index: number) => U` + +Child function. It receives an accessor for the item at that index and the index number. + +## Return value + +- **Type:** `JSX.Element` + +## Behavior + +- `<Index>` maps items by index rather than by value identity. +- The `item` argument is an accessor. +- The `index` argument is a number. +- Updating a value at the same index updates the corresponding rendered item. +- When the array is reordered, rendered positions stay tied to indexes, and `item()` updates to the current value at that index. +- `<Index>` uses [`indexArray`](/reference/reactive-utilities/index-array) internally. + +## Examples + +### Basic usage ```tsx -<Index each={state.list} fallback={<div>Loading...</div>}> - {(item) => <div>{item()}</div>} -</Index> -``` +const items = ["A", "B", "C"]; -Notice that the item is a signal unlike the `For` component. This is because the `Index` component is not keyed to the item itself but rather the index. +<Index each={items} fallback={<div>No items</div>}> + {(item) => <div>{item()}</div>} +</Index>; +``` -Optional second argument is an index number: +### Access the index ```tsx -<Index each={state.list} fallback={<div>Loading...</div>}> - {(item, index) => ( - <div> - #{index} {item()} - </div> - )} -</Index> +const items = ["A", "B", "C"]; + +<Index each={items}> + {(item, index) => ( + <div> + #{index} {item()} + </div> + )} +</Index>; ``` -## Props +## Related -| Name | Type | Description | -| :------- | :------------------------------------ | :-------------------------------------------------------------- | -| each | `readonly T[]` | The array to iterate over. | -| fallback | `JSX.Element` | Optional fallback element to render while the array is loading. | -| children | `(item: () => T, index: number) => U` | The function that renders the children. | \ No newline at end of file +- [`<For>`](/reference/components/for) +- [`indexArray`](/reference/reactive-utilities/index-array) diff --git a/src/routes/reference/components/no-hydration.mdx b/src/routes/reference/components/no-hydration.mdx index 347380d39..94104e743 100644 --- a/src/routes/reference/components/no-hydration.mdx +++ b/src/routes/reference/components/no-hydration.mdx @@ -1,28 +1,66 @@ --- title: <NoHydration> +use_cases: >- + static content, server-rendered content, skipping hydration for a subtree +tags: + - ssr + - hydration + - server-rendering + - components +version: "1.0" +description: >- + Render children during server rendering and skip hydration for that subtree + on the client. --- -The `<NoHydration>` component prevents the client-side hydration process from being applied to its children. -During server-side rendering, components and elements wrapped within `<NoHydration>` will render normally on the server, contributing to the initial HTML output. -However, during client-side hydration, Solid bypasses the hydration process for the content within `<NoHydration>`. -This means that elements within `<NoHydration>` will not have event listeners attached by Solid, and their state will not be managed reactively on the client-side after the initial render. +`<NoHydration>` skips hydration for its subtree on the client. -:::note -Placing a `<Hydration>` component inside `<NoHydration>` has no effect and will not override the `<NoHydration>` behavior. -::: +## Import -## Example - -```tsx +```ts import { NoHydration } from "solid-js/web"; -import { InteractiveComponent, StaticContent } from "./components"; +``` + +## Type + +```ts +function NoHydration(props: { children?: JSX.Element }): JSX.Element; +``` + +## Props + +### `children` + +- **Type:** `JSX.Element` +Content inside the boundary. + +## Return value + +- **Type:** `JSX.Element` + +Returns the children during server and client-only rendering. + +## Behavior + +- During server rendering, children inside `<NoHydration>` render normally. +- During client hydration, Solid leaves the existing server-rendered DOM in place and does not hydrate that subtree. +- In client-only rendering, `<NoHydration>` renders its children normally. +- Interactive behavior inside the boundary does not hydrate on the client. + +## Examples + +### Basic usage + +```tsx function Example() { return ( <div> - <InteractiveComponent /> + <button onClick={() => console.log("hydrated")}>Hydrated button</button> <NoHydration> - <StaticContent /> + <div> + <strong>Rendered on the server without hydration</strong> + </div> </NoHydration> </div> ); diff --git a/src/routes/reference/components/portal.mdx b/src/routes/reference/components/portal.mdx index 1e4984430..432ae43a7 100644 --- a/src/routes/reference/components/portal.mdx +++ b/src/routes/reference/components/portal.mdx @@ -1,40 +1,120 @@ --- title: <Portal> +use_cases: >- + modals, tooltips, overlays, popups, dropdowns, rendering outside parent DOM + hierarchy +tags: + - portal + - dom + - overlays + - tooltips + - components +version: "1.0" +description: >- + Render children into a DOM node outside the parent DOM hierarchy. --- -`<Portal>` is a component that allows you to render children into a DOM node that exists outside the DOM hierarchy of the parent component. +`<Portal>` renders its children into a different DOM node while preserving the Solid component hierarchy. -This is useful when your UI has some elements that need to appear on top of everything else, such as modals and tooltips. +## Import -```tsx -import { Portal } from "solid-js/web" -import type { JSX } from "solid-js" +```ts +import { Portal } from "solid-js/web"; +``` +## Type + +```ts function Portal(props: { - mount?: Node - useShadow?: boolean - isSVG?: boolean - children: JSX.Element -}): Text + mount?: Node; + useShadow?: boolean; + isSVG?: boolean; + ref?: + | HTMLDivElement + | SVGGElement + | ((el: HTMLDivElement | SVGGElement) => void); + children: JSX.Element; +}): Text; ``` -This inserts the element in the mount node. -Useful for inserting Modals outside of the page layout. -Events still propagate through the component hierarchy, however `<Portal>` will only run on the client and has hydration _disabled_. +## Props + +### `mount` + +- **Type:** `Node` + +Mount point for the portal. When omitted, the portal mounts to `document.body`. + +### `useShadow` + +- **Type:** `boolean` + +Creates a shadow root on the portal container when supported. + +### `isSVG` + +- **Type:** `boolean` + +Creates an SVG `<g>` container instead of an HTML `<div>`. + +### `ref` + +- **Type:** `HTMLDivElement | SVGGElement | ((el: HTMLDivElement | SVGGElement) => void)` -The portal is mounted in a `<div>` unless the target is the document head. -`useShadow` places the element in a Shadow Root for style isolation, and `isSVG` is required if inserting into an SVG element so that the `<div>` is not inserted. +Receives the created portal container element. This is a `<div>` by default or a `<g>` when `isSVG` is `true`. + +### `children` + +- **Type:** `JSX.Element` + +Content rendered into the portal container. + +## Return value + +- **Type:** `Text` + +Returns a marker node used to preserve the portal position in the component tree. + +## Behavior + +- `<Portal>` renders its children outside the parent DOM hierarchy, but events still propagate through the Solid component hierarchy. +- When the mount target is not `document.head`, the portal creates a container element and appends it to the mount target. +- When the mount target is `document.head`, the portal inserts its children without creating that container element. +- During server rendering, `<Portal>` returns no output. +- Portals render only on the client and are skipped during hydration. + +## Examples + +### Basic usage ```tsx -<Portal mount={document.getElementById("modal")}> - <div>My Content</div> -</Portal> -``` +import { createSignal, Show } from "solid-js"; -## Props +function App() { + const [open, setOpen] = createSignal(false); + + return ( + <> + <button onClick={() => setOpen(true)}>Open</button> -| Name | Type | Default | Description | -| :---------- | :-------- | :------------ | :------------------------------------------------ | -| `mount` | `Node` | document.body | The DOM node to mount the portal in. | -| `useShadow` | `boolean` | false | Whether to use a Shadow Root for style isolation. | -| `isSVG` | `boolean` | false | Whether the mount node is an SVG element. | + <Show when={open()}> + <Portal> + <div + style={{ + position: "fixed", + top: "2rem", + left: "2rem", + padding: "1rem", + background: "white", + border: "1px solid #ccc", + }} + > + <div>Popup</div> + <button onClick={() => setOpen(false)}>Close</button> + </div> + </Portal> + </Show> + </> + ); +} +``` diff --git a/src/routes/reference/components/show.mdx b/src/routes/reference/components/show.mdx index 1a9788ab0..dd0cf37da 100644 --- a/src/routes/reference/components/show.mdx +++ b/src/routes/reference/components/show.mdx @@ -1,90 +1,119 @@ --- title: <Show> order: 5 +use_cases: >- + conditional rendering, toggling ui, feature flags, loading states, user + permissions, responsive design +tags: + - conditional + - rendering + - components + - control-flow + - ui + - toggle +version: "1.0" +description: >- + Render children when a condition is truthy, with optional fallback content + and keyed behavior. --- -The `<Show>` component is used for conditionally rendering UI elements. -It takes a `when` prop that defines the condition for rendering. -When the `when` prop is truthy, the children of the `<Show>` component are displayed. -Additionally, an optional `fallback` prop can be provided to specify an element that is shown when the condition is falsy. +`<Show>` renders its children when `when` is truthy and renders `fallback` otherwise. -```tsx -import { createSignal, Show } from "solid-js"; - -function Example() { - const [value, setValue] = createSignal(true); - return ( - <div> - <button onClick={() => setValue((prev) => !prev)}>Toggle Show</button> - <Show when={value()} fallback={<div>Fallback Element</div>}> - <div>Child Element</div> - </Show> - </div> - ); -} +## Import + +```ts +import { Show } from "solid-js"; +``` + +## Type + +```ts +type Accessor<T> = () => T; + +function Show<T>(props: { + when: T | undefined | null | false; + keyed?: false; + fallback?: JSX.Element; + children: JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element); +}): JSX.Element; + +function Show<T>(props: { + when: T | undefined | null | false; + keyed: true; + fallback?: JSX.Element; + children: JSX.Element | ((item: NonNullable<T>) => JSX.Element); +}): JSX.Element; ``` -## Keyed rendering +## Props + +### `when` + +- **Type:** `T | undefined | null | false` + +Condition value that determines whether the children are rendered. + +### `keyed` + +- **Type:** `boolean` + +Controls whether function children receive the current value directly instead of an accessor. + +### `fallback` + +- **Type:** `JSX.Element` -When the `keyed` is set to `true`, any change to the `when` prop — including changes in its reference — will cause the `<Show>` component to re-render its children. +Content rendered when `when` is falsy. + +### `children` + +- **Type:** `JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element) | ((item: NonNullable<T>) => JSX.Element)` + +Content rendered when `when` is truthy. + +## Return value + +- **Type:** `JSX.Element` + +Returns the rendered children or `fallback` content. + +## Behavior + +- With `keyed` omitted or `false`, `<Show>` updates only when the truthiness of `when` changes. Replacing one truthy value with another truthy value does not recreate the child block, and function children receive an accessor that can only be read while the condition remains truthy. +- With `keyed={true}`, changes to the `when` value trigger a new render even when the value remains truthy, and function children receive the value directly. +- Function children are wrapped in [`untrack`](/reference/reactive-utilities/untrack). + +## Examples + +### Basic usage ```tsx -import { createSignal, Show } from "solid-js"; - -function KeyedExample() { - const [user, setUser] = createSignal({ name: "John Wick" }); - - function update() { - // This operation changes the reference of the user object. - setUser({ ...user() }); - } - - return ( - <div> - <button onClick={update}>Update</button> - <Show when={user()} keyed> - <p>Name: {user().name}</p> - {/* Updates shown with each click */} - <p>Last updated: {Date.now()}</p> - </Show> - </div> - ); -} +const loading = () => false; + +<Show when={!loading()} fallback={<div>Loading...</div>}> + <div>Loaded</div> +</Show>; ``` -## Render function +### Function child -The `<Show>` component can also accept a render function as its child. -In this case, the first argument of the render function is an _accessor_ to the `when` prop. -However, when the `keyed` prop is set to `true`, the argument is the `when` prop itself instead of an accessor. +```tsx +const user = () => ({ name: "Ada" }); -When a render function is used, it is internally wrapped with [`untrack`](/reference/reactive-utilities/untrack). -As a result, signals accessed directly within the render function's scope will not react to updates. +<Show when={user()}>{(user) => <div>{user().name}</div>}</Show>; +``` -For example, in the following code, the count displayed in the first `<Show>` component does not update when the `count` signal changes. -However, the second `<Show>` component does update since the `count` signal is accessed within a JSX element, which creates a tracking scope. +### Keyed function child ```tsx -import { createSignal, Show } from "solid-js"; - -function RenderFunctionExample() { - const [count, setCount] = createSignal(0); - return ( - <div> - <button onClick={() => setCount((c) => c + 1)}>Increment</button> - {/* This does not update. */} - <Show when={count()}>{(c) => count()}</Show> - {/* This will update. */} - <Show when={count()}>{(c) => <>{count()}</>}</Show> - </div> - ); -} +const user = () => ({ name: "Ada" }); + +<Show when={user()} keyed> + {(user) => <div>{user.name}</div>} +</Show>; ``` -## Props +## Related -| Name | Type | Description | -| :--------- | :-------------------------------- | :---------------------------------------------------- | -| `when` | `T \| undefined \| null \| false` | The condition value. | -| `keyed` | `boolean` | Whether to key the block to the value of when. | -| `fallback` | `JSX.Element` | The fallback to render when the `when` prop is falsy. | +- [`untrack`](/reference/reactive-utilities/untrack) +- [`<Switch> / <Match>`](/reference/components/switch-and-match) diff --git a/src/routes/reference/components/suspense-list.mdx b/src/routes/reference/components/suspense-list.mdx index 38bc42b37..68604cca2 100644 --- a/src/routes/reference/components/suspense-list.mdx +++ b/src/routes/reference/components/suspense-list.mdx @@ -1,52 +1,116 @@ --- title: <SuspenseList> order: 5 +use_cases: >- + coordinating suspense boundaries, controlling reveal order, coordinating + fallback display +tags: + - suspense + - async + - loading + - coordination + - experimental + - components +version: "1.0" +description: >- + Coordinate how multiple suspense boundaries reveal their content. --- -SuspenseList allows for coordinating multiple parallel Suspense and SuspenseList components. It controls the order in which content is revealed to reduce layout thrashing and has an option to collapse or hide fallback states. +:::[warning] +This is an experimental component +::: -```ts -import { SuspenseList } from "solid-js" -import type { JSX } from "solid-js" +`<SuspenseList>` coordinates how multiple child suspense boundaries reveal their content. -function SuspenseList(props: { - children: JSX.Element - revealOrder: "forwards" | "backwards" | "together" - tail?: "collapsed" | "hidden" -}): JSX.Element -``` +## Import -**Note**: SuspenseList is still in the experimental stage and does not have full `SSR` support. +```ts +import { SuspenseList } from "solid-js"; +``` -Here's an example of how to use SuspenseList: +## Type -```tsx -<SuspenseList revealOrder="forwards" tail="collapsed"> - <ProfileDetails user={resource.user} /> - <Suspense fallback={<h2>Loading posts...</h2>}> - <ProfileTimeline posts={resource.posts} /> - </Suspense> - <Suspense fallback={<h2>Loading fun facts...</h2>}> - <ProfileTrivia trivia={resource.trivia} /> - </Suspense> -</SuspenseList> +```ts +function SuspenseList(props: { + children: JSX.Element; + revealOrder: "forwards" | "backwards" | "together"; + tail?: "collapsed" | "hidden"; +}): JSX.Element; ``` ## Props -| Name | Type | Default | Description | -| ------------- | ----------------------------------------- | ------------ | --------------------------------------------------------------------------- | -| `revealOrder` | `"forwards" \| "backwards" \| "together"` | `"forwards"` | Determines the order in which the SuspenseList children should be revealed. | -| `tail` | `"collapsed" \| "hidden"` | `undefined` | TODO | +### `children` + +- **Type:** `JSX.Element` + +Suspense and suspense-list children inside the list. ### `revealOrder` -`"forwards" | "backwards" | "together"` +- **Type:** `"forwards" | "backwards" | "together"` -- `"forwards"`: Reveals each item in the list once the previous item has finished rendering. This is the default. -- `"backwards"`: Reveals each item in the list once the next item has finished rendering. -- `"together"`: Reveals all items in the list at the same time. +Order used to reveal child boundaries. ### `tail` -`"collapsed" | "hidden"` +- **Type:** `"collapsed" | "hidden"` + +Controls fallback visibility for later items after the first still-pending item in ordered reveal modes. + +## Return value + +- **Type:** `JSX.Element` + +Returns the coordinated suspense boundaries. + +## Behavior + +- `revealOrder="forwards"` reveals items from first to last. +- `revealOrder="backwards"` reveals items from last to first. +- `revealOrder="together"` reveals all items only after all coordinated boundaries are ready. +- With `tail="collapsed"`, the first still-pending item can keep its fallback visible, while later pending items hide theirs. +- With `tail="hidden"`, pending items after the first still-pending item hide their fallbacks. +- `<SuspenseList>` coordinates child suspense boundaries. It does not suspend by itself. + +## Examples + +### Basic usage + +```tsx +import { createResource, Suspense } from "solid-js"; + +const delayed = async <T,>(value: T, ms: number) => { + await new Promise((resolve) => setTimeout(resolve, ms)); + return value; +}; + +function ProfileDetails() { + const [user] = createResource(() => delayed({ name: "Ada" }, 500)); + return <h2>{user()?.name}</h2>; +} + +function ProfileTimeline() { + const [posts] = createResource(() => delayed(["First post"], 1000)); + return ( + <ul> + {posts()?.map((post) => ( + <li>{post}</li> + ))} + </ul> + ); +} + +<SuspenseList revealOrder="forwards" tail="collapsed"> + <Suspense fallback={<h2>Loading profile...</h2>}> + <ProfileDetails /> + </Suspense> + <Suspense fallback={<h2>Loading posts...</h2>}> + <ProfileTimeline /> + </Suspense> +</SuspenseList>; +``` + +## Related + +- [`<Suspense>`](/reference/components/suspense) diff --git a/src/routes/reference/components/suspense.mdx b/src/routes/reference/components/suspense.mdx index dd433d1dc..a192b2cc8 100644 --- a/src/routes/reference/components/suspense.mdx +++ b/src/routes/reference/components/suspense.mdx @@ -1,148 +1,120 @@ --- title: <Suspense> order: 5 +use_cases: >- + async data, loading states, resources, lazy-loaded components, asynchronous + subtrees +tags: + - suspense + - async + - loading + - resources + - components +version: "1.0" +description: >- + Render fallback content while suspense-tracked async dependencies under the boundary are pending. --- -A component that tracks all resources read under it and shows a fallback placeholder state until they are resolved. What makes `Suspense` different than `Show` is that it is non-blocking in the sense that both branches exist at the same time even if not currently in the DOM. This means that the fallback can be rendered while the children are loading. This is useful for loading states and other asynchronous operations. +`<Suspense>` renders `fallback` while suspense-tracked async dependencies under its boundary are pending. -```tsx -import { Suspense } from "solid-js" -import type { JSX } from "solid-js" +## Import -function Suspense(props: { - fallback?: JSX.Element - children: JSX.Element -}): JSX.Element +```ts +import { Suspense } from "solid-js"; +``` + +## Type +```ts +function Suspense(props: { + fallback?: JSX.Element; + children: JSX.Element; +}): JSX.Element; ``` -Here's an example of a `Suspense` component that shows a loading spinner while the `User` component is loading. +## Props -```tsx -<Suspense fallback={<LoadingSpinner />}> - <AsyncComponent /> -</Suspense> +### `fallback` -``` +- **Type:** `JSX.Element` -## Nested Suspense - -`<Suspense>` is triggered whenever a resource is read under the suspense boundary, and waits until all resources read -under the suspense boundary have resolved. Often, however, you may not want this behavior. For example, if your entire page is -wrapped in suspense, you may not want a resource that only populates a certain part of the page to trigger suspense. -In that case, you can wrap that resource usage in its own suspense boundary, and the resource will only trigger the -closest suspense boundary. - -For example, in the code below, only the `title()` resource will trigger the top level suspense boundary, and only the `data()` -resource will trigger the nested suspense boundary: - -```jsx -const MyComponent = () => { - const [title] = createResource(async () => { /* fetcher code here */ }) - const [data] = createResource(async () => { /* fetcher code here */ }) - <Suspense> - <h1>{title()}</h1> - <Suspense> - <DataComponent>{data()}</DataComponent> - </Suspense> - </Suspense> -} +Content rendered while suspense-tracked async dependencies are pending. -``` +### `children` -## The purpose of {"<Suspense>"} +- **Type:** `JSX.Element` -To understand the purpose of suspense, let's consider the following code snippets. These snippets will have some drawbacks which we will solve by using suspense. We will also see how it is possible to use `Suspense` yet not reap its benefits. +Subtree inside the suspense boundary. -Our example use case is to display a user profile. A naive snippet would look like this: +## Return value -```jsx -const MyComponentWithOptionalChaining = () => { - const [profile] = createResource(async () => { - /* fetcher code here */ - }) - return ( - <> - <div>{profile()?.name}</div> - <div>{profile()?.email}</div> - </> - ) -} +- **Type:** `JSX.Element` -``` +Returns the rendered subtree or `fallback` content depending on pending suspense-tracked async dependencies. -In this code, `profile()` starts as `undefined`, and when the fetcher code finishes, resolves to an object with `name` and `email` properties. Although the resource has not resolved yet, the two `div`s are already created and attached to the document body, albeit with empty text nodes. Once the resource resolves, the `div`s are updated with the appropriate data. - -The downside of this approach is that the user is shown an empty component - let's see if we can do better than that in this next snippet: - -```jsx -const MyComponentWithShow = () => { - const [profile] = createResource(async () => { - /* fetcher code here */ - }) - return ( - <Show when={profile()} fallback={<div>fetching user data</div>}> - <div>{profile().name}</div> - <div>{profile().email}</div> - </Show> - ) -} +## Behavior -``` +- When a suspense-tracked async dependency is read inside the boundary, `<Suspense>` renders `fallback` until the pending work resolves. +- `<Suspense>` is non-blocking: the subtree can continue running and create reactive owners before the boundary reveals the resolved content in the DOM. +- Nested suspense boundaries handle suspense-tracked async dependencies under the nearest boundary. +- `onMount` and `createEffect` inside the suspended subtree run after the boundary resolves. + +## Examples -In this snippet, we first show a fallback when the resource hasn't resolved yet, and then switch to showing the profile data once it has. This results in a better user experience. +### Basic usage -On the other hand, there is a slight downside to this approach. In our first example (using optional chaining), the divs were created immediately, and once the resource resolves all that is needed to be done is to fill in the text of the `div`s. But in our second example (using `<Show>`), the `div`s are only created once the resource has resolved, which means there is more work that needs to be done after the resource has resolved before the data can be shown to the user (of course, in this toy example the amount of DOM work is relatively trivial). +```tsx +import { createResource } from "solid-js"; -We can have the best of both worlds by using {"<Suspense>"}: +const fetchMessage = async () => { + await new Promise((resolve) => setTimeout(resolve, 1000)); + return "Loaded"; +}; -```jsx -const MyComponentWithSuspense = () => { - const [profile] = createResource(async () => { - /* fetcher code here */ - }) - return ( - <Suspense fallback={<div>fetching user data</div>}> - <div>{profile()?.name}</div> - <div>{profile()?.email}</div> - </Suspense> - ) +function AsyncMessage() { + const [message] = createResource(fetchMessage); + return <p>{message()}</p>; } + +<Suspense fallback={<p>Loading...</p>}> + <AsyncMessage /> +</Suspense>; ``` -In this case, the `div`s are created immediately, but instead of being attached to the document body, the fallback is shown. Once the resource resolves, the text in the `div`s is updated, and then they are attached to the document (and the fallback removed). - -It is important to note that _the execution of the component does not pause_ when using suspense. Instead, when a resource is read under a suspense boundary, it ensures that the nodes are not attached to the document until after the resource has resolved. Suspense allows us to have the best of both worlds: do as much work as we can _before_ the resource resolves, and also show a fallback until then. - -With this in mind, we can understand that there isn't much gained from suspense in the following code: - -```jsx -const MyComponentWithSuspenseAndShow = () => { - const [profile] = createResource(async () => { - /* fetcher code here */ - }) - return ( - <Suspense fallback={<div>fetching user data</div>}> - <Show when={profile()}> - <div>{profile().name}</div> - <div>{profile().email}</div> - </Show> - </Suspense> - ) +### Nested suspense + +```tsx +import { createResource } from "solid-js"; + +const fetchTitle = async () => { + await new Promise((resolve) => setTimeout(resolve, 500)); + return "Profile"; +}; + +const fetchDetails = async () => { + await new Promise((resolve) => setTimeout(resolve, 1000)); + return "Details loaded"; +}; + +function Title() { + const [title] = createResource(fetchTitle); + return <h1>{title()}</h1>; } -``` -In this code, we don't create _any_ DOM nodes inside {"<Suspense>"} before the resource resolves, so it is pretty much the same as the second example where we only used `<Show>`. +function Details() { + const [details] = createResource(fetchDetails); + return <p>{details()}</p>; +} -:::note - Suspense is triggered by reading a resource inside the {"<Suspense>"}{" "} - boundary. Components wrapped with suspense still run fully, just as they would - without suspense. However, code wrapped in `onMount` and `createEffect` only - run after the resource resolves. -::: +<Suspense fallback={<div>Loading page...</div>}> + <Title /> + <Suspense fallback={<div>Loading details...</div>}> + <Details /> + </Suspense> +</Suspense>; +``` -## Props +## Related -| Name | Type | Description | -| :--------- | :------------ | :--------------------------------------------------------------- | -| `fallback` | `JSX.Element` | The fallback component to render while the children are loading. | +- [`<SuspenseList>`](/reference/components/suspense-list) +- [`createResource`](/reference/basic-reactivity/create-resource) diff --git a/src/routes/reference/components/switch-and-match.mdx b/src/routes/reference/components/switch-and-match.mdx index f733467b5..cbcb1384b 100644 --- a/src/routes/reference/components/switch-and-match.mdx +++ b/src/routes/reference/components/switch-and-match.mdx @@ -1,68 +1,131 @@ --- title: <Switch> / <Match> order: 5 +use_cases: >- + multiple conditions, routing, complex branching, state machines, multi-way + decisions, replacing if-else chains +tags: + - conditional + - routing + - control-flow + - components + - branching + - switch +version: "1.0" +description: >- + Render the first matching branch from a set of mutually exclusive conditions. --- -Useful for when there are more than 2 mutual exclusive conditions. It is a more flexible version of the if-else-if-else-if-else-... chain. +`<Switch>` renders the first child `<Match>` whose `when` prop is truthy. `<Match>` can render JSX directly or accept a function child. + +## Import ```ts -import { Switch, Match } from "solid-js" -import type { MatchProps, JSX } from "solid-js" +import { Match, Switch } from "solid-js"; +``` + +## Type + +```ts +type Accessor<T> = () => T; function Switch(props: { - fallback?: JSX.Element - children: JSX.Element -}): () => JSX.Element - -type MatchProps<T> = { - when: T | undefined | null | false - children: JSX.Element | ((item: T) => JSX.Element) -} -function Match<T>(props: MatchProps<T>) + fallback?: JSX.Element; + children: JSX.Element; +}): JSX.Element; + +function Match<T>(props: { + when: T | undefined | null | false; + keyed?: false; + children: JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element); +}): JSX.Element; + +function Match<T>(props: { + when: T | undefined | null | false; + keyed: true; + children: JSX.Element | ((item: NonNullable<T>) => JSX.Element); +}): JSX.Element; ``` -A super simple implementation of this component would be: +## `<Switch>` props -```tsx -function Switch(props) { - let children = props.children +### `fallback` - if (!Array.isArray(children)) children = [children] +- **Type:** `JSX.Element` - for (let i = 0; i < children.length; i++) { - const child = children[i] - if (child.props.when) return child - } +Content rendered when no child `<Match>` has a truthy `when` value. - return props.fallback -} -``` +### `children` -For example, it can be used to perform basic routing: +- **Type:** `JSX.Element` -```tsx -<Switch fallback={<div>Not Found</div>}> - <Match when={state.route === "home"}> - <Home /> - </Match> - <Match when={state.route === "settings"}> - <Settings /> - </Match> -</Switch> -``` +Child `<Match>` elements. + +## `<Match>` props + +### `when` + +- **Type:** `T | undefined | null | false` + +Condition value for the branch. -Match also supports function children to serve as keyed flow. +### `keyed` -## Props +- **Type:** `boolean` -### Switch +Controls whether function children receive the current value directly instead of an accessor. -| Name | Type | Default | Description | -| ---------- | ------------- | ----------- | -------------------------------------------------------------------------------- | -| `fallback` | `JSX.Element` | `undefined` | The fallback element to render if no `Match` component has a truthy `when` prop. | +### `children` + +- **Type:** `JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element) | ((item: NonNullable<T>) => JSX.Element)` + +Content rendered when the branch matches. + +## Return value + +- **Type:** `JSX.Element` + +Returns the selected branch or the `fallback` content. + +## Behavior + +- `<Switch>` evaluates its child `<Match>` elements in order and renders only the first truthy branch. +- If no branch matches, `<Switch>` renders `fallback`. +- Function children in `<Match>` are wrapped in [`untrack`](/reference/reactive-utilities/untrack). +- With `keyed={false}`, function children in `<Match>` receive an accessor that can only be read while that branch remains selected. Replacing one truthy value with another truthy value does not recreate the child block. +- With `keyed={true}`, function children receive the current value directly, and changing the `when` value recreates the child block even when it remains truthy. + +## Examples + +### Basic usage + +```tsx +import { createSignal } from "solid-js"; + +const [status, setStatus] = createSignal<"loading" | "success" | "error">( + "loading" +); + +<> + <button onClick={() => setStatus("loading")}>Loading</button> + <button onClick={() => setStatus("success")}>Success</button> + <button onClick={() => setStatus("error")}>Error</button> + + <Switch fallback={<p>Unknown status</p>}> + <Match when={status() === "loading"}> + <p>Loading...</p> + </Match> + <Match when={status() === "success"}> + <p>Saved</p> + </Match> + <Match when={status() === "error"}> + <p>Failed</p> + </Match> + </Switch> +</>; +``` -### Match +## Related -| Name | Type | Default | Description | -| ------ | --------------------------------- | ----------- | ------------------------------------------------------------------------- | -| `when` | `T \| undefined \| null \| false` | `undefined` | The condition to check. If it is truthy, the `children` will be rendered. | +- [`<Show>`](/reference/components/show) +- [`untrack`](/reference/reactive-utilities/untrack) diff --git a/src/routes/reference/jsx-attributes/attr.mdx b/src/routes/reference/jsx-attributes/attr.mdx index 934b911fe..5775c4801 100644 --- a/src/routes/reference/jsx-attributes/attr.mdx +++ b/src/routes/reference/jsx-attributes/attr.mdx @@ -1,15 +1,50 @@ --- -title: attr:* +title: "attr:*" +use_cases: >- + custom elements, forcing attribute assignment, writing HTML attributes +tags: + - attributes + - dom + - custom-elements +version: "1.0" +description: >- + Force a JSX key to be written as an attribute instead of a property. --- -Forces the prop to be treated as an attribute instead of a property. -Useful for Web Components where you want to set attributes. - -```tsx -<my-element attr:status={props.status} /> -``` +`attr:*` forces a JSX key to be written as an attribute instead of a property. :::note[Strong-Typing Custom Attributes] Type definitions are required when using TypeScript. See the[TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples. ::: + +## Syntax + +```tsx +<my-element attr:status={value} /> +``` + +## Value + +- **Type:** attribute value + +Value passed to normal attribute serialization after the `attr:` prefix is removed. + +## Behavior + +- `attr:name={value}` writes the value to the `name` attribute after the `attr:` prefix is removed. +- In the DOM runtime, `attr:name={undefined}` or `attr:name={null}` removes the attribute. +- In SSR output, the stripped attribute name and escaped value are written as HTML. + +## Examples + +### Basic usage + +```tsx +<my-element attr:status={props.status} /> +``` + +## Related + +- [`prop:*`](/reference/jsx-attributes/prop) +- [`bool:*`](/reference/jsx-attributes/bool) diff --git a/src/routes/reference/jsx-attributes/bool.mdx b/src/routes/reference/jsx-attributes/bool.mdx index 94a682099..6acd955b2 100644 --- a/src/routes/reference/jsx-attributes/bool.mdx +++ b/src/routes/reference/jsx-attributes/bool.mdx @@ -1,26 +1,59 @@ --- -title: bool:* +title: "bool:*" +use_cases: >- + boolean attributes, custom elements, controlling attribute presence +tags: + - attributes + - boolean + - custom-elements +version: "1.0" +description: >- + Control whether an attribute is present by writing through `bool:*`. --- -`bool:*` controls the presence of an attribute in an element. -When the value is `truthy` it adds the `attribute` to the element. -Alternatively, when the value is `falsy` it removes the `attribute` from the element. -This attribute is most useful for Web Components. +`bool:*` controls whether an attribute is present on an element. + +:::note[Strong-Typing Custom Boolean Attributes] +Type definitions are required when using TypeScript. +See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples. +::: + +## Syntax ```tsx -<my-element bool:status={prop.value} /> +<my-element bool:status={value} /> ``` +## Value + +- **Type:** any truthy or falsy value + +Any JavaScript value is coerced by truthiness. + +## Behavior + +- `bool:name={value}` writes `name=""` when `value` is truthy. +- `bool:name={value}` removes `name` when `value` is falsy. +- SSR output follows the same presence-or-absence behavior. + +## Examples + +### Basic usage + +```tsx +<my-element bool:status={props.value} /> +``` + +### Resulting markup + ```tsx -// Assuming `prop.value` is `truthy`, then it becomes +// props.value is truthy <my-element status /> -// And when `falsy`, then it becomes +// props.value is falsy <my-element /> - ``` -:::note[Strong-Typing Custom Boolean Attributes] -Type definitions are required when using TypeScript. -See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples. -::: +## Related + +- [`attr:*`](/reference/jsx-attributes/attr) diff --git a/src/routes/reference/jsx-attributes/classlist.mdx b/src/routes/reference/jsx-attributes/classlist.mdx index e98d52575..16515a269 100644 --- a/src/routes/reference/jsx-attributes/classlist.mdx +++ b/src/routes/reference/jsx-attributes/classlist.mdx @@ -1,29 +1,49 @@ --- title: classList order: 1 +use_cases: >- + toggling classes, conditional classes, reactive class updates +tags: + - styling + - css + - classes + - reactive +version: "1.0" +description: >- + Toggle element classes from an object of class names and boolean values. --- -Solid offers two attributes to set the class of an element: `class` and `classList`. +:::warning +`className` was deprecated in Solid 1.4 in favor of `class`. +::: + +`classList` toggles element classes from an object of class names and boolean values. -First, `class` can be set like other attributes. For example: +## Syntax ```tsx -// Two static classes -<div class="active editing" /> +<div classList={{ active: state.active }} /> +``` -// One dynamic class, deleting class attribute if it's not needed -<div class={state.active ? 'active' : undefined} /> +## Value -// Two dynamic classes -<div class={`${state.active ? 'active' : ''} ${state.currentId === row.id ? 'editing' : ''}`} /> -``` +- **Type:** `Record<string, boolean | undefined>` -:::note - Note that <code>className</code> was deprecated in Solid 1.4 in favor of {" "} - <code>class</code>. -::: +Object whose keys are class names and whose values control whether each class is present. -Alternatively, the `classList` pseudo-attribute lets you specify an object, where each key is a class and the value is treated as a boolean representing whether to include that class. For example (matching the last example): +## Behavior + +- Each key is treated as a class name. +- Keys can contain multiple space-separated class names, which are toggled individually. +- Truthy values add the class and falsy values remove it. +- Updates are applied per class rather than replacing the whole `class` attribute. +- `classList` works through normal DOM prop assignment, including prop spreads and `<Dynamic>` when it renders an intrinsic element. +- If both `class` and `classList` are reactive, updates to `class` can overwrite classes managed by `classList`. +- SSR output merges `class`, `className`, and `classList` into the emitted `class` attribute. + +## Examples + +### Basic usage ```tsx <div @@ -34,23 +54,12 @@ Alternatively, the `classList` pseudo-attribute lets you specify an object, wher /> ``` -This example compiles to a render effect that dynamically calls [element.classList.toggle](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle) to turn each class on or off, only when the corresponding boolean changes. For example, when `state.active` becomes true [false], the element gains [loses] the `active` class. - -The value passed into `classList` can be any expression (including a signal getter) that evaluates to an appropriate object. Some examples: +### Dynamic class name ```tsx -// Dynamic class name and value <div classList={{ [className()]: classOn() }} /> - -// Signal class list -const [classes, setClasses] = createSignal({}) -setClasses((c) => ({ ...c, active: true })) -<div classList={classes()} /> ``` -While possible, mixing `class` and `classList` in Solid can lead to unexpected behavior. -The safest approach is to use a static string (or nothing) for `class` and keep `classList` reactive. -You can also use a static computed value for class, such as `class={baseClass()}`, however you must make sure it comes before any `classList` pseudo-attributes. -If both `class` and `classList` are reactive, changes to `class` will overwrite the entire `class` attribute, potentially undoing any updates made by `classList`. +## Related -Because classList is a compile-time pseudo-attribute, it does not work in a prop spread like `<div {...props} />` or in `<Dynamic>`. +- [`class`](/reference/jsx-attributes/class) diff --git a/src/routes/reference/jsx-attributes/innerhtml.mdx b/src/routes/reference/jsx-attributes/innerhtml.mdx index 9c8162a8c..313d60592 100644 --- a/src/routes/reference/jsx-attributes/innerhtml.mdx +++ b/src/routes/reference/jsx-attributes/innerhtml.mdx @@ -1,12 +1,50 @@ --- title: innerHTML +use_cases: >- + rendering HTML strings, replacing element children with parsed markup +tags: + - html + - dom + - security + - markup +version: "1.0" +description: >- + Set an element's `innerHTML` property from JSX. --- -The `innerHTML` attribute is equivalent to the [`innerHTML` DOM property](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML). -This attribute replaces all existing nodes of the element with new nodes generated by parsing the provided string as HTML. +`innerHTML` sets an element's `innerHTML` property. -:::caution +## Syntax -Using `innerHTML` with unsanitized user-supplied data can introduce security vulnerabilities. +```tsx +<div innerHTML={html} /> +``` + +## Value + +- **Type:** `string` + +HTML string inserted as raw markup into the element. + +## Behavior + +- Setting `innerHTML` replaces the element's existing children with nodes parsed from the string. +- The value is written through the DOM `innerHTML` property. +- In SSR output, the HTML string is emitted as child content without escaping. +- Unlike [`textContent`](/reference/jsx-attributes/textcontent), `innerHTML` parses markup instead of inserting plain text. +:::caution +Using `innerHTML` with unsanitized user-supplied data can introduce security vulnerabilities. ::: + +## Examples + +### Basic usage + +```tsx +<div innerHTML={"<strong>Hello</strong>"} /> +``` + +## Related + +- [`textContent`](/reference/jsx-attributes/textcontent) diff --git a/src/routes/reference/jsx-attributes/on.mdx b/src/routes/reference/jsx-attributes/on.mdx index c7e8ee4ec..23a55ab7d 100644 --- a/src/routes/reference/jsx-attributes/on.mdx +++ b/src/routes/reference/jsx-attributes/on.mdx @@ -1,37 +1,87 @@ --- -title: on:* +title: "on:*" order: 4 +use_cases: >- + direct event listeners, custom event names, event listener options +tags: + - events + - listeners + - dom + - capture + - passive +version: "1.0" +description: >- + Attach an event listener directly to an element with `addEventListener`. --- -For events with capital letters, listener options, or if you need to attach event handlers directly to a DOM element instead of optimized delegating via the document, use `on:*` in place of `on*`. +`on:*` attaches an event listener directly to an element with `addEventListener`. + +## Syntax ```tsx -<div on:DOMContentLoaded={(e) => console.log("Welcome!")} /> +<div on:wheel={handler} /> ``` -This directly attaches an event handler (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`. +## Value -:::note -<span>New in v1.9.0</span> -::: +- **Type:** event handler function or object with `handleEvent` and optional `AddEventListenerOptions` + +Listener passed to `addEventListener`. + +## Behavior + +- `on:name={handler}` attaches a listener for the event named `name`. +- The listener is attached directly to the element instead of using Solid's delegated event system. +- Event names keep the text after `on:` exactly as written. +- Use `on:*` when you need exact event casing, such as case-sensitive custom events. +- When the value changes, Solid removes the previous direct listener and adds the new one. +- Listener options such as `once`, `passive`, `capture`, and `signal` can be provided by passing an object that implements `handleEvent`. +- `oncapture:*` remains available as a deprecated capture-specific form. + +## Examples + +### Basic usage + +```tsx +const [message, setMessage] = createSignal("Waiting"); +let el; + +<> + <button + onClick={() => + el.dispatchEvent(new CustomEvent("MyEvent", { detail: "Hello" })) + } + > + Dispatch event + </button> -An aditional special syntax that allows full control of [`capture`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#capture), [`passive`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive), [`once`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#once) and [`signal`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal) is an intersection or combination of `EventListenerObject` & `AddEventListenerOptions`, as follows: + <div on:MyEvent={(e) => setMessage(e.detail)} ref={el} /> + <p>{message()}</p> +</>; +``` + +### Listener options ```tsx +const [count, setCount] = createSignal(0); + const handler = { - handleEvent(e) { - console.log(e) + handleEvent() { + setCount((count) => count + 1); }, - once:true, - passive:false, - capture:true -} + once: true, +}; -<div on:wheel={handler} /> +<> + <button on:click={handler}>Click me</button> + <p>Clicked {count()} time(s)</p> +</>; +``` -// or inline +:::note +The object-listener form was added in Solid 1.9.0. It is useful when you need options such as `once`, `passive`, `capture`, or `signal`. +::: -<div on:click={{passive:true, handleEvent(e) { console.log("Weeeee!")}}} /> -``` +## Related -This new syntax replaces the now deprecated `oncapture:` and it's future proof for any posible new event listener options. +- [`on*`](/reference/jsx-attributes/on_) diff --git a/src/routes/reference/jsx-attributes/on_.mdx b/src/routes/reference/jsx-attributes/on_.mdx index c274af477..dccfa80ca 100644 --- a/src/routes/reference/jsx-attributes/on_.mdx +++ b/src/routes/reference/jsx-attributes/on_.mdx @@ -1,35 +1,60 @@ --- title: on* order: 3 +use_cases: >- + delegated UI events, click handlers, input handlers, keyboard handlers +tags: + - events + - handlers + - delegation + - dom +version: "1.0" +description: >- + Attach an event handler with Solid's delegated event system when the event is + supported. --- -Event handlers in Solid typically take the form of `onclick` or `onClick` depending on style. +`on*` attaches an event handler using Solid's delegated event system when the event is supported. + +## Syntax ```tsx -<div onClick={(e) => console.log(e.currentTarget)} /> +<div onClick={handler} /> ``` -Conceptually, this example attaches a `click` event listener (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`. However, Solid actually handles common UI events that bubble and are composed (such as `click`) at the document level, and then synthetically implements delegation (capturing and bubbling). This improves performance for these common events by reducing the number of event handlers. +## Value -Note that `onClick` handles the event `click`; in general, event names get mapped to lower case. If you need to work with event names containing capital letters, or use listener options such once, passive, capture see [`on:`](/reference/jsx-attributes/on) which attaches event handlers directly (also avoiding fancy delegation via document). +- **Type:** event handler function or `[handler, data]` -Solid also supports passing a two-element array to the event handler to bind a value to the first argument of the event handler. This doesn't use `bind` or create an additional closure, so it is a highly optimized way of delegating events. +Event handler, or a handler/data pair for delegated binding. -```tsx -function handler(itemId, e) { - /*...*/ -} +## Behavior + +- Events in Solid's delegated event set use document-level delegation; other `on*` handlers attach directly to the element. +- Event names are mapped to lower case, so `onClick` listens to `click`. +- The two-element array form passes the first item as bound data to the handler. +- Delegated bindings are not reactive and are not rebound automatically when the handler reference changes. +- `onInput` uses the native input event, and `onChange` uses the native change event. +- For direct element listeners, custom event casing, or listener options, use [`on:*`](/reference/jsx-attributes/on). + +## Examples -<ul> - <For each={state.list}>{(item) => <li onClick={[handler, item.id]} />}</For> -</ul>; +### Basic usage + +```tsx +<div onClick={(e) => console.log(e.currentTarget)} /> ``` -Events are never rebound and the bindings are not reactive, as it is expensive to attach and detach listeners. Since event handlers are called like any other function each time an event fires, there is no need for reactivity; shortcut your handler if desired. +### Handler and bound data ```tsx -// if defined, call it; otherwise don't. -<div onClick={() => props.handleClick?.()} /> +function handler(itemId, e) { + console.log(itemId, e); +} + +<For each={state.list}>{(item) => <li onClick={[handler, item.id]} />}</For>; ``` -Note that `onChange` and `onInput` work according to their native behavior (unlike, say, React). [`onInput`](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) will fire immediately after the value has changed; for most `<input>` fields, [`onChange`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) will only fire after the field loses focus. The event's `currentTarget` refers to the element that the event was attached to, while `target` gives the element that actually triggered the event (e.g. the user clicked on). +## Related + +- [`on:*`](/reference/jsx-attributes/on) diff --git a/src/routes/reference/jsx-attributes/once.mdx b/src/routes/reference/jsx-attributes/once.mdx index bd8633755..2e110b5d6 100644 --- a/src/routes/reference/jsx-attributes/once.mdx +++ b/src/routes/reference/jsx-attributes/once.mdx @@ -1,17 +1,41 @@ --- title: "@once" order: 5 +use_cases: >- + non-reactive JSX expressions, compile-time opt-out from reactive wrapping +tags: + - compiler + - jsx + - optimization +version: "1.0" +description: >- + Mark a JSX expression as static at compile time. --- -Solid's compiler uses a heuristic for reactive wrapping and lazy evaluation of JSX expressions. Does it contain a function call, a property access, or JSX? If yes we wrap it in a getter when passed to components or in an effect if passed to native elements. +`/*@once*/` is a compiler marker comment that marks a JSX expression as static. -Knowing this heuristic and its limitations, we can reduce overhead of things we know will never change by accessing them outside of the JSX. A lone variable will never be wrapped. We can also tell the compiler not to wrap them by starting the expression with a comment decorator `/* @once */`. +## Syntax + +```tsx +<MyComponent value={/*@once*/ expr} /> +``` + +## Behavior + +- `/*@once*/` applies to the expression that follows it. +- Marked expressions are compiled as static and do not update when reactive dependencies change. +- It can be used in props and in children. +- Some compiler transforms, including parts of `classList` and `style` handling, do not fully respect `/*@once*/`. + +## Examples + +### Prop value ```tsx <MyComponent static={/*@once*/ state.wontUpdate} /> ``` -This also works on children. +### Child value ```tsx <MyComponent>{/*@once*/ state.wontUpdate}</MyComponent> diff --git a/src/routes/reference/jsx-attributes/prop.mdx b/src/routes/reference/jsx-attributes/prop.mdx index 3195a2275..f1265b830 100644 --- a/src/routes/reference/jsx-attributes/prop.mdx +++ b/src/routes/reference/jsx-attributes/prop.mdx @@ -1,15 +1,51 @@ --- -title: prop:* +title: "prop:*" order: 6 +use_cases: >- + forcing property assignment, writing DOM properties, custom element property + access +tags: + - properties + - dom + - attributes +version: "1.0" +description: >- + Force a JSX key to be written as a DOM property instead of an attribute. --- -Forces the prop to be treated as a property instead of an attribute. - -```tsx -<div prop:scrollTop={props.scrollPos + "px"} /> -``` +`prop:*` forces a JSX key to be written as a DOM property instead of an attribute. :::note[Strong-Typing Custom Properties] Type definitions are required when using TypeScript. See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples. ::: + +## Syntax + +```tsx +<div prop:scrollTop={value} /> +``` + +## Value + +- **Type:** property value + +Value assigned directly to the property after the `prop:` prefix is removed. + +## Behavior + +- On the client, `prop:name={value}` strips the `prop:` prefix and assigns the value directly to the `name` property. +- `prop:*` does not produce SSR output. +- Use `prop:*` when a DOM property must receive the value directly. Solid can still assign some custom-element properties without `prop:*`. + +## Examples + +### Basic usage + +```tsx +<input type="checkbox" prop:indeterminate={true} /> +``` + +## Related + +- [`attr:*`](/reference/jsx-attributes/attr) diff --git a/src/routes/reference/jsx-attributes/ref.mdx b/src/routes/reference/jsx-attributes/ref.mdx index 630806570..7434dff3b 100644 --- a/src/routes/reference/jsx-attributes/ref.mdx +++ b/src/routes/reference/jsx-attributes/ref.mdx @@ -1,33 +1,70 @@ --- title: ref order: 7 +use_cases: >- + element references, imperative DOM access, component refs +tags: + - refs + - dom + - elements +version: "1.0" +description: >- + Capture a rendered element or forwarded component ref. --- -Refs are a way of getting access to underlying DOM elements in our JSX. While it is true one could just assign an element to a variable, it is more optimal to leave components in the flow of JSX. Refs are assigned at render time but before the elements are connected to the DOM. They come in 2 flavors. +`ref` captures a rendered element or forwarded component ref. + +## Syntax + +```tsx +<div ref={value} /> +``` + +## Value + +- **Type:** variable binding or callback function + +For DOM elements, variable refs are assigned during render and callback refs receive the element. + +## Behavior + +- Refs are assigned during rendering before the element is connected to the DOM. +- A variable ref assigns the rendered element to the referenced variable. +- A callback ref is called with the rendered element. When `ref` comes through a spread, functional refs are invoked from the spread handling path instead. +- Component refs work only when the component uses or forwards the `ref` prop to an underlying element or child component. + +## Examples + +### Variable ref ```tsx -// variable assigned directly by ref let myDiv; -// use onMount or createEffect to read after connected to the DOM onMount(() => console.log(myDiv)); -<div ref={myDiv} /> +<div ref={myDiv} />; +``` + +### Callback ref -// Or, callback function (called before connected to the DOM) -<div ref={el => console.log(el)} /> +```tsx +<div ref={(el) => console.log(el)} /> ``` -Refs can also be used on Components. They still need to be attached on the other side. +### Component ref ```tsx function MyComp(props) { - return <div ref={props.ref} /> + return <div ref={props.ref} />; } function App() { - let myDiv - onMount(() => console.log(myDiv.clientWidth)) - return <MyComp ref={myDiv} /> + let myDiv; + onMount(() => console.log(myDiv.clientWidth)); + return <MyComp ref={myDiv} />; } ``` + +## Related + +- [`onMount`](/reference/lifecycle/on-mount) diff --git a/src/routes/reference/jsx-attributes/style.mdx b/src/routes/reference/jsx-attributes/style.mdx index 4a65409b8..cc34fce61 100644 --- a/src/routes/reference/jsx-attributes/style.mdx +++ b/src/routes/reference/jsx-attributes/style.mdx @@ -1,38 +1,66 @@ --- title: style order: 7 +use_cases: >- + inline styles, dynamic style values, CSS variables +tags: + - styling + - css + - inline + - variables +version: "1.0" +description: >- + Set inline styles with a CSS string or an object of property names and values. --- -Solid's style attribute lets you provide either a CSS string or an object where keys are CSS property names: +`style` sets inline styles from either a CSS string or an object. + +## Syntax ```tsx -// string -<div style={`color: green; height: ${state.height}px`} /> +<div style="color: green" /> +<div style={{ color: "green" }} /> +``` -// object -<div style={{ - color: "green", - height: state.height + "px" }} -/> +## Value + +- **Type:** `string | CSSProperties` + +CSS string or style object. + +## Behavior + +- String values are written as inline CSS text. +- Object values are applied property by property with `element.style.setProperty`, so keys should use lower-case, dash-separated CSS property names instead of camelCase. CSS custom properties can use keys such as `--my-color`. +- Nullish values in a style object remove that property, and falsy overall `style` values remove the `style` attribute. +- In SSR output, object values are serialized into the emitted `style` attribute. + +## Examples + +### CSS string + +```tsx +<div style={`color: green; height: ${state.height}px`} /> ``` -Unlike [React's style attribute](https://reactjs.org/docs/dom-elements.html#style), Solid uses **element.style.setProperty** under the hood. This means you need to use the lower-case, dash-separated version of property names instead of the JavaScript camel-cased version, such as `background-color` rather than `backgroundColor`. This actually leads to better performance and consistency with SSR output. +### Style object ```tsx -// string -<div style={`color: green; background-color: ${state.color}; height: ${state.height}px`} /> - -// object -<div style={{ - color: "green", - "background-color": state.color, - height: state.height + "px" }} +<div + style={{ + color: "green", + "background-color": state.color, + height: `${state.height}px`, + }} /> ``` -This also means you can set CSS variables! For example: +### CSS variable ```tsx -// set css variable <div style={{ "--my-custom-color": state.themeColor }} /> ``` + +## Related + +- [`classList`](/reference/jsx-attributes/classlist) diff --git a/src/routes/reference/jsx-attributes/textcontent.mdx b/src/routes/reference/jsx-attributes/textcontent.mdx index bb80437b8..f90639b84 100644 --- a/src/routes/reference/jsx-attributes/textcontent.mdx +++ b/src/routes/reference/jsx-attributes/textcontent.mdx @@ -1,8 +1,43 @@ --- title: textContent +use_cases: >- + text-only content, replacing element children with text +tags: + - text + - content + - dom +version: "1.0" +description: >- + Set an element's `textContent` property from JSX with plain text content. --- -The `textContent` attribute is equivalent to the [`textContent` DOM property](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent). -This attribute replaces all existing child nodes of the element with a single text node containing the provided string. +`textContent` sets an element's `textContent` property with plain text content. -Using `textContent` can improve performance when the element's children are known to be exclusively text, as it bypasses the generic diffing process. +## Syntax + +```tsx +<div textContent={value} /> +``` + +## Value + +- **Type:** `string | number` + +Text written to the element without parsing markup. + +## Behavior + +- `textContent` replaces the element's existing child content instead of merging with JSX children. +- On the client, the value is written through the DOM `textContent` property. During SSR, it is emitted as escaped text instead of raw HTML. + +## Examples + +### Basic usage + +```tsx +<div textContent={"<strong>Hello</strong>"} /> +``` + +## Related + +- [`innerHTML`](/reference/jsx-attributes/innerhtml) diff --git a/src/routes/reference/jsx-attributes/use.mdx b/src/routes/reference/jsx-attributes/use.mdx index b622f82c2..4f7e80cc4 100644 --- a/src/routes/reference/jsx-attributes/use.mdx +++ b/src/routes/reference/jsx-attributes/use.mdx @@ -1,41 +1,76 @@ --- -title: use:* +title: "use:*" order: 5 +use_cases: >- + reusable DOM behavior, directives, element setup helpers +tags: + - directives + - dom + - jsx +version: "1.0" +description: >- + Attach a directive function to a native element with `use:*`. --- -These are custom directives. In a sense this is just syntax sugar over ref but allows us to easily attach multiple directives to a single element. A directive is a function with the following signature: +`use:*` attaches a directive function to a native element. + +## Syntax + +```tsx +<input use:model={[value, setValue]} /> +``` + +## Type ```ts -function directive(element: Element, accessor: () => any): void +type Accessor<T> = () => T; + +function directive(element: Element, accessor?: Accessor<any>): void; ``` -Directive functions are called at render time but before being added to the DOM. You can do whatever you'd like in them including create signals, effects, register clean-up etc. +## Value + +- **Type:** directive argument + +The directive reads the value through an accessor. Without an explicit value, the accessor returns `true`. + +## Behavior + +- `use:name={value}` passes the element and an accessor for `value` to the directive. +- Without an explicit value, the accessor returns `true`. +- The directive runs during rendering in the current owner, before the element is connected to the DOM, so it can create effects and register cleanup. +- `use:*` works only on native elements, including custom elements, and is not forwarded through user-defined components. + +## Examples + +### Basic usage ```tsx -const [name, setName] = createSignal("") +function model(element, value) { + const [field, setField] = value(); + const onInput = ({ currentTarget }) => setField(currentTarget.value); + + createRenderEffect(() => (element.value = field())); + element.addEventListener("input", onInput); + onCleanup(() => element.removeEventListener("input", onInput)); +} -function model(el, value) { - const [field, setField] = value() - createRenderEffect(() => (el.value = field())) - el.addEventListener("input", (e) => setField(e.target.value)) -}; +const [name, setName] = createSignal(""); -<input type="text" use:model={[name, setName]} /> +<input type="text" use:model={[name, setName]} />; ``` -To register with TypeScript extend the JSX namespace. +:::note +When using TypeScript, custom directives may require extending Solid's JSX directive typings: ```ts declare module "solid-js" { namespace JSX { interface Directives { - model: [() => any, (v: any) => any] + model: [Accessor<string>, Setter<string>]; } } } ``` -:::caution[Limitations] -Directives only work with native HTML elements (HTML/SVG/MathML/Custom Elements). -Directives are not forwarded and **won't work in user defined components**, such as `<MyComponent use:myinput={[..]}/>` [see also](https://github.com/solidjs/solid/discussions/722) ::: diff --git a/src/routes/reference/lifecycle/on-cleanup.mdx b/src/routes/reference/lifecycle/on-cleanup.mdx index 1472442f5..954a582d5 100644 --- a/src/routes/reference/lifecycle/on-cleanup.mdx +++ b/src/routes/reference/lifecycle/on-cleanup.mdx @@ -1,40 +1,103 @@ --- title: onCleanup order: 5 +use_cases: >- + component unmounting, memory leak prevention, event listener cleanup, side + effect cleanup, resource disposal +tags: + - lifecycle + - cleanup + - memory + - events + - disposal +version: "1.0" +description: >- + Register a cleanup function on the current reactive scope. The cleanup runs + when the scope is disposed or refreshed. --- -`onCleanup` registers a cleanup method that executes on disposal and recalculation of the current tracking scope. -Can be used anywhere to clean up any side effects left behind by initialization. +`onCleanup` registers a cleanup function on the current reactive scope. +The cleanup runs when that scope is disposed or refreshed. -When used in a Component, it runs when the component is unmounted. -When used in tracking scope, such [`createEffect`](/reference/basic-reactivity/create-effect), [`createMemo`](/reference/basic-reactivity/create-memo) or a [`createRoot`](/reference/reactive-utilities/create-root), it runs when the tracking scope is disposed or refreshed. +## Import ```ts -import { onCleanup } from "solid-js" +import { onCleanup } from "solid-js"; +``` + +## Type -function onCleanup(fn: () => void): void; +```ts +function onCleanup<T extends () => any>(fn: T): T; ``` -Without the `onCleanup` function, the event listener would remain attached to the `document` even after the component is removed from the page. -This can cause memory leaks and other issues. +## Parameters + +### `fn` + +- **Type:** `() => any` +- **Required:** Yes + +Cleanup function registered on the current reactive scope. + +## Return value + +- **Type:** `T` + +Returns `fn` unchanged. + +## Behavior + +- In a component, the cleanup runs when that component is unmounted. +- In a tracking scope such as [`createEffect`](/reference/basic-reactivity/create-effect), [`createMemo`](/reference/basic-reactivity/create-memo), or [`createRoot`](/reference/reactive-utilities/create-root), the cleanup runs when that scope is disposed or re-executes. +- Multiple cleanup functions run when the owning scope is cleaned up. +- Calling `onCleanup` outside a reactive owner does not register a cleanup. In development, Solid warns that the cleanup will never run. +- On the server, cleanup also runs when server-side owners or reactive branches are disposed. + +## Examples + +### Remove an event listener ```tsx -import { createSignal, onCleanup } from "solid-js" +import { onCleanup } from "solid-js"; const Component = () => { - const [count, setCount] = createSignal(0); - - const handleClick = () => setCount((value) => value + 1); + const handleClick = () => console.log("clicked"); document.addEventListener("click", handleClick); - /** - * Remove the event listener when the component is removed/unmounted from the page. - */ onCleanup(() => { document.removeEventListener("click", handleClick); }); - return <main>Document has been clicked {count()} times</main>; + return <main>Listening for document clicks</main>; }; ``` + +### Clean up before an effect re-runs + +```tsx +import { createEffect, createSignal, onCleanup } from "solid-js"; + +function Example() { + const [topic, setTopic] = createSignal("news"); + + createEffect(() => { + const currentTopic = topic(); + + console.log("subscribing to", currentTopic); + + onCleanup(() => { + console.log("cleaning up", currentTopic); + }); + }); + + return <button onClick={() => setTopic("sports")}>Change topic</button>; +} +``` + +## Related + +- [`onMount`](/reference/lifecycle/on-mount) +- [`createEffect`](/reference/basic-reactivity/create-effect) +- [`createRoot`](/reference/reactive-utilities/create-root) diff --git a/src/routes/reference/lifecycle/on-mount.mdx b/src/routes/reference/lifecycle/on-mount.mdx index 9d59843dd..2ead251c2 100644 --- a/src/routes/reference/lifecycle/on-mount.mdx +++ b/src/routes/reference/lifecycle/on-mount.mdx @@ -1,31 +1,91 @@ --- title: onMount order: 5 +use_cases: >- + initial setup, dom refs access, one-time initialization, component mounting, + element manipulation after render +tags: + - lifecycle + - mounting + - refs + - dom + - initialization +version: "1.0" +description: >- + Register a function that runs once after the initial render of the current + component or root. --- -Registers a method that runs after initial rendering is done and the elements are mounted to the page. -Ideal for using [refs](/reference/jsx-attributes/ref) and managing other one-time setup. +`onMount` registers a function that runs once after the initial render for the current component or root. -```tsx -import { onMount } from "solid-js" +## Import + +```ts +import { onMount } from "solid-js"; +``` -function onMount(fn: () => void): void +## Type +```ts +function onMount(fn: () => void): void; ``` -This is an alias for an effect that is non-tracking, meaning that it is equivalent to a [`createEffect`](/reference/basic-reactivity/create-effect) with no dependencies. +## Parameters + +### `fn` + +- **Type:** `() => void` +- **Required:** Yes + +Non-tracking function executed once on mount. + +## Return value + +`onMount` does not return a value. + +## Behavior + +- On the client, `onMount` runs once after the initial render. It does not run during server rendering. +- `fn` does not track reactive dependencies. +- Internally, `onMount(fn)` is equivalent to `createEffect(() => untrack(fn))`. +- By the time `onMount` runs, refs have already been assigned. +- Returning a function from `fn` does not register cleanup. Use [`onCleanup`](/reference/lifecycle/on-cleanup) inside `onMount` when cleanup is needed. + +## Examples + +### Access a ref after mount ```tsx -// example that shows how to use onMount to get a reference to an element -import { onMount } from "solid-js" +import { onMount } from "solid-js"; function MyComponent() { - let ref: HTMLButtonElement + let ref: HTMLButtonElement; - // when the component is mounted, the button will be disabled onMount(() => { - ref.disabled = true - }) - return <button ref={ref}>Focus me!</button> + ref.disabled = true; + }); + + return <button ref={ref}>Focus me!</button>; } ``` + +### Run one-time browser setup + +```tsx +import { onMount } from "solid-js"; + +function Example() { + onMount(() => { + // Browser-only code + console.log(window.location.pathname); + }); + + return <div>Mounted</div>; +} +``` + +## Related + +- [`onCleanup`](/reference/lifecycle/on-cleanup) +- [`createEffect`](/reference/basic-reactivity/create-effect) +- [`untrack`](/reference/reactive-utilities/untrack) diff --git a/src/routes/reference/reactive-utilities/batch.mdx b/src/routes/reference/reactive-utilities/batch.mdx index 1763c9819..ab04ae9bd 100644 --- a/src/routes/reference/reactive-utilities/batch.mdx +++ b/src/routes/reference/reactive-utilities/batch.mdx @@ -1,76 +1,104 @@ --- title: batch +use_cases: >- + performance optimization, multiple signal updates, reducing re-renders, bulk + state changes, avoiding unnecessary recalculations +tags: + - performance + - optimization + - signals + - batching + - updates +version: "1.0" +description: >- + Group reactive updates so downstream computations run after the batch + completes. --- +`batch` groups multiple reactive updates so downstream computations run once after the batch completes instead of after each individual update. + +## Import + ```ts -import { batch } from "solid-js" +import { batch } from "solid-js"; +``` -function batch<T>(fn: () => T): T +## Type + +```ts +function batch<T>(fn: () => T): T; ``` -`batch` is a low-level API that batches updates together. -More precisely, `batch(fn)` holds the execution of downstream computations during the `fn` block, executing them all together once the block `fn` returns. -Thus, instead of a downstream computation executing after every dependency update, it will update just once at the end of the batch. +## Parameters + +### `fn` + +- **Type:** `() => T` +- **Required:** Yes + +Function executed inside the batch. + +## Return value + +- **Type:** `T` + +Returns the value produced by `fn`. -Batching improves performance by avoiding unnecessary recalculation. -Suppose you have a downstream memo `down` that depends on multiple upstream signals `up1`, `up2`, and `up3`: +## Behavior + +- Downstream computations are deferred until the batch completes. +- Nested `batch` calls behave like a single larger batch. +- If you read a stale memo or signal inside the batch, Solid updates it on demand before returning the value. +- If `fn` is asynchronous, batching applies only to updates before the first `await` or other async suspension point. + +## Automatic batching + +Solid automatically batches updates in several cases, including: + +- inside [`createEffect`](/reference/basic-reactivity/create-effect) and [`onMount`](/reference/lifecycle/on-mount) +- inside the setter returned by [`createStore`](/reference/store-utilities/create-store) +- inside array mutation methods on [`createMutable`](/reference/store-utilities/create-mutable) + +## Examples + +### Basic usage ```ts -import { createSignal, createMemo, createEffect } from "solid-js" -const [up1, setUp1] = createSignal(1) -const [up2, setUp2] = createSignal(2) -const [up3, setUp3] = createSignal(3) -const down = createMemo(() => up1() + up2() + up3()) -// For illustration, monitor when `down` gets recomputed: -createEffect(() => console.log(down())) // outputs 6 +const [count, setCount] = createSignal(0); +const [total, setTotal] = createSignal(0); + +const summary = createMemo(() => `${count()} / ${total()}`); +createEffect(() => console.log(summary())); // logs "0 / 0" ``` -If you directly update all of the upstream signals outside of batch mode, then `down` will recompute every time. +Outside `batch`: ```ts -setUp1(4) // recomputes down, outputs 9 -setUp2(5) // recomputes down, outputs 12 -setUp3(6) // recomputes down, outputs 15 +setCount(1); // logs "1 / 0" +setTotal(5); // logs "1 / 5" ``` -If instead you update the upstream signals within a `batch`, then `down` will update only once at the end: +Inside `batch`: ```ts batch(() => { - setUp1(10) // doesn't update down yet - setUp2(10) // doesn't update down yet - setUp3(10) // doesn't update down yet -}) // recomputes down, outputs 30 + setCount(1); + setTotal(5); +}); // logs "1 / 5" ``` -The impact is even more dramatic if you have *m* downstream computations (memos, effects, etc.) that each depends on *n* upstream signals. -Without batching, modifying all *n* upstream signals would cause *m n* updates to the downstream computations. -With batching, modifying all *n* upstream signals would cause *m* updates to the downstream computations. -Given that each update takes at least *n* time (just to read the upstream signals), this cost savings can be significant. -Batching is also especially helpful when the downstream effects include DOM updates, which can be expensive. - -Solid uses `batch` internally to automatically batch updates for you in a few cases: - -* Within [`createEffect`](/reference/basic-reactivity/create-effect) and [`onMount`](/reference/lifecycle/on-mount) (unless they are outside a [root](/reference/reactive-utilities/create-root)) -* Within the [setter of a store](/reference/store-utilities/create-store#setter) (which can update several properties at once) -* Within array methods (e.g. `Array.prototype.splice`) of a [mutable store](/reference/store-utilities/create-mutable) (which can update several elements at once) - -These save you from having to use `batch` yourself in many cases. -For the most part, automatic batching should be transparent to you, because accessing a signal or memo will cause it to update if it is out of date (as of Solid 1.4). -For example: +### Read inside a batch ```ts batch(() => { - setUp1(11) // doesn't update down yet - setUp2(11) // doesn't update down yet - setUp3(11) // doesn't update down yet - console.log(down()) // recomputes down, outputs 33 - setUp1(12) // doesn't update down yet - setUp2(12) // doesn't update down yet - setUp3(12) // doesn't update down yet -}) // recomputes down, outputs 36 + setCount(2); + console.log(summary()); // logs "2 / 5" + setTotal(10); +}); // logs "2 / 10" ``` -You can think of `batch(fn)` as setting a global "batch mode" variable, calling the function `fn`, and then restoring the global variable to its previous value. -This means that you can nest `batch` calls, and they will form one big batch. -It also means that, if `fn` is asynchronous, only the updates before the first `await` will be batched. +## Related + +- [`createEffect`](/reference/basic-reactivity/create-effect) +- [`createStore`](/reference/store-utilities/create-store) +- [`createMutable`](/reference/store-utilities/create-mutable) diff --git a/src/routes/reference/reactive-utilities/catch-error.mdx b/src/routes/reference/reactive-utilities/catch-error.mdx index 49d1db388..b9b5b4c77 100644 --- a/src/routes/reference/reactive-utilities/catch-error.mdx +++ b/src/routes/reference/reactive-utilities/catch-error.mdx @@ -1,17 +1,89 @@ --- title: catchError +use_cases: >- + error handling, error boundaries, exception management, debugging, graceful + error recovery +tags: + - errors + - debugging + - exceptions + - handlers +version: "1.0" +description: >- + Establish an error boundary for work performed inside the provided function. --- -:::note -<span>New in v1.7.0</span> -::: +`catchError` establishes an error boundary for work performed inside the provided function. + +## Import + +```ts +import { catchError } from "solid-js"; +``` + +## Type + +```ts +function catchError<T>( + fn: () => T, + handler: (err: Error) => void +): T | undefined; +``` + +## Parameters + +### `fn` + +- **Type:** `() => T` +- **Required:** Yes + +Function executed inside the error boundary. + +### `handler` + +- **Type:** `(err: Error) => void` +- **Required:** Yes + +Error handler invoked when a thrown value reaches this boundary. + +## Return value + +- **Type:** `T | undefined` + +Returns the value produced by `fn`, or `undefined` when a thrown value is caught and handled. + +## Behavior + +- While `fn` runs, `catchError` establishes an error boundary for reactive scopes created inside it. +- Only the nearest matching error boundary handles a thrown error. +- If `handler` throws, the next parent error boundary handles that error. + +## Examples + +### Handle an error in a child scope ```tsx -import { catchError } from "solid-js" +import { catchError, createEffect, createSignal } from "solid-js"; + +function Example() { + const [count, setCount] = createSignal(0); -function catchError<T>(tryFn: () => T, onError: (err: any) => void): T + catchError( + () => { + createEffect(() => { + if (count() > 2) throw new Error("count too large"); + }); + }, + (err) => { + console.error(err.message); + } + ); + + return <button onClick={() => setCount((c) => c + 1)}>Increment</button>; +} ``` -Wraps a `tryFn` with an error handler that fires if an error occurs below that point. -Only the nearest scope error handlers execute. -Rethrow to trigger up the line. +## Related + +- [`ErrorBoundary`](/reference/components/error-boundary) +- [`createEffect`](/reference/basic-reactivity/create-effect) diff --git a/src/routes/reference/reactive-utilities/create-root.mdx b/src/routes/reference/reactive-utilities/create-root.mdx index 588664d27..cd633a8ab 100644 --- a/src/routes/reference/reactive-utilities/create-root.mdx +++ b/src/routes/reference/reactive-utilities/create-root.mdx @@ -1,16 +1,129 @@ --- title: createRoot +use_cases: >- + memory management, nested tracking scopes, non-auto-disposing scopes, manual + cleanup control, top-level code wrapping +tags: + - roots + - memory + - scopes + - disposal + - tracking +version: "1.0" +description: >- + Create non-tracked owner scopes in SolidJS for manual memory management. + Essential for nested tracking scopes and preventing auto-disposal. --- +The `createRoot` function creates a new owned context, which requires explicit disposal of computations it owns. + +## Import + +```ts +import { createRoot } from "solid-js"; +``` + +## Type + +```ts +function createRoot<T>( + fn: (dispose: () => void) => T, + detachedOwner?: Owner +): T; +``` + +## Parameters + +### `fn` + +- **Type:** `(dispose: () => void) => T` +- **Required:** Yes + +The function executes within a newly created owned context. +The computations created within this function are managed by the root and will only be disposed of when the provided `dispose` function is called. + +If a function is passed without a `dispose` parameter, an unowned root is created. +In this case, the computations are not managed for disposal, which may lead to memory leaks. + +This function itself does not track dependencies and only runs once. + +### `detachedOwner` + +- **Type:** `Owner` +- **Required:** No + +An optional owner that establishes the root's position in the ownership hierarchy. +When provided, the root becomes owned by this owner and inherits its contextual state (such as [contexts](/concepts/context)). + +## Return Value + +`createRoot` returns the value returned by the `fn` function. + +## Examples + +### Basic Usage + +```ts +import { createSignal, createEffect, createRoot } from "solid-js"; + +function createCounter(initial = 0) { + const [count, setCount] = createSignal(initial); + + createEffect(() => { + console.log(`Count changed, new value: ${count()}`); + }); + + function increment() { + setCount((c) => c + 1); + } + + function reset() { + setCount(initial); + } + + return { count, increment, reset }; +} + +test("createCounter works correctly", () => { + createRoot((dispose) => { + const { count, increment, reset } = createCounter(10); + + expect(count()).toBe(10); + increment(); + expect(count()).toBe(11); + reset(); + expect(count()).toBe(10); + + dispose(); + }); +}); +``` + +### Returning Values + ```ts -import { createRoot } from "solid-js" +import { createRoot, createSignal, onCleanup } from "solid-js"; + +const counter = createRoot((dispose) => { + const [count, setCount] = createSignal(0); + + onCleanup(() => { + console.log("Dispose was called!"); + }); -function createRoot<T>(fn: (dispose: () => void) => T): T + return { + value: count, + increment: () => setCount((c) => c + 1), + dispose, + }; +}); +console.log(counter.value()); // 0 +counter.increment(); +console.log(counter.value()); // 1 +counter.dispose(); // Logs "Dispose was called!" ``` -Creates a new non-tracked owner scope that doesn't auto-dispose. -This is useful for nested tracking scopes that you do not wish to release when the parent re-evaluates. +## Related -All Solid code should be wrapped in one of these top level as they ensure that all memory/computations are freed up. -Normally you do not need to worry about this as createRoot is embedded into all render entry functions. +- [`render`](/reference/rendering/render) diff --git a/src/routes/reference/reactive-utilities/from.mdx b/src/routes/reference/reactive-utilities/from.mdx index ad45aea13..07a28c0c6 100644 --- a/src/routes/reference/reactive-utilities/from.mdx +++ b/src/routes/reference/reactive-utilities/from.mdx @@ -1,43 +1,117 @@ --- title: from +use_cases: >- + rxjs interop, svelte stores integration, external observables, third-party + state management, converting subscriptions to signals +tags: + - interop + - rxjs + - observables + - signals + - integration +version: "1.0" +description: >- + Convert an external producer or subscribable into a Solid accessor. --- -```tsx -import { from } from "solid-js" - -function from<T>( - producer: - | ((setter: (v: T) => T) => () => void) - | { - subscribe: ( - fn: (v: T) => void - ) => (() => void) | { unsubscribe: () => void } - } -): () => T | undefined +`from` creates an accessor from an external producer or subscribable source. + +## Import + +```ts +import { from } from "solid-js"; +``` + +## Type + +```ts +function from<T>(producer: Producer<T>, initialValue: T): () => T; +function from<T>(producer: Producer<T | undefined>): () => T | undefined; +type Producer<T> = + | ((setter: Setter<T>) => () => void) + | { + subscribe: ( + fn: (value: T) => void + ) => (() => void) | { unsubscribe: () => void }; + }; ``` -A helper to make it easier to interop with external producers like RxJS observables or with Svelte Stores. -This basically turns any subscribable (object with a subscribe method) into a Signal and manages subscription and disposal. +## Parameters + +### `producer` + +- **Type:** `Producer<T>` or `Producer<T | undefined>` +- **Required:** Yes + +Producer function or subscribable object. + +### `initialValue` + +- **Type:** `T` +- **Required:** No + +Initial value for the accessor. + +## Return value + +- **Type:** `() => T` or `() => T | undefined` + +Returns an accessor backed by the external source. + +## Behavior + +- `from` subscribes to the producer immediately when it runs. +- A producer function receives a Solid setter and returns a cleanup function. +- A subscribable source must expose `subscribe()`, and that subscription may return either a cleanup function or an object with `unsubscribe()`. +- Emitted values are not deduplicated by equality. +- Cleanup is registered on the current Solid owner when one exists. +- When `from` runs without an owner, the subscription still starts but is not cleaned up automatically. +- When `initialValue` is omitted, the accessor can return `undefined`. + +## Examples + +### Create an accessor from a subscribable source ```tsx -const signal = from(obsv$) +import { from } from "solid-js"; + +function Clock() { + const time = from( + { + subscribe(next) { + const interval = setInterval( + () => next(new Date().toLocaleTimeString()), + 1000 + ); + return () => clearInterval(interval); + }, + }, + "" + ); + + return <div>{time()}</div>; +} ``` -It can also take a custom producer function where the function is passed a setter function that returns an unsubscribe function: +### Create an accessor from a producer function ```tsx -const clock = from((set) => { - const interval = setInterval(() => { - set((v) => v + 1) - }, 1000) +import { from } from "solid-js"; + +function Counter() { + const count = from((set) => { + const interval = setInterval(() => { + set((value = 0) => value + 1); + }, 1000); + + return () => clearInterval(interval); + }, 0); - return () => clearInterval(interval) -}) + return <div>{count()}</div>; +} ``` -## Arguments +## Related -| Name | Type | Description | -| :------- | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- | -| producer | `((setter: (v: T) => T) => () => void) \| { subscribe: (fn: (v: T) => void) => (() => void) \| { unsubscribe: () => void }; }` | The producer function or subscribable object | +- [`observable`](/reference/reactive-utilities/observable) diff --git a/src/routes/reference/reactive-utilities/get-owner.mdx b/src/routes/reference/reactive-utilities/get-owner.mdx index 7c1f59504..506b962d6 100644 --- a/src/routes/reference/reactive-utilities/get-owner.mdx +++ b/src/routes/reference/reactive-utilities/get-owner.mdx @@ -1,24 +1,80 @@ --- title: getOwner +use_cases: >- + advanced tracking control, custom cleanup logic, understanding component + hierarchy, debugging ownership chains, manual scope management +tags: + - ownership + - tracking + - scopes + - cleanup + - debugging +version: "1.0" +description: >- + Return the owner for the currently executing reactive scope. --- -```tsx -import { getOwner } from "solid-js" -import type { Owner } from "solid-js" +`getOwner` returns the owner for the currently executing reactive scope. + +## Import + +```ts +import { getOwner } from "solid-js"; +``` + +## Type -function getOwner(): Owner +```ts +type Owner = unknown; +function getOwner(): Owner | null; ``` -Gets the tracking scope that owns the currently running code, e.g., for passing into a later call to `runWithOwner` outside of the current scope. +The `Owner` interface is public, but its concrete shape is mostly useful for advanced interop such as [`runWithOwner`](/reference/reactive-utilities/run-with-owner). + +## Parameters + +`getOwner` does not take any parameters. + +## Return value + +- **Type:** `Owner | null` + +Returns the current owner or `null` when no owner is active. -Internally, computations (effects, memos, etc.) create owners which are children of their owner, all the way up to the root owner created by `createRoot` or `render`. -In particular, this ownership tree lets Solid automatically clean up a disposed computation by traversing its subtree and calling all `onCleanup` callbacks. -For example, when a createEffect's dependencies change, the effect calls all descendant `onCleanup` callbacks before running the effect function again. -Calling `getOwner` returns the current owner node that is responsible for disposal of the current execution block. +## Behavior + +- `getOwner` returns the current owner and does not create or modify ownership. +- Owners determine cleanup and context lookup for descendant computations. +- A computation created inside the current scope becomes part of the current owner tree unless ownership is overridden. +- Component functions run under an owner created for that subtree. +- Calling `getOwner` inside component code returns the owner responsible for rendering and disposing that component subtree. +- Turning off tracking with [`untrack`](/reference/reactive-utilities/untrack) does not create a new owner. + +## Examples + +### Capture an owner for later use + +```tsx +import { getOwner, runWithOwner } from "solid-js"; + +function Example() { + const owner = getOwner(); + + queueMicrotask(() => { + if (owner) { + runWithOwner(owner, () => { + console.log("owner restored"); + }); + } + }); + + return null; +} +``` -Components are not computations, so do not create an owner node, but they are typically rendered from a `createEffect` which does, so the result is similar: when a component gets unmounted, all descendant `onCleanup` callbacks get called. -Calling `getOwner` from a component scope returns the owner that is responsible for rendering and unmounting that component. +## Related -Note that the owning tracking scope isn't necessarily tracking. -For example, untrack turns off tracking for the duration of a function (without creating a new tracking scope), as do components created via JSX (`<Component ...>`). +- [`runWithOwner`](/reference/reactive-utilities/run-with-owner) +- [`onCleanup`](/reference/lifecycle/on-cleanup) +- [`untrack`](/reference/reactive-utilities/untrack) diff --git a/src/routes/reference/reactive-utilities/index-array.mdx b/src/routes/reference/reactive-utilities/index-array.mdx index a8b6036ee..43a0820f5 100644 --- a/src/routes/reference/reactive-utilities/index-array.mdx +++ b/src/routes/reference/reactive-utilities/index-array.mdx @@ -1,41 +1,94 @@ --- title: indexArray +use_cases: >- + rendering lists by index, stable item references, index-based list operations, + optimized list rendering +tags: + - arrays + - lists + - index + - rendering + - optimization +version: "1.0" +description: >- + Reactively map an array by index and return an accessor for the mapped + result. --- -```tsx -import { indexArray } from "solid-js" +`indexArray` reactively maps an array by index. -function indexArray<T, U>( - list: () => readonly T[], - mapFn: (v: () => T, i: number) => U -): () => U[] +## Import +```ts +import { indexArray } from "solid-js"; ``` -Similar to `mapArray` except it maps by index. -The item is a signal and the index is now the constant. - -Underlying helper for the `<Index>` control flow. - -```tsx -const mapped = indexArray(source, (model) => { - return { - get id() { - return model().id - } - get firstInitial() { - return model().firstName[0]; - }, - get fullName() { - return `${model().firstName} ${model().lastName}`; - }, - } -}); +## Type + +```ts +function indexArray<T, U>( + list: () => readonly T[] | undefined | null | false, + mapFn: (value: () => T, index: number) => U, + options?: { fallback?: () => any } +): () => U[]; +``` + +## Parameters + +### `list` + +- **Type:** `() => readonly T[] | undefined | null | false` +- **Required:** Yes + +Accessor that returns the source array. + +### `mapFn` + +- **Type:** `(value: () => T, index: number) => U` +- **Required:** Yes + +Mapping function for each index. + +### `options` + +#### `fallback` + +- **Type:** `() => any` + +Fallback accessor used when the source array is empty or falsy. +The mapped result becomes a single fallback entry. + +## Return value + +- **Type:** `() => U[]` + +Returns an accessor for the mapped array. + +## Behavior + +- Items are mapped by index rather than by value identity. +- The item argument is an accessor. +- The index argument is a number. +- Updating an item at the same index updates the corresponding mapped result. +- Reordering the source array changes which item each index points to instead of moving mapped entries by identity. +- This is the underlying helper for [`<Index>`](/reference/components/index-component). + +## Examples + +### Map an array by index + +```ts +import { createSignal, indexArray } from "solid-js"; + +const [source] = createSignal([{ status: "pending" }, { status: "done" }]); + +const mapped = indexArray(source, (item, index) => ({ + index, + status: () => item().status, +})); ``` -## Arguments +## Related -| Name | Type | Description | -| :---- | :----------------------------- | :-------------------- | -| list | `() => readonly T[]` | The list to map. | -| mapFn | `(v: () => T, i: number) => U` | The mapping function. | +- [`<Index>`](/reference/components/index-component) +- [`mapArray`](/reference/reactive-utilities/map-array) diff --git a/src/routes/reference/reactive-utilities/map-array.mdx b/src/routes/reference/reactive-utilities/map-array.mdx index 78e2dbfd4..71014379a 100644 --- a/src/routes/reference/reactive-utilities/map-array.mdx +++ b/src/routes/reference/reactive-utilities/map-array.mdx @@ -1,45 +1,96 @@ --- title: mapArray +use_cases: >- + efficient list rendering, dynamic arrays, cached list transformations, + optimized updates, for loop alternatives +tags: + - arrays + - lists + - rendering + - caching + - optimization +version: "1.0" +description: >- + Reactively map an array by item identity and return an accessor for the mapped + result. --- +`mapArray` reactively maps an array and caches mapped items by value identity. + +## Import + ```ts -import { mapArray } from "solid-js" +import { mapArray } from "solid-js"; +``` -function mapArray<T, U>( - list: () => readonly T[], - mapFn: (v: T, i: () => number) => U -): () => U[] +## Type +```ts +function mapArray<T, U>( + list: () => readonly T[] | undefined | null | false, + mapFn: (value: T, index: () => number) => U, + options?: { fallback?: () => any } +): () => U[]; ``` -Reactive map helper that caches each item by reference to reduce unnecessary mapping on updates. -It only runs the mapping function once per value and then moves or removes it as needed. -The index argument is a signal. The map function itself is not tracking. +## Parameters + +### `list` + +- **Type:** `() => readonly T[] | undefined | null | false` +- **Required:** Yes + +Accessor that returns the source array. + +### `mapFn` + +- **Type:** `(value: T, index: () => number) => U` +- **Required:** Yes + +Mapping function for each item. -Underlying helper for the `<For>` control flow. +### `options` + +#### `fallback` + +- **Type:** `() => any` + +Fallback accessor used when the source array is empty or falsy. The mapped result becomes a single fallback entry. + +## Return value + +- **Type:** `() => U[]` + +Returns an accessor for the mapped array. + +## Behavior + +- Items are cached by value identity. +- The index argument is an accessor. +- `mapFn` is not a tracking scope, so reads inside the callback do not track unless they happen inside nested JSX or another reactive scope. +- Reordering reuses existing mapped items for retained source values and updates their index accessors. +- This is the underlying helper for [`<For>`](/reference/components/for). + +## Examples + +### Map an array with cached items ```ts -const mapped = mapArray(source, (model) => { - const [name, setName] = createSignal(model.name) - const [description, setDescription] = createSignal(model.description) - - return { - id: model.id, - get name() { - return name() - }, - get description() { - return description() - }, - setName, - setDescription, - } -}) +import { createSignal, mapArray } from "solid-js"; + +const [source] = createSignal([ + { id: 1, status: "pending" }, + { id: 2, status: "done" }, +]); + +const mapped = mapArray(source, (item, index) => ({ + id: item.id, + status: item.status, + position: () => index(), +})); ``` -## Arguments +## Related -| Name | Type | Description | -| :---- | :----------------------------- | :----------------------- | -| list | `() => readonly T[]` | The source array to map. | -| mapFn | `(v: T, i: () => number) => U` | The mapping function. | +- [`<For>`](/reference/components/for) +- [`indexArray`](/reference/reactive-utilities/index-array) diff --git a/src/routes/reference/reactive-utilities/merge-props.mdx b/src/routes/reference/reactive-utilities/merge-props.mdx index 5027201f1..26099a905 100644 --- a/src/routes/reference/reactive-utilities/merge-props.mdx +++ b/src/routes/reference/reactive-utilities/merge-props.mdx @@ -1,28 +1,74 @@ --- title: mergeProps +use_cases: >- + component props, default values, prop cloning, combining multiple prop + sources +tags: + - props + - components + - reactivity + - defaults + - merging +version: "1.0" +description: >- + Merge multiple prop sources into a single object while preserving reactive + property access. --- +`mergeProps` merges prop sources from left to right and resolves reads from the last source that defines each property. + +## Import + ```ts -import { mergeProps } from "solid-js" +import { mergeProps } from "solid-js"; +``` -function mergeProps(...sources: any): any +## Type +```ts +function mergeProps<T extends unknown[]>(...sources: T): MergeProps<T>; ``` -A reactive object **merge** method. -Useful for setting default props for components in case caller doesn't provide them. -Or cloning the props object including reactive properties. +## Parameters -This method works by using a proxy and resolving properties in reverse order. -This allows for dynamic tracking of properties that aren't present when the prop object is first merged. +### `sources` -```ts -// default props -props = mergeProps({ name: "Smith" }, props) +- **Type:** `unknown[]` + +Prop sources to merge. + +## Return value + +- **Type:** `MergeProps<T>` -// clone props -newProps = mergeProps(props) +Returns a merged object with lazy reactive property resolution across the provided sources. -// merge props -props = mergeProps(props, otherProps) +## Behavior + +- `mergeProps` is shallow. +- The last source with a non-`undefined` value for a property wins. +- Function sources are wrapped so property reads stay reactive. +- When reactive proxies are involved, the merged result uses proxy-backed property resolution. +- Property lookups are resolved when read rather than copied eagerly from every source. + +## Examples + +### Basic usage + +```tsx +import { mergeProps } from "solid-js"; + +function Greeting(props) { + const merged = mergeProps({ greeting: "Hello", name: "Smith" }, props); + + return ( + <div> + {merged.greeting} {merged.name} + </div> + ); +} ``` + +## Related + +- [`splitProps`](/reference/reactive-utilities/split-props) diff --git a/src/routes/reference/reactive-utilities/observable.mdx b/src/routes/reference/reactive-utilities/observable.mdx index 4e1bf23df..e1203784d 100644 --- a/src/routes/reference/reactive-utilities/observable.mdx +++ b/src/routes/reference/reactive-utilities/observable.mdx @@ -1,27 +1,70 @@ --- title: observable +use_cases: >- + rxjs integration, observable patterns, signal interop, third-party libraries, + reactive streams +tags: + - observables + - rxjs + - signals + - integration + - reactive + - streams +version: "1.0" +description: >- + Convert a Solid accessor into an Observable-compatible object. --- +`observable` creates an Observable-compatible object from a Solid accessor. + +## Import + ```ts -import { observable } from "solid-js" +import { observable } from "solid-js"; +``` -function observable<T>(input: () => T): Observable<T> +## Type +```ts +function observable<T>(input: () => T): Observable<T>; ``` -This method takes a signal and produces an Observable. -You can consume it from another Observable library of your choice, typically with the `from` operator. +## Parameters + +### `input` + +- **Type:** `() => T` +- **Required:** Yes + +Accessor used as the observable source. + +## Return value + +- **Type:** `Observable<T>` + +Returns an object with `subscribe()` and `[Symbol.observable]()` that returns the same object. + +## Behavior + +- `subscribe()` accepts either a function observer or an object observer with `next`. +- Each subscription creates an effect over the accessor and returns an object with `unsubscribe()`. +- If subscription happens inside an owned Solid scope, cleanup is also registered on that owner. + +## Examples + +### Convert an accessor to an Observable-compatible source ```ts -// How to integrate rxjs with a Solid signal -import { observable } from "solid-js" -import { from } from "rxjs" +import { createSignal, observable } from "solid-js"; +import { from } from "rxjs"; -const [s, set] = createSignal(0) +const [value] = createSignal(0); -const obsv$ = from(observable(s)) +const value$ = from(observable(value)); -obsv$.subscribe((v) => console.log(v)) +value$.subscribe((next) => console.log(next)); ``` -You can also use `from` without rxjs; check out this [page](/reference/reactive-utilities/from). +## Related + +- [`from`](/reference/reactive-utilities/from) diff --git a/src/routes/reference/reactive-utilities/on-util.mdx b/src/routes/reference/reactive-utilities/on-util.mdx index 1a8c45a88..b3f22014e 100644 --- a/src/routes/reference/reactive-utilities/on-util.mdx +++ b/src/routes/reference/reactive-utilities/on-util.mdx @@ -1,15 +1,29 @@ --- -title: on +title: "on" +use_cases: >- + explicit dependencies, effect control, conditional tracking, deferred + execution, store tracking +tags: + - effects + - dependencies + - tracking + - stores + - reactive + - defer +version: "1.0" +description: >- + Control effect dependencies explicitly with SolidJS's on utility. Define when + effects run and manage tracking behavior for precise reactivity. --- ```ts -import { on } from "solid-js" +import { on } from "solid-js"; function on<T extends Array<() => any> | (() => any), U>( deps: T, fn: (input: T, prevInput: T, prevValue?: U) => U, options: { defer?: boolean } = {} -): (prevValue?: U) => U | undefined +): (prevValue?: U) => U | undefined; ``` `on` is designed to be passed into a computation to make its dependencies explicit. @@ -37,8 +51,8 @@ setA("new"); // now it runs ## Using `on` with stores :::note - Please note that on stores and mutable, adding or removing a property from the - parent object will trigger an effect. See [`createMutable`](/reference/store-utilities/create-mutable) +Please note that on stores and mutable, adding or removing a property from the +parent object will trigger an effect. See [`createMutable`](/reference/store-utilities/create-mutable) ::: diff --git a/src/routes/reference/reactive-utilities/run-with-owner.mdx b/src/routes/reference/reactive-utilities/run-with-owner.mdx index 10638849f..9d52709a3 100644 --- a/src/routes/reference/reactive-utilities/run-with-owner.mdx +++ b/src/routes/reference/reactive-utilities/run-with-owner.mdx @@ -1,43 +1,90 @@ --- title: runWithOwner order: 5 +use_cases: >- + async operations, manual cleanup, context access, ownership control, + setTimeout callbacks, lifecycle management +tags: + - async + - ownership + - context + - cleanup + - lifecycle + - effects +version: "1.0" +description: >- + Execute a function under the provided owner. --- +`runWithOwner` executes a function under the provided owner. + +## Import + +```ts +import { runWithOwner } from "solid-js"; +``` + +## Type + ```ts -import { runWithOwner } from "solid-js" -import type { Owner } from "solid-js" +type Owner = unknown; -function runWithOwner<T>(owner: Owner, fn: (() => void) => T): T +function runWithOwner<T>(owner: Owner | null, fn: () => T): T | undefined; ``` -Executes the given function under the provided owner, instead of (and without affecting) the owner of the outer scope. -By default, computations created by `createEffect`, `createMemo`, etc. are owned by the owner of the currently executing code (the return value of `getOwner`), so in particular these will get disposed when their owner does. -Calling `runWithOwner` provides a way to override this default to a manually specified owner (typically, the return value from a previous call to `getOwner`), enabling more precise control of when computations get disposed. +## Parameters -Having a (correct) owner is important for two reasons: +### `owner` -- Computations without an owner cannot be cleaned up. -For example, if you call `createEffect` without an owner (e.g., in the global scope), the effect will continue running forever, instead of being disposed when its owner gets disposed. +- **Type:** `Owner | null` +- **Required:** Yes -- `useContext` obtains context by walking up the owner tree to find the nearest ancestor providing the desired context. -So without an owner you cannot look up any provided context (and with the wrong owner, you might obtain the wrong context). +Owner used while executing `fn`. -Manually setting the owner is especially helpful when doing reactivity outside of any owner scope. -In particular, asynchronous computation (via either `async` functions or callbacks like `setTimeout`) lose their automatically set owner, so remembering the original owner via `getOwner` and restoring it via `runWithOwner` is necessary in these cases. -For example: +### `fn` -```ts -const owner = getOwner() -setTimeout(() => { - // This callback gets run without owner. - // Restore owner via runWithOwner: - runWithOwner(owner, () => { - const foo = useContext(FooContext) - createEffect(() => { - console.log(foo) - }) - }) -}, 1000) +- **Type:** `() => T` +- **Required:** Yes + +Function executed under `owner`. + +## Return value + +- **Type:** `T | undefined` + +Returns the value produced by `fn`, or `undefined` when an error is routed through Solid's error handling. + +## Behavior + +- During the synchronous execution of `fn`, `runWithOwner` restores the provided owner for cleanup, context lookup, and descendant computations created inside `fn`. +- `runWithOwner` does not restore dependency tracking because the current tracking listener is cleared while `fn` runs. +- Code after the first `await` in an `async` function runs without the restored owner or reactive dependency tracking. + +## Examples + +### Restore an owner in a callback + +```tsx +import { createEffect, getOwner, runWithOwner } from "solid-js"; + +function Example() { + const owner = getOwner(); + + queueMicrotask(() => { + if (owner) { + runWithOwner(owner, () => { + createEffect(() => { + console.log("effect created under the captured owner"); + }); + }); + } + }); + + return null; +} ``` -**Note:** that owners are not what determines dependency tracking, so `runWithOwner` does not help with tracking in asynchronous functions; use of reactive state in the asynchronous part (e.g. after the first `await`) will not be tracked as a dependency. +## Related + +- [`getOwner`](/reference/reactive-utilities/get-owner) +- [`onCleanup`](/reference/lifecycle/on-cleanup) diff --git a/src/routes/reference/reactive-utilities/split-props.mdx b/src/routes/reference/reactive-utilities/split-props.mdx index 3841792ce..a6b8d4496 100644 --- a/src/routes/reference/reactive-utilities/split-props.mdx +++ b/src/routes/reference/reactive-utilities/split-props.mdx @@ -1,54 +1,102 @@ --- title: splitProps +use_cases: >- + prop forwarding, component composition, prop separation, splitting props into + multiple groups +tags: + - props + - components + - composition + - destructuring + - reactive +version: "1.0" +description: >- + Split a reactive props object into multiple reactive subsets and a remainder + object. --- +`splitProps` partitions a props object by key groups and returns a reactive object for each group plus a final object containing the remaining keys. + +## Import + ```ts -import { splitProps } from "solid-js" +import { splitProps } from "solid-js"; +``` -function splitProps<T>( - props: T, - ...keys: Array<(keyof T)[]> -): [...parts: Partial<T>] +## Type +```ts +function splitProps< + T extends Record<any, any>, + K extends [readonly (keyof T)[], ...(readonly (keyof T)[])[]], +>(props: T, ...keys: K): SplitProps<T, K>; ``` -Splits a reactive object by keys. +## Parameters + +### `props` + +- **Type:** `T` + +Source props object. + +### `keys` + +- **Type:** `(readonly (keyof T)[])[]` + +Arrays of keys that determine each returned subset. + +## Return value -It takes a reactive object and any number of arrays of keys; for each array of keys, it will return a reactive object with just those properties of the original object. -The last reactive object in the returned array will have any leftover properties of the original object. +- **Type:** `SplitProps<T, typeof keys>` -This can be useful if you want to consume a subset of props and pass the rest to a child. +Returns a tuple of reactive subsets followed by a reactive remainder object. + +## Behavior + +- Each returned object preserves reactive property access. +- A key is assigned to the first matching group only. +- The last returned object contains keys not included in the provided key arrays. +- When the source props object is proxy-backed, the returned objects use proxy-backed property access. +- `splitProps` separates props into groups without destructuring them into non-reactive locals. + +## Examples + +### Basic usage ```tsx +import { splitProps } from "solid-js"; + function MyComponent(props) { - const [local, others] = splitProps(props, ["children"]) + const [local, others] = splitProps(props, ["children"]); return ( <> <div>{local.children}</div> <Child {...others} /> </> - ) + ); } ``` -Because `splitProps` takes any number of arrays, we can split a props object as much as we wish (if, for example, we had multiple child components that each required a subset of the props). - -Let's say a component was passed six props: +### Split multiple groups ```tsx -;<MyComponent a={1} b={2} c={3} d={4} e={5} foo="bar" /> -// ... +import { splitProps } from "solid-js"; function MyComponent(props) { - console.log(props) // {a: 1, b: 2, c: 3, d: 4, e: 5, foo: "bar"} const [vowels, consonants, leftovers] = splitProps( props, ["a", "e"], ["b", "c", "d"] - ) - console.log(vowels) // {a: 1, e: 5} - console.log(consonants) // {b: 2, c: 3, d: 4} - console.log(leftovers.foo) // bar + ); + + return ( + <Child vowels={vowels} consonants={consonants} leftovers={leftovers} /> + ); } ``` + +## Related + +- [`mergeProps`](/reference/reactive-utilities/merge-props) diff --git a/src/routes/reference/reactive-utilities/start-transition.mdx b/src/routes/reference/reactive-utilities/start-transition.mdx index 2abdf9dad..1aa7e1c1d 100644 --- a/src/routes/reference/reactive-utilities/start-transition.mdx +++ b/src/routes/reference/reactive-utilities/start-transition.mdx @@ -1,13 +1,93 @@ --- title: startTransition +use_cases: >- + async updates, performance optimization, non-blocking updates, transition + control +tags: + - transitions + - async + - performance + - updates + - batching +version: "1.0" +description: >- + Start a transition and return a promise that resolves when the transition + completes. --- +`startTransition` starts a transition without exposing a pending-state accessor. + +## Import + ```ts -import { startTransition } from "solid-js" +import { startTransition } from "solid-js"; +``` -function startTransition: (fn: () => void) => Promise<void> +## Type +```ts +function startTransition(fn: () => unknown): Promise<void>; ``` -Similar to `useTransition` except there is no associated pending state. -This one can just be used directly to start the Transition. +## Parameters + +### `fn` + +- **Type:** `() => unknown` +- **Required:** Yes + +Function executed inside the transition. + +## Return value + +- **Type:** `Promise<void>` + +Resolves when the transition completes. + +## Behavior + +- On the client, `fn` runs asynchronously in a microtask and its updates run as a transition. +- Nested calls inside an active transition reuse that transition and return its existing promise, which resolves after transition work completes. +- On the server, `startTransition(fn)` runs `fn()` synchronously. +- `startTransition` is the transition-starting function exposed by [`useTransition`](/reference/reactive-utilities/use-transition), without the `pending` accessor. + +## Examples + +### Basic usage + +```tsx +import { + Suspense, + createResource, + createSignal, + startTransition, +} from "solid-js"; + +function Example() { + const [userId, setUserId] = createSignal(1); + const [user] = createResource(userId, async (id) => { + const response = await fetch(`/api/users/${id}`); + return response.json(); + }); + + async function showNextUser() { + await startTransition(() => { + setUserId(2); + }); + } + + return ( + <> + <button onClick={showNextUser}>Load next user</button> + <Suspense fallback={<p>Loading user...</p>}> + <pre>{JSON.stringify(user(), null, 2)}</pre> + </Suspense> + </> + ); +} +``` + +## Related + +- [`useTransition`](/reference/reactive-utilities/use-transition) +- [`Suspense`](/reference/components/suspense) diff --git a/src/routes/reference/reactive-utilities/untrack.mdx b/src/routes/reference/reactive-utilities/untrack.mdx index 136ed1d83..4c9cfbbe0 100644 --- a/src/routes/reference/reactive-utilities/untrack.mdx +++ b/src/routes/reference/reactive-utilities/untrack.mdx @@ -1,45 +1,120 @@ --- title: untrack +use_cases: >- + static values, initial values, default props, performance optimization, + non-reactive access +tags: + - tracking + - performance + - props + - reactivity + - optimization + - defaults +version: "1.0" +description: >- + Execute a function without collecting dependencies from the current reactive + scope. --- -Ignores tracking any of the dependencies in the executing code block and returns the value. This helper is useful when a certain `prop` will never update and thus it is ok to use it outside of the tracking scope. +`untrack` executes a function without collecting dependencies from the current reactive scope. -```tsx title="component.tsx" -import { untrack } from "solid-js" +## Import + +```ts +import { untrack } from "solid-js"; +``` + +## Type + +```ts +function untrack<T>(fn: () => T): T; +``` + +## Parameters + +### `fn` + +- **Type:** `() => T` +- **Required:** Yes + +Function executed outside the current tracking context. + +## Return value + +- **Type:** `T` + +Returns the value produced by `fn` unchanged. + +## Behavior + +- `untrack` only affects reads inside the provided function. Signals read there do not become dependencies of the surrounding computation. +- `untrack` does not create or restore an owner. + +## Examples + +### Read part of an effect without tracking + +```tsx +import { createEffect, untrack } from "solid-js"; export function Component(props) { - const value = untrack(() => props.value) + createEffect(() => { + console.log( + props.id, + untrack(() => props.label) + ); + }); - return <div>{value}</div> - } + return <div>{props.id}</div>; } ``` -## Initial and Default Values +### Avoid tracking part of an effect + +```tsx +import { createEffect, createSignal, untrack } from "solid-js"; + +function Example() { + const [count, setCount] = createSignal(0); + const [label] = createSignal("count"); -It is not necessary to manually untrack values that are suppose to serve as a default or initial value to a signal. Even with the linter configured to enforce tracking, the linter will accept it when a `prop` is prefixed with `default` or `initial` as it is a common pattern to use them as such. + createEffect(() => { + console.log( + untrack(() => label()), + count() + ); + }); + return <button onClick={() => setCount((c) => c + 1)}>Increment</button>; +} +``` + +## Notes + +Default and initial prop values can be read directly when initializing a signal. This pattern commonly appears with names such as `initialName` and `defaultName`. ```tsx tab title="initialValue" {5} -// component.tsx -import { createSignal } from "solid-js" +import { createSignal } from "solid-js"; export function Component(props) { - const [name, setName] = createSignal(props.initialName) + const [name, setName] = createSignal(props.initialName); - return <div>{name()}</div> - } + return <div>{name()}</div>; } ``` ```tsx tab title="defaultValue" {5} -// component.tsx -import { createSignal } from "solid-js" +import { createSignal } from "solid-js"; export function Component(props) { - const [name, setName] = createSignal(props.defaultName) + const [name, setName] = createSignal(props.defaultName); - return <div>{name()}</div> - } + return <div>{name()}</div>; } ``` + +## Related + +- [`onMount`](/reference/lifecycle/on-mount) +- [`createEffect`](/reference/basic-reactivity/create-effect) +- [`on`](/reference/reactive-utilities/on-util) diff --git a/src/routes/reference/reactive-utilities/use-transition.mdx b/src/routes/reference/reactive-utilities/use-transition.mdx index 97b085731..c43d10842 100644 --- a/src/routes/reference/reactive-utilities/use-transition.mdx +++ b/src/routes/reference/reactive-utilities/use-transition.mdx @@ -1,26 +1,97 @@ --- title: useTransition +use_cases: >- + async batching, loading states, suspense integration, concurrent updates, ui + transitions +tags: + - transitions + - async + - suspense + - loading + - batching + - concurrent +version: "1.0" +description: >- + Return a pending-state accessor and a function that starts a transition. --- +`useTransition` returns a pending-state accessor and a function that starts a transition. + +## Import + ```ts -import { useTransition } from "solid-js" +import { useTransition } from "solid-js"; +``` +## Type + +```ts function useTransition(): [ pending: () => boolean, - startTransition: (fn: () => void) => Promise<void> -] - + start: (fn: () => void) => Promise<void>, +]; ``` -Used to batch async updates in a transaction deferring commit until all async processes are complete. -This is tied into Suspense and only tracks resources read under Suspense boundaries. +## Parameters -```ts -const [isPending, start] = useTransition(); +`useTransition` does not take any parameters. + +## Return value + +- **Type:** `[() => boolean, (fn: () => void) => Promise<void>]` -// check if transitioning -isPending(); +Returns a tuple containing: -// wrap in transition -start(() => setSignal(newValue), () => /* transition is done */) +- `pending`: an accessor that reports whether the transition is pending +- `start`: a function that starts a transition + +## Behavior + +- `start` is the same transition-starting function exposed by [`startTransition`](/reference/reactive-utilities/start-transition). +- On the client, `start` schedules its callback asynchronously in a microtask. +- `pending()` reflects whether that transition is still pending. +- Transition state integrates with Suspense and resource reads under Suspense boundaries. +- On the server, `pending()` is `false` and transitions run synchronously. + +## Examples + +### Basic usage + +```tsx +import { + Suspense, + createResource, + createSignal, + useTransition, +} from "solid-js"; + +function Example() { + const [userId, setUserId] = createSignal(1); + const [user] = createResource(userId, async (id) => { + const response = await fetch(`/api/users/${id}`); + return response.json(); + }); + const [pending, start] = useTransition(); + + return ( + <> + <button + onClick={async () => { + await start(() => setUserId(2)); + }} + > + Load next user + </button> + <div>{pending() ? "Loading transition..." : "Ready"}</div> + <Suspense fallback={<p>Loading user...</p>}> + <pre>{JSON.stringify(user(), null, 2)}</pre> + </Suspense> + </> + ); +} ``` + +## Related + +- [`startTransition`](/reference/reactive-utilities/start-transition) +- [`Suspense`](/reference/components/suspense) diff --git a/src/routes/reference/rendering/data.json b/src/routes/reference/rendering/data.json index cd3ffdce0..3f811d6b3 100644 --- a/src/routes/reference/rendering/data.json +++ b/src/routes/reference/rendering/data.json @@ -4,6 +4,7 @@ "dev.mdx", "hydrate.mdx", "hydration-script.mdx", + "is-dev.mdx", "is-server.mdx", "render.mdx", "render-to-stream.mdx", diff --git a/src/routes/reference/rendering/dev.mdx b/src/routes/reference/rendering/dev.mdx index 39cf81e4f..f019ecf69 100644 --- a/src/routes/reference/rendering/dev.mdx +++ b/src/routes/reference/rendering/dev.mdx @@ -1,24 +1,66 @@ --- title: DEV +use_cases: >- + development builds, development-only checks, conditional dev-only code +tags: + - development + - debugging + - builds + - conditional +version: "1.0" +description: >- + Read the development-only `DEV` export from `solid-js`. --- +`DEV` is a development-only export from `solid-js`. +It exposes Solid's development hooks and internals for development tooling and diagnostics. + +## Import + ```ts -import { DEV } from "solid-js" +import { DEV } from "solid-js"; +``` -const DEV: object | undefined +## Type + +```ts +const DEV: + | { + readonly hooks: { + afterUpdate: (() => void) | null; + afterCreateOwner: ((owner: unknown) => void) | null; + afterCreateSignal: ((signal: unknown) => void) | null; + afterRegisterGraph: ((sourceMapValue: unknown) => void) | null; + }; + readonly writeSignal: (...args: unknown[]) => unknown; + readonly registerGraph: (...args: unknown[]) => unknown; + } + | undefined; ``` -On the client, Solid provides (via [conditional exports](https://nodejs.org/api/packages.html#conditional-exports)) different builds depending on whether the **development** condition is set. -Development mode provides some additional checking — e.g. detecting accidental use of multiple instances of Solid — which are removed in production builds. +## Value + +- **Type:** development-only object or `undefined` -If you want code to run only in development mode (most useful in libraries), you can check whether the **DEV** export is defined. -Note that it is always defined on the server, so you may want to combine with [isServer](/reference/rendering/is-server): +## Behavior + +- In the development browser bundle, `DEV` is defined and exposes development hooks and internals. +- In production and server bundles, `DEV` is `undefined`. +- `DEV` is intended for tooling, diagnostics, and library code that needs development-only behavior. + +## Examples + +### Basic usage ```ts -import { DEV } from "solid-js" -import { isServer } from "solid-js/web" +import { DEV } from "solid-js"; -if (DEV && !isServer) { - console.log(...); +if (DEV) { + console.warn("development-only check"); } ``` + +## Related + +- [`isDev`](/reference/rendering/is-dev) +- [`isServer`](/reference/rendering/is-server) diff --git a/src/routes/reference/rendering/hydrate.mdx b/src/routes/reference/rendering/hydrate.mdx index 31ce37db1..0a57d5858 100644 --- a/src/routes/reference/rendering/hydrate.mdx +++ b/src/routes/reference/rendering/hydrate.mdx @@ -1,32 +1,96 @@ --- title: hydrate +use_cases: >- + hydrating server-rendered HTML, attaching client behavior to an SSR subtree +tags: + - hydration + - ssr + - rendering + - dom +version: "1.0" +description: >- + Hydrate server-rendered HTML and attach Solid's client-side behavior to an + existing DOM subtree. --- -```ts -import { hydrate } from "solid-js/web" -import type { JSX } from "solid-js" -import type { MountableElement } from "solid-js/web" +`hydrate` attaches Solid's client-side behavior to DOM that was already rendered on the server. -function hydrate( - fn: () => JSX.Element, - node: MountableElement, - options?: { renderId?: string; owner?: unknown } -): () => void +## Import +```ts +import { hydrate } from "solid-js/web"; ``` -This method is similar to `render` except that it attempts to rehydrate what is already rendered to the DOM. -When initializing in the browser a page has already been server rendered. +## Type ```ts -const dispose = hydrate(App, document.getElementById("app")) +type MountableElement = + | Element + | Document + | ShadowRoot + | DocumentFragment + | Node; + +function hydrate( + fn: () => JSX.Element, + node: MountableElement, + options?: { renderId?: string; owner?: unknown } +): () => void; ``` ## Parameters -| Prop | type | description | -| -------------------- | ------------------ | ----------------------------------------------- | -| fn | `() => JSX.Element`| Function that returns the application code. | -| node | MountableElement | DOM Element to mount the application to | -| options.renderId | string | | -| options.owner | unknown | | \ No newline at end of file +### `fn` + +- **Type:** `() => JSX.Element` + +Function that returns the root JSX to hydrate. + +### `node` + +- **Type:** `MountableElement` + +DOM node that contains the server-rendered markup. + +### `options` + +#### `renderId` + +- **Type:** `string` + +Scopes hydration lookup to a specific rendered subtree. + +#### `owner` + +- **Type:** `unknown` + +Owner used for the created hydration root. + +## Return value + +- **Type:** `() => void` + +Dispose function for the hydrated root. + +## Behavior + +- `hydrate` is a client-only API. +- `hydrate` reuses DOM produced by Solid's server renderer instead of creating a new subtree, locating nodes through Solid's hydration markers and optionally scoping that lookup with `renderId`. +- The hydrated DOM and the JSX returned by `fn` must match the server output for hydration to succeed. +- The returned function disposes the hydrated root. + +## Examples + +### Basic usage + +```tsx +import { hydrate } from "solid-js/web"; + +// #app already contains server-rendered Solid markup +const dispose = hydrate(() => <App />, document.getElementById("app")!); +``` + +## Related + +- [`render`](/reference/rendering/render) +- [`HydrationScript`](/reference/rendering/hydration-script) diff --git a/src/routes/reference/rendering/hydration-script.mdx b/src/routes/reference/rendering/hydration-script.mdx index 3448d9041..33225c728 100644 --- a/src/routes/reference/rendering/hydration-script.mdx +++ b/src/routes/reference/rendering/hydration-script.mdx @@ -1,26 +1,109 @@ --- title: hydrationScript +use_cases: >- + server rendering, hydration bootstrap, capturing delegated events before + client hydration +tags: + - ssr + - hydration + - bootstrap + - events +version: "1.0" +description: >- + Generate the SSR hydration bootstrap script with `HydrationScript` or + `generateHydrationScript`. --- +`HydrationScript` and `generateHydrationScript` generate Solid's SSR hydration bootstrap script. + +## Import + ```ts -import { generateHydrationScript, HydrationScript } from "solid-js/web" -import type { JSX } from "solid-js" +import { HydrationScript, generateHydrationScript } from "solid-js/web"; +``` -function generateHydrationScript(options: { - nonce?: string - eventNames?: string[] -}): string +## Type +```ts function HydrationScript(props: { - nonce?: string - eventNames?: string[] -}): JSX.Element + nonce?: string; + eventNames?: string[]; +}): JSX.Element; + +function generateHydrationScript(options: { + nonce?: string; + eventNames?: string[]; +}): string; +``` + +## `HydrationScript` props + +### `nonce` + +- **Type:** `string` + +Nonce applied to the generated `<script>` tag. + +### `eventNames` + +- **Type:** `string[]` + +Delegated event names captured before client scripts load. + +## `generateHydrationScript` options + +### `nonce` + +- **Type:** `string` + +Nonce applied to the generated script tag. + +### `eventNames` + +- **Type:** `string[]` + +Delegated event names captured before client scripts load. + +## Return value + +- **Type:** `JSX.Element` for `HydrationScript`, `string` for `generateHydrationScript` + +## Behavior + +- The generated script initializes `window._$HY` and bootstraps delegated event replay before the runtime loads. +- The default captured delegated events are `"click"` and `"input"` unless `eventNames` is overridden. +- Place the generated script once in the server-rendered document when the page will hydrate on the client. +- `HydrationScript` returns JSX for server-rendered HTML output, and `generateHydrationScript` returns a string for manual HTML generation. +- In browser bundles, these exports are placeholders that return `undefined`. + +## Examples + +### `HydrationScript` + +```tsx +import { HydrationScript } from "solid-js/web"; +import type { JSX } from "solid-js"; + +function Html(props: { children: JSX.Element }) { + return ( + <html lang="en"> + <head> + <HydrationScript /> + </head> + <body>{props.children}</body> + </html> + ); +} +``` + +### `generateHydrationScript` + +```ts +import { generateHydrationScript } from "solid-js/web"; +const script = generateHydrationScript({ nonce: "nonce-value" }); ``` -Hydration Script is a special script that should be placed once on the page to bootstrap hydration before Solid's runtime has loaded. -It comes both as a function that can be called and inserted in an HTML string, or as a Component if you are rendering JSX from the `<html>` tag. +## Related -The options are for the **nonce** to be put on the script tag and any event names for that Solid should capture before scripts have loaded and replay during hydration. -These events are limited to those that Solid delegates which include most UI Events that are composed and bubble. -By default it is only click and input events. +- [`hydrate`](/reference/rendering/hydrate) diff --git a/src/routes/reference/rendering/is-dev.mdx b/src/routes/reference/rendering/is-dev.mdx new file mode 100644 index 000000000..7ab4a7c20 --- /dev/null +++ b/src/routes/reference/rendering/is-dev.mdx @@ -0,0 +1,50 @@ +--- +title: isDev +use_cases: >- + development-build checks, browser-side dev-only branches, bundle-level + development flags +tags: + - development + - debugging + - builds + - conditional +version: "1.0" +description: >- + Read the boolean that indicates whether the imported `solid-js/web` bundle is the development browser bundle. +--- + +`isDev` is a constant boolean exported by `solid-js/web`. + +## Import + +```ts +import { isDev } from "solid-js/web"; +``` + +## Type + +```ts +const isDev: boolean; +``` + +## Behavior + +- `isDev` is a bundle constant: it is `true` in the development browser bundle and `false` in production and server bundles. [`DEV`](/reference/rendering/dev) is a separate development-only export from `solid-js`. +- Because it is exported as a constant, bundlers can eliminate unreachable branches. + +## Examples + +### Basic usage + +```ts +import { isDev } from "solid-js/web"; + +if (isDev) { + debugPanel.mount(); +} +``` + +## Related + +- [`DEV`](/reference/rendering/dev) +- [`isServer`](/reference/rendering/is-server) diff --git a/src/routes/reference/rendering/is-server.mdx b/src/routes/reference/rendering/is-server.mdx index 4a8539ab2..331f40f54 100644 --- a/src/routes/reference/rendering/is-server.mdx +++ b/src/routes/reference/rendering/is-server.mdx @@ -1,23 +1,49 @@ --- title: isServer +use_cases: >- + server-only branches, client-only branches, bundle-level environment checks +tags: + - ssr + - environment + - bundling + - conditional +version: "1.0" +description: >- + Read whether the current `solid-js/web` bundle is the server bundle. --- +`isServer` is a constant boolean that indicates whether code is running in the server bundle. + +## Import + ```ts -import { isServer } from "solid-js/web" +import { isServer } from "solid-js/web"; +``` -const isServer: boolean +## Type +```ts +const isServer: boolean; ``` -This indicates that the code is being run as the server or browser bundle. -As the underlying runtimes export this as a constant boolean it allows bundlers to eliminate the code and their used imports from the respective bundles. +## Behavior + +- `isServer` is `true` in the server bundle and `false` in the browser bundle. +- Because it is exported as a constant, bundlers can eliminate unreachable branches. + +## Examples + +### Basic usage ```ts import { isServer } from "solid-js/web"; if (isServer) { - // I will never make it to the browser bundle -} else { - // won't be run on the server; + serverOnlyWork(); } ``` + +## Related + +- [`DEV`](/reference/rendering/dev) +- [`isDev`](/reference/rendering/is-dev) diff --git a/src/routes/reference/rendering/render-to-stream.mdx b/src/routes/reference/rendering/render-to-stream.mdx index d51076eb5..7ea469481 100644 --- a/src/routes/reference/rendering/render-to-stream.mdx +++ b/src/routes/reference/rendering/render-to-stream.mdx @@ -1,51 +1,112 @@ --- title: renderToStream +use_cases: >- + streaming server rendering, progressive HTML delivery, suspense-driven server + output +tags: + - ssr + - streaming + - async + - suspense +version: "1.0" +description: >- + Stream server-rendered HTML and continue writing async content as it + resolves. --- +`renderToStream` streams server-rendered HTML and continues writing async content as it resolves. + +## Import + ```ts -import { renderToStream } from "solid-js/web" +import { renderToStream } from "solid-js/web"; +``` + +## Type +```ts function renderToStream<T>( fn: () => T, options?: { - nonce?: string - renderId?: string - onCompleteShell?: () => void - onCompleteAll?: () => void + nonce?: string; + renderId?: string; + onCompleteShell?: (info: { write: (v: string) => void }) => void; + onCompleteAll?: (info: { write: (v: string) => void }) => void; } ): { - pipe: (writable: { write: (v: string) => void }) => void - pipeTo: (writable: WritableStream) => void -} - + pipe: (writable: { write: (v: string) => void }) => void; + pipeTo: (writable: WritableStream) => void; +}; ``` -This method renders to a stream. -It renders the content synchronously including any Suspense fallback placeholders, and then continues to stream the data and HTML from any async resource as it completes. +## Parameters -```ts -// node -renderToStream(App).pipe(res) +### `fn` + +- **Type:** `() => T` + +Function that returns the root output to render. + +### `options` + +#### `nonce` + +- **Type:** `string` + +Nonce applied to inline scripts emitted during rendering. + +#### `renderId` + +- **Type:** `string` + +Identifier used to namespace the render output. -// web stream -const { readable, writable } = new TransformStream() -renderToStream(App).pipeTo(writable) +#### `onCompleteShell` + +- **Type:** `(info: { write: (v: string) => void }) => void` + +Callback invoked when the shell is ready to flush. + +#### `onCompleteAll` + +- **Type:** `(info: { write: (v: string) => void }) => void` + +Callback invoked after all server suspense boundaries have settled. + +## Return value + +- **Type:** `{ pipe: ..., pipeTo: ... }` + +Streaming controller with `pipe` and `pipeTo` methods. + +## Behavior + +- `renderToStream` is a server rendering API and is unsupported in browser bundles. +- It renders the shell first, including suspense fallback content, and can flush that output before later async fragments and serialized data stream as resources resolve. +- `onCompleteShell` and `onCompleteAll` receive a `write()` helper for injecting additional output into the stream. +- `pipe` writes to Node-style writable targets. +- `pipeTo` writes to a `WritableStream`. + +## Examples + +### `pipe` + +```tsx +import { renderToStream } from "solid-js/web"; + +renderToStream(() => <App />).pipe(response); ``` -`onCompleteShell` fires when synchronous rendering is complete before writing the first flush to the stream out to the browser. -`onCompleteAll` is called when all server Suspense boundaries have settled. -`renderId` is used to namespace renders when having multiple top level roots. +### `pipeTo` -:::note - This API replaces the previous pipeToWritable and pipeToNodeWritable - APIs. -::: +```tsx +import { renderToStream } from "solid-js/web"; + +const { writable } = new TransformStream(); +renderToStream(() => <App />).pipeTo(writable); +``` -## Options +## Related -| Name | Type | Description | -| --------------- | ---------- | ---------------------------------------------------------------- | -| nonce | string | The nonce to use for inline scripts. | -| renderId | string | The id to use for this render. | -| onCompleteShell | () => void | A callback that fires when the shell is complete. | -| onCompleteAll | () => void | A callback that fires when all Suspense boundaries have settled. | +- [`renderToString`](/reference/rendering/render-to-string) +- [`renderToStringAsync`](/reference/rendering/render-to-string-async) diff --git a/src/routes/reference/rendering/render-to-string-async.mdx b/src/routes/reference/rendering/render-to-string-async.mdx index 16c2509eb..b6fcf3ad1 100644 --- a/src/routes/reference/rendering/render-to-string-async.mdx +++ b/src/routes/reference/rendering/render-to-string-async.mdx @@ -1,34 +1,92 @@ --- title: renderToStringAsync +use_cases: >- + async server rendering, waiting for suspense boundaries, HTML generation with + async data +tags: + - ssr + - async + - suspense + - rendering +version: "1.0" +description: >- + Render HTML to a string after async suspense boundaries settle. --- +`renderToStringAsync` renders HTML to a string after async suspense boundaries settle. + +## Import + ```ts -import { renderToStringAsync } from "solid-js/web" +import { renderToStringAsync } from "solid-js/web"; +``` + +## Type +```ts function renderToStringAsync<T>( fn: () => T, options?: { - timeoutMs?: number - renderId?: string - nonce?: string + timeoutMs?: number; + nonce?: string; + renderId?: string; } -): Promise<string> - +): Promise<string>; ``` -Same as `renderToString` except that it will wait for all `<Suspense>` boundaries to resolve before returning the results. -Resource data is automatically serialized into the script tag and will be hydrated on client load. +## Parameters -`renderId` is used to namespace renders when having multiple top level roots. +### `fn` -```ts -const html = await renderToStringAsync(App) +- **Type:** `() => T` + +Function that returns the root output to render. + +### `options` + +#### `timeoutMs` + +- **Type:** `number` + +Maximum wait time before the returned promise rejects. + +#### `nonce` + +- **Type:** `string` + +Nonce applied to inline scripts emitted during rendering. + +#### `renderId` + +- **Type:** `string` + +Identifier used to namespace the render output. + +## Return value + +- **Type:** `Promise<string>` + +Promise that resolves to the rendered HTML string. + +## Behavior + +- `renderToStringAsync` is a server rendering API and is unsupported in browser bundles. +- It waits for server suspense boundaries to settle before resolving the final HTML string. +- `timeoutMs` limits how long the render waits for async suspense work to finish. +- Resource data is serialized for client hydration. +- `renderId` namespaces the render output when multiple top-level roots are present. + +## Examples + +### Basic usage + +```tsx +import { renderToStringAsync } from "solid-js/web"; + +const html = await renderToStringAsync(() => <App />); ``` -## Options +## Related -| Name | Type | Description | -| ----------- | -------- | -------------------------------------------------------------------------------------------- | -| `timeoutMs` | `number` | The number of milliseconds to wait for a `<Suspense>` boundary to resolve before timing out. | -| `renderId` | `string` | The id to use for the render. | -| `nonce` | `string` | The nonce to use for the script tag. | +- [`renderToString`](/reference/rendering/render-to-string) +- [`renderToStream`](/reference/rendering/render-to-stream) diff --git a/src/routes/reference/rendering/render-to-string.mdx b/src/routes/reference/rendering/render-to-string.mdx index 454b0c971..3ce5667ca 100644 --- a/src/routes/reference/rendering/render-to-string.mdx +++ b/src/routes/reference/rendering/render-to-string.mdx @@ -1,33 +1,84 @@ --- title: renderToString +use_cases: >- + synchronous server rendering, HTML generation, progressive hydration output +tags: + - ssr + - rendering + - hydration + - synchronous +version: "1.0" +description: >- + Render HTML to a string synchronously on the server. --- +`renderToString` renders HTML to a string synchronously on the server. + +## Import + ```ts -import { renderToString } from "solid-js/web" +import { renderToString } from "solid-js/web"; +``` +## Type + +```ts function renderToString<T>( fn: () => T, options?: { - nonce?: string - renderId?: string + nonce?: string; + renderId?: string; } -): string - +): string; ``` -Renders to a string synchronously. -The function also generates a script tag for progressive hydration. -Options include eventNames to listen to before the page loads and play back on hydration, and nonce to put on the script tag. +## Parameters -`renderId` is used to namespace renders when having multiple top level roots. +### `fn` -```ts -const html = renderToString(App) +- **Type:** `() => T` + +Function that returns the root output to render. + +### `options` + +#### `nonce` + +- **Type:** `string` + +Nonce applied to inline scripts emitted during rendering. + +#### `renderId` + +- **Type:** `string` + +Identifier used to namespace the render output. + +## Return value + +- **Type:** `string` + +Rendered HTML string. + +## Behavior + +- `renderToString` is a server rendering API, is unsupported in browser bundles, and completes synchronously. +- It returns the current render output without waiting for async suspense boundaries to settle. +- The output includes hydration markup. Inline serialized scripts are emitted only when serializer data is produced. +- Registered assets are injected into the HTML output, typically before `</head>`. +- `renderId` namespaces the render output when multiple top-level roots are present. + +## Examples + +### Basic usage + +```tsx +import { renderToString } from "solid-js/web"; + +const html = renderToString(() => <App />); ``` -## Options +## Related -| Name | Type | Description | -| ---------- | -------- | ------------------------------------ | -| `nonce` | `string` | The nonce to use for the script tag. | -| `renderId` | `string` | The id to use for the script tag. | +- [`renderToStringAsync`](/reference/rendering/render-to-string-async) +- [`renderToStream`](/reference/rendering/render-to-stream) diff --git a/src/routes/reference/rendering/render.mdx b/src/routes/reference/rendering/render.mdx index f30f5b297..b78314e51 100644 --- a/src/routes/reference/rendering/render.mdx +++ b/src/routes/reference/rendering/render.mdx @@ -1,34 +1,74 @@ --- title: render +use_cases: >- + mounting a client app, browser entry points, attaching a root to the DOM +tags: + - mounting + - rendering + - client + - dom +version: "1.0" +description: >- + Mount a Solid root into a DOM node in the browser. --- -```ts -import { render } from "solid-js/web" -import type { JSX } from "solid-js" -import type { MountableElement } from "solid-js/web" +`render` mounts a Solid root into a DOM node in the browser. -function render( - code: () => JSX.Element, - element: MountableElement -): () => void +## Import +```ts +import { render } from "solid-js/web"; ``` -This is the browser app entry point. -Provide a top-level component function and an element to mount to. -It is recommended this element be empty: while `render` will just append children, the returned dispose function will remove all children. +## Type ```ts -const dispose = render(App, document.getElementById("app")) -// or -const dispose = render(() => <App />, document.getElementById("app")) -``` +type MountableElement = + | Element + | Document + | ShadowRoot + | DocumentFragment + | Node; -It's important that the first argument is a function: do not pass JSX directly (as in `render(<App/>, ...)`), because this will call App before render can set up a root to track signal dependencies within App. +function render(code: () => JSX.Element, element: MountableElement): () => void; +``` ## Parameters -| Argument | Type | Description | -| -------------------- | ------------------- | ----------------------------------------------- | -| code | `() => JSX.Element` | Function that returns the application code. | -| element | MountableElement | DOM Element to mount the application to | \ No newline at end of file +### `code` + +- **Type:** `() => JSX.Element` + +Function that returns the root JSX to mount. + +### `element` + +- **Type:** `MountableElement` + +DOM node that receives the rendered output. + +## Return value + +- **Type:** `() => void` + +Dispose function for the mounted root. + +## Behavior + +- `render` is a browser/client API and is unsupported in the server bundle. It creates a new root and appends its output to `element`. When `element` is `document`, it evaluates `code()` directly instead of using DOM insertion. +- The first argument must be a function so Solid can establish the root before evaluating JSX. +- The returned function disposes the root and clears the mount container's content, so mounting into an empty container is safest. + +## Examples + +### Basic usage + +```tsx +import { render } from "solid-js/web"; + +const dispose = render(() => <App />, document.getElementById("app")!); +``` + +## Related + +- [`hydrate`](/reference/rendering/hydrate) diff --git a/src/routes/reference/secondary-primitives/create-computed.mdx b/src/routes/reference/secondary-primitives/create-computed.mdx index bd565ff38..624067c1f 100644 --- a/src/routes/reference/secondary-primitives/create-computed.mdx +++ b/src/routes/reference/secondary-primitives/create-computed.mdx @@ -1,31 +1,126 @@ --- title: createComputed +use_cases: >- + immediate reactivity, building primitives, side effects with dependencies, + reactive updates, custom reactive patterns +tags: + - reactivity + - computation + - primitives + - effects + - tracking +version: "1.0" +description: >- + Create an immediate reactive computation that runs synchronously when created + and whenever its dependencies change. --- +`createComputed` creates an immediate reactive computation. +It runs synchronously in the current execution context when created, then re-runs whenever its tracked dependencies change. + +## Import + ```ts -import { createComputed } from "solid-js" +import { createComputed } from "solid-js"; +``` -function createComputed<T>(fn: (v: T) => T, value?: T): void +## Type +```ts +function createComputed<Next>( + fn: EffectFunction<undefined | NoInfer<Next>, Next> +): void; +function createComputed<Next, Init = Next>( + fn: EffectFunction<Init | Next, Next>, + value: Init, + options?: { name?: string } +): void; +function createComputed<Next, Init>( + fn: EffectFunction<Init | Next, Next>, + value?: Init, + options?: { name?: string } +): void; ``` -`createComputed` creates a new computation that immediately runs the given function in a tracking scope, thus automatically tracking its dependencies, and automatically reruns the function whenever the dependencies changes. -The function gets called with an argument equal to the value returned from the function's last execution, or on the first call, equal to the optional second argument to `createComputed`. -Note that the return value of the function is not otherwise exposed; in particular, createComputed has no return value. +## Parameters + +### `fn` + +- **Type:** `EffectFunction<undefined | NoInfer<Next>, Next> | EffectFunction<Init | Next, Next>` +- **Required:** Yes + +The function that performs the computation. +It executes immediately to track dependencies and re-runs whenever a dependency changes. + +It receives the value returned from the previous execution as its argument. +On the initial execution, it receives the [`value`](#value) parameter (if provided) or `undefined`. + +### `value` + +- **Type:** `Init` +- **Required:** No + +The initial value passed to `fn` on its first execution. + +### `options` + +- **Type:** `{ name?: string }` +- **Required:** No + +An optional configuration object with the following properties: + +#### `name` -`createComputed` is the most immediate form of reactivity in Solid, and is most useful for building other reactive primitives. -For example, some other Solid primitives are built from `createComputed`. -However, it should be used with care, as `createComputed` can easily cause more unnecessary updates than other reactive primitives. -Before using it, consider the closely related primitives [`createMemo`](/reference/basic-reactivity/create-memo) and [`createRenderEffect`](/reference/secondary-primitives/create-render-effect). +- **Type:** `string` +- **Required:** No -Like `createMemo`, `createComputed` calls its function immediately on updates (unless you're in a [batch](/reference/reactive-utilities/batch), [effect](/reference/basic-reactivity/create-effect), or [transition](/reference/reactive-utilities/use-transition)). -However, while `createMemo` functions should be pure (not set any signals), `createComputed` functions can set signals. -Related, `createMemo` offers a readonly signal for the return value of the function, whereas to do the same with `createComputed` you would need to set a signal within the function. -If it is possible to use pure functions and `createMemo`, this is likely more efficient, as Solid optimizes the execution order of memo updates, whereas updating a signal within `createComputed` will immediately trigger reactive updates some of which may turn out to be unnecessary. +A debug name for the computation. +It is used for identification in debugging tools like the [Solid Debugger](https://github.com/thetarnav/solid-devtools). + +## Return value + +- **Type:** `void` + +`createComputed` does not return a value. + +## Behavior + +- `createComputed` runs immediately when it is created. +- It tracks reactive reads inside `fn` and re-runs synchronously when those dependencies change. +- Unlike [`createMemo`](/reference/basic-reactivity/create-memo), it does not expose a derived accessor. +- `createComputed` is primarily used to build reactive primitives. Application code that derives state usually wants [`createMemo`](/reference/basic-reactivity/create-memo) instead. + +## Examples + +### Build a writable derived signal + +```tsx +import { createComputed, createSignal } from "solid-js"; + +function createWritableMemo<T>(fn: () => T) { + const [value, setValue] = createSignal(fn()); + + createComputed(() => { + setValue(fn()); + }); + + return value; +} + +function Counter() { + const [count, setCount] = createSignal(1); + const double = createWritableMemo(() => count() * 2); + + return ( + <> + <p>{double()}</p> + <button onClick={() => setCount((value) => value + 1)}>Increment</button> + </> + ); +} +``` -## Arguments +## Related -| Name | Type | Description | -| :------ | :------------ | :----------------------------------------- | -| `fn` | `(v: T) => T` | The function to run in a tracking scope. | -| `value` | `T` | The initial value to pass to the function. | +- [`createMemo`](/reference/basic-reactivity/create-memo) +- [`createRenderEffect`](/reference/secondary-primitives/create-render-effect) diff --git a/src/routes/reference/secondary-primitives/create-deferred.mdx b/src/routes/reference/secondary-primitives/create-deferred.mdx index d62f43b08..5dfb8bc09 100644 --- a/src/routes/reference/secondary-primitives/create-deferred.mdx +++ b/src/routes/reference/secondary-primitives/create-deferred.mdx @@ -1,29 +1,110 @@ --- title: createDeferred +use_cases: >- + performance optimization, idle updates, non-critical ui updates, debouncing + changes, reducing re-renders +tags: + - performance + - optimization + - deferred + - idle + - updates +version: "1.0" +description: >- + Create a deferred accessor whose updates are scheduled for later execution or + when the timeout is reached. --- +`createDeferred` returns a deferred accessor for a source accessor. + +## Import + +```ts +import { createDeferred } from "solid-js"; +``` + +## Type + ```ts -import { createDeferred } from "solid-js" +type Accessor<T> = () => T; function createDeferred<T>( - source: () => T, + source: Accessor<T>, options?: { - timeoutMs?: number - equals?: false | ((prev: T, next: T) => boolean) - name?: string + timeoutMs?: number; + equals?: false | ((prev: T, next: T) => boolean); + name?: string; } -): () => T - +): Accessor<T>; ``` -Creates a readonly that only notifies downstream changes when the browser is idle. -`timeoutMs` is the maximum time to wait before forcing the update. +## Parameters + +### `source` + +- **Type:** `Accessor<T>` +- **Required:** Yes + +Accessor used as the deferred source. + +### `options` + +#### `timeoutMs` + +- **Type:** `number` + +Maximum delay before the deferred value is updated. + +#### `equals` -## Options +- **Type:** `false | ((prev: T, next: T) => boolean)` + +Comparison function used to determine whether the deferred accessor should notify dependents. + +#### `name` + +- **Type:** `string` + +Debug name used by development tooling. + +## Return value + +- **Type:** `Accessor<T>` + +Returns an accessor that exposes the deferred value. + +## Behavior + +- The deferred accessor initially reflects the current source value. +- Later updates are deferred through Solid's scheduler until later execution or until `timeoutMs` is reached, so the returned accessor can lag behind the source accessor. +- `equals` controls whether downstream dependents are notified for a new value. +- `createDeferred` defers propagation of the accessor value. It does not debounce writes to the source accessor. +- On the server, `createDeferred` returns the source accessor unchanged. + +## Examples + +### Basic usage + +```tsx +import { createDeferred, createSignal } from "solid-js"; + +function Example() { + const [value, setValue] = createSignal(""); + const deferredValue = createDeferred(value); + + return ( + <> + <input + value={value()} + onInput={(event) => setValue(event.currentTarget.value)} + /> + <div>{deferredValue()}</div> + </> + ); +} +``` -| Name | Type | Description | -| --------- | ------------------------------------------ | ------------------------------------------------------ | -| timeoutMs | `number` | The maximum time to wait before forcing the update. | -| equals | `false or ((prev: T, next: T) => boolean)` | A function that returns true if the value has changed. | -| name | `string` | The name of the readonly. | +## Related +- [`createMemo`](/reference/basic-reactivity/create-memo) +- [`startTransition`](/reference/reactive-utilities/start-transition) diff --git a/src/routes/reference/secondary-primitives/create-reaction.mdx b/src/routes/reference/secondary-primitives/create-reaction.mdx index 9a49a35c1..7cfa6a092 100644 --- a/src/routes/reference/secondary-primitives/create-reaction.mdx +++ b/src/routes/reference/secondary-primitives/create-reaction.mdx @@ -1,26 +1,83 @@ --- title: createReaction +use_cases: >- + custom tracking logic, one-time reactions, separating tracking from execution, + advanced reactive patterns +tags: + - reactivity + - tracking + - custom + - effects + - advanced +version: "1.0" +description: >- + Create a reaction that runs once when the tracked expression is invalidated. --- +`createReaction` creates a reaction that invalidates once for each call to the returned tracking function. + +## Import + ```ts -import { createReaction } from "solid-js" +import { createReaction } from "solid-js"; +``` -function createReaction(onInvalidate: () => void): (fn: () => void) => void +## Type +```ts +function createReaction( + onInvalidate: () => void, + options?: { name?: string } +): (tracking: () => void) => void; ``` -Sometimes it is useful to separate tracking from re-execution. -This primitive registers a side effect that is run the first time the expression wrapped by the returned tracking function is notified of a change. +## Parameters + +### `onInvalidate` + +- **Type:** `() => void` +- **Required:** Yes + +Callback invoked when the tracked computation is invalidated. + +### `options` + +#### `name` + +- **Type:** `string` + +Debug name used by development tooling. + +## Return value + +- **Type:** `(tracking: () => void) => void` + +Returns a function that executes `tracking` and records its dependencies for a single invalidation. + +## Behavior + +- Each call to the returned function records dependencies read during `tracking`. +- `onInvalidate` runs untracked on the first change to any recorded dependency. +- On the server, the returned function just executes `tracking`. + +## Examples + +### Track a signal for one invalidation ```ts -const [s, set] = createSignal("start") +import { createReaction, createSignal } from "solid-js"; -const track = createReaction(() => console.log("something")) +const [value, setValue] = createSignal("start"); -// run the reaction next time `s` changes. -track(() => s()) +const track = createReaction(() => console.log("changed")); -set("end") // "something" +track(() => value()); -set("final") // no-op since the reaction only runs on the first update, need to call `track` again. +setValue("end"); // logs "changed" +setValue("final"); // no-op until track() runs again ``` + +## Related + +- [`createEffect`](/reference/basic-reactivity/create-effect) +- [`createComputed`](/reference/secondary-primitives/create-computed) diff --git a/src/routes/reference/secondary-primitives/create-render-effect.mdx b/src/routes/reference/secondary-primitives/create-render-effect.mdx index bf8a77852..aac6df1a1 100644 --- a/src/routes/reference/secondary-primitives/create-render-effect.mdx +++ b/src/routes/reference/secondary-primitives/create-render-effect.mdx @@ -1,57 +1,133 @@ --- title: createRenderEffect +use_cases: >- + dom manipulation during render, immediate effects, rendering phase logic, + ref-independent effects, custom rendering +tags: + - rendering + - effects + - dom + - immediate + - refs + - lifecycle +version: "1.0" +description: >- + Create a reactive computation that runs immediately during the render phase. --- -```ts -import { createRenderEffect } from "solid-js" +`createRenderEffect` creates a reactive computation that runs during the render phase as DOM is created and updated. +It tracks reactive reads inside the provided function and re-runs whenever those dependencies change. -function createRenderEffect<T>(fn: (v: T) => T, value?: T): void +## Execution Timing -``` +### Initial Run + +- A render effect runs **synchronously during the current rendering phase**, while DOM elements are being created or updated. +- It **runs before elements are mounted** to the DOM. +- **[Refs](/concepts/refs) are not set** during this initial run. + +### Subsequent Runs + +- After the initial render, the render effect **re-runs whenever any of its tracked dependencies change**. +- When multiple dependencies change within the same batch, the render effect **runs once per batch**. -A render effect is a computation similar to a regular effect (as created by [`createEffect`](/reference/basic-reactivity/create-effect)), but differs in when Solid schedules the first execution of the effect function. -While `createEffect` waits for the current rendering phase to be complete, `createRenderEffect` immediately calls the function. -Thus the effect runs as DOM elements are being created and updated, but possibly before specific elements of interest have been created, and probably before those elements have been connected to the document. -In particular, **refs** will not be set before the initial effect call. -Indeed, Solid uses `createRenderEffect` to implement the rendering phase itself, including setting of **refs**. +### Server-Side Rendering -Reactive updates to render effects are identical to effects: they queue up in response to a reactive change (e.g., a single signal update, or a batch of changes, or collective changes during an entire render phase) and run in a single [`batch`](/reference/reactive-utilities/batch) afterward (together with effects). -In particular, all signal updates within a render effect are batched. +- During SSR, render effects **run once on the server**, since they are part of the synchronous rendering phase. +- On the client, an initial run still occurs during the client rendering phase. +- After hydration, subsequent runs occur on the client when dependencies change. + +## Import + +```ts +import { createRenderEffect } from "solid-js"; +``` -Here is an example of the behavior. (Compare with the example in [`createEffect`](/reference/basic-reactivity/create-effect).) +## Type ```ts -// assume this code is in a component function, so is part of a rendering phase -const [count, setCount] = createSignal(0) - -// this effect prints count at the beginning and when it changes -createRenderEffect(() => console.log("count =", count())) -// render effect runs immediately, printing `count = 0` -console.log("hello") -setCount(1) // effect won't run yet -setCount(2) // effect won't run yet - -queueMicrotask(() => { - // now `count = 2` will print - console.log("microtask") - setCount(3) // immediately prints `count = 3` - console.log("goodbye") -}) - -// --- overall output: --- -// count = 0 [this is the only added line compared to createEffect] -// hello -// count = 2 -// microtask -// count = 3 -// goodbye +function createRenderEffect<Next>( + fn: EffectFunction<undefined | NoInfer<Next>, Next> +): void; +function createRenderEffect<Next, Init = Next>( + fn: EffectFunction<Init | Next, Next>, + value: Init, + options?: { name?: string } +): void; +function createRenderEffect<Next, Init>( + fn: EffectFunction<Init | Next, Next>, + value?: Init, + options?: { name?: string } +): void; ``` -Just like `createEffect`, the effect function gets called with an argument equal to the value returned from the effect function's last execution, or on the first call, equal to the optional second argument of `createRenderEffect`. +## Parameters + +### `fn` + +- **Type:** `EffectFunction<undefined | NoInfer<Next>, Next> | EffectFunction<Init | Next, Next>` +- **Required:** Yes + +A function to be executed as the render effect. + +It receives the value returned from the previous run, or the initial `value` during the first run. +The value returned by `fn` is passed to the next run. + +### `value` + +- **Type:** `Init` +- **Required:** No + +The initial value passed to `fn` during its first run. + +### `options` + +- **Type:** `{ name?: string }` +- **Required:** No + +An optional configuration object with the following properties: + +#### `name` + +- **Type:** `string` +- **Required:** No + +A name for the render effect, which can be useful for identification in debugging tools like the [Solid Debugger](https://github.com/thetarnav/solid-devtools). + +## Return value + +`createRenderEffect` does not return a value. + +## Behavior + +- `createRenderEffect` runs immediately when it is created. +- Its initial run happens during the render phase, before mounted DOM is connected and before refs are assigned. +- Later runs happen when tracked dependencies change. +- Most application code should use [`createEffect`](/reference/basic-reactivity/create-effect). `createRenderEffect` is mainly for render-phase work where that timing is required. + +## Examples + +### Ref timing + +```tsx +import { createRenderEffect, onMount } from "solid-js"; + +function Example() { + let element: HTMLDivElement | undefined; + + createRenderEffect(() => { + console.log("render effect", element); // undefined on the initial run + }); + + onMount(() => { + console.log("mounted", element); // <div> + }); + + return <div ref={element}>Hello</div>; +} +``` -## Arguments +## Related -| Name | Type | Description | -| :------ | :------------ | :----------------------------------------------------- | -| `fn` | `(v: T) => T` | The effect function to be called. | -| `value` | `T` | The initial value to be passed to the effect function. | +- [`createEffect`](/reference/basic-reactivity/create-effect) +- [`onCleanup`](/reference/lifecycle/on-cleanup) diff --git a/src/routes/reference/secondary-primitives/create-selector.mdx b/src/routes/reference/secondary-primitives/create-selector.mdx index 8b5c0ade0..3b43ec360 100644 --- a/src/routes/reference/secondary-primitives/create-selector.mdx +++ b/src/routes/reference/secondary-primitives/create-selector.mdx @@ -1,63 +1,104 @@ --- title: createSelector +use_cases: >- + selection states, active items, dropdown menus, tab navigation, list + highlighting, performance optimization +tags: + - reactivity + - performance + - selection + - ui-state + - optimization +version: "1.0" +description: >- + Create a keyed boolean accessor that reports whether a key matches the current + source value. --- -```ts -import { createSelector } from "solid-js" +`createSelector` returns a keyed boolean accessor derived from a source accessor. + +## Import -function createSelector<T, U>( - source: () => T, - fn?: (a: U, b: T) => boolean -): (key: U) => boolean +```ts +import { createSelector } from "solid-js"; ``` -Creates a parameterized derived boolean signal `selector(key)` that indicates -whether `key` is equal to the current value of the `source` signal. -These signals are optimized to notify each subscriber only when their `key` -starts or stops matching the reactive `source` value -(instead of every time `key` changes). -If you have *n* different subscribers with different keys, -and the `source` value changes from `a` to `b`, then -instead of all *n* subscribers updating, -at most two subscribers will update: -the signal with key `a` will change to `false`, -and the signal with key `b` will change to `true`. -Thus it reduces from *n* updates to 2 updates. - -Useful for defining the selection state of several selectable elements. -For example: +## Type -```tsx -const [selectedId, setSelectedId] = createSignal() -const isSelected = createSelector(selectedId) +```ts +type Accessor<T> = () => T; -<For each={list()}> - {(item) => <li classList={{ active: isSelected(item.id) }}>{item.name}</li>} -</For> +function createSelector<T, U = T>( + source: Accessor<T>, + fn?: (key: U, value: T) => boolean, + options?: { name?: string } +): (key: U) => boolean; ``` -In the code above, each `li` element receives an `active` class -exactly when the corresponding `item.id` is equal to `selectedId()`. -When the `selectedId` signal changes, the `li` element(s) that previously -had previously matching `id` get the `active` class removed, and the -`li` element(s) that now have a matching `id` get the `active` class added. -All other `li` elements get skipped, so if `id`s are distinct, -only 2 DOM operations get performed. +## Parameters + +### `source` + +- **Type:** `Accessor<T>` +- **Required:** Yes + +Accessor used as the selection source. + +### `fn` + +- **Type:** `(key: U, value: T) => boolean` + +Comparison function used to match a key against the current source value. + +### `options` -By contrast, the following code would perform `list().length` DOM operations -every time the `selectedId` signal changes: +#### `name` + +- **Type:** `string` + +Debug name used by development tooling. + +## Return value + +- **Type:** `(key: U) => boolean` + +Returns an accessor function that reports whether the provided key matches the current source value. Each subscriber tracks only its own key. + +## Behavior + +- The returned function compares each key against the current source value. With the default comparison, matching uses strict equality. +- Solid tracks subscribers by key, so only subscribers whose key starts or stops matching need to update. +- On the server, `createSelector` compares each key directly against `source()` without keyed subscriber bookkeeping. + +Compared with checking equality directly in every subscriber, `createSelector` keeps subscriptions keyed by the compared value. + +## Examples + +### Basic usage ```tsx -const [selectedId, setSelectedId] = createSignal() +import { createSelector, createSignal, For } from "solid-js"; + +function Example(props) { + const [selectedId, setSelectedId] = createSignal<number>(); + const isSelected = createSelector(selectedId); -<For each={list()}> - {(item) => <li classList={{ active: selectedId() === item.id }}>{item.name}</li>} -</For> + return ( + <For each={props.list}> + {(item) => ( + <li + classList={{ active: isSelected(item.id) }} + onClick={() => setSelectedId(item.id)} + > + {item.name} + </li> + )} + </For> + ); +} ``` -## Arguments +## Related -| Name | Type | Description | -| :------- | :------------------------ | :------------------------------------------- | -| `source` | `() => T` | The source signal to get the value from and compare with keys. | -| `fn` | `(a: U, b: T) => boolean` | A function to compare the key and the value, returning whether they should be treated as equal. Default: `===` | +- [`createMemo`](/reference/basic-reactivity/create-memo) +- [`<For>`](/reference/components/for) diff --git a/src/routes/reference/server-utilities/data.json b/src/routes/reference/server-utilities/data.json index 5f09a10a8..3d47aead9 100644 --- a/src/routes/reference/server-utilities/data.json +++ b/src/routes/reference/server-utilities/data.json @@ -1,6 +1,4 @@ { "title": "Server utilities", - "pages": [ - "get-request-event.mdx" - ] + "pages": ["get-request-event.mdx"] } diff --git a/src/routes/reference/server-utilities/get-request-event.mdx b/src/routes/reference/server-utilities/get-request-event.mdx index 1a409b888..37a00c6fb 100644 --- a/src/routes/reference/server-utilities/get-request-event.mdx +++ b/src/routes/reference/server-utilities/get-request-event.mdx @@ -1,68 +1,56 @@ --- title: getRequestEvent +use_cases: >- + reading the current request object, accessing request-scoped server context +tags: + - server + - ssr + - request + - context +version: "1.0" +description: >- + Read the current request event from `solid-js/web`. --- -Solid uses Async Local Storage as a way of injecting the request context anywhere on the server. -The server provides a utility function to access this context -(called a `RequestEvent`). +`getRequestEvent` returns the current request event when one is available. -```js -import { getRequestEvent } from "solid-js/web" -import type { RequestEvent } from "solid-js/web" +## Import -function getRequestEvent(): RequestEvent | undefined +```ts +import { getRequestEvent } from "solid-js/web"; ``` -You can retrieve the request event by calling `getRequestEvent`: +## Type -```js -import { getRequestEvent } from "solid-js/web" +```ts +import type { RequestEvent } from "solid-js/web"; -const event = getRequestEvent() +function getRequestEvent(): RequestEvent | undefined; ``` -## Request +## Return value -`.request` is the most important property of the `RequestEvent`. -This is a Web [Request object](https://developer.mozilla.org/en-US/docs/Web/API/Request) that represents the current request to the server. -You can access properties off of it such as `url` and `headers`. - `body`, however, does not typically need to be handled directly for things such as server functions or rendering, which already handle mapping. +- **Type:** `RequestEvent | undefined` -```js -import { getRequestEvent } from "solid-js/web" +## Behavior -const event = getRequestEvent(); -if (event) { - const auth = event.request.headers.get("Authorization"); -} -``` +- `getRequestEvent` is for managed server/request scope. +- When available, the returned event includes the current `Request` as `event.request`. +- Depending on the server integration, the event can also expose request-scoped fields such as `response`, `locals`, or router state. +- If no current request event is available, including outside managed async scope, `getRequestEvent` returns `undefined`. -## Response +## Examples -The `getRequestEvent` can also be used to stub out the Response - this extends the [options that can be passed to the `Response constructor`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#options). -This is kept up to date so it can be used to read and write headers and status for the current response. +### Basic usage -```js -import { getRequestEvent } from "solid-js/web" +```ts +import { getRequestEvent } from "solid-js/web"; -const event = getRequestEvent(); -if (event) { - event.response.headers.append("Set-Cookie", "foo=hello"); - event.response.status = 201; +function readAuthorizationHeader() { + const event = getRequestEvent(); + + return event?.request.headers.get("Authorization") ?? null; } ``` -### Change event.response or create a new Response - -The `getRequestEvent` event is considered global and lasts the life of the request. -Therefore, if you are calling a server function on the server during SSR or an RPC call, setting values on `event.response` will reflect on that request. - -The returned response will only impact the response when it is an RPC call. -This is important because some headers previously set may not be needed to be set for the whole page, but only for a specific request. - -**Note:** This is important to keep in mind when choosing where to set headers and responses. - -:::note[Usage with SolidStart] - See this guide on [Request - Events](/solid-start/advanced/request-events). -::: +This example reads the event during request-scoped server execution. diff --git a/src/routes/reference/store-utilities/create-mutable.mdx b/src/routes/reference/store-utilities/create-mutable.mdx index 97b92394e..d04ae0900 100644 --- a/src/routes/reference/store-utilities/create-mutable.mdx +++ b/src/routes/reference/store-utilities/create-mutable.mdx @@ -1,53 +1,100 @@ --- title: createMutable +use_cases: >- + mutable proxy state, interop with mutable systems, object mutation through a + store proxy +tags: + - store + - mutable + - proxy + - state +version: "1.0" +description: >- + Create a mutable store proxy. --- -`createMutable` creates a new mutable Store proxy object that provides a way to selectively trigger updates only when values change. +`createMutable` creates a mutable store proxy. -By intercepting property access, it allows automatic tracking of deep nesting via proxy making it useful for integrating external systems or serving as a compatibility layer with frameworks like MobX or Vue. +## Import -```tsx -import { createMutable } from "solid-js/store" -import type { Store, StoreNode } from "solid-js/store" +```ts +import { createMutable } from "solid-js/store"; +``` + +## Type -function createMutable<T extends StoreNode>(state: T | Store<T>): Store<T>; +```ts +function createMutable<T extends StoreNode>( + state: T, + options?: { name?: string } +): T; ``` -:::note - It's important to recognize that a mutable state, which can be passed around and modified anywhere, may complicate the code structure and increase the risk of breaking unidirectional flow. +## Parameters + +### `state` + +- **Type:** `T` + +Initial mutable state. + +### `options` + +#### `name` + +- **Type:** `string` + +Debug name used by development tooling. + +## Return value - For a more robust alternative, it is generally recommended to use `createStore` instead. - Additionally, the [`produce`](/reference/store-utilities/produce) utility can provide many of these same benefits without the associated downsides. -::: +- **Type:** `T` + +Mutable store proxy. + +## Behavior + +- `createMutable` creates mutable shared state through a reactive proxy. Property reads and writes go through that proxy, and nested property access is reactive. +- Writes, deletes, and array mutator methods are batched through the proxy while updating the store in place. +- `createMutable` exposes reads and writes through the same proxy instead of separating them into a getter and setter. +- Getters and setters defined on the initial object remain available on the mutable store. + +## Examples + +### Basic usage ```tsx -import { createMutable } from "solid-js/store" +import { createMutable } from "solid-js/store"; const state = createMutable({ someValue: 0, list: [], }); -// read value -state.someValue; - -// set value state.someValue = 5; - -state.list.push(anotherValue); +state.list.push("item"); ``` -Mutables support setters along with getters. +### Getter and setter ```tsx +import { createMutable } from "solid-js/store"; + const user = createMutable({ firstName: "John", lastName: "Smith", get fullName() { return `${this.firstName} ${this.lastName}`; }, - set setFullName(value) { + set fullName(value) { [this.firstName, this.lastName] = value.split(" "); }, }); + +user.fullName = "Jane Doe"; ``` + +## Related + +- [`modifyMutable`](/reference/store-utilities/modify-mutable) +- [`createStore`](/reference/store-utilities/create-store) diff --git a/src/routes/reference/store-utilities/create-store.mdx b/src/routes/reference/store-utilities/create-store.mdx index c084231aa..180b7ddd0 100644 --- a/src/routes/reference/store-utilities/create-store.mdx +++ b/src/routes/reference/store-utilities/create-store.mdx @@ -1,88 +1,104 @@ --- title: createStore +use_cases: >- + object state, array state, nested state, structured application state +tags: + - store + - state + - objects + - arrays +version: "1.0" +description: >- + Create a reactive store and a setter function for structured state. --- -Stores were intentionally designed to manage data structures like objects and arrays but are capable of handling other data types, such as strings and numbers. +`createStore` creates a reactive store and setter function for structured state. -## Types Signature +## Import -```tsx -import { createStore } from "solid-js/store" -import type { StoreNode, Store, SetStoreFunction } from "solid-js/store" +```ts +import { createStore } from "solid-js/store"; +``` -function createStore<T extends StoreNode>( - state: T | Store<T> -): [get: Store<T>, set: SetStoreFunction<T>]; +## Type -type Store<T> = T; // conceptually readonly, but not typed as such +```ts +type Store<T> = T; + +interface SetStoreFunction<T> { + (setter: T | Partial<T> | ((prev: T) => T | Partial<T>)): void; + (...path: unknown[]): void; +} + +function createStore<T extends object = {}>( + store?: T | Store<T>, + options?: { name?: string } +): [Store<T>, SetStoreFunction<T>]; ``` -## Usage +## Parameters -```tsx -import { createStore } from "solid-js/store"; +### `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: 1, - username: "johny123", - location: "India", - loggedIn: true, - }, - ], -}); -``` +- **Type:** `T | Store<T>` + +Initial store value. + +### `options` + +#### `name` + +- **Type:** `string` + +Debug name used by development tooling. + +## Return value + +- **Type:** `[Store<T>, SetStoreFunction<T>]` + +Tuple containing the store proxy and its setter. + +## Behavior -## Getter +- The returned store is read through a proxy, and property reads track at the property level. +- The setter supports both top-level updates and path syntax for nested updates. +- Object updates shallow-merge by default, while single-array updates replace array contents. Setting a property to `undefined` deletes it. +- Getters defined on the initial object remain available on the store. -Store objects support the use of getters to store derived values. +## Examples + +### Basic usage ```tsx +import { createStore } from "solid-js/store"; + const [state, setState] = createStore({ user: { firstName: "John", lastName: "Smith", - get fullName() { - return `${this.firstName} ${this.lastName}`; - }, }, }); -``` -## Setter +setState("user", "firstName", "Jane"); +``` -Changes can take the form of function that passes previous state and returns new state or a value. -Objects are always shallowly merged. Set values to undefined to delete them from the Store. -In TypeScript, you can delete a value by using a non-null assertion, like `undefined!`. +### Getter ```tsx -const [state, setState] = createStore({ - firstName: "John", - lastName: "Miller", -}); - -setState({ firstName: "Johnny", middleName: "Lee" }); -// ({ firstName: 'Johnny', middleName: 'Lee', lastName: 'Miller' }) +import { createStore } from "solid-js/store"; -setState((state) => ({ preferredName: state.firstName, lastName: "Milner" })); -// ({ firstName: 'Johnny', preferredName: 'Johnny', middleName: 'Lee', lastName: 'Milner' }) +const [state] = createStore({ + user: { + firstName: "John", + lastName: "Smith", + get fullName() { + return `${this.firstName} ${this.lastName}`; + }, + }, +}); ``` ---- +## Related -To learn more about using stores check the [Stores Guide](/concepts/stores), and the **Store utilities** section for more advanced APIs. +- [`createMutable`](/reference/store-utilities/create-mutable) +- [Stores](/concepts/stores) diff --git a/src/routes/reference/store-utilities/modify-mutable.mdx b/src/routes/reference/store-utilities/modify-mutable.mdx index ac5621304..7673917de 100644 --- a/src/routes/reference/store-utilities/modify-mutable.mdx +++ b/src/routes/reference/store-utilities/modify-mutable.mdx @@ -1,79 +1,68 @@ --- title: modifyMutable +use_cases: >- + batched mutable-store updates, applying store modifiers to mutable stores +tags: + - store + - mutable + - batch + - updates +version: "1.0" +description: >- + Apply a modifier to a mutable store inside a batch. --- -`modifyMutable` streamlines the process of making multiple changes to a mutable Store, as obtained through the use of [`createMutable`](/reference/store-utilities/create-mutable). +`modifyMutable` applies a modifier to a mutable store inside a batch. -It operates within a single [`batch`](/reference/reactive-utilities/batch), ensuring that dependent computations are updated just once, rather than triggering updates for each individual change. +## Import -```tsx -import { modifyMutable } from "solid-js/store" - -function modifyMutable<T>(mutable: T, modifier: (state: T) => T): void +```ts +import { modifyMutable } from "solid-js/store"; ``` -The function takes two arguments: +## Type -1. The first argument is the mutable Store that needs modification. -2. The second argument is a Store modifier, which could be one of those returned by [`reconcile`](/reference/store-utilities/reconcile). +```ts +function modifyMutable<T>(state: T, modifier: (state: T) => T): void; +``` -:::caution - When passing in your own modifier function, it's important to be aware that - its argument is an unwrapped version of the store. -::: +## Parameters -For example, if the UI depends on multiple fields of a mutable: +### `state` -```tsx -import { createMutable } from "solid-js/store" +- **Type:** `T` -const state = createMutable({ - user: { - firstName: "John", - lastName: "Smith", - }, -}); +Mutable store to modify. -<h1>Hello {state.user.firstName + " " + state.user.lastName}</h1>; -``` +### `modifier` -Modifying n fields in sequence will cause the UI to update n times: +- **Type:** `(state: T) => T` -```tsx -state.user.firstName = "Jane"; -state.user.lastName = "Doe"; -``` +Modifier applied to the mutable store. For direct mutation-style modifiers, the return value is ignored. -To trigger just a single update, the fields can be modified using a `batch`: +## Return value -```tsx -import { batch } from "solid-js" +- **Type:** `void` -batch(() => { - state.user.firstName = "Jane"; - state.user.lastName = "Doe"; -}); -``` +## Behavior -`modifyMutable` combined with [`reconcile`](/reference/store-utilities/reconcile) or [`produce`](/reference/store-utilities/produce) provides two alternate ways to do similar things: +- `modifyMutable` runs inside a [`batch`](/reference/reactive-utilities/batch), so multiple changes notify dependents after the modifier completes, and the modifier receives the unwrapped underlying state object instead of the proxy. +- The modifier can be a function returned by helpers such as [`reconcile`](/reference/store-utilities/reconcile) or [`produce`](/reference/store-utilities/produce). -```tsx -import { modifyMutable, reconcile } from "solid-js/store" +## Examples -// Replace state.user with the specified object (deleting any other fields) -modifyMutable( - state.user, - reconcile({ - firstName: "Jane", - lastName: "Doe", - }) -); -``` +### Basic usage ```tsx -import { modifyMutable, produce } from "solid-js/store" +import { createMutable, modifyMutable, produce } from "solid-js/store"; + +const state = createMutable({ + user: { + firstName: "John", + lastName: "Smith", + }, +}); -// Modify two fields in a batch, triggering just one update modifyMutable( state, produce((state) => { @@ -82,3 +71,9 @@ modifyMutable( }) ); ``` + +## Related + +- [`createMutable`](/reference/store-utilities/create-mutable) +- [`produce`](/reference/store-utilities/produce) +- [`reconcile`](/reference/store-utilities/reconcile) diff --git a/src/routes/reference/store-utilities/produce.mdx b/src/routes/reference/store-utilities/produce.mdx index 612769d9a..efd55d775 100644 --- a/src/routes/reference/store-utilities/produce.mdx +++ b/src/routes/reference/store-utilities/produce.mdx @@ -1,37 +1,73 @@ --- title: produce +use_cases: >- + store updates, nested store changes, draft-style mutations +tags: + - store + - updates + - mutations +version: "1.0" +description: >- + Create a store modifier that applies changes by mutating the current state through a helper proxy. --- -`produce` is an [Immer](https://immerjs.github.io/immer/) inspired API for Solid's Store objects that allows the store to be mutated inside the `produce` function. +`produce` creates a store modifier that applies changes by mutating the current state through a helper proxy. + +## Import + +```ts +import { produce } from "solid-js/store"; +``` + +## Type ```ts -import { produce } from "solid-js/store" -import type { NotWrappable, Store } from "solid-js/store" - -function produce<T>( - fn: (state: T) => void -): ( - state: T extends NotWrappable ? T : Store<T> -) => T extends NotWrappable ? T : Store<T>; +function produce<T>(fn: (state: T) => void): (state: T) => T; ``` -For use with `createStore`: +## Parameters + +### `fn` + +- **Type:** `(state: T) => void` + +Function that mutates the provided proxy state. + +## Return value + +- **Type:** `(state: T) => T` + +Store modifier function. + +## Behavior + +- `produce` returns a function that can be passed to store setters or [`modifyMutable`](/reference/store-utilities/modify-mutable). +- The returned modifier mutates the passed state and returns that same state. +- The helper is primarily for store objects and nested wrappable data. + +## Examples + +### Basic usage ```tsx -import { produce } from "solid-js/store"; +import { createStore, produce } from "solid-js/store"; const [state, setState] = createStore({ user: { name: "John", - age: 30, }, - list: ["book", "pen"], + list: ["book"], }); setState( produce((state) => { state.user.name = "Jane"; - state.list.push("pencil"); + state.list.push("pen"); }) ); ``` + +## Related + +- [`modifyMutable`](/reference/store-utilities/modify-mutable) +- [`reconcile`](/reference/store-utilities/reconcile) diff --git a/src/routes/reference/store-utilities/reconcile.mdx b/src/routes/reference/store-utilities/reconcile.mdx index cfd0e7d94..000e7ffc4 100644 --- a/src/routes/reference/store-utilities/reconcile.mdx +++ b/src/routes/reference/store-utilities/reconcile.mdx @@ -1,45 +1,83 @@ --- title: reconcile +use_cases: >- + syncing store state, applying immutable data updates, diffing incoming data +tags: + - store + - diffing + - synchronization +version: "1.0" +description: >- + Create a store modifier that reconciles existing state with a new value. --- -`reconcile` is designed for diffing data changes in situations where granular updates cannot be applied. -This is useful when dealing with immutable data from stores or handling large API responses. +`reconcile` creates a store modifier that reconciles existing state with a new value. -```tsx -import { reconcile } from "solid-js/store" -import type { NotWrappable, Store } from "solid-js/store" +## Import -function reconcile<T>( - value: T | Store<T>, +```ts +import { reconcile } from "solid-js/store"; +``` + +## Type + +```ts +function reconcile<T extends U, U>( + value: T, options?: { key?: string | null; merge?: boolean; - } = { key: "id" } -): ( - state: T extends NotWrappable ? T : Store<T> -) => T extends NotWrappable ? T : Store<T> + } +): (state: U) => T; ``` -`reconcile` has a `key` option that can be used when available to match items. -The `value` accepts either a value of type `T` or a Store containing values of type `T`. -This represents the data to be reconciled. +## Parameters + +### `value` + +- **Type:** `T` + +New value to reconcile against the current state. + +### `options` + +#### `key` + +- **Type:** `string | null` -The `reconcile` function helps manage data changes by performing a diffing process, making it particularly handy in scenarios where applying granular updates is challenging or inefficient. +Key used to match items during reconciliation. -The `key` and `merge` options provide flexibility to customize the reconciliation process based on specific needs. +#### `merge` + +- **Type:** `boolean` + +Controls whether reconciliation pushes updates to the leaves instead of replacing non-matching branches. + +## Return value + +- **Type:** `(state: U) => T` + +Store modifier function. + +## Behavior + +- `reconcile` is for reconciling an incoming snapshot against existing store state. +- With the default `key`, array items are matched by `"id"` where possible and otherwise fall back to positional or reference matching. +- Non-wrappable values are replaced directly. +- When `merge` is `false`, reconciliation prefers replacing non-matching branches. When `merge` is `true`, it pushes updates deeper into the structure. + +## Examples + +### Basic usage ```ts -// subscribing to an observable -const unsubscribe = store.subscribe(({ todos }) => ( - setState('todos', reconcile(todos)); -); -onCleanup(() => unsubscribe()); +import { createStore, reconcile } from "solid-js/store"; + +const [state, setState] = createStore({ todos: [] }); +setState("todos", reconcile([{ id: 1, title: "Write docs" }])); ``` -##### Options +## Related -| Option | Type | Default | Description | -| ------ | ------- | ------- | ---------------------------------- | -| key | string | "id" | Specifies the key to be used for matching items during reconciliation | -| merge | boolean | false | When merge is false, referential checks are performed where possible to determine equality, and items that are not referentially equal are replaced. When merge is true, all diffing is pushed to the leaves, effectively morphing the previous data to the new value. | +- [`produce`](/reference/store-utilities/produce) diff --git a/src/routes/reference/store-utilities/unwrap.mdx b/src/routes/reference/store-utilities/unwrap.mdx index 64742a17e..551e26acf 100644 --- a/src/routes/reference/store-utilities/unwrap.mdx +++ b/src/routes/reference/store-utilities/unwrap.mdx @@ -1,12 +1,66 @@ --- title: unwrap +use_cases: >- + reading store data without proxies, passing plain data to other APIs +tags: + - store + - proxy + - data +version: "1.0" +description: >- + Remove store proxy wrapping from a store or store subtree. --- -`unwrap` returns the underlying data in the store without a proxy. +`unwrap` removes store proxy wrapping from a store or store subtree. -```tsx -import { unwrap } from "solid-js/store" -import type { Store } from "solid-js/store" +## Import -function unwrap(store: Store<T>): T +```ts +import { unwrap } from "solid-js/store"; ``` + +## Type + +```ts +function unwrap<T>(item: T): T; +``` + +## Parameters + +### `item` + +- **Type:** `T` + +Store value or store subtree to unwrap. + +## Return value + +- **Type:** `T` + +Unwrapped value. + +## Behavior + +- `unwrap` removes store proxies recursively and returns underlying plain data, reusing existing objects or arrays instead of cloning them when possible. +- Frozen objects and arrays are shallow-copied before recursive unwrapping, while mutable ones are unwrapped in place. +- Non-proxy input values are returned unchanged. +- Mutating the returned value can mutate the underlying store data. + +Do not assume `unwrap` produces an isolated deep clone. + +## Examples + +### Basic usage + +```ts +import { createStore, unwrap } from "solid-js/store"; + +const [state] = createStore({ user: { name: "John" } }); +const user = unwrap(state.user); + +user.name = "Jane"; +``` + +## Related + +- [`createStore`](/reference/store-utilities/create-store) diff --git a/src/routes/solid-meta/getting-started/client-setup.mdx b/src/routes/solid-meta/getting-started/client-setup.mdx index 32bc50c83..79065614e 100644 --- a/src/routes/solid-meta/getting-started/client-setup.mdx +++ b/src/routes/solid-meta/getting-started/client-setup.mdx @@ -1,6 +1,19 @@ --- title: Client setup order: 2 +use_cases: >- + seo, meta tags, document head management, social media tags, page titles, + canonical urls +tags: + - meta + - seo + - head + - client + - tags +version: "1.0" +description: >- + Manage document head tags in Solid apps. Add titles, meta tags, and links + dynamically for better SEO and social media sharing. --- You can inject a tag into the `<head />` by rendering one of the head tag components when necessary. diff --git a/src/routes/solid-meta/getting-started/installation-and-setup.mdx b/src/routes/solid-meta/getting-started/installation-and-setup.mdx index 223501dc2..72ebe2a63 100644 --- a/src/routes/solid-meta/getting-started/installation-and-setup.mdx +++ b/src/routes/solid-meta/getting-started/installation-and-setup.mdx @@ -1,6 +1,19 @@ --- title: Install and configure order: 1 +use_cases: >- + initial setup, meta tags configuration, seo setup, head management setup, ssr + meta tags +tags: + - setup + - installation + - meta + - configuration + - seo +version: "1.0" +description: >- + Install and configure @solidjs/meta for head tag management. Set up dynamic + titles, meta tags, and SEO optimization in Solid apps. --- :::note[Prerequisites] @@ -20,15 +33,23 @@ To get started, install using your preferred package manager. 1. Wrap your application with [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider) 2. To include head tags within your application, render any of the following: - 1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page. - 2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page. - 3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page. - 4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource. - 5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document. + 1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page. + 2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page. + 3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page. + 4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource. + 5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document. + 6. [`useHead`](/solid-meta/reference/meta/use-head): Inserts arbitrary head tags when a dedicated component does not exist. + - These components can be used multiple times within the application. + 3. If using Solid on the server with JSX, no additional configuration is required. +:::note[Overriding existing tags] +If your `index.html` includes a `<head>` tag, Solid-Meta will not overwrite its contents. You can mark individual tags as overwritable by adding an empty `data-sm` attribute to them. +::: + Here is an example of how your code might look after this setup. + ```js import { MetaProvider, Title, Link, Meta } from "@solidjs/meta"; @@ -42,6 +63,7 @@ const App = () => ( </MetaProvider> ); ``` + On the server, tags are collected, and then on the client, server-generated tags are replaced with those rendered on the client side. This process is important for maintaining the expected behavior, such as Single Page Applications (SPAs) when pages load that require changes to the head tags. diff --git a/src/routes/solid-meta/getting-started/server-setup.mdx b/src/routes/solid-meta/getting-started/server-setup.mdx index 19a0bc691..bd2dd7e09 100644 --- a/src/routes/solid-meta/getting-started/server-setup.mdx +++ b/src/routes/solid-meta/getting-started/server-setup.mdx @@ -1,6 +1,20 @@ --- title: Server setup order: 3 +use_cases: >- + ssr setup, server rendering, meta tags on server, seo optimization, initial + page load +tags: + - ssr + - server + - meta + - seo + - setup + - rendering +version: "1.0" +description: >- + Configure server-side rendering for Solid Meta tags with MetaProvider. Learn + to properly inject head tags in SSR for optimal SEO and performance. --- For server setup, wrap your application with [`MetaProvider`](/solid-meta/reference/meta/metaprovider) on the server. diff --git a/src/routes/solid-meta/index.mdx b/src/routes/solid-meta/index.mdx index 3cee39418..02077625c 100644 --- a/src/routes/solid-meta/index.mdx +++ b/src/routes/solid-meta/index.mdx @@ -1,6 +1,21 @@ --- -title: Overview +title: Solid Meta Docs +nav_title: Overview +titleTemplate: ":title" mainNavExclude: true +use_cases: >- + managing head tags, seo optimization, document metadata, dynamic meta tags, + ssr meta management +tags: + - meta + - head + - seo + - ssr + - overview +version: "1.0" +description: >- + Solid Meta provides asynchronous SSR-ready document head management. Define + meta tags at any component level for flexible SEO and metadata control. --- # Overview diff --git a/src/routes/solid-meta/reference/meta/base.mdx b/src/routes/solid-meta/reference/meta/base.mdx index f0be6b9f9..91a1607df 100644 --- a/src/routes/solid-meta/reference/meta/base.mdx +++ b/src/routes/solid-meta/reference/meta/base.mdx @@ -1,6 +1,19 @@ --- title: Base order: 5 +use_cases: >- + setting base url, relative urls, external resources, multi-page apps, cdn + assets +tags: + - base + - url + - meta + - head + - routing +version: "1.0" +description: >- + Set the base URL for all relative URLs in your Solid app with the Base + component. Essential for apps with complex routing or external resources. --- `Base` is a component that specifies the base URL for all relative URLs in the document. @@ -26,4 +39,4 @@ export default function Root() { </MetaProvider> ); } -``` \ No newline at end of file +``` diff --git a/src/routes/solid-meta/reference/meta/data.json b/src/routes/solid-meta/reference/meta/data.json index 640bff60c..56a76d69d 100644 --- a/src/routes/solid-meta/reference/meta/data.json +++ b/src/routes/solid-meta/reference/meta/data.json @@ -6,6 +6,7 @@ "meta.mdx", "style.mdx", "base.mdx", - "metaprovider.mdx" + "metaprovider.mdx", + "use-head.mdx" ] } diff --git a/src/routes/solid-meta/reference/meta/link.mdx b/src/routes/solid-meta/reference/meta/link.mdx index e925f1dc9..3220ebf12 100644 --- a/src/routes/solid-meta/reference/meta/link.mdx +++ b/src/routes/solid-meta/reference/meta/link.mdx @@ -1,6 +1,18 @@ --- title: Link order: 2 +use_cases: "adding favicon, stylesheets, external resources, preloading assets, web fonts" +tags: + - link + - favicon + - stylesheet + - assets + - head + - resources +version: "1.0" +description: >- + Add external resources like stylesheets and favicons to your Solid app. Learn + to use the Link component for optimal resource loading and icons. --- The Link component establishes a connection between the page and an external resource. diff --git a/src/routes/solid-meta/reference/meta/meta.mdx b/src/routes/solid-meta/reference/meta/meta.mdx index 13e077da5..27ed5cfc1 100644 --- a/src/routes/solid-meta/reference/meta/meta.mdx +++ b/src/routes/solid-meta/reference/meta/meta.mdx @@ -1,6 +1,20 @@ --- title: Meta order: 3 +use_cases: >- + seo optimization, social media tags, viewport settings, charset configuration, + open graph +tags: + - meta + - seo + - viewport + - metadata + - head + - tags +version: "1.0" +description: >- + Add SEO and viewport metadata to your Solid app with the Meta component. + Configure description, keywords, and social media tags for better reach. --- The `<Meta>` component represents metadata that cannot be represented by other HTML elements. @@ -12,9 +26,9 @@ import { Meta } from "@solidjs/meta"; <Meta name="description" content="My site description" />; ``` - `Meta` components can be placed in the [`MetaProvider`](/solid-meta/reference/meta/metaprovider) or added throughout the application for additional metadata or override parents. `Meta` tags are considered the same and will be overridden if `name` attributes match. + ## Usage ### Adding `meta` tag @@ -31,4 +45,4 @@ export default function Root() { </MetaProvider> ); } -``` \ No newline at end of file +``` diff --git a/src/routes/solid-meta/reference/meta/metaprovider.mdx b/src/routes/solid-meta/reference/meta/metaprovider.mdx index d9932fa27..e1debf701 100644 --- a/src/routes/solid-meta/reference/meta/metaprovider.mdx +++ b/src/routes/solid-meta/reference/meta/metaprovider.mdx @@ -1,6 +1,20 @@ --- title: MetaProvider order: 6 +use_cases: >- + initializing meta tags, wrapping app, head management setup, meta context, + always in meta apps +tags: + - provider + - meta + - setup + - context + - wrapper + - head +version: "1.0" +description: >- + MetaProvider wraps your Solid app to enable head tag management. Essential + parent component for all metadata components to function properly. --- `MetaProvider` is a parent component responsible for wrapping all the metadata components. @@ -10,4 +24,4 @@ All components that are contained within this will be added to the application ` import { MetaProvider } from "@solidjs/meta"; <MetaProvider>// add meta components</MetaProvider>; -``` \ No newline at end of file +``` diff --git a/src/routes/solid-meta/reference/meta/style.mdx b/src/routes/solid-meta/reference/meta/style.mdx index 4d049ab3e..eb66313a8 100644 --- a/src/routes/solid-meta/reference/meta/style.mdx +++ b/src/routes/solid-meta/reference/meta/style.mdx @@ -1,6 +1,17 @@ --- title: Style order: 4 +use_cases: "inline styles, critical css, theme styles, dynamic styling, css-in-js" +tags: + - style + - css + - inline + - styling + - head +version: "1.0" +description: >- + Add inline CSS styles to your Solid app's head with the Style component. + Useful for critical CSS and dynamic styling needs in your application. --- `Style` is a component that adds the [`style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) element to your document's `head`. @@ -25,7 +36,7 @@ The `Style` component can add CSS to style elements within your application. It is recommended to add styles in an external stylesheet and use a `Link` instead, rather than using this component, however. :::tip[Note] - Styles within the `Style` component are not scoped. +Styles within the `Style` component are not scoped. ::: ```tsx twoslash diff --git a/src/routes/solid-meta/reference/meta/title.mdx b/src/routes/solid-meta/reference/meta/title.mdx index 01df78926..a22ca6e55 100644 --- a/src/routes/solid-meta/reference/meta/title.mdx +++ b/src/routes/solid-meta/reference/meta/title.mdx @@ -1,6 +1,19 @@ --- title: Title order: 1 +use_cases: >- + page titles, seo optimization, browser tab text, dynamic titles, navigation + context +tags: + - title + - seo + - head + - meta + - browser +version: "1.0" +description: >- + Set dynamic page titles in your Solid app with the Title component. Essential + for SEO and providing context in browser tabs and bookmarks. --- `Title` is a component that renders the [`title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) element. @@ -24,4 +37,4 @@ export default function Root() { </MetaProvider> ); } -``` \ No newline at end of file +``` diff --git a/src/routes/solid-meta/reference/meta/use-head.mdx b/src/routes/solid-meta/reference/meta/use-head.mdx new file mode 100644 index 000000000..c297d9a7e --- /dev/null +++ b/src/routes/solid-meta/reference/meta/use-head.mdx @@ -0,0 +1,183 @@ +--- +title: useHead +order: 7 +use_cases: >- + custom head tags, scripts, json-ld, arbitrary head elements, dynamic metadata, + ssr head management +tags: + - usehead + - head + - meta + - script + - json-ld + - ssr +version: "1.0" +description: >- + useHead inserts custom elements into document head with fine-grained control, + including scripts and JSON-LD, while staying SSR-ready. +--- + +`useHead` is a low-level API for registering custom `<head>` tags with the nearest [`MetaProvider`](/solid-meta/reference/meta/metaprovider). + +## Import + +```ts +import { useHead } from "@solidjs/meta"; +``` + +## Type + +```ts +type TagDescription = { + tag: string; + props: Record<string, unknown>; + setting?: { + close?: boolean; + escape?: boolean; + }; + id: string; + name?: string; + ref?: Element; +}; + +function useHead(tag: TagDescription): void; +``` + +## Parameters + +### `tag` + +- **Type:** `string` +- **Required:** Yes + +The tag name to render in `<head>` (eg. `<script>`, `<meta>`, `<title>`). + +### `props` + +- **Type:** `Record<string, unknown>` +- **Required:** Yes + +Attributes and properties applied to the rendered element. + +If `props.children` is provided, is provided, it is used as the element’s content for tags such as `title`, `style`, and `script`. +During server-side rendering, arrays of strings are concatenated without commas. + +### `setting` + +- **Type:** `{ close?: boolean; escape?: boolean }` +- **Required:** No + +SSR-only rendering options for the tag contents. + +#### `close` + +- **Type:** `boolean` +- **Required:** No + +Required for elements that cannot be self-closing, such as `script`, `style`, and `title`. When `true`, the server renders a closing tag and includes `children`. If `false`, `children` is not rendered. + +#### `escape` + +- **Type:** `boolean` +- **Required:** No + +When `true`, HTML-escapes `children` during SSR. +If omitted or `false`, renders `children` as raw HTML. + +### `id` + +- **Type:** `string` +- **Required:** Yes + +A stable identifier used to match server-rendered tags during hydration. +Value should remain consistent for the lifetime of the component. + +### `name` + +- **Type:** `string` +- **Required:** No + +An optional label for the tag. +With `meta` tags, can mirror `props.name` or `props.property`. + +### `ref` + +- **Type:** `Element` +- **Required:** No + +An existing element to reuse instead of creating a new one, typically managed internally. + +## Return value + +`useHead` does not return a value. + +## Examples + +### Simple custom tag + +```tsx +import { useHead } from "@solidjs/meta"; + +useHead({ + tag: "link", + id: "rss-feed", + props: { + rel: "alternate", + type: "application/rss+xml", + title: "Solid RSS", + href: "/rss.xml", + }, +}); +``` + +### JSON-LD per page (script with `close` and `escape`) + +```tsx +import { useHead } from "@solidjs/meta"; + +const jsonLD = JSON.stringify({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "Solid Docs", + url: "https://docs.solidjs.com/", +}); + +useHead({ + tag: "script", + setting: { close: true, escape: false }, + id: "schema-home", + props: { + type: "application/ld+json", + children: jsonLD, + }, +}); +``` + +### Reactive updates + +```tsx +import { createSignal } from "solid-js"; +import { useHead } from "@solidjs/meta"; + +const [pageTitle, setPageTitle] = createSignal("Getting started"); + +useHead({ + tag: "title", + setting: { close: true, escape: true }, + id: "page-title", + props: { + get children() { + return `${pageTitle()} | Solid`; + }, + }, +}); +``` + +## Related + +- [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider) +- [`<Title />`](/solid-meta/reference/meta/title) +- [`<Meta />`](/solid-meta/reference/meta/meta) +- [`<Link />`](/solid-meta/reference/meta/link) +- [`<Style />`](/solid-meta/reference/meta/style) +- [`<Base />`](/solid-meta/reference/meta/base) diff --git a/src/routes/solid-router/advanced-concepts/data.json b/src/routes/solid-router/advanced-concepts/data.json index 0f6e6c5f8..a41c62b1a 100644 --- a/src/routes/solid-router/advanced-concepts/data.json +++ b/src/routes/solid-router/advanced-concepts/data.json @@ -1,4 +1,4 @@ -{ - "title": "Advanced concepts", - "pages": ["lazy-loading.mdx"] -} +{ + "title": "Advanced concepts", + "pages": ["preloading.mdx", "lazy-loading.mdx"] +} diff --git a/src/routes/solid-router/advanced-concepts/lazy-loading.mdx b/src/routes/solid-router/advanced-concepts/lazy-loading.mdx index 2ef9d89a4..bc2055bf2 100644 --- a/src/routes/solid-router/advanced-concepts/lazy-loading.mdx +++ b/src/routes/solid-router/advanced-concepts/lazy-loading.mdx @@ -1,28 +1,42 @@ ---- -title: Lazy loading ---- - -Lazy loading allows you to load only the necessary resources when they are needed. -This can be useful when you have a large application with a lot of routes and components, and you want to reduce the initial load time. - -In Solid Router, you can lazy load components using the `lazy` function from Solid: - -```jsx -import { lazy } from "solid-js"; -import { Router, Route } from "@solidjs/router"; - -const Home = lazy(() => import("./Home")); - -const Users = lazy(() => import("./Users")); - -const App = () => ( - <Router> - <Route path="/" component={Home} /> - <Route path="/users" component={Users} /> - </Router> -); -``` - -In the example above, the `Users` component is lazy loaded using the `lazy` function. -The `lazy` function takes a function that returns a promise, which resolves to the component you want to load. -When the route is matched, the component will be loaded and rendered. +--- +title: Lazy loading +use_cases: >- + optimizing bundle size, code splitting, reducing initial load, large apps, + performance optimization +tags: + - lazy + - performance + - routing + - optimization + - splitting + - loading +version: "1.0" +description: >- + Implement lazy loading in Solid Router to reduce initial bundle size. Load + components on-demand for better performance in large applications. +--- + +Lazy loading allows you to load only the necessary resources when they are needed. +This can be useful when you have a large application with a lot of routes and components, and you want to reduce the initial load time. + +In Solid Router, you can lazy load components using the `lazy` function from Solid: + +```jsx +import { lazy } from "solid-js"; +import { Router, Route } from "@solidjs/router"; + +const Home = lazy(() => import("./Home")); + +const Users = lazy(() => import("./Users")); + +const App = () => ( + <Router> + <Route path="/" component={Home} /> + <Route path="/users" component={Users} /> + </Router> +); +``` + +In the example above, the `Users` component is lazy loaded using the `lazy` function. +The `lazy` function takes a function that returns a promise, which resolves to the component you want to load. +When the route is matched, the component will be loaded and rendered. diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx new file mode 100644 index 000000000..73b949287 --- /dev/null +++ b/src/routes/solid-router/advanced-concepts/preloading.mdx @@ -0,0 +1,44 @@ +--- +title: Preloading +--- + +Preloading smooths navigation by resolving route code and data before a user completes a transition. +Solid Router listens for intent signals, such as hover and focus, and primes the matching route after a short delay to balance responsiveness and network cost. +Understanding the timing and scope of this work lets you decide when to rely on the default behaviour and when to layer custom strategies. + +| user action | route behaviour | +| ----------- | ------------------------------------- | +| hover | waits roughly 20 ms before preloading | +| focus | preloads immediately | + +## How Solid Router Detects Intent + +Anchors registered with Solid Router emit hover and focus events that feed a small scheduler. +The router debounces the hover signal for 20ms to ignore incidental pointer passes while still reacting quickly to purposeful movement. +When the delay elapses, the router loads the route module and runs its preload routine so that navigation has the assets it needs when the user commits. + +Route modules can export a [`preload`](/solid-router/reference/preload-functions/preload) function that receives params, search values, and router context. +The function lets you seed caches, warm derived computations, or coordinate streaming behaviours without blocking the eventual render. + +> [!NOTE] +> SSR invokes route `preload` functions during the initial server render and resumes them on the client during hydration. +> Keep these functions pure so the hydrated client does not need to undo server work when it takes over. + +## Imperative Preloading Hooks + +Not every interaction funnels through an anchor element. +The [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) primitive exposes the same scheduling behaviour for imperative flows like flyout previews, timers, or observer driven experiences. + +This helper mirrors the router behaviour by resolving the module, optionally running the loader, and caching the result for the eventual navigation. +Empirical tuning of delay values helps you avoid excessive prefetching in dense UIs while still keeping high intent interactions snappy. + +## Coordinating Nested Lazy Components + +Nested lazy components live outside the router hierarchy, so route preloading does not automatically warm them. +The component API [`lazy()`](/reference/component-apis/lazy) exposes a `preload()` method that resolves a component without rendering it. +Calling both the route preload and the nested component preload can keep large detail panels responsive when a user hovers or focuses on the entry point. + +Balancing manual preloading requires observing real user flows so you avoid prefetching large bundles that the user never requests. +Profiling tools help you spot whether preloading reduces long tasks or simply shifts work earlier without net gains. + +To learn more about lazy loading components, see the [lazy documentation](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components). diff --git a/src/routes/solid-router/concepts/actions.mdx b/src/routes/solid-router/concepts/actions.mdx index 53a96da9c..d7801c50c 100644 --- a/src/routes/solid-router/concepts/actions.mdx +++ b/src/routes/solid-router/concepts/actions.mdx @@ -1,152 +1,461 @@ --- -title: "Actions" +title: Actions +use_cases: >- + form submissions, data mutations, server communication, user input handling, + api calls, crud operations +tags: + - actions + - forms + - data + - api + - server + - submission + - mutations +version: "1.0" +description: >- + Handle form submissions and server mutations with Solid Router actions. Build + isomorphic data flows with progressive enhancement support. --- -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/data-fetching/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 [`<form>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/form) or programmatically using the [`useAction` primitive](/solid-router/reference/data-apis/use-action). -### Benefits of using actions +The recommended approach is to use a `<form>` element. +This ensures a robust user experience with progressive enhancement, since the form works even without JavaScript. -1. **Isomorphic**: Since actions can run on both the server and client, you can optimize performance by choosing the best execution environment for your needs. -2. **Asynchronous processing**: Actions handle data submissions asynchronously, ensuring that your application remains responsive. -3. **Simplified data handling**: By using actions, the process of managing and tracking data submissions can be streamlined, reducing the complexity of your application. +For cases where a form is not suitable, the [`useAction` primitive](/solid-router/reference/data-apis/use-action) can be used to trigger the action programmatically. -## Creating actions +### With the `<form>` element -To create an action, use the `action` function from the `@solidjs/router` package. -This function takes an asynchronous function as an argument and returns a new function that can be used to submit data. +Solid Router extends the standard HTML `<form>` element to work with actions. +Form submissions can be handled using action by passing an action to the `action` prop. + +Consider these points when using actions with `<form>`: + +1. The `<form>` element **must** have `method="post"`. +2. The action function will automatically receive the form's data as a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object as its first parameter. +3. For SSR environments, a unique name **must** be provided as the second parameter to the `action` function. + This name is used by Solid Router to identify and serialize the action across the client and server. ```tsx import { action } from "@solidjs/router"; -const echo = action(async (message: string) => { - // Simulates an asynchronous operation, such as an API call - await new Promise((resolve, reject) => setTimeout(resolve, 1000)); - console.log(message); -}); +const submitFeedbackAction = action(async (formData: FormData) => { + const message = formData.get("message")?.toString(); + // ... Sends the feedback to the server. +}, "submitFeedback"); + +function FeedbackForm() { + return ( + <form action={submitFeedbackAction} method="post"> + <textarea name="message" placeholder="Message" /> + <button type="submit">Send feedback</button> + </form> + ); +} ``` -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 `<form>` element must have `enctype="multipart/form-data"` to correctly send the file data. + +```tsx +<form action={uploadFileAction} method="post" enctype="multipart/form-data"> + <input type="file" name="myFile" /> + <button type="submit">Upload</button> +</form> +``` -:::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 ( + <form action={updateProductAction.with(props.productId)} method="post"> + <input name="name" placeholder="Product name" /> + <button type="submit">Save</button> + </form> + ); +} +``` + +In this example, `updateProductAction` receives `productId` (passed via `with`), and then the `formData` from the form. + +### With the `useAction` primitive + +For scenarios where a `<form>` element is not suitable, the `useAction` primitive provides a way to trigger an action programmatically. +The `useAction` primitive takes an action as its parameter and returns a function that, when called, triggers the action with the provided arguments. + +This approach requires client-side JavaScript and is not progressively enhanceable. + +```tsx import { action, useAction } from "@solidjs/router"; -const echo = action(async (message: string) => { - await new Promise((resolve, reject) => setTimeout(resolve, 1000)); - console.log(message); +const markNotificationReadAction = action(async (notificationId: string) => { + // ... Marks a notification as read on the server. }); -export function MyComponent() { - const myEcho = useAction(echo); +function NotificationItem(props: { id: string }) { + const markRead = useAction(markNotificationReadAction); - myEcho("Hello from Solid!"); + return <button onClick={() => markRead(props.id)}>Mark as read</button>; } ``` -In this component, `useAction` is used to get a reference to the `echo` action. -The action is then called with the message `"Hello from Solid!"`, which will be logged to the console after a 1 second delay. +In this example, `markRead` is a function that can be called with arguments matching `markNotificationReadAction`. +When the button is clicked, the action is triggered with the provided arguments. -### Returning data from actions +## Tracking submission state -In many cases, after submitting data, the server sends some data back as well. -This may be in the form of an error message if something has failed or the results of a successful operation. -Anything returned from an action can be accessed using the reactive `action.result` property, where the value can change each time you submit your action. +When an action is triggered, it creates a **submission** object. +This object is a snapshot of the action's execution, containing its input, current status (pending or complete), and its final result or error. +To access this state, Solid Router provides the [`useSubmission`](/solid-router/reference/data-apis/use-submission) and [`useSubmissions`](/solid-router/reference/data-apis/use-submissions) primitives. -To access the action's result, you must pass the action to `useSubmission`: +The `useSubmission` primitive tracks the state of the _most recent_ submission for a specific action. +This is ideal for most use cases, such as disabling a form's submit button while the action is pending or displaying a confirmation message upon success. -```tsx del={1} ins={2,11,15-17} -import { action, useAction } from "@solidjs/router"; -import { action, useAction, useSubmission } from "@solidjs/router"; +```tsx +import { Show } from "solid-js"; +import { action, useSubmission } from "@solidjs/router"; -const echo = action(async (message: string) => { - await new Promise((resolve, reject) => setTimeout(resolve, 1000)); - return message; -}); +const updateSettingsAction = action(async (formData: FormData) => { + // ... Sends the settings data to the server. +}, "updateSettings"); -export function MyComponent() { - const myEcho = useAction(echo); - const echoing = useSubmission(echo); +function UserSettingsForm() { + const submission = useSubmission(updateSettingsAction); - myEcho("Hello from solid!"); + return ( + <form action={updateSettingsAction} method="post"> + <input name="email" type="email" placeholder="Enter your email" /> - setTimeout(() => myEcho("This is a second submission!"), 1500); + <button disabled={submission.pending}> + {submission.pending ? "Saving..." : "Save settings"} + </button> + </form> + ); +} +``` - return <p>{echoing.result}</p>; +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 ( + <form action={verifyTwoFactorAction} method="post"> + <div> + <input name="code" placeholder="6-digit code" inputMode="numeric" /> + <Show when={errors()?.code}> + <p>{errors().code}</p> + </Show> + </div> + + <button type="submit" disabled={submission.pending}> + {submission.pending ? "Verifying..." : "Verify"} + </button> + </form> + ); +} +``` + +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/data-fetching/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 ( + <div> + <h2>Registered devices</h2> + <For each={devices()}>{(device) => <p>{device.name}</p>}</For> + + <h3>Register new device</h3> + <form action={registerDeviceAction} method="post"> + <input name="name" placeholder="Device name" /> + <button type="submit">Register device</button> + </form> + </div> + ); } ``` -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 ( - <form action={isAdmin} method="post"> - <label for="username">Username:</label> - <input type="text" name="username" /> - <input type="submit" value="submit" /> - </form> - ); -} + // 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 `<form>` element. +:::tip[Throwing vs. Returning] +A response helper can be either `return`ed or `throw`n. +In TypeScript, `throw` can be more convenient, as it avoids potential type conflicts with an action's expected return value. +::: + +## Optimistic UI + +Optimistic UI is a pattern where the user interface is updated immediately after a user performs an operation. +This is done without waiting for the server to confirm the operation's success. +This approach makes an application feel faster and more responsive. + +Actions can be combined with local state management to implement optimistic UI. +The `useSubmission` primitive can be used to access the input of an action as it's being submitted. +This input can be used to temporarily update the UI. -## Error handling +```tsx +import { For, Show } from "solid-js"; +import { query, action, createAsync, useSubmission } from "@solidjs/router"; + +const getCartQuery = query(async () => { + // ... Fetches the current shopping cart items. +}, "cart"); + +const addToCartAction = action(async (formData: FormData) => { + // ... Adds a product to the cart. +}, "addToCart"); + +function CartPage() { + const cart = createAsync(() => getCartQuery()); + const submission = useSubmission(addToCartAction); + + const optimisticCart = () => { + const originalItems = cart() ?? []; + if (submission.pending) { + const formData = submission.input[0] as FormData; + const productId = formData.get("productId")?.toString(); + const name = formData.get("name")?.toString(); + if (productId && name) { + // Add the optimistic line item with a temporary identifier. + return [...originalItems, { id: "temp", productId, name, quantity: 1 }]; + } + } + return originalItems; + }; + + return ( + <div> + <h2>Your cart</h2> + <For each={optimisticCart()}>{(item) => <p>{item.name}</p>}</For> + + <h3>Add item</h3> + <form action={addToCartAction} method="post"> + <input name="productId" placeholder="Product ID" /> + <input name="name" placeholder="Product name" /> + <button type="submit" disabled={submission.pending}> + {submission.pending ? "Adding..." : "Add to cart"} + </button> + </form> + </div> + ); +} +``` -Rather than throwing errors, it is recommended to return them from actions. -This helps with the typing of submissions that would be used with `useSubmission`. -This is important when handling progressive enhancement where no JavaScript is present in the client, so that errors can be used declaratively to render the updated page on the server. +In this example, a derived signal `optimisticCart` is created. +When an action is pending, it checks the `submission.input` and adds the new cart item to the list with a temporary ID. +If the action fails, `submission.pending` becomes false, and `optimisticCart` will revert to showing the original list from `cart`. +When the action succeeds, Solid Router automatically revalidates `getCartQuery` and updates the UI with the confirmed cart state. -Additionally, when using server actions, it is good practice to handle errors on the server to sanitize error messages. +:::note +For more advanced patterns, consider using [TanStack Query](https://tanstack.com/query/latest/docs/framework/solid/guides/optimistic-updates). +It provides robust tools for managing server state, including cache-based optimistic updates. +::: diff --git a/src/routes/solid-router/concepts/alternative-routers.mdx b/src/routes/solid-router/concepts/alternative-routers.mdx index 4f86f3751..53ded3fcb 100644 --- a/src/routes/solid-router/concepts/alternative-routers.mdx +++ b/src/routes/solid-router/concepts/alternative-routers.mdx @@ -1,9 +1,24 @@ --- title: Alternative routers +use_cases: >- + single-page apps without server routing, legacy hash-based urls, testing + router logic, client-only navigation +tags: + - hash-mode + - memory-mode + - client-side + - testing + - spa + - routing +version: "1.0" +description: >- + Learn to use hash-based and memory routers in SolidJS for client-side + navigation and testing without server interaction. --- While the default router uses the browser's `location.pathname` to determine the current route, you can use alternative routers to change this behavior. This includes: + - [**Hash mode**](#hash-mode): Uses the hash portion of the URL to determine the current route. - [**Memory mode**](#memory-mode): Keeps the history of the router in memory, useful for testing. @@ -15,10 +30,10 @@ To use hash mode, replace the `<Router />` component in the application with [`< ```jsx del={3, 16} ins={4,17} import { render } from "solid-js/web"; -import { +import { Router HashRouter, - Route + Route } from "@solidjs/router"; const App = (props) => ( @@ -46,10 +61,10 @@ To use memory mode, replace the `<Router />` component in the application with [ ```jsx del={3, 16} ins={4,17} import { render } from "solid-js/web"; -import { +import { Router MemoryRouter, - Route + Route } from "@solidjs/router"; const App = (props) => ( @@ -65,4 +80,4 @@ render( document.getElementById("app") ); -``` \ No newline at end of file +``` diff --git a/src/routes/solid-router/concepts/catch-all.mdx b/src/routes/solid-router/concepts/catch-all.mdx index a08de71c5..c2668856b 100644 --- a/src/routes/solid-router/concepts/catch-all.mdx +++ b/src/routes/solid-router/concepts/catch-all.mdx @@ -1,8 +1,21 @@ --- title: Catch-all routes +use_cases: >- + 404 pages, handling invalid urls, fallback routes, error boundaries, redirect + unknown paths +tags: + - "404" + - error-pages + - fallback + - routing + - wildcards +version: "1.0" +description: >- + Create catch-all routes in SolidJS to handle 404 errors and redirect users + from invalid URLs to proper fallback pages. --- -Catch-all routes are used to match any URL that does not match any other route in the application. +Catch-all routes are used to match any URL that does not match any other route in the application. This is useful for displaying a 404 page or redirecting to a specific route when a user enters an invalid URL. To create a catch-all route, place a route with an asterisk (`*`) as the path at the end of the route list. @@ -16,11 +29,11 @@ import About from "./About"; import NotFound from "./NotFound"; const App = () => ( - <Router> - <Route path="/home" component={Home} /> - <Route path="/about" component={About} /> - <Route path="*404" component={NotFound} /> - </Router> + <Router> + <Route path="/home" component={Home} /> + <Route path="/about" component={About} /> + <Route path="*404" component={NotFound} /> + </Router> ); ``` diff --git a/src/routes/solid-router/concepts/data.json b/src/routes/solid-router/concepts/data.json index 9d91d50dd..8cef16056 100644 --- a/src/routes/solid-router/concepts/data.json +++ b/src/routes/solid-router/concepts/data.json @@ -10,4 +10,4 @@ "alternative-routers.mdx", "actions.mdx" ] -} \ No newline at end of file +} diff --git a/src/routes/solid-router/concepts/dynamic-routes.mdx b/src/routes/solid-router/concepts/dynamic-routes.mdx index aba2b544e..9be0e08de 100644 --- a/src/routes/solid-router/concepts/dynamic-routes.mdx +++ b/src/routes/solid-router/concepts/dynamic-routes.mdx @@ -1,5 +1,18 @@ --- title: Dynamic routes +use_cases: >- + user profiles, product pages, blog posts, id-based content, variable urls, + data-driven pages +tags: + - dynamic + - parameters + - validation + - wildcards + - routing +version: "1.0" +description: >- + Build dynamic routes with parameters in SolidJS for user profiles, products, + and content that changes based on URL values. --- When a path is unknown ahead of time, it can be treated as a flexible parameter that is passed on to the component: diff --git a/src/routes/solid-router/concepts/layouts.mdx b/src/routes/solid-router/concepts/layouts.mdx index bf6dcf534..0ae860298 100644 --- a/src/routes/solid-router/concepts/layouts.mdx +++ b/src/routes/solid-router/concepts/layouts.mdx @@ -1,8 +1,21 @@ --- -title: "Layouts" +title: Layouts +use_cases: >- + consistent headers/footers, shared navigation, admin panels, dashboard + layouts, nested ui structure +tags: + - layouts + - nesting + - ui-structure + - components + - routing +version: "1.0" +description: >- + Create consistent page layouts in SolidJS with shared headers, footers, and + nested structures for better UI organization. --- -To maintain consistency across an application's page you can use layouts. +To maintain consistency across an application's page you can use layouts. Layouts are components that wrap the content of a route and can be used to define a common structure for all pages or specific sections of an application. ## Root-level layouts @@ -17,23 +30,23 @@ import { Router, Route } from "@solidjs/router"; import Home from "./pages/Home"; const Layout = (props) => { - return ( - <> - <header>Header</header> - {props.children} - <footer>Footer</footer> - </> - ); + return ( + <> + <header>Header</header> + {props.children} + <footer>Footer</footer> + </> + ); }; render( - () => ( - <Router root={Layout}> - <Route path="/" component={Home} /> - <Route path="/hello-world" component={() => <div>Hello world!</div>} /> - </Router> - ), - document.getElementById("app") + () => ( + <Router root={Layout}> + <Route path="/" component={Home} /> + <Route path="/hello-world" component={() => <div>Hello world!</div>} /> + </Router> + ), + document.getElementById("app") ); ``` @@ -63,10 +76,10 @@ For `PageWrapper` to be used as a layout, in this case, you can pass it as a com ```jsx <Router> - <Route path="/users" component={PageWrapper}> - <Route path="/" component={Users} /> - <Route path="/:id" component={User} /> - </Route> + <Route path="/users" component={PageWrapper}> + <Route path="/" component={Users} /> + <Route path="/:id" component={User} /> + </Route> </Router> ``` diff --git a/src/routes/solid-router/concepts/navigation.mdx b/src/routes/solid-router/concepts/navigation.mdx index 5f2e9b115..82a21ae3c 100644 --- a/src/routes/solid-router/concepts/navigation.mdx +++ b/src/routes/solid-router/concepts/navigation.mdx @@ -1,110 +1,123 @@ ---- -title: "Navigation" ---- - -When using Solid Router, you can use the standard standard HTML [`<a>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a), which triggers [soft navigation](/solid-router/reference/components/a#soft-navigation). -In addition to using this, Solid Router offers other options for navigating between routes: - -- The [`<A>` component](/solid-router/reference/components/a). -- The [`useNavigate` primitive](/solid-router/reference/primitives/use-navigate). -- The [`redirect` function](/solid-router/reference/response-helpers/redirect). - -## `<A>` component - -The `<A>` component extends the native `<a>` element by automatically applying the base URL path and, additionally, supports relative paths. - -```tsx -import { A } from "@solidjs/router"; - -function DashboardPage() { - return ( - <main> - <nav> - <A href="/">Home</A> - </nav> - {/* This is a relative path that, from /dashboard, links to /dashboard/users */} - <A href="users">Users</A> - </main> - ); -} -``` - -See the [`<A>` API reference](/solid-router/reference/components/a) for more information. - -### Styling - -The `<A>` component allows you to style links based on their active state using the `activeClass` and `inactiveClass` props. -When provided, these props apply the corresponding CSS classes to the link. -If omitted, the default classes `active` and `inactive` are used. - -By default, a link is considered active when the current route matches the link's `href` or any of its descendant routes. -For example, a link with `href="/dashboard"` is active when the current route is `/dashboard`, `/dashboard/users`, or `/dashboard/users/1/profile`. - -To match an exact route, the prop `end` can be used. -When `true`, it ensures that the link is only considered active if the `href` exactly matches the current route. -This is useful for root route links (href="/"), which might otherwise match all routes. - -```tsx -import { A } from "@solidjs/router"; - -function Navbar() { - return ( - <nav> - <A href="/" end={true}> - Home - </A> - <A - href="/login" - activeClass="text-blue-900" - inactiveClass="text-blue-500" - > - Login - </A> - </nav> - ); -} -``` - -## `useNavigate` primitive - -The `useNavigate` primitive allows for programmatically navigating to a specified route. - -```tsx -import { useNavigate } from "@solidjs/router"; - -function LoginPage() { - const navigate = useNavigate(); - - return ( - <button - onClick={() => { - // Login logic - navigate("/dashboard", { replace: true }); - }} - > - Login - </button> - ); -} -``` - -This example redirects the user to `/dashboard` after login. -By using `replace: true`, the login page is removed from the browser's history stack and replaced with the `/dashboard` route. -This prevents the user from navigating back to the login page using the back button. - -See the [`useNavigate` API reference](/solid-router/reference/primitives/use-navigate) for more information. - -## `redirect` function - -The `redirect` function returns a [`Response` object](https://developer.mozilla.org/en-US/docs/Web/API/Response), which enables navigation to a specified route within [query](/solid-router/reference/data-apis/query) or [action](/solid-router/reference/data-apis/action). - -```tsx -import { action, redirect } from "@solidjs/router"; - -const logout = action(async () => { - localStorage.remove("token"); - throw redirect("/"); -}); -``` - -See the [`redirect` API reference](/solid-router/reference/response-helpers/redirect) for more information. +--- +title: Navigation +use_cases: >- + page transitions, programmatic routing, user actions, form submissions, + authentication flows, redirects +tags: + - navigation + - links + - redirects + - routing + - programmatic +version: "1.0" +description: >- + Navigate between routes in SolidJS using links, programmatic navigation, and + redirects for seamless user experiences. +--- + +When using Solid Router, you can use the standard standard HTML [`<a>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a), which triggers [soft navigation](/solid-router/reference/components/a#soft-navigation). +In addition to using this, Solid Router offers other options for navigating between routes: + +- The [`<A>` component](/solid-router/reference/components/a). +- The [`useNavigate` primitive](/solid-router/reference/primitives/use-navigate). +- The [`redirect` function](/solid-router/reference/response-helpers/redirect). + +## `<A>` component + +The `<A>` component extends the native `<a>` element by automatically applying the base URL path and, additionally, supports relative paths. + +```tsx +import { A } from "@solidjs/router"; + +function DashboardPage() { + return ( + <main> + <nav> + <A href="/">Home</A> + </nav> + {/* This is a relative path that, from /dashboard, links to /dashboard/users */} + <A href="users">Users</A> + </main> + ); +} +``` + +See the [`<A>` API reference](/solid-router/reference/components/a) for more information. + +### Styling + +The `<A>` component allows you to style links based on their active state using the `activeClass` and `inactiveClass` props. +When provided, these props apply the corresponding CSS classes to the link. +If omitted, the default classes `active` and `inactive` are used. + +By default, a link is considered active when the current route matches the link's `href` or any of its descendant routes. +For example, a link with `href="/dashboard"` is active when the current route is `/dashboard`, `/dashboard/users`, or `/dashboard/users/1/profile`. + +To match an exact route, the prop `end` can be used. +When `true`, it ensures that the link is only considered active if the `href` exactly matches the current route. +This is useful for root route links (href="/"), which might otherwise match all routes. + +```tsx +import { A } from "@solidjs/router"; + +function Navbar() { + return ( + <nav> + <A href="/" end={true}> + Home + </A> + <A + href="/login" + activeClass="text-blue-900" + inactiveClass="text-blue-500" + > + Login + </A> + </nav> + ); +} +``` + +## `useNavigate` primitive + +The `useNavigate` primitive allows for programmatically navigating to a specified route. + +```tsx +import { useNavigate } from "@solidjs/router"; + +function LoginPage() { + const navigate = useNavigate(); + + return ( + <button + onClick={() => { + // Login logic + navigate("/dashboard", { replace: true }); + }} + > + Login + </button> + ); +} +``` + +This example redirects the user to `/dashboard` after login. +By using `replace: true`, the login page is removed from the browser's history stack and replaced with the `/dashboard` route. +This prevents the user from navigating back to the login page using the back button. + +See the [`useNavigate` API reference](/solid-router/reference/primitives/use-navigate) for more information. + +## `redirect` function + +The `redirect` function returns a [`Response` object](https://developer.mozilla.org/en-US/docs/Web/API/Response), which enables navigation to a specified route within [query](/solid-router/reference/data-apis/query) or [action](/solid-router/reference/data-apis/action). + +```tsx +import { action, redirect } from "@solidjs/router"; + +const logout = action(async () => { + localStorage.remove("token"); + throw redirect("/"); +}); +``` + +See the [`redirect` API reference](/solid-router/reference/response-helpers/redirect) for more information. diff --git a/src/routes/solid-router/concepts/nesting.mdx b/src/routes/solid-router/concepts/nesting.mdx index 0da70a850..44616c0e4 100644 --- a/src/routes/solid-router/concepts/nesting.mdx +++ b/src/routes/solid-router/concepts/nesting.mdx @@ -1,5 +1,18 @@ --- title: Nesting routes +use_cases: >- + hierarchical pages, parent-child relationships, shared layouts, complex + routing structures, admin sections +tags: + - nesting + - hierarchy + - routing + - layouts + - config +version: "1.0" +description: >- + Build nested route hierarchies in SolidJS for complex applications with + parent-child relationships and shared layouts. --- Nested routes are a way to create a hierarchy of routes in your application. @@ -44,8 +57,8 @@ Another way to achieve the same result is to nest the routes and explicitly defi ```jsx <Route path="/users"> - <Route path="/" component={Users} /> - <Route path="/:id" component={User} /> + <Route path="/" component={Users} /> + <Route path="/:id" component={User} /> </Route> ``` diff --git a/src/routes/solid-router/concepts/path-parameters.mdx b/src/routes/solid-router/concepts/path-parameters.mdx index 4d7ff707e..1b7ef9829 100644 --- a/src/routes/solid-router/concepts/path-parameters.mdx +++ b/src/routes/solid-router/concepts/path-parameters.mdx @@ -1,121 +1,132 @@ ---- -title: "Path parameters" ---- - -Parameters within a route are used to capture dynamic values from the URL. -This is useful for creating routes that are more flexible and can handle different values. - -```jsx -<Route path="/users/:id" component={User} /> - -``` - -In this example, the `:id` parameter will capture any value that comes after `/users/` in the URL. -The colon `:` is used to denote a parameter, and `id` is the name of the parameter. -When a URL matches this route, the `User` component will be rendered. - -:::note[Animations & Transitions] -Routes that share the same path match will be treated as the same route. -If a force re-render is needed, you can wrap your component in a keyed [`Show`](/reference/components/show) component: - -```jsx -<Show when={params.something} keyed> - <MyComponent /> -</Show> - -``` - -::: - -## Accessing parameters - -You can retrieve the values captured by parameters using [`useParams`](/solid-router/reference/primitives/use-params). - -```jsx frame="terminal" title="http://localhost:3000/users/123" -import { useParams } from "@solidjs/router"; - -function User() { - const params = useParams(); - return <div>User ID: {params.id}</div>; {/* Output: User ID: 123 */} -} - -``` - -## Validating parameters - -Each path parameter can be validated using the `MatchFilter` on the `Route` component. -Rather than checking for the presence of a parameter manually, you can use a `MatchFilter` to ensure that the parameter is in the correct format. - -```jsx -import { lazy } from "solid-js"; -import { render } from "solid-js/web"; -import { Router, Route } from "@solidjs/router"; - -const User = import("./pages/User"); - -const filters = { - parent: ["mom", "dad"], // allow enum values - id: /^\d+$/, // only allow numbers - withHtmlExtension: (v: string) => v.length > 5 && v.endsWith(".html"), // we want an `*.html` extension -}; - -render(() => ( - <Router> - <Route - path="/users/:parent/:id/:withHtmlExtension" - component={User} - matchFilters={filters} - /> - </Router> -), document.getElementById("app")); - -``` - -Here, the `matchFilter` prop validates the `parent`, `id`, and `withHtmlExtension` parameters against the specified filters defined in the `filters` object. -If the validation fails, the route will not match and the component will not be rendered. - -In this example, that means: -- `/users/mom/123/contact.html` would match, -- `/users/dad/456/about.html` would match, -- `/users/aunt/123/contact.html` would not match as `:parent` is not 'mom' or 'dad', -- `/users/mom/me/contact.html` would not match as `:id` is not a number, -- `/users/dad/123/contact` would not match as `:withHtmlExtension` is missing .html. - -## Optional parameters - -Parameters can be made optional by adding a `?` after the parameter name. - -```jsx -<Route path="/users/:id?" component={User} /> - -``` - -With this setup, the route would match both `/users` and `/users/123`. -However, it is important to note that the `?` only makes the parameter optional for the last segment of the path. -As a result, paths beyond the optional parameter will _not_ be matched. -For instance, `/users/123/contact` would not match. - -## Wildcard routes - -Wildcard routes can be used to match any number of segments in a path. -To create a wildcard route, use `*` followed by the parameter name. - -```jsx -<Route path="/users/*" component={User} /> - -``` - -Using an asterisk `*` as a parameter will match any number of segments after `/users`. -This includes `/users`, `/users/123`, `/users/123/contact`, and so on. - -If you need to expose the wildcard segments of the path, you can name them: - -```jsx -<Route path="/users/*rest" component={User} /> - -``` - -In this case, `rest` will contain the rest of the path after `/users/`. - -It is important to note that wildcard routes must be located at the **end of the path**. -If you place a wildcard route before the end, such as `/users/*rest/:id`, no routes will be matched. +--- +title: Path parameters +use_cases: >- + dynamic content, user profiles, resource ids, filtering data, validation, + flexible routing +tags: + - parameters + - validation + - dynamic + - wildcards + - routing +version: "1.0" +description: >- + Capture and validate dynamic URL parameters in SolidJS routes for flexible + content display and data-driven pages. +--- + +Parameters within a route are used to capture dynamic values from the URL. +This is useful for creating routes that are more flexible and can handle different values. + +```jsx +<Route path="/users/:id" component={User} /> +``` + +In this example, the `:id` parameter will capture any value that comes after `/users/` in the URL. +The colon `:` is used to denote a parameter, and `id` is the name of the parameter. +When a URL matches this route, the `User` component will be rendered. + +:::note[Animations & Transitions] +Routes that share the same path match will be treated as the same route. +If a force re-render is needed, you can wrap your component in a keyed [`Show`](/reference/components/show) component: + +```jsx +<Show when={params.something} keyed> + <MyComponent /> +</Show> +``` + +::: + +## Accessing parameters + +You can retrieve the values captured by parameters using [`useParams`](/solid-router/reference/primitives/use-params). + +```jsx frame="terminal" title="http://localhost:3000/users/123" +import { useParams } from "@solidjs/router"; + +function User() { + const params = useParams(); + return <div>User ID: {params.id}</div>; + { + /* Output: User ID: 123 */ + } +} +``` + +## Validating parameters + +Each path parameter can be validated using the `MatchFilter` on the `Route` component. +Rather than checking for the presence of a parameter manually, you can use a `MatchFilter` to ensure that the parameter is in the correct format. + +```jsx +import { lazy } from "solid-js"; +import { render } from "solid-js/web"; +import { Router, Route } from "@solidjs/router"; + +const User = import("./pages/User"); + +const filters = { + parent: ["mom", "dad"], // allow enum values + id: /^\d+$/, // only allow numbers + withHtmlExtension: (v: string) => v.length > 5 && v.endsWith(".html"), // we want an `*.html` extension +}; + +render(() => ( + <Router> + <Route + path="/users/:parent/:id/:withHtmlExtension" + component={User} + matchFilters={filters} + /> + </Router> +), document.getElementById("app")); + +``` + +Here, the `matchFilter` prop validates the `parent`, `id`, and `withHtmlExtension` parameters against the specified filters defined in the `filters` object. +If the validation fails, the route will not match and the component will not be rendered. + +In this example, that means: + +- `/users/mom/123/contact.html` would match, +- `/users/dad/456/about.html` would match, +- `/users/aunt/123/contact.html` would not match as `:parent` is not 'mom' or 'dad', +- `/users/mom/me/contact.html` would not match as `:id` is not a number, +- `/users/dad/123/contact` would not match as `:withHtmlExtension` is missing .html. + +## Optional parameters + +Parameters can be made optional by adding a `?` after the parameter name. + +```jsx +<Route path="/users/:id?" component={User} /> +``` + +With this setup, the route would match both `/users` and `/users/123`. +However, it is important to note that the `?` only makes the parameter optional for the last segment of the path. +As a result, paths beyond the optional parameter will _not_ be matched. +For instance, `/users/123/contact` would not match. + +## Wildcard routes + +Wildcard routes can be used to match any number of segments in a path. +To create a wildcard route, use `*` followed by the parameter name. + +```jsx +<Route path="/users/*" component={User} /> +``` + +Using an asterisk `*` as a parameter will match any number of segments after `/users`. +This includes `/users`, `/users/123`, `/users/123/contact`, and so on. + +If you need to expose the wildcard segments of the path, you can name them: + +```jsx +<Route path="/users/*rest" component={User} /> +``` + +In this case, `rest` will contain the rest of the path after `/users/`. + +It is important to note that wildcard routes must be located at the **end of the path**. +If you place a wildcard route before the end, such as `/users/*rest/:id`, no routes will be matched. diff --git a/src/routes/solid-router/concepts/search-parameters.mdx b/src/routes/solid-router/concepts/search-parameters.mdx index 8df4ddd72..98cd76e7d 100644 --- a/src/routes/solid-router/concepts/search-parameters.mdx +++ b/src/routes/solid-router/concepts/search-parameters.mdx @@ -1,69 +1,82 @@ ---- -title: "Search parameters" ---- - -Search parameters are used to pass data to a route using the query string. -The query string is the part of the URL that comes after the `?` character and is used to pass key-value pairs to the route. - -In Solid Router, these query parameters can be accessed using [`useSearchParams`](/solid-router/reference/primitives/use-search-params). -This primitive retrieves a tuple that contains a reactive object that reads the current search parameters and a function to update them. - -```jsx {4} -import { useSearchParams } from "@solidjs/router"; - -export const App = () => { - const [searchParams, setSearchParams] = useSearchParams(); - - return ( - <div> - <span>Username: {searchParams.username}</span> - <input - type="text" - onChange={(e) => { - e.preventDefault(); - setSearchParams({ username: e.target.value }); - }} - /> - </div> - ); -}; -``` - -The getter, in this case `searchParams`, is used to read the current search parameters. -`setSearchParams` works as the setter which accepts an _object_ whose entries will be merged into the current query. - -## Multiple queries - -Since `setSearchParams` accepts an object, you can pass multiple key-value pairs to update multiple search parameters at once. - -```jsx -setSearchParams({ - username: "john", - page: 1, -}); -``` - -:::note[Empty or null values] - If the value of a search parameter's key is `undefined`, `null`, or an empty - string (`""`), it will be removed from the query string. -::: - -## Accessing query strings - -If you require accessing the query string directly, you can use the [`useLocation`](/solid-router/reference/primitives/use-location) primitive: - -```jsx -import { useLocation } from "@solidjs/router"; - -export const App = () => { - const location = useLocation(); - - return ( - <div> - <span>Query String: {location.search}</span> - </div> - ); -}; -``` - -If the URL was `http://localhost:3000/users?username=john&page=1`, the output would be `Query String: ?username=john&page=1`. +--- +title: Search parameters +use_cases: >- + filtering, pagination, search queries, form state in url, shareable urls, + stateful navigation +tags: + - query-params + - search + - state + - url + - routing +version: "1.0" +description: >- + Manage query strings and search parameters in SolidJS for filtering, + pagination, and maintaining state in the URL. +--- + +Search parameters are used to pass data to a route using the query string. +The query string is the part of the URL that comes after the `?` character and is used to pass key-value pairs to the route. + +In Solid Router, these query parameters can be accessed using [`useSearchParams`](/solid-router/reference/primitives/use-search-params). +This primitive retrieves a tuple that contains a reactive object that reads the current search parameters and a function to update them. + +```jsx {4} +import { useSearchParams } from "@solidjs/router"; + +export const App = () => { + const [searchParams, setSearchParams] = useSearchParams(); + + return ( + <div> + <span>Username: {searchParams.username}</span> + <input + type="text" + onChange={(e) => { + e.preventDefault(); + setSearchParams({ username: e.target.value }); + }} + /> + </div> + ); +}; +``` + +The getter, in this case `searchParams`, is used to read the current search parameters. +`setSearchParams` works as the setter which accepts an _object_ whose entries will be merged into the current query. + +## Multiple queries + +Since `setSearchParams` accepts an object, you can pass multiple key-value pairs to update multiple search parameters at once. + +```jsx +setSearchParams({ + username: "john", + page: 1, +}); +``` + +:::note[Empty or null values] +If the value of a search parameter's key is `undefined`, `null`, or an empty +string (`""`), it will be removed from the query string. +::: + +## Accessing query strings + +If you require accessing the query string directly, you can use the [`useLocation`](/solid-router/reference/primitives/use-location) primitive: + +```jsx +import { useLocation } from "@solidjs/router"; + +export const App = () => { + const location = useLocation(); + + return ( + <div> + <span>Query String: {location.search}</span> + </div> + ); +}; +``` + +If the URL was `http://localhost:3000/users?username=john&page=1`, the output would be `Query String: ?username=john&page=1`. diff --git a/src/routes/solid-router/data-fetching/data.json b/src/routes/solid-router/data-fetching/data.json new file mode 100644 index 000000000..e67f9ab6e --- /dev/null +++ b/src/routes/solid-router/data-fetching/data.json @@ -0,0 +1,4 @@ +{ + "title": "Data fetching", + "pages": ["queries.mdx", "streaming.mdx", "revalidation.mdx", "how-to"] +} diff --git a/src/routes/solid-router/data-fetching/how-to/data.json b/src/routes/solid-router/data-fetching/how-to/data.json new file mode 100644 index 000000000..d96966227 --- /dev/null +++ b/src/routes/solid-router/data-fetching/how-to/data.json @@ -0,0 +1,4 @@ +{ + "title": "How to", + "pages": ["preload-data.mdx", "handle-error-and-loading-states.mdx"] +} diff --git a/src/routes/solid-router/data-fetching/how-to/handle-error-and-loading-states.mdx b/src/routes/solid-router/data-fetching/how-to/handle-error-and-loading-states.mdx new file mode 100644 index 000000000..2f559a617 --- /dev/null +++ b/src/routes/solid-router/data-fetching/how-to/handle-error-and-loading-states.mdx @@ -0,0 +1,29 @@ +--- +title: "Handle pending and error states" +--- + +The `createAsync` primitive is designed to work with Solid's native components for managing asynchronous states. +It reports its pending state to the nearest [`<Suspense>` boundary](/reference/components/suspense) to display loading fallbacks, and propagate errors to an [`<ErrorBoundary>`](/reference/components/error-boundary) for handling and displaying error messages. + +```tsx +import { Suspense, ErrorBoundary, For } from "solid-js"; +import { query, createAsync } from "@solidjs/router"; + +const getNewsQuery = query(async () => { + // ... Fetches the latest news from an API. +}, "news"); + +function NewsFeed() { + const news = createAsync(() => getNewsQuery()); + + return ( + <ErrorBoundary fallback={<p>Could not fetch news.</p>}> + <Suspense fallback={<p>Loading news...</p>}> + <ul> + <For each={news()}>{(item) => <li>{item.headline}</li>}</For> + </ul> + </Suspense> + </ErrorBoundary> + ); +} +``` 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 ( + <Show when={product()}> + <h1>{product().name}</h1> + </Show> + ); +} + +function preloadProduct({ params }: { params: { id: string } }) { + getProductQuery(params.id); +} + +function Routes() { + return ( + <Route + path="/products/:id" + component={ProductDetails} + preload={preloadProduct} + /> + ); +} +``` + +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 [`<ErrorBoundary>`](/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 ( + <Show when={articles()}> + <For each={articles()}>{(article) => <p>{article.title}</p>}</For> + </Show> + ); +} +``` + +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 ( + <div> + <button onClick={refetchAllTasks}>Refetch all tasks</button> + <For each={projects()}>{(project) => <Project id={project.id} />}</For> + </div> + ); +} + +function Project(props: { id: string }) { + const tasks = createAsync(() => getProjectTasksQuery(props.id)); + + function refetchTasks() { + revalidate(getProjectTasksQuery.keyFor(props.id)); + } + + return ( + <div> + <button onClick={refetchTasks}>Refetch tasks for this project</button> + <For each={project.tasks}>{(task) => <div>{task.title}</div>}</For> + </div> + ); +} +``` 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 [`<Suspense>` 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 ( + <div> + <h1>Dashboard</h1> + <Suspense fallback={<p>Loading account stats...</p>}> + <For each={stats()}> + {(stat) => ( + <p> + {stat.label}: {stat.value} + </p> + )} + </For> + </Suspense> + + <Suspense fallback={<p>Loading recent transactions...</p>}> + <For each={transactions()}> + {(transaction) => ( + <h2> + {transaction.description} - {transaction.amount} + </h2> + )} + </For> + </Suspense> + </div> + ); +} +``` + +For example, each `<Suspense>` component creates its own independent boundary. +The server can stream the heading `<h1>Dashboard</h1>` 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 <h1>{article()?.title}</h1>; +} +``` 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/getting-started/component.mdx b/src/routes/solid-router/getting-started/component.mdx index dd214874c..d26965595 100644 --- a/src/routes/solid-router/getting-started/component.mdx +++ b/src/routes/solid-router/getting-started/component.mdx @@ -1,5 +1,18 @@ --- -title: "Component routing" +title: Component routing +use_cases: >- + defining routes, jsx routing, template-based routing, initial setup, basic + navigation +tags: + - jsx + - components + - routing + - setup + - templates +version: "1.0" +description: >- + Define routes using JSX components in SolidJS Router for intuitive, + template-based routing in your applications. --- In Solid Router, routes can be defined directly in an application's template using JSX. @@ -14,12 +27,12 @@ import { Router, Route } from "@solidjs/router"; import Home from "./routes/Home"; render( - () => ( - <Router> - <Route path="/" component={Home} /> - </Router> - ), - document.getElementById("app") + () => ( + <Router> + <Route path="/" component={Home} /> + </Router> + ), + document.getElementById("app") ); ``` @@ -36,15 +49,15 @@ import Home from "./routes/index.jsx"; import About from "./routes/about.jsx"; render( - () => ( - <Router> - <Route path="/" component={Home} /> - <Route path="/hello-world" component={() => <h1>Hello World!</h1>} /> - <Route path="/about" component={About} /> - </Router> - ), - document.getElementById("app") + () => ( + <Router> + <Route path="/" component={Home} /> + <Route path="/hello-world" component={() => <h1>Hello World!</h1>} /> + <Route path="/about" component={About} /> + </Router> + ), + document.getElementById("app") ); ``` -This example defines three routes: the root path (`/`) which renders the `Home` page, the path `/hello-world` which renders an `h1` element, and the path `/about` which renders the `About` component. \ No newline at end of file +This example defines three routes: the root path (`/`) which renders the `Home` page, the path `/hello-world` which renders an `h1` element, and the path `/about` which renders the `About` component. diff --git a/src/routes/solid-router/getting-started/config.mdx b/src/routes/solid-router/getting-started/config.mdx index f1b00bd85..8b3c66eb0 100644 --- a/src/routes/solid-router/getting-started/config.mdx +++ b/src/routes/solid-router/getting-started/config.mdx @@ -1,5 +1,18 @@ --- -title: "Config-based routing" +title: Config-based routing +use_cases: >- + centralized routing, lazy loading, config-based setup, dynamic imports, + performance optimization +tags: + - config + - lazy-loading + - routing + - performance + - setup +version: "1.0" +description: >- + Configure SolidJS routes with config objects for centralized routing, lazy + loading, and optimized performance. --- Solid Router supports config-based routing, which offers the same capabilities as [component routing](/solid-router/getting-started/component). @@ -13,10 +26,9 @@ import { render } from "solid-js/web"; import { Router } from "@solidjs/router"; const routes = { - path: "/", - component: lazy(() => import("/routes/index.js")), -} - + path: "/", + component: lazy(() => import("/routes/index.js")), +}; render(() => <Router>{routes}</Router>, document.getElementById("app")); ``` @@ -31,20 +43,19 @@ import { render } from "solid-js/web"; import { Router } from "@solidjs/router"; const routes = [ - { - path: "/", - component: lazy(() => import("/routes/index.js")), - }, - { - path: "/hello-world", - component: () => <h1>Hello, World!</h1> - }, - { - path: "/about", - component: lazy(() => import("/routes/about.js")), - } -] - + { + path: "/", + component: lazy(() => import("/routes/index.js")), + }, + { + path: "/hello-world", + component: () => <h1>Hello, World!</h1>, + }, + { + path: "/about", + component: lazy(() => import("/routes/about.js")), + }, +]; render(() => <Router>{routes}</Router>, document.getElementById("app")); ``` @@ -62,20 +73,19 @@ import { render } from "solid-js/web"; import { Router } from "@solidjs/router"; const routes = [ - { - path: "/", - component: lazy(() => import("/routes/index.js")), - }, - { - path: "/hello-world", - component: () => <h1>Hello, World!</h1> - }, - { - path: "/about", - component: lazy(() => import("/routes/about.js")), - } -] - + { + path: "/", + component: lazy(() => import("/routes/index.js")), + }, + { + path: "/hello-world", + component: () => <h1>Hello, World!</h1>, + }, + { + path: "/about", + component: lazy(() => import("/routes/about.js")), + }, +]; render(() => <Router>{routes}</Router>, document.getElementById("app")); ``` diff --git a/src/routes/solid-router/getting-started/installation-and-setup.mdx b/src/routes/solid-router/getting-started/installation-and-setup.mdx index 15ec2e8e9..782cf3dbc 100644 --- a/src/routes/solid-router/getting-started/installation-and-setup.mdx +++ b/src/routes/solid-router/getting-started/installation-and-setup.mdx @@ -1,5 +1,19 @@ --- title: Installation and setup +use_cases: >- + starting new project, initial setup, configuring routing, spa applications, + client-side routing +tags: + - setup + - installation + - configuration + - spa + - routing + - getting-started +version: "1.0" +description: >- + Learn how to install and configure Solid Router for client and server-side + routing in your single-page applications with step-by-step setup guide. --- Solid Router is the universal router for Solid which works for rendering on the client or the server. @@ -31,10 +45,10 @@ import { Router } from "@solidjs/router"; const wrapper = document.getElementById("app"); if (!wrapper) { - throw new Error("Wrapper div not found"); + throw new Error("Wrapper div not found"); } -render(() => <Router />, wrapper) +render(() => <Router />, wrapper); ``` This sets up the router that will match on the url and render the appropriate route. diff --git a/src/routes/solid-router/getting-started/linking-routes.mdx b/src/routes/solid-router/getting-started/linking-routes.mdx index d24c5deba..52ea8428d 100644 --- a/src/routes/solid-router/getting-started/linking-routes.mdx +++ b/src/routes/solid-router/getting-started/linking-routes.mdx @@ -1,5 +1,19 @@ --- title: Linking routes +use_cases: >- + navigation between pages, creating menu bars, active link styling, internal + linking, user navigation +tags: + - navigation + - links + - anchors + - active-states + - menu + - ui +version: "1.0" +description: >- + Create navigation links between routes using anchor tags and the A component + with active state styling and automatic base path handling. --- Once routes have been created within an application, using anchor tags will help users navigate between different views or pages. diff --git a/src/routes/solid-router/guides/migration.mdx b/src/routes/solid-router/guides/migration.mdx index 6ddf20e18..b7d4bec00 100644 --- a/src/routes/solid-router/guides/migration.mdx +++ b/src/routes/solid-router/guides/migration.mdx @@ -1,5 +1,19 @@ --- title: Migration from v0.9.x +use_cases: >- + upgrading from v0.9, breaking changes, api migration, updating legacy code, + version upgrade +tags: + - migration + - upgrade + - breaking-changes + - v0.10 + - api-changes + - legacy +version: "1.0" +description: >- + Migrate your Solid Router application to v0.10 with this comprehensive guide + covering removed APIs, new patterns, and Islands support changes. --- v0.10.0 brings some big changes to support the future of routing including Islands/Partial Hydration hybrid solutions. diff --git a/src/routes/solid-router/index.mdx b/src/routes/solid-router/index.mdx index d75f93c71..17eb790e0 100644 --- a/src/routes/solid-router/index.mdx +++ b/src/routes/solid-router/index.mdx @@ -1,12 +1,28 @@ --- -title: Overview +title: Solid Router Docs +nav_title: Overview +titleTemplate: ":title" +use_cases: >- + understanding routing, learning basics, overview needed, getting started, spa + routing concepts +tags: + - overview + - introduction + - basics + - spa + - routing + - concepts +version: "1.0" +description: >- + Solid Router is the universal routing solution for Solid applications, + enabling client and server-side navigation in single-page applications. --- # Overview :::note[Prerequisites] - The docs are based on latest Solid Router. - To use this version, you need to have Solid v1.8.4 or later installed. +The docs are based on latest Solid Router. +To use this version, you need to have Solid v1.8.4 or later installed. ::: Solid Router is the universal router for Solid which works for rendering on the client or the server. diff --git a/src/routes/solid-router/reference/components/a.mdx b/src/routes/solid-router/reference/components/a.mdx index e09be7df1..8f828b489 100644 --- a/src/routes/solid-router/reference/components/a.mdx +++ b/src/routes/solid-router/reference/components/a.mdx @@ -1,5 +1,19 @@ --- title: A +use_cases: >- + creating navigation links, active link styling, soft navigation, relative + paths, menu items +tags: + - component + - navigation + - links + - active-states + - anchors + - soft-navigation +version: "1.0" +description: >- + The A component provides enhanced anchor tags with automatic base path + support, active states, and soft navigation for better user experience. --- Solid Router exposes the `<A />` component as a wrapper around the [native anchor tag ](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a). @@ -16,8 +30,8 @@ The `<A>` tag has an `active` class if its href matches the current location, an By default matching includes locations that are descendants (e.g.: href `/users` matches locations `/users` and `/users/123`). :::tip - Use the boolean `end` prop to prevent matching these. This is particularly - useful for links to the root route `/` which would match everything. +Use the boolean `end` prop to prevent matching these. This is particularly +useful for links to the root route `/` which would match everything. ::: ## Soft Navigation diff --git a/src/routes/solid-router/reference/components/hash-router.mdx b/src/routes/solid-router/reference/components/hash-router.mdx index 168edac88..f7aaf9b5d 100644 --- a/src/routes/solid-router/reference/components/hash-router.mdx +++ b/src/routes/solid-router/reference/components/hash-router.mdx @@ -1,5 +1,19 @@ --- title: HashRouter +use_cases: >- + static file hosting, single html file apps, no server routing, github pages, + static deployment +tags: + - hash-routing + - static-hosting + - client-side + - spa + - deployment + - component +version: "1.0" +description: >- + HashRouter enables client-side routing using URL hash values, perfect for + static file hosting where server-side routing isn't available. --- The `HashRouter` is a top level component that manages the routing of your application. @@ -29,11 +43,11 @@ render( ); ``` -| prop | type | description | -| ------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| children | `JSX.Element`, `RouteDefinition`, or `RouteDefinition[]` | The route definitions | -| root | Component | Top level layout component | -| base | string | Base url to use for matching routes | -| actionBase | string | Root url for server actions, default: `/_server` | -| preload | boolean | Enables/disables preloads globally, default: `true` | +| prop | type | description | +| ------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| children | `JSX.Element`, `RouteDefinition`, or `RouteDefinition[]` | The route definitions | +| root | Component | Top level layout component | +| base | string | Base url to use for matching routes | +| actionBase | string | Root url for server actions, default: `/_server` | +| preload | boolean | Enables/disables preloads globally, default: `true` | | explicitLinks | boolean | Disables all anchors being intercepted and instead requires [`<A>`](/solid-router/reference/components/a). default: `false` | diff --git a/src/routes/solid-router/reference/components/memory-router.mdx b/src/routes/solid-router/reference/components/memory-router.mdx index f58b84d79..701833a05 100644 --- a/src/routes/solid-router/reference/components/memory-router.mdx +++ b/src/routes/solid-router/reference/components/memory-router.mdx @@ -1,5 +1,19 @@ --- title: MemoryRouter +use_cases: >- + testing routing, controlled navigation, internal history, unit tests, + programmatic routing +tags: + - testing + - memory + - history + - component + - navigation + - programmatic +version: "1.0" +description: >- + MemoryRouter keeps routing history in memory for complete control, ideal for + testing scenarios and programmatic navigation management. --- The `MemoryRouter` can be used to route while keeping the entire routing history within internal memory. @@ -48,8 +62,6 @@ The `MemoryHistory` object contains the following methods, which you can use to - The `back` and `forward` methods mimic the browser's back and forward buttons, respectively, and the `go` method navigates a specific number of steps in the history, either backward or forward. - The `listen` method registers a callback to be called on navigation change. - - ## Properties ### `MemoryHistory` diff --git a/src/routes/solid-router/reference/components/navigate.mdx b/src/routes/solid-router/reference/components/navigate.mdx index 7edd009ea..75151e43c 100644 --- a/src/routes/solid-router/reference/components/navigate.mdx +++ b/src/routes/solid-router/reference/components/navigate.mdx @@ -1,5 +1,18 @@ --- title: Navigate +use_cases: >- + automatic redirects, programmatic navigation, conditional routing, auth + redirects, dynamic routing +tags: + - component + - redirects + - navigation + - programmatic + - dynamic +version: "1.0" +description: >- + Navigate component provides immediate programmatic navigation and redirects, + perfect for authentication flows and conditional routing logic. --- Solid Router provides a `Navigate` component that works similarly to [`<A>`](/solid-router/reference/components/a), but it will _immediately_ navigate to the provided path as soon as the component is rendered. diff --git a/src/routes/solid-router/reference/components/route.mdx b/src/routes/solid-router/reference/components/route.mdx index e1848905f..917056870 100644 --- a/src/routes/solid-router/reference/components/route.mdx +++ b/src/routes/solid-router/reference/components/route.mdx @@ -1,5 +1,19 @@ --- title: Route +use_cases: >- + defining routes, app structure, url mapping, component rendering, nested + routing +tags: + - component + - routes + - structure + - paths + - nested + - configuration +version: "1.0" +description: >- + Route component defines your application's URL structure and maps paths to + components with support for multiple paths and nested routing. --- `Route` is the component used when defining the routes of an application. diff --git a/src/routes/solid-router/reference/components/router.mdx b/src/routes/solid-router/reference/components/router.mdx index 4a85425bf..7400ea5a6 100644 --- a/src/routes/solid-router/reference/components/router.mdx +++ b/src/routes/solid-router/reference/components/router.mdx @@ -1,5 +1,19 @@ --- title: Router +use_cases: >- + app initialization, root setup, layout wrapper, routing context, main + configuration +tags: + - component + - root + - initialization + - layout + - configuration + - context +version: "1.0" +description: >- + Router is the top-level component that manages your app's routing, providing + context and configuration for all child routes and navigation. --- The `Router` component is a top level component that manages the routing of your application. @@ -18,7 +32,7 @@ const App = (props) => ( render( () => <Router root={App}>{/*... routes */}</Router>, - document.getElementById("app") + document.getElementById("root") ); ``` diff --git a/src/routes/solid-router/reference/data-apis/action.mdx b/src/routes/solid-router/reference/data-apis/action.mdx index 8f3a5e666..3c58bebf8 100644 --- a/src/routes/solid-router/reference/data-apis/action.mdx +++ b/src/routes/solid-router/reference/data-apis/action.mdx @@ -1,197 +1,155 @@ --- title: action +use_cases: >- + forms, user input, data mutations, optimistic updates, form submissions, + server actions, post requests +tags: + - actions + - forms + - mutations + - post + - validation + - optimistic-updates + - server +version: "1.0" +description: >- + Learn how to handle form submissions and data mutations in SolidJS with + actions, including optimistic updates and server-side processing. --- -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 -<form action={myAction} method="post" /> +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 -<button type="submit" formaction={myAction}></button> +## 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) -}) - -<form action={deleteTodo} method="post"> - <input type="hidden" name="id" value={todo.id} /> - <button type="submit">Delete</button> -</form> - +## Type + +```tsx +function action<T extends Array<any>, U = void>( + fn: (...args: T) => Promise<U>, + name?: string +): Action<T, U>; + +function action<T extends Array<any>, U = void>( + fn: (...args: T) => Promise<U>, + options?: { name?: string; onComplete?: (s: Submission<T, U>) => void } +): Action<T, U>; + +function action<T extends Array<any>, U = void>( + fn: (...args: T) => Promise<U>, + options: + | string + | { name?: string; onComplete?: (s: Submission<T, U>) => void } = {} +): Action<T, U>; ``` -Using `with`: +## Parameters -```jsx del={5,6} ins={7} -const deleteTodo = action(async (id: number) => { - await api.deleteTodo(id) -}) +### `handler` -<form action={deleteTodo} method="post"> - <input type="hidden" name="id" value={todo.id} /> -<form action={deleteTodo.with(todo.id)} method="post"> - <button type="submit">Delete</button> -</form> +- **Type:** `(...args: T) => Promise<U>` +- **Required:** Yes -``` +An asynchronous function that performs the action's logic. +When the action is used with a [`<form>` 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 `<form>` implementation and SSR +- **Type:** `string | { name?: string; onComplete?: (s: Submission<T, U>) => 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 `<form>` 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 `<form>` usage. -``` +#### `onComplete` (optional): -The outside of a form context can use custom data instead of `formData`. -These helpers preserve types. +- **Type:** `(s: Submission<T, U>) => 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<T, U> = { - 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 `<form>`, 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 ( + <form action={addTodoAction} method="post"> + <input name="name" /> + <button>Add todo</button> + </form> + ); +} ``` -## 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 ( + <form action={addTodoAction.with(userId)} method="post"> + <input name="name" /> + <button>Add todo</button> + </form> + ); +} ``` -### 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 <button onClick={() => markDone(props.id)}>Mark as done</button>; } - ``` diff --git a/src/routes/solid-router/reference/data-apis/cache.mdx b/src/routes/solid-router/reference/data-apis/cache.mdx index 6c43c2626..22f98a72a 100644 --- a/src/routes/solid-router/reference/data-apis/cache.mdx +++ b/src/routes/solid-router/reference/data-apis/cache.mdx @@ -1,6 +1,19 @@ --- title: cache isDeprecated: true +use_cases: >- + api calls, data fetching, deduplication, preloading routes, caching responses, + preventing waterfalls +tags: + - cache + - deprecated + - data-fetching + - deduplication + - preload +version: "1.0" +description: >- + Deprecated caching API for deduplicating requests and preloading data. Use + query instead for better performance and invalidation. --- :::caution[Deprecation Warning] 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..0fea473bc 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 @@ -1,9 +1,142 @@ --- title: createAsyncStore +use_cases: >- + large datasets, reactive stores, model data, fine-grained updates, complex + state +tags: + - async + - stores + - reactive + - data-fetching + - state +version: "1.0" +description: >- + Create deeply reactive stores from async data sources for fine-grained updates + on large datasets and complex model structures. --- -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<T>( + fn: (prev: T) => Promise<T>, + options: { + name?: string; + initialValue: T; + deferStream?: boolean; + reconcile?: ReconcileOptions; + } +): AccessorWithLatest<T>; + +function createAsyncStore<T>( + fn: (prev: T | undefined) => Promise<T>, + options?: { + name?: string; + initialValue?: T; + deferStream?: boolean; + reconcile?: ReconcileOptions; + } +): AccessorWithLatest<T | undefined>; +``` + +## Parameters + +### `fetcher` + +- **Type:** `(prev: T | undefined) => Promise<T>` +- **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/data-fetching/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 ( + <div> + <button onClick={() => setUnreadOnly(!unreadOnly())}> + Toggle unread + </button> + <ul> + <For each={notifications()}> + {(notification) => ( + <li> + <div>{notification.message}</div> + <div>{notification.user.name}</div> + </li> + )} + </For> + </ul> + </div> + ); +} ``` 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..11d1f6b80 100644 --- a/src/routes/solid-router/reference/data-apis/create-async.mdx +++ b/src/routes/solid-router/reference/data-apis/create-async.mdx @@ -1,43 +1,174 @@ --- title: createAsync +use_cases: >- + data fetching, async operations, suspense boundaries, loading states, api + calls, ssr data +tags: + - async + - suspense + - data-fetching + - loading + - promises + - ssr +version: "1.0" +description: >- + Transform promises into reactive signals with createAsync. Handle async data + with Suspense and automatic loading states. --- -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<T>( + fn: (prev: T) => Promise<T>, + options: { + name?: string; + initialValue: T; + deferStream?: boolean; + } +): AccessorWithLatest<T>; + +function createAsync<T>( + fn: (prev: T | undefined) => Promise<T>, + options?: { + name?: string; + initialValue?: T; + deferStream?: boolean; + } +): AccessorWithLatest<T | undefined>; +``` + +## Parameters + +### `fetcher` + +- **Type:** `(prev: T | undefined) => Promise<T>` +- **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/data-fetching/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 getCurrentUser = query(async () => { + // ... Fetches the current authenticated user from the server. +}, "currentUser"); + +function UserProfile() { + const user = createAsync(() => getCurrentUser()); + + return <div>{user()?.name}</div>; +} +``` + +### With parameter + +```tsx +import { createAsync, query } from "@solidjs/router"; + +const getInvoiceQuery = query(async (invoiceId: string) => { + // ... Fetches the invoice details from the server. +}, "invoice"); + +function InvoiceDetails(props: { invoiceId: string }) { + const invoice = createAsync(() => getInvoiceQuery(props.invoiceId)); + + return ( + <div> + <h2>Invoice #{invoice()?.number}</h2> + <p>Total: ${invoice()?.total}</p> + </div> + ); +} +``` + +### With error handling and pending state + +```tsx +import { createAsync, query } from "@solidjs/router"; +import { Suspense, ErrorBoundary, For } from "solid-js"; + +const getAllRecipesQuery = query(async () => { + // ... Fetches the recipes from the server and throws an error if an issue occurred. +}, "recipes"); -export function Component () => { - const user = createAsync(() => getUser(params.id)); +function Recipes() { + const recipes = createAsync(() => getAllRecipesQuery()); return ( - <Suspense fallback="loading user..."> - <p>{user()}</p> - </Suspense> + <ErrorBoundary fallback={<p>Couldn't fetch any recipes!</p>}> + <Suspense fallback={<p>Fetching recipes...</p>}> + <For each={recipes()}> + {(recipe) => ( + <div> + <h3>{recipe.name}</h3> + <p>Cook time: {recipe.time}</p> + </div> + )} + </For> + </Suspense> + </ErrorBoundary> ); +} ``` -## Options +## Related -| 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 +- [`query`](/solid-router/reference/data-apis/query) +- [`<Suspense>`](/reference/components/suspense) +- [`<ErrorBoundary>`](/reference/components/error-boundary) diff --git a/src/routes/solid-router/reference/data-apis/query.mdx b/src/routes/solid-router/reference/data-apis/query.mdx index eab7749ba..f4854f7f1 100644 --- a/src/routes/solid-router/reference/data-apis/query.mdx +++ b/src/routes/solid-router/reference/data-apis/query.mdx @@ -1,119 +1,103 @@ --- title: query +use_cases: >- + api calls, data fetching, caching, deduplication, preloading routes, + preventing waterfalls, ssr +tags: + - query + - cache + - data-fetching + - deduplication + - preload + - ssr + - api +version: "1.0" +description: >- + Cache and deduplicate API calls with query. Prevent waterfalls, enable + preloading, and manage server-side rendering efficiently. --- -`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. +The `query` function wraps an asynchronous function (the fetcher) and returns a query. -:::note -`query` can be defined anywhere and then used inside your components with [`createAsync`](/solid-router/reference/data-apis/create-async). +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: -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. +- **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 -## 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 +```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 - -const User = lazy(() => import("./pages/users/[id].js")); - -// preload function -function preloadUser({params, location}) { - void getUser(params.id) -} +## Type -// Pass it in the route definition -<Route path="/users/:id" component={User} preload={preloadUser} />; +```tsx +function query<T extends (...args: any) => any>( + fn: T, + name: string +): CachedFunction<T>; ``` -### Inside a route's component +## Parameters -Using it inside a route's component: +### `fetcher` -```jsx -// pages/users/[id].js -import { getUser } from ... // the cache function +- **Type:** `T extends (...args: any) => any` +- **Required:** Yes -export default function User(props) { - const user = createAsync(() => getUser(props.params.id)); - return <h1>{user().name}</h1>; -} -``` - -## Query Function Capabilities - -`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"; + +const getUserProfileQuery = query(async (userId: string) => { + const response = await fetch( + `https://api.example.com/users/${encodeURIComponent(userId)}` + ); + const json = await response.json(); -### `revalidate` + if (!response.ok) { + throw new Error(json?.message ?? "Failed to load user profile."); + } -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. + return json; +}, "userProfile"); +``` diff --git a/src/routes/solid-router/reference/data-apis/revalidate.mdx b/src/routes/solid-router/reference/data-apis/revalidate.mdx index 0319ba41d..e455657e7 100644 --- a/src/routes/solid-router/reference/data-apis/revalidate.mdx +++ b/src/routes/solid-router/reference/data-apis/revalidate.mdx @@ -1,43 +1,109 @@ --- title: revalidate +use_cases: >- + refresh data, invalidate cache, polling, real-time updates, manual refetch, + stale data +tags: + - revalidate + - cache + - refresh + - invalidation + - polling + - refetch +version: "1.0" +description: >- + Manually revalidate cached queries to refresh stale data, implement polling, + or trigger updates after mutations in SolidJS. --- -The `revalidate` function is used to revalidate queries associated with specified [query keys](/solid-router/reference/data-apis/query#query-keys). -When a [query](/solid-router/reference/data-apis/query) is revalidated, it is executed again, and any references to the associated query data are updated accordingly. +The `revalidate` function triggers revalidation of [queries](/solid-router/data-fetching/queries) by their keys. +Each query with active subscribers re-executes and updates its dependents; queries without subscribers are marked stale but don't execute until subscribed. + +## Import + +```tsx +import { revalidate } from "@solidjs/router"; +``` + +## Type + +```tsx +function revalidate( + key?: string | string[] | void, + force?: boolean +): Promise<void>; +``` + +## Parameters + +### `key` + +- **Type:** `string | string[] | void` +- **Required:** No + +The query key or array of query keys to revalidate. +If not provided, all queries on the current page are revalidated. + +### `force` + +- **Type:** `boolean` +- **Required:** No +- **Default:** `true` + +When `true`, clears the internal cache used for deduplication. +When `false`, allows cached data to be reused if available. + +## Return value + +`revalidate` returns a `Promise` that resolves when the revalidation transition completes. + +## Examples + +### Basic usage ```tsx -import { For } from "solid-js"; import { query, createAsync, revalidate } from "@solidjs/router"; -const getPosts = query(async () => { - return await fetch("https://api.com/posts").then((response) => - response.json() - ); -}, "posts"); +const getUserQuery = query(async () => { + // ... Fetches user data. + return { name: "John" }; +}, "user"); -function Posts() { - const posts = createAsync(() => getPosts()); +function UserProfile() { + const user = createAsync(() => getUserQuery()); - function refetchPosts() { - revalidate(getPosts.key); + function refreshUser() { + revalidate(getUserQuery.key); } return ( <div> - <button onClick={refetchPosts}>Refetch posts</button> - <ul> - <For each={posts()}>{(post) => <li>{post.title}</li>}</For> - </ul> + <button onClick={refreshUser}>Refresh</button> + <p>{user()?.name}</p> </div> ); } ``` -## Parameters +### Revalidating multiple queries + +```tsx +import { query, revalidate } from "@solidjs/router"; + +const getUsersQuery = query(async () => { + // ... Fetches users. +}, "users"); + +const getPostsQuery = query(async () => { + // ... Fetches posts. +}, "posts"); + +function refreshAll() { + revalidate([getUsersQuery.key, getPostsQuery.key]); +} +``` + +## Related -- `key`: The query key or an array of query keys to be revalidated. -- `force` (optional): A boolean that indicates whether to delete the existing cached value of the queries. - Note that this cache is solely for de-duplication purposes. - Therefore, deleting the cache only affects de-duplication. - For more information on how `query` works, refer to [the `query` documentation](/solid-router/reference/data-apis/query). - The default value is `true`. +- [`query`](/solid-router/reference/data-apis/query) +- [`createAsync`](/solid-router/reference/data-apis/create-async) 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..68cd27232 100644 --- a/src/routes/solid-router/reference/data-apis/use-action.mdx +++ b/src/routes/solid-router/reference/data-apis/use-action.mdx @@ -1,27 +1,64 @@ --- title: useAction +use_cases: >- + programmatic forms, client-side mutations, imperative actions, non-form + submissions +tags: + - actions + - mutations + - client + - imperative + - programmatic +version: "1.0" +description: >- + Invoke actions programmatically without forms using useAction. Perfect for + client-side mutations and imperative updates. --- -`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<T extends Array<any>, U, V>( + action: Action<T, U, V> +): (...args: Parameters<Action<T, U, V>>) => Promise<NarrowResponse<U>>; ``` -:::note -`useAction` requires client-side JavaScript and is not progressively enhanceable. -::: - ## Parameters -- `action`: The action to be invoked. +### `action` + +- **Type:** `Action<T, U, V>` +- **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 <button onClick={() => likePost(props.postId)}>Like</button>; +} +``` 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..ff9bfec65 100644 --- a/src/routes/solid-router/reference/data-apis/use-submission.mdx +++ b/src/routes/solid-router/reference/data-apis/use-submission.mdx @@ -1,161 +1,142 @@ --- title: useSubmission +use_cases: >- + form feedback, pending states, optimistic updates, error handling, single + submission tracking +tags: + - forms + - submissions + - pending + - optimistic + - errors + - feedback +version: "1.0" +description: >- + Track form submission states with useSubmission. Handle pending feedback, + optimistic updates, and errors for single forms. --- -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 ( - <form action={postNameAction} method="post"> - <input type="text" name="name" /> - <button type="submit"> - {submission.pending ? "Adding..." : "Add"} - </button> - </form> - ) -} +## Type + +```tsx +function useSubmission<T extends Array<any>, U, V>( + fn: Action<T, U, V>, + filter?: (input: V) => boolean +): Submission<T, NarrowResponse<U>> | 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<T, U, V>` +- **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 ( - <form action={postNameAction} method="post"> - <input type="text" name="name" /> - <button type="submit"> - {submission.pending ? "Adding..." : "Add"} - </button> - </form> - ) -} -``` +### `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 ( - <> - <Show when={submission.input?.[0].get("name")}> - {(name) => <div>Optimistic: {name() as string}</div>} - </Show> - - <Show when={submission.result?.name}> - {(name) => <div>Result: {name()}</div>} - </Show> - - <form method="post" action={sendData}> - <input type="text" name="name" required /> - <button type="submit" disabled={submission.pending}> - {submission.pending ? "Submitting" : "Submit"} - </button> - </form> - </> - ) -} -``` +`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 ( - <> - <Show when={submission.input?.[0].get("name")}> - {(name) => <div>Optimistic: {name()}</div>} - </Show> - - <Show when={submission.result?.name}> - {(name) => <div>Result: {name()}</div>} - </Show> - - <form method="post" action={sendData}> - <input type="text" name="name" required /> - <button type="submit" disabled={submission.pending}> - {submission.pending ? "Submitting" : "Submit"} - </button> - </form> - </> - ) -} -``` +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 ( + <form action={addTodoAction} method="post"> + <input name="name" /> + <button type="submit">{submission.pending ? "Adding..." : "Add"}</button> + <Show when={!submission.result?.ok}> + <div> + <p>{submission.result.message}</p> + <button onClick={() => submission.clear()}>Clear</button> + <button onClick={() => submission.retry()}>Retry</button> + </div> + </Show> + </form> + ); +} +``` + +### Filtering submissions + +```tsx import { useSubmission } from "@solidjs/router"; -function Component() { - const submission = useSubmission(postNameAction); - - return ( - <> - <Show when={submission.error}> - {(error) => ( - <div> - <p>Error: {error.message}</p> - <button onClick={() => submission.clear()}> - Clear - </button> - <button onClick={async () => submission.retry()}> - Retry - </button> - </div> - )} - </Show> - - <form method="post" action={sendData}> - <input type="text" name="name" required /> - <button type="submit" disabled={submission.pending}> - {submission.pending ? "Submitting" : "Submit"} - </button> - </form> - </> - ) +const addTodoAction = action(async (formData: FormData) => { + // ... Sends the todo data to the server. +}, "addTodo"); + +function LatestTodo() { + const latestValidSubmission = useSubmission( + addTodoAction, + ([formData]: [FormData]) => { + const name = formData.get("name")?.toString(); + return name && name.length > 2; + } + ); + + return <p>Latest valid submission: {latestValidSubmission.result}</p>; } ``` 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..96cf940ed 100644 --- a/src/routes/solid-router/reference/data-apis/use-submissions.mdx +++ b/src/routes/solid-router/reference/data-apis/use-submissions.mdx @@ -1,190 +1,161 @@ --- title: useSubmissions +use_cases: >- + multiple forms, submission history, batch operations, optimistic lists, error + recovery +tags: + - forms + - submissions + - multiple + - history + - optimistic + - batch +version: "1.0" +description: >- + Manage multiple form submissions simultaneously with useSubmissions. Track + history, handle errors, and show optimistic updates. --- -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 ( - <form method="post" action={postNameAction}> - <ul> - <For each={Array.from(submissions.entries())}> - {([attemptIndex, data]) => ( - <Show when={data.result}> - { result => ( - <li> - Backend {attemptIndex}: {result.name} - </li> - )} - </Show> - </> - )} - </For> - </ul> - <input name="name" type="text" /> - <button type="submit">{submissions.pending ? "sending" : "send"}</button> - </form> - ) -} +## Type + +```tsx +function useSubmissions<T extends Array<any>, U, V>( + fn: Action<T, U, V>, + filter?: (input: V) => boolean +): Submission<T, NarrowResponse<U>>[] & { + 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<T, U, V>` +- **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 ( - <form method="post" action={postNameAction}> - <ul> - <For each={Array.from(submissions.entries())}> - {([attemptIndex, data]) => ( - <Show when={data.result}> - { result => ( - <li> - Backend {attemptIndex}: {result.name} - </li> - )} - </Show> - </> - )} - </For> - </ul> - <input name="name" type="text" /> - <button type="submit">{submissions.pending ? "sending" : "send"}</button> - </form> - ) -} -``` +### `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 ( - <form method="post" action={postNameAction}> - <ul> - <For each={Array.from(submissions.entries())}> - {([attemptIndex, data]) => ( - <Show when={data.input[0].entries().next()}> - {(input) => { - const name = (input().value as [string, string])[1] - - return ( - <li>Optimistic: {name}</li> - )}} - </Show> - )} - </For> - </ul> - <input name="name" type="text" /> - <button type="submit">{submissions.pending ? "sending" : "send"}</button> - </form> - ) -} -``` +`useSubmissions` returns a reactive array of submission objects. +Each submission object has the following properties: -```tsx tab title="JavaScript" {6,13-20} -// component.jsx -import { Show } from "solid-js"; -import { useSubmissions } from "@solidjs/router"; +### `input` -function Component() { - const submissions = useSubmissions(postNameAction); - - return ( - <form method="post" action={postNameAction}> - <ul> - <For each={Array.from(submissions.entries())}> - {([attemptIndex, data]) => ( - <Show when={data.input[0].entries().next()}> - {(input) => { - const name = input().value[1] - - return ( - <li>Optimistic: {name}</li> - )}} - </Show> - )} - </For> - </ul> - <input name="name" type="text" /> - <button type="submit">{submissions.pending ? "sending" : "send"}</button> - </form> - ) -} -``` +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 ( + <div> + <form action={addTodoAction} method="post"> + <input name="name" /> + <button type="submit">Add</button> + </form> + <For each={submissions}> + {(submission) => ( + <div> + <span>Adding "{submission.input[0].get("name")?.toString()}"</span> + <Show when={submission.pending}> + <span> (pending...)</span> + </Show> + <Show when={submission.result?.ok}> + <span> (completed)</span> + </Show> + <Show when={!submission.result?.ok}> + <span>{` (Error: ${submission.result?.message})`}</span> + <button onClick={() => submission.retry()}>Retry</button> + </Show> + </div> + )} + </For> + </div> + ); +} +``` -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 ( - <form method="post" action={postNameAction}> - <ul> - <For each={Array.from(submissions.entries())}> - {([attempt, data]) => ( - <Show when={data.error}> - <li> - <p>Backend {attempt}: {data.error.message}</p> - <button onClick={() => data.retry()}>retry</button> - <button onClick={() => data.clear()}>clear</button> - </li> - </Show> - )} - </For> - </ul> - <input name="name" type="text" required autocomplete="off" /> - <button type="submit">{submissions.pending ? "sending" : "send"}</button> - </form> - ) +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 ( + <div> + <p>Failed submissions:</p> + <For each={failedSubmissions}> + {(submission) => ( + <div> + <span>{submission.input[0].get("name")?.toString()}</span> + <button onClick={() => submission.retry()}>Retry</button> + </div> + )} + </For> + </div> + ); } ``` diff --git a/src/routes/solid-router/reference/preload-functions/preload.mdx b/src/routes/solid-router/reference/preload-functions/preload.mdx index 71f27bc60..aea659caa 100644 --- a/src/routes/solid-router/reference/preload-functions/preload.mdx +++ b/src/routes/solid-router/reference/preload-functions/preload.mdx @@ -1,46 +1,106 @@ --- -title: Preload +title: preload +use_cases: >- + route preloading, hover prefetch, parallel loading, performance optimization, + lazy routes, code splitting +tags: + - preload + - performance + - routing + - prefetch + - lazy + - optimization +version: "1.0" +description: >- + Preload route data and code in parallel to eliminate waterfalls. Enable hover + prefetching for instant page transitions. --- -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<T = unknown> = (args: RoutePreloadFuncArgs) => T; -// Pass it in the route definition -<Route path="/users/:id" component={User} preload={preloadUser} />; +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. <ul><li>"initial" - the route is being initially shown (ie page load)</li><li>"native" - navigate originated from the browser (eg back/forward)</li><li>"navigate" - navigate originated from the router (eg call to navigate or anchor clicked)</li><li>"preload" - not navigating, just preloading (eg link hover)</li></ul> | +## 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 -<Route path="/users/:id" component={User} preload={preloadUser} />; -``` +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 <div>{product()?.title}</div>; +} + +function preloadData({ params }) { + getProductQuery(params.id); +} + +function ProductRoutes() { + return ( + <Route path="/products/:id" component={ProductPage} preload={preloadData} /> + ); +} +``` diff --git a/src/routes/solid-router/reference/primitives/use-before-leave.mdx b/src/routes/solid-router/reference/primitives/use-before-leave.mdx index 784ea506d..3d0bf20ab 100644 --- a/src/routes/solid-router/reference/primitives/use-before-leave.mdx +++ b/src/routes/solid-router/reference/primitives/use-before-leave.mdx @@ -1,5 +1,19 @@ --- title: useBeforeLeave +use_cases: >- + unsaved forms, exit confirmations, data loss prevention, user prompts before + navigation, dirty state handling +tags: + - navigation + - forms + - confirmation + - prevent + - prompt + - leave +version: "1.0" +description: >- + Prevent route navigation with useBeforeLeave - prompt users before leaving + with unsaved changes, handle exit confirmations in SolidJS. --- `useBeforeLeave` takes a function that will be called prior to leaving a route. diff --git a/src/routes/solid-router/reference/primitives/use-current-matches.mdx b/src/routes/solid-router/reference/primitives/use-current-matches.mdx index b0674c361..4ccd4b2e1 100644 --- a/src/routes/solid-router/reference/primitives/use-current-matches.mdx +++ b/src/routes/solid-router/reference/primitives/use-current-matches.mdx @@ -1,5 +1,18 @@ --- title: useCurrentMatches +use_cases: >- + breadcrumbs, route metadata, nested routes, navigation menus, route info + extraction +tags: + - routes + - breadcrumbs + - matches + - navigation + - metadata +version: "1.0" +description: >- + Access all matched route information with useCurrentMatches - build + breadcrumbs, extract route metadata, and navigate nested routes. --- `useCurrentMatches` returns all the matches for the current matched route. Useful for getting all the route information. diff --git a/src/routes/solid-router/reference/primitives/use-is-routing.mdx b/src/routes/solid-router/reference/primitives/use-is-routing.mdx index 2913b8bc2..37c4e08c6 100644 --- a/src/routes/solid-router/reference/primitives/use-is-routing.mdx +++ b/src/routes/solid-router/reference/primitives/use-is-routing.mdx @@ -1,16 +1,64 @@ --- title: useIsRouting +use_cases: >- + loading states, transition indicators, pending ui, stale content, concurrent + rendering feedback +tags: + - loading + - transition + - pending + - state + - ui +version: "1.0" +description: >- + Track route transitions with useIsRouting - display loading states, pending + UI, and transition feedback during navigation in SolidJS. --- -Retrieves a signal that indicates whether the route is currently in a transition. -This is useful for showing a stale or pending state when the route resolution is suspended state during concurrent rendering. +The `useIsRouting` function is a utility for detecting when the router is processing a route transition. -```js -const isRouting = useIsRouting(); +## Import -return ( - <div classList={{ "grey-out": isRouting() }}> - <MyAwesomeContent /> - </div> -); +```ts +import { useIsRouting } from "@solidjs/router"; ``` + +## Type + +```ts +const useIsRouting: () => () => boolean; +``` + +## Parameters + +None. + +## Return value + +**Type:** `() => boolean` + +An accessor function that returns `true` during route transitions and `false` otherwise. + +## Examples + +### Route transition indicator + +```tsx +import { useIsRouting } from "@solidjs/router"; + +function App() { + const isRouting = useIsRouting(); + + return ( + <> + {isRouting() && <div class="loading-bar" />} + <MyContent /> + </> + ); +} +``` + +## Related + +- [`<Router>`](/solid-router/reference/components/router) +- [`useNavigate`](/solid-router/reference/primitives/use-navigate) diff --git a/src/routes/solid-router/reference/primitives/use-location.mdx b/src/routes/solid-router/reference/primitives/use-location.mdx index 8da0c0ecf..6ce9b86df 100644 --- a/src/routes/solid-router/reference/primitives/use-location.mdx +++ b/src/routes/solid-router/reference/primitives/use-location.mdx @@ -1,19 +1,111 @@ --- title: useLocation +use_cases: >- + current url tracking, query parameters, pathname parsing, hash navigation, + location state access +tags: + - location + - url + - pathname + - query + - hash + - state +version: "1.0" +description: >- + Access reactive URL information with useLocation - track pathname, query + strings, hash, and navigation state in your SolidJS app. --- -Retrieves reactive `location` object useful for getting things like `pathname` +The `useLocation` function provides information about the current URL, including pathname, query strings, hash, and navigation state. -```js -const location = useLocation(); +## Import -const pathname = createMemo(() => parsePath(location.pathname)); +```ts +import { useLocation } from "@solidjs/router"; ``` -| attribute | type | description | -| ---------- | ------ | ----------------------------------------------------------------------------------------- | -| `pathname` | string | The pathname part of the URL, without the query string. | -| `search` | string | The query string part of the URL. | -| `hash` | string | The hash part of the URL, including the `#`. | -| `state` | any | Custom state passed from [`useNavigate`](/solid-router/reference/primitives/use-navigate) | -| `query` | object | Returns a store-like object containing all the query parameters of the URL. | +## Type + +```ts +const useLocation: <S = unknown>() => Location<S>; + +interface Location<S = unknown> extends Path { + query: SearchParams; + state: Readonly<Partial<S>> | null; +} + +interface Path { + pathname: string; + search: string; + hash: string; +} +``` + +## Parameters + +None. + +## Return value + +`useLocation` returns a reactive `Location` object containing the current URL information. + +The `Location` object contains: + +### `pathname` + +**Type:** `string` + +The path portion of the URL, beginning with a `/` and excluding the query string and hash. + +### `search` + +**Type:** `string` + +The query string portion of the URL, including the leading `?` character if a parameter exists. + +### `hash` + +**Type:** `string` + +The hash fragment of the URL, including the leading `#` character if a hash exists. + +### `state` + +**Type:** `Readonly<Partial<S>> | null` + +Custom state passed from [`useNavigate`](/solid-router/reference/primitives/use-navigate). + +### `query` + +**Type:** `SearchParams` + +A reactive object containing the parsed query parameters from the URL. + +## Examples + +### Basic usage + +```tsx +import { useLocation } from "@solidjs/router"; + +function ProductFilter() { + const location = useLocation(); + + const category = () => location.query.category || "all"; + const page = () => location.query.page || "1"; + + return ( + <div> + <p> + Filtering by: {category()}, Page {page()} + </p> + </div> + ); +} +``` + +## Related + +- [`useNavigate`](/solid-router/reference/primitives/use-navigate) +- [`useParams`](/solid-router/reference/primitives/use-params) +- [`useSearchParams`](/solid-router/reference/primitives/use-search-params) diff --git a/src/routes/solid-router/reference/primitives/use-match.mdx b/src/routes/solid-router/reference/primitives/use-match.mdx index c0391d906..3b0446131 100644 --- a/src/routes/solid-router/reference/primitives/use-match.mdx +++ b/src/routes/solid-router/reference/primitives/use-match.mdx @@ -1,47 +1,152 @@ --- title: useMatch +use_cases: >- + active links, navigation highlighting, conditional rendering, path matching, + menu items +tags: + - match + - active + - navigation + - path + - conditional + - links +version: "1.0" +description: >- + Check if paths match current route with useMatch - create active navigation + links, conditional rendering based on route matching. --- -`useMatch` takes an accessor that returns the path and creates a Memo that returns match information if the current path matches the provided path. -Useful for determining if a given path matches the current route. +The `useMatch` function checks whether the current path matches a provided path pattern. -```js -const match = useMatch(() => props.href); +## Import -return <div classList={{ active: Boolean(match()) }} />; +```ts +import { useMatch } from "@solidjs/router"; ``` -As a second parameter, `useMatch` also accepts a group of `MatchFilters`. -These filteres allow for a more granular check. +## Type -The filters are the same used by the `<Router>` itself and they accept either a an array of strings, or a regular expression. Additionally, there's a `boolean` option to match a route only if it has, or doesn't have, the HTML extension. +```ts +const useMatch: <S extends string>( + path: () => S, + matchFilters?: MatchFilters<S> +): Accessor<PathMatch | undefined>; -```js -const filters: MatchFilters = { - parent: ["mom", "dad"] - id: /^\d+$/, - withHtmlExtension: (v: string) => v.length > 5 && v.endsWith(".html") +type MatchFilters<P extends string | readonly string[] = any> = P extends string + ? { [K in PathParams<P>[number]]?: MatchFilter } + : Record<string, MatchFilter>; + +interface PathMatch { + params: Params; + path: string; +} +``` + +## Parameters + +### `path` + +- **Type:** `() => S` +- **Required:** Yes + +An accessor function that returns the path pattern to match against the current route. +Uses the same syntax as the `path` prop in the [`<Route>`](/solid-router/reference/components/route) component. +Supports [path parameters](/solid-router/concepts/path-parameters), [optional parameters](/solid-router/concepts/path-parameters#optional-parameters), and [wildcard parameters](/solid-router/concepts/path-parameters#wildcard-routes). + +### `filters` + +- **Type:** `MatchFilters<S>` +- **Required:** No + +An object where keys correspond to route parameter names and values define match filters. +Each filter can be: + +- An array of allowed strings +- A regular expression pattern +- A function that receives the parameter value as a string and returns true if the parameter should match + +## Return value + +`useMatch` returns a memo containing a `PathMatch` object when the path matches, or `undefined` when there's no match. + +The `PathMatch` object contains: + +### `params` + +- **Type:** `Record<string, string>` + +An object containing the matched path parameters as key-value pairs. + +### `path` + +- **Type:** `string` + +The matched path. + +## Examples + +### Basic usage + +```tsx +import { useMatch } from "@solidjs/router"; +import { type JSXElement } from "solid-js"; + +type NavLinkProps = { + href: string; + children: JSXElement; }; + +function NavLink(props: NavLinkProps) { + const match = useMatch(() => props.href); + + return ( + <a href={props.href} classList={{ active: Boolean(match()) }}> + {props.children} + </a> + ); +} ``` -Finally, any parameter can be determined optional by adding a `?` at the end of the parameter name. +### With filters -```js - const isReference = useMatch(() => "/:project?/reference/*?", { - project: ["solid-router", "solid-meta", "solid-start"], +```tsx +import { useMatch } from "@solidjs/router"; +import { Show } from "solid-js"; + +function BlogPost() { + const match = useMatch(() => "/:lang?/blog/:slug", { + lang: ["en", "es", "fr"], + slug: /^[a-z0-9-]+$/, // Only allow lowercase letters, numbers, and hyphens }); + + const lang = () => match()?.params.lang || "en"; + + return ( + <Show when={match()}> + <article lang={lang()}> + <p>Blog slug: {match()?.params.slug}</p> + </article> + </Show> + ); +} ``` -The check above will match: +### With custom filter functions + +```tsx +import { useMatch } from "@solidjs/router"; + +function FileInfo() { + const match = useMatch(() => "/files/:type/:name", { + type: ["images", "documents", "videos"], + name: (name) => name.length > 5 && name.endsWith(".html"), + }); + + return <div>File: {match()?.params.name}</div>; +} +``` -```text -/reference -/solid-router/reference -/solid-meta/reference -/solid-start/reference +## Related -/reference/... -/solid-router/reference/... -/solid-meta/reference/... -/solid-start/reference/... -``` \ No newline at end of file +- [`useParams`](/solid-router/reference/primitives/use-params) +- [`useLocation`](/solid-router/reference/primitives/use-location) diff --git a/src/routes/solid-router/reference/primitives/use-navigate.mdx b/src/routes/solid-router/reference/primitives/use-navigate.mdx index 82988990a..4cf41a210 100644 --- a/src/routes/solid-router/reference/primitives/use-navigate.mdx +++ b/src/routes/solid-router/reference/primitives/use-navigate.mdx @@ -1,26 +1,167 @@ --- title: useNavigate +use_cases: >- + programmatic navigation, redirects, auth flows, form submissions, history + manipulation +tags: + - navigate + - redirect + - programmatic + - history + - state +version: "1.0" +description: >- + Navigate programmatically with useNavigate - redirect users, handle auth + flows, and control navigation with replace and scroll options. --- -Retrieves the method which accepts a path to navigate to and an optional object with the following options: +The `useNavigate` function provides a function for programmatically navigating to a new route. -- resolve (_boolean_, default `true`): resolve the path against the current route -- replace (_boolean_, default `false`): replace the history entry -- scroll (_boolean_, default `true`): scroll to top after navigation -- state (_any_, default `undefined`): pass custom state to `location.state` +## Import + +```ts +import { useNavigate } from "@solidjs/router"; +``` + +## Type + +```ts +interface NavigateOptions<S = unknown> { + resolve: boolean; + replace: boolean; + scroll: boolean; + state: S; +} + +function useNavigate(): ( + to: string, + options?: Partial<NavigateOptions> +) => void; +function useNavigate(delta: number): void; +``` + +## Parameters + +`useNavigate` takes no arguments. + +## Return value + +- **Type:** `(to: string | number, options?: NavigateOptions) => void | (delta: number) => void` + +Returns a function that accepts two arguments: + +### `to` + +- **Type:** `string | number` +- **Required:** Yes + +The target destination. + +- `string`: + A path to navigate to. +- `number`: + A history delta (e.g., `-1` for back, `1` for forward). + If provided, the `options` argument is ignored. + +### `options` + +- **Type:** `NavigateOptions` +- **Required:** No + +Configuration object for the navigation. + +#### `resolve` + +- **Type:** `boolean` +- **Default:** `true` + +Resolves the path relative to the current route. +If `false`, the path is resolved against the root (`/`). + +If `to` is a query-only string (e.g., `?sort=asc`), this defaults to `false` to preserve the current pathname. + +#### `replace` + +- **Type**: `boolean` +- **Default**: `false` + +Replaces the current history entry instead of adding a new one. +Used for redirects or state updates to prevent the user from navigating back to the previous state. + +#### `scroll` + +- **Type**: `boolean` +- **Default**: `true` + +Scrolls the window to the top after navigation. + +- `true`: + Scrolls to the top or to the element matching the hash. +- `false`: + Maintains the current scroll position (unless a hash matches). + +#### `state` + +- **Type**: `any` +- **Default**: `undefined` + +Arbitrary state stored in `history.state`. +This value is accessible via `useLocation().state`. + +State is serialized using the [structured clone algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm), which supports most built-in types but not functions or DOM nodes. + +## Examples + +### Basic usage + +```tsx +import { useNavigate } from "@solidjs/router"; + +const navigate = useNavigate(); + +navigate("/users/123"); +``` + +### With `replace` + +```tsx +import { useNavigate } from "@solidjs/router"; + +const navigate = useNavigate(); + +// Redirect (replace history) +function login() { + navigate("/dashboard", { replace: true }); +} +``` + +### With `delta` + +```tsx +import { useNavigate } from "@solidjs/router"; -```js const navigate = useNavigate(); -if (unauthorized) { - navigate("/login", { replace: true }); +// Go back one page +function goBack() { + navigate(-1); } ``` -If you are inside of a query, action or cache (deprecated) function you will instead want to use [redirect](/solid-router/reference/response-helpers/redirect) or [reload](/solid-router/reference/response-helpers/reload). +### With `state` + +```tsx +import { useNavigate } from "@solidjs/router"; + +const navigate = useNavigate(); + +// Pass custom state +navigate("/checkout", { + state: { from: "cart", total: 100 }, +}); +``` + +## Related -:::note - The state is serialized using the [structured clone - algorithm](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) - which does not support all object types. -::: +- [useLocation](/solid-router/reference/primitives/use-location) +- [redirect](/solid-router/reference/response-helpers/redirect) diff --git a/src/routes/solid-router/reference/primitives/use-params.mdx b/src/routes/solid-router/reference/primitives/use-params.mdx index c7291ae74..46c0bad05 100644 --- a/src/routes/solid-router/reference/primitives/use-params.mdx +++ b/src/routes/solid-router/reference/primitives/use-params.mdx @@ -1,13 +1,63 @@ --- title: useParams +use_cases: "dynamic routes, user profiles, product pages, id-based content, url parameters" +tags: + - params + - dynamic + - routes + - parameters + - reactive +version: "1.0" +description: >- + Access route parameters reactively with useParams - extract dynamic segments + from URLs for user profiles, products, and ID-based pages. --- -`useParams` retrieves a reactive object similar to a store. -It contains the current route's path parameters as defined in the Route. +The `useParams` function reads the path parameters of the current route. -```js -const params = useParams(); +## Import -// Route path: /user/:id => /user/123 -console.log(params.id); // 123 +```ts +import { useParams } from "@solidjs/router"; ``` + +## Type + +```ts +function useParams<T extends Record<string, string>>(): T; +``` + +## Parameters + +`useParams` takes no arguments. + +## Return value + +- **Type**: `T` + +`useParams` returns a reactive object where keys match the dynamic segments defined in the route path. +Accessing a property within a tracking scope registers a dependency, causing the computation to re-run when the parameter changes. + +## Examples + +### Basic usage + +```ts +import { createMemo } from "solid-js"; +import { useParams } from "@solidjs/router"; + +// Rendered via <Route path="/users/:id" component={UserPage} /> +function UserPage() { + const params = useParams(); + + // Derived value updates when the route parameter changes. + const title = createMemo(() => `Profile for ${params.id}`); + + return <h1>{title()}</h1>; +} +``` + +## Related + +- [useLocation](/solid-router/reference/primitives/use-location) +- [useSearchParams](/solid-router/reference/primitives/use-search-params) diff --git a/src/routes/solid-router/reference/primitives/use-preload-route.mdx b/src/routes/solid-router/reference/primitives/use-preload-route.mdx index 8534db781..30192ede2 100644 --- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx +++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx @@ -1,11 +1,84 @@ --- title: usePreloadRoute +use_cases: >- + performance optimization, manual preloading, predictive navigation, + prefetching routes +tags: + - preload + - performance + - optimization + - prefetch + - manual +version: "1.0" +description: >- + Manually preload routes with usePreloadRoute - optimize performance by + prefetching route data before navigation in your SolidJS app. --- -`usePreloadRoute` returns a function that can be used to preload a route manually. This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API. +The `usePreloadRoute` function is a utility for manually preloading a route. -```js -const preload = usePreloadRoute(); +## Import -preload(`/users/settings`, { preloadData: true }); +```ts +import { usePreloadRoute } from "@solidjs/router"; ``` + +## Type + +```ts +const usePreloadRoute: () => ( + url: string | URL, + options?: { preloadData?: boolean } +) => void; +``` + +## Parameters + +### `url` + +**Type:** `string | URL` +**Required:** Yes + +The route path to preload. +Accepts either a `string` path or a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object. + +### `options` + +- **Type:** `{ preloadData?: boolean }` +- **Required:** No + +A configuration object with the following properties: + +#### `preloadData` + +- **Type:** `boolean` +- **Default:** `false` + +When `true`, triggers the route's data loading in addition to preloading the route itself. + +## Return value + +None. + +## Examples + +### Basic usage + +```tsx +import { usePreloadRoute } from "@solidjs/router"; + +function SettingsButton() { + const preload = usePreloadRoute(); + + return ( + <button onClick={() => preload("/users/settings", { preloadData: true })}> + Load settings + </button> + ); +} +``` + +## Related + +- [`<A>`](/solid-router/reference/components/a) +- [`preload`](/solid-router/reference/preload-functions/preload) diff --git a/src/routes/solid-router/reference/primitives/use-resolved-path.mdx b/src/routes/solid-router/reference/primitives/use-resolved-path.mdx index edf2d2aeb..6c9d5cbcb 100644 --- a/src/routes/solid-router/reference/primitives/use-resolved-path.mdx +++ b/src/routes/solid-router/reference/primitives/use-resolved-path.mdx @@ -1,37 +1,55 @@ --- title: useResolvedPath +use_cases: >- + modular routing, nested routers, relative paths, dynamic base paths, component + isolation +tags: + - path + - modular + - nested + - routing + - base + - resolved +version: "1.0" +description: >- + Resolve relative paths with useResolvedPath - build modular routers, handle + nested routes, and create isolated routing components. --- `useResolvedPath` retrieves a signal\<string\>. It contains the current resolved path as defined in the Route. ```js -const path = useResolvedPath(() => ''); +const path = useResolvedPath(() => ""); -// Parent Route path: /user/* +// Parent Route path: /user/* console.log(path()); // /user -const path = useResolvedPath(() => 'a/b/c'); +const path = useResolvedPath(() => "a/b/c"); -// Parent Route path: /user/* +// Parent Route path: /user/* console.log(path()); // /user/a/b/c -const path = useResolvedPath(() => '/a/b/c'); // Note: / +const path = useResolvedPath(() => "/a/b/c"); // Note: / -// Parent Route path: /user/* +// Parent Route path: /user/* console.log(path()); // a/b/c ``` Useful for making modular routers ```js -const parentRoutePath = useResolvedPath(() => ''); - -return <> - <h1>Module component layer</h1> - <Router base={parentRoutePath()}> // Modular magic - <Route path="/" component={() => <div>Index</div>}/> - <Route path="/a" component={() => <div>AComponent</div>}/> - </Router> -</> +const parentRoutePath = useResolvedPath(() => ""); + +return ( + <> + <h1>Module component layer</h1> + <Router base={parentRoutePath()}> + {" "} + // Modular magic + <Route path="/" component={() => <div>Index</div>} /> + <Route path="/a" component={() => <div>AComponent</div>} /> + </Router> + </> +); ``` diff --git a/src/routes/solid-router/reference/primitives/use-search-params.mdx b/src/routes/solid-router/reference/primitives/use-search-params.mdx index 7b26ed638..224a6f49b 100644 --- a/src/routes/solid-router/reference/primitives/use-search-params.mdx +++ b/src/routes/solid-router/reference/primitives/use-search-params.mdx @@ -1,29 +1,79 @@ --- title: useSearchParams +use_cases: "pagination, filters, search forms, url state management, query string updates" +tags: + - search + - query + - params + - pagination + - filters + - url +version: "1.0" +description: >- + Manage URL query parameters with useSearchParams - handle pagination, filters, + and search state directly in the URL query string. --- -Retrieves a tuple containing a reactive object to read the current location's query parameters and a method to update them. -The object is a proxy so you must access properties to subscribe to reactive updates. -Note values will be strings and property names will retain their casing. - -The setter method accepts an object as an input, and its key-value pairs will be merged into the existing query string. -If a value is `''`, `undefined` or `null`, the corresponding key will be omitted from the resulting query string. -The updates behave like navigation and will not scroll the page to the top. -Additionally, the setter can take an optional second parameter, the same as `navigate`, to control the navigation behavior and auto-scrolling, which are disabled by default. - -```js -const [searchParams, setSearchParams] = useSearchParams(); - -return ( - <div> - <span>Page: {searchParams.page}</span> - <button - onClick={() => - setSearchParams({ page: (parseInt(searchParams.page) || 0) + 1 }) - } - > - Next Page - </button> - </div> -); +The `useSearchParams` function reads the URL query parameters for the current route and provides a function to update them. + +## Import + +```ts +import { useSearchParams } from "@solidjs/router"; +``` + +## Type + +```ts +function useSearchParams<T extends Record<string, string | string[]>>(): [ + Partial<T>, + (params: SetSearchParams, options?: Partial<NavigateOptions>) => void, +]; ``` + +## Parameters + +`useSearchParams` takes no arguments. + +## Return value + +- **Type:** `[ Partial<T>, (params: SetSearchParams, options?: Partial<NavigateOptions>) => void ]` + +`useSearchParams` returns an array with two items. + +The first item is a reactive object containing the current query parameters. +Accessing a property within a tracking scope registers a dependency, causing the computation to re-run when the parameter changes. +Values are always strings. + +The second item is a function that updates the query string. +It merges the object provided as its first argument with the current query parameters. +Passing an empty string (`""`), an empty array (`[]`), `undefined`, or `null` as a value removes the key. +It accepts the same options as [`useNavigate`](/solid-router/reference/primitives/use-navigate) as the second parameter. +By default, the `resolve` and `scroll` options are set to `false`. + +## Examples + +### Basic usage + +```tsx +import { useSearchParams } from "@solidjs/router"; + +function Paginator() { + const [params, setParams] = useSearchParams(); + + const page = () => Number(params.page || "1"); + + return ( + <div> + <span>Current Page: {page()}</span> + <button onClick={() => setParams({ page: page() + 1 })}>Next</button> + </div> + ); +} +``` + +## Related + +- [`useParams`](/solid-router/reference/primitives/use-params) +- [`useLocation`](/solid-router/reference/primitives/use-location) +- [`useNavigate`](/solid-router/reference/primitives/use-navigate) diff --git a/src/routes/solid-router/reference/response-helpers/json.mdx b/src/routes/solid-router/reference/response-helpers/json.mdx index c5643d4d2..a6bf91a8c 100644 --- a/src/routes/solid-router/reference/response-helpers/json.mdx +++ b/src/routes/solid-router/reference/response-helpers/json.mdx @@ -1,30 +1,140 @@ --- title: json +use_cases: >- + returning api data, action responses, cache control, revalidation strategies, + server actions +tags: + - json + - api + - actions + - queries + - revalidation + - response +version: "1.0" +description: >- + Return JSON data from actions with query revalidation control. Configure how + route data updates after mutations for optimal performance. --- -Returns JSON data from an action while also providing options for controlling revalidation of cache data on the route. +The `json` function returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that contains the provided data. +It is intended for sending JSON data from a [query](/solid-router/reference/data-apis/query) or [action](/solid-router/concepts/actions) while also allowing configuration of query revalidation. -```ts title="/actions/get-completed-todos.ts" {7} -import { action, json } from "@solidjs/router"; -import { fetchTodo } from "../fetchers"; +This works both in client and server (e.g., using a server function) environments. -const getCompletedTodos = action(async () => { - const completedTodos = await fetchTodo({ status: 'complete' }); +## Import - return json(completedTodos, { revalidate: getTodo.keyFor(id) }); -}); +```ts +import { json } from "@solidjs/router"; ``` -Also read [action](/solid-router/reference/data-apis/action) and [revalidate](/solid-router/reference/response-helpers/revalidate). +## Type -## Type Signature +```ts +function json<T>( + data: T, + init: { + revalidate?: string | string[]; + headers?: HeadersInit; + status?: number; + statusText?: string; + } = {} +): CustomResponse<T>; +``` + +## Parameters + +### `data` + +- **Type:** `T` +- **Required:** Yes + +The data to be serialized as JSON in the response body. +It must be a value that can be serialized with [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). + +### `init` + +- **Type:** `{ revalidate?: string | string[]; headers?: HeadersInit; status?: number; statusText?: string; }` +- **Required:** No + +An optional configuration object with the following properties: + +#### `revalidate` + +- **Type:** `string | string[]` +- **Required:** No + +A query key or an array of query keys to revalidate. +Passing an empty array (`[]`) disables query revalidation entirely. + +#### `headers` + +- **Type:** `HeadersInit` +- **Required:** No + +An object containing any headers to be sent with the response. + +#### `status` -```typescript -interface ResponseOptions & Omit<ResponseInit, "body"> { - revalidate?: string | string[]; +- **Type:** `number` +- **Required:** No + +The HTTP status code of the response. +Defaults to [`200 OK`](http://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200). + +#### `statusText` + +- **Type:** `string` +- **Required:** No + +The status text associated with the status code. + +## Examples + +### Invalidating Data After a Mutation + +```tsx +import { For } from "solid-js"; +import { query, action, json, createAsync } from "@solidjs/router"; + +const getCurrentUserQuery = query(async () => { + return await fetch("/api/me").then((response) => response.json()); +}, "currentUser"); + +const getPostsQuery = query(async () => { + return await fetch("/api/posts").then((response) => response.json()); +}, "posts"); + +const createPostAction = action(async (formData: FormData) => { + const title = formData.get("title")?.toString(); + const newPost = await fetch("/api/posts", { + method: "POST", + body: JSON.stringify({ title }), + }).then((response) => response.json()); + + // Only revalidate the "posts" query. + return json(newPost, { revalidate: "posts" }); +}, "createPost"); + +function Posts() { + const currentUser = createAsync(() => getCurrentUserQuery()); + const posts = createAsync(() => getPostsQuery()); + + return ( + <div> + <p>Welcome back {currentUser()?.name}</p> + <ul> + <For each={posts()}>{(post) => <li>{post.title}</li>}</For> + </ul> + <form action={createPostAction} method="post"> + <input name="title" /> + <button>Create Post</button> + </form> + </div> + ); } +``` -json<T>(data: T, opt?: ResponseOptions): CustomResponse<T>; -``` +## Related -The `ResponseOptions` extens the types from the native [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#options) interface. \ No newline at end of file +- [`query`](/solid-router/reference/data-apis/query) +- [`action`](/solid-router/reference/data-apis/action) diff --git a/src/routes/solid-router/reference/response-helpers/redirect.mdx b/src/routes/solid-router/reference/response-helpers/redirect.mdx index 9d49940e0..57535bcb9 100644 --- a/src/routes/solid-router/reference/response-helpers/redirect.mdx +++ b/src/routes/solid-router/reference/response-helpers/redirect.mdx @@ -1,74 +1,115 @@ --- title: redirect +use_cases: >- + authentication flows, login redirects, form submissions, route guards, user + authorization, navigation control +tags: + - redirect + - authentication + - navigation + - routing + - authorization + - forms +version: "1.0" +description: >- + Redirect users between routes with proper status codes. Handle authentication + flows, form submissions, and protected route access. --- -Redirects to the next route. -When done over a server RPC (Remote Procedure Call), the redirect will be done through the server. -By default the status code of a `redirect()` is `302 - FOUND`, also known as a temporary redirect. +The `redirect` function returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that instructs the router to navigate to a different route when returned or thrown from a [query](/solid-router/reference/data-apis/query) or [action](/solid-router/concepts/actions). -Other useful redirect codes: +This works both in client and server (e.g., using a server function) environments. -| Code | Description | -| ---- | ----------- | -| `301` | Moved Permanently | -| `307` | Temporary Redirect | -| `308` | Permanent redirect | +## Import -:::tip[Redirect Methods] -307 and 308 won't allow the browser to change the method of the request. -If you want to change the method, you should use 301 or 302. -::: - -A common use-case for throwing a redirect is when a user is not authenticated and needs to be sent to the login page or another public route. +```ts +import { redirect } from "@solidjs/router"; +``` -```js title="/queries/get-user.ts" {7} -import { query, redirect } from "@solidjs/router"; -import { getCurrentUser } from "../auth"; - -const getUser = query(() => { - const user = await getCurrentUser(); - - if (!user) throw redirect("/login"); - - return user; -}, "get-user") +## Type + +```ts +function redirect( + url: string, + init?: + | number + | { + revalidate?: string | string[]; + headers?: HeadersInit; + status?: number; + statusText?: string; + } +): CustomResponse<never>; ``` -## Single-Flight Mutations +## Parameters -When using `redirect` during a Server Action, the redirect will be done through the server. -The response value will automatically send data for the destination route, avoiding a subsequent roundtrip to load the data from the target route. +### `url` -This is useful when redirecting the user to a different route once a mutation is done. +- **Type:** `string` +- **Required:** Yes -```ts title="/actions/add-user.ts" {3,6} -import { action, redirect } from "@solidjs/router"; +The absolute or relative URL to which the redirect should occur. -const addUser = action(async (user: User) => { - await postUser(user); - - return redirect("/users"); -}); -``` +### `init` + +- **Type:** `number | { revalidate?: string | string[]; headers?: HeadersInit; status?: number; statusText?: string; }` +- **Required:** No + +Either a number representing the status code or a configuration object with the following properties: + +#### `revalidate` + +- **Type:** `string | string[]` +- **Required:** No + +A query key or an array of query keys to revalidate on the destination route. + +#### `status` -The `addUser` action will redirect the user to the `/users` route once the user has been added to the database. -The response from the form action will send the updated data for the `/users` route without the developer needing to revalidate or reload. +- **Type:** `number` +- **Required:** No -## Throw vs Return +The HTTP status code for the redirect. +Defaults to [`302 Found`)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/302). -Both `throw` and `return` can be used to redirect the user to a different route. -For general usage `throw` is recommended as it immediately stops the execution of the current action and redirects the user. +## Examples -When returning from a nested method, the parent method will continue to execute, which can lead to unexpected behavior. +### Basic Usage -### TypeScript Signature +```ts +import { query, redirect } from "@solidjs/router"; + +const getCurrentUserQuery = query(async () => { + const response = await fetch("/api/me"); + + if (response.status === 401) { + return redirect("/login"); + } + + return await response.json(); +}, "currentUser"); +``` + +### Configuring Query Revalidation -```typescript -type RouterResponseInit = Omit<ResponseInit, "body"> & { - revalidate?: string | string[]; -}; +```ts +import { action, redirect } from "@solidjs/router"; + +const loginAction = action(async (formData: FormData) => { + const username = formData.get("username")?.toString(); + const password = formData.get("password")?.toString(); + + await fetch("/api/login", { + method: "POST", + body: JSON.stringify({ username, password }), + }).then((response) => response.json()); + + return redirect("/users", { revalidate: ["currentUser"] }); +}, "login"); +``` -function redirect(url: string, init?: number | RouterResponseInit): CustomResponse<never>; -``` +## Related -The `RouterResponseInit` type extends the native [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#options) interface. +- [`query`](/solid-router/reference/data-apis/query) +- [`action`](/solid-router/reference/data-apis/action) diff --git a/src/routes/solid-router/reference/response-helpers/reload.mdx b/src/routes/solid-router/reference/response-helpers/reload.mdx index fed946069..94c390963 100644 --- a/src/routes/solid-router/reference/response-helpers/reload.mdx +++ b/src/routes/solid-router/reference/response-helpers/reload.mdx @@ -1,32 +1,89 @@ --- title: reload +use_cases: >- + data refresh, cache invalidation, after mutations, updating queries, form + submissions, data synchronization +tags: + - reload + - cache + - revalidation + - mutations + - queries + - refresh +version: "1.0" +description: >- + Reload and revalidate specific queries after mutations. Efficiently update + cached data without full page refreshes for better UX. --- -Reload is a response helper built on top of [revalidate](/solid-router/reference/response-helpers/revalidate). -It will receive a query key, or an array of query keys, to invalidate those queries, and cause them to fire again. +The `reload` function returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object that instructs the router to revalidate specific queries when returned or thrown from a [query](/solid-router/reference/data-apis/query) or [action](/solid-router/concepts/actions). -```ts title="/actions/update-todo.ts" {7} -import { action, reload } from "@solidjs/router"; -import { putTodo, getTodo } from "../db"; +## Import -const updateTodo = action(async (todo: Todo) => { - await putTodo(todo.id, todo); - - return reload({ revalidate: getTodo.keyFor(id) }); -}); +```ts +import { reload } from "@solidjs/router"; ``` -The code snippet above uses the query key from a user-defined query (`getTodo`). -To better understand how queries work, check the [query](/solid-router/reference/data-apis/query) documentation. +## Type + +```ts +function reload(init?: { + revalidate?: string | string[]; + headers?: HeadersInit; + status?: number; + statusText?: string; +}): CustomResponse<never>; +``` + +## Parameters + +### `init` + +- **Type:** `{ revalidate?: string | string[]; headers?: HeadersInit; status?: number; statusText?: string; }` +- **Required:** No + +An optional configuration object with the following properties: + +#### `revalidate` + +- **Type:** `string | string[]` +- **Required:** No + +A query key or an array of query keys to revalidate. + +#### `headers` -## TypeScript Signature +- **Type:** `HeadersInit` +- **Required:** No + +An object containing any headers to be sent with the response. + +#### `status` + +- **Type:** `number` +- **Required:** No + +The HTTP status code of the response. +Defaults to [`200 OK`](http://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/200). + +#### `statusText` + +- **Type:** `string` +- **Required:** No + +The status text associated with the status code. + +## Examples + +### Basic Usage ```ts -interface ResponseOptions & Omit<ResponseInit, "body"> { - revalidate?: string | string[]; -} +import { action, reload } from "@solidjs/router"; -reload(opt?: ResponseOptions): CustomResponse<never>; -``` +const savePreferencesAction = action(async () => { + // ... Saves the user preferences. -The `ResponseOptions` extends the types from the native [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#options) interface. + // Only revalidate the "userPreferences" query. + return reload({ revalidate: ["userPreferences"] }); +}, "savePreferences"); +``` diff --git a/src/routes/solid-router/rendering-modes/spa.mdx b/src/routes/solid-router/rendering-modes/spa.mdx index 6bdcc8263..9629b8928 100644 --- a/src/routes/solid-router/rendering-modes/spa.mdx +++ b/src/routes/solid-router/rendering-modes/spa.mdx @@ -1,8 +1,22 @@ --- title: Single page applications +use_cases: >- + client-side routing, cdn deployment, static hosting, spa configuration, + deployment setup +tags: + - spa + - deployment + - cdn + - hosting + - client-side + - routing +version: "1.0" +description: >- + Configure single-page applications for proper CDN and hosting deployment. + Handle client-side routing without server-side rendering. --- -When deploying applications that use a client-side router without relying on Server-Side Rendering, it is important that redirects to the index page are handled properly. +When deploying applications that use a client-side router without relying on Server-Side Rendering, it is important that redirects to the index page are handled properly. This prevents the CDN or hosting service from returning a "not found" error when accessing URLs that do not correspond to files. Each provider has a different way of doing this. diff --git a/src/routes/solid-router/rendering-modes/ssr.mdx b/src/routes/solid-router/rendering-modes/ssr.mdx index fdced89d3..ba9a73d88 100644 --- a/src/routes/solid-router/rendering-modes/ssr.mdx +++ b/src/routes/solid-router/rendering-modes/ssr.mdx @@ -1,5 +1,19 @@ --- title: Server side rendering +use_cases: >- + server rendering, seo optimization, initial page load, performance + optimization, data preloading +tags: + - ssr + - server + - rendering + - seo + - performance + - preload +version: "1.0" +description: >- + Enable server-side rendering with Solid Router for SEO and performance. + Support suspense, resources, and render-as-you-fetch patterns. --- Solid Router supports all of Solid's SSR capabilities. diff --git a/src/routes/solid-start/advanced/auth.mdx b/src/routes/solid-start/advanced/auth.mdx index 96c7814e6..7fa21c2fa 100644 --- a/src/routes/solid-start/advanced/auth.mdx +++ b/src/routes/solid-start/advanced/auth.mdx @@ -1,19 +1,33 @@ --- -title: "Auth" +title: Auth +use_cases: >- + user authentication, protected routes, authorization checks, secure data + access, login systems +tags: + - authentication + - authorization + - security + - protected + - login + - users +version: "1.0" +description: >- + Implement authentication and protected routes in SolidStart. Secure sensitive + resources and handle user authorization properly. --- Server functions can be used to protect sensitive resources like user data. ```tsx -"use server" +"use server"; async function getPrivatePosts() { - const user = await getUser() - if(!user) { - return null // or throw an error + const user = await getUser(); + if (!user) { + return null; // or throw an error } - return db.getPosts({ userId: user.id, private: true }) + return db.getPosts({ userId: user.id, private: true }); } ``` @@ -25,20 +39,23 @@ Routes can be protected by checking the user or session object during data fetch This example uses [Solid Router](/solid-router). ```tsx -const getPrivatePosts = query(async function() { - "use server" - const user = await getUser() - if(!user) { +const getPrivatePosts = query(async function () { + "use server"; + const user = await getUser(); + if (!user) { throw redirect("/login"); } - return db.getPosts({ userId: user.id, private: true }) -}) + return db.getPosts({ userId: user.id, private: true }); +}); export default function Page() { - const posts = createAsync(() => getPrivatePosts()); + const posts = createAsync(() => getPrivatePosts(), { deferStream: true }); } ``` Once the user hits this route, the router will attempt to fetch `getPrivatePosts` data. If the user is not signed in, `getPrivatePosts` will throw and the router will redirect to the login page. + +To prevent errors when opening the page directly, set `deferStream: true`. +This would ensure `getPrivatePosts` resolves before the page loads since server-side redirects cannot occur after streaming has started. diff --git a/src/routes/solid-start/advanced/data.json b/src/routes/solid-start/advanced/data.json index e0f08e8ba..b9f0ac6d3 100644 --- a/src/routes/solid-start/advanced/data.json +++ b/src/routes/solid-start/advanced/data.json @@ -5,6 +5,7 @@ "session.mdx", "request-events.mdx", "return-responses.mdx", + "serialization.mdx", "auth.mdx", "websocket.mdx" ] diff --git a/src/routes/solid-start/advanced/middleware.mdx b/src/routes/solid-start/advanced/middleware.mdx index 871f9b236..cca076be1 100644 --- a/src/routes/solid-start/advanced/middleware.mdx +++ b/src/routes/solid-start/advanced/middleware.mdx @@ -1,5 +1,19 @@ --- -title: "Middleware" +title: Middleware +use_cases: >- + request interception, header management, global data sharing, request + preprocessing, logging, redirects +tags: + - middleware + - headers + - interceptors + - logging + - preprocessing + - locals +version: "1.0" +description: >- + Intercept HTTP requests with middleware for authentication, logging, and + header management. Share request-scoped data across your app. --- Middleware intercepts HTTP requests and responses to perform tasks like authentication, redirection, logging, and more. diff --git a/src/routes/solid-start/advanced/request-events.mdx b/src/routes/solid-start/advanced/request-events.mdx index c69550043..3f6954467 100644 --- a/src/routes/solid-start/advanced/request-events.mdx +++ b/src/routes/solid-start/advanced/request-events.mdx @@ -1,5 +1,19 @@ --- title: Request events +use_cases: >- + server context access, local data storage, request handling, server functions, + event access +tags: + - events + - server + - context + - locals + - requests + - functions +version: "1.0" +description: >- + Access request events and local context in SolidStart server functions. + Type-safe locals and native event handling for server code. --- Request events in SolidStart are retrieved using the [`getRequestEvent`](/reference/server-utilities/get-request-event) from `@solidjs/web`. @@ -14,18 +28,18 @@ When adding fields to `event.locals`, the fields can be typed: ```tsx title="global.d.ts" /// <reference types="@solidjs/start/env" /> declare module App { - interface RequestEventLocals { - /** - * Declare your getRequestEvent().locals here - */ - } + interface RequestEventLocals { + /** + * Declare your getRequestEvent().locals here + */ + } } ``` ## nativeEvent -Sometimes access is still needed to the underlying event from [Vinxi](https://vinxi.vercel.app/). -This can be accessed that using the `.nativeEvent` property, which is the underlying H3Event used, and can be passed to the helpers available in the ecosystem. +Sometimes access is still needed to the underlying event from [Vinxi](https://vinxi.vercel.app/). +This can be accessed that using the `.nativeEvent` property, which is the underlying H3Event used, and can be passed to the helpers available in the ecosystem. Note that Vinxi HTTP helpers _do not_ treeshake so you can only import them in files that do not contain client or isomorphic code. Many of these events support Async Local Storage so this may not be needed. diff --git a/src/routes/solid-start/advanced/return-responses.mdx b/src/routes/solid-start/advanced/return-responses.mdx index 9a100790b..4be635103 100644 --- a/src/routes/solid-start/advanced/return-responses.mdx +++ b/src/routes/solid-start/advanced/return-responses.mdx @@ -1,9 +1,23 @@ --- title: Returning responses +use_cases: >- + server function responses, error handling, response types, api responses, + typescript typing +tags: + - responses + - server + - functions + - typescript + - errors + - api +version: "1.0" +description: >- + Return typed Response objects from server functions. Handle redirects, + reloads, and JSON responses with proper TypeScript support. --- -In SolidStart, it is possible to return a Response object from a server function. -[`solid-router`](/solid-router) knows how to handle certain responses with its [`query`](/solid-router/reference/data-apis/query) and [`action`](/solid-router/reference/data-apis/action) APIs. +In SolidStart, it is possible to return a Response object from a server function. +[`solid-router`](/solid-router) knows how to handle certain responses with its [`query`](/solid-router/reference/data-apis/query) and [`action`](/solid-router/reference/data-apis/action) APIs. For TypeScript, when returning a response using `solid-router`'s `redirect`, `reload`, or `json` helpers, they will not impact the return value of the server function. While we suggest depending on the type of the function to handle errors differently, you can always return or throw a response. diff --git a/src/routes/solid-start/advanced/serialization.mdx b/src/routes/solid-start/advanced/serialization.mdx new file mode 100644 index 000000000..f896c92cc --- /dev/null +++ b/src/routes/solid-start/advanced/serialization.mdx @@ -0,0 +1,78 @@ +--- +title: Serialization +use_cases: >- + server function payloads, data transfer, csp, security, performance +tags: + - serialization + - server-functions + - csp + - security + - performance +version: "1.0" +description: >- + Understand how SolidStart serializes server function payloads, supported + types, and CSP tradeoffs. +--- + +SolidStart serializes server function arguments and return values so they can travel between server and client. It uses Seroval under the hood and streams payloads to keep responses responsive. + +## Configuration + +Configure serialization in your `app.config.ts` with `defineConfig`: + +```tsx tab title="v1" +import { defineConfig } from "@solidjs/start/config"; + +export default defineConfig({ + serialization: { + mode: "js", + }, +}); +``` + +```tsx tab title="v2" +import { defineConfig } from "vite"; +import { solidStart } from "@solidjs/start"; + +export default defineConfig({ + plugins: [ + solidStart({ + serialization: { + mode: "json", + }, + }), + ], +}); +``` + +See the full config reference in [`defineConfig`](/solid-start/reference/config/define-config#serialization). + +## Modes + +- `json`: Uses `JSON.parse` on the client. Best for strict CSP because it avoids `eval`. Payloads can be slightly larger. +- `js`: Uses Seroval's JS serializer for smaller payloads and better performance, but it requires `unsafe-eval` in CSP. + +:::caution[v2 Breaking Change: Defaults] +SolidStart v1 defaults to `js` for backwards compatibility. SolidStart v2 defaults to `json` for CSP compatibility. +::: + +## Supported types (default) + +SolidStart enables Seroval plus a default set of web platform plugins. These plugins add support for: + +- `AbortSignal`, `CustomEvent`, `DOMException`, `Event` +- `FormData`, `Headers`, `ReadableStream` +- `Request`, `Response` +- `URL`, `URLSearchParams` + +Seroval supports additional value types. The compatibility list is broader than what SolidStart enables by default, so treat it as a superset. See the [Seroval compatibility docs](https://github.com/lxsmnsyc/seroval/blob/main/docs/COMPATIBILITY.md). + +## Limits and exclusions + +- `RegExp` is disabled by default. +- JSON mode enforces a maximum serialization depth of 64. If you exceed this, flatten the structure or return a simpler payload. + +## Related guidance + +- Configure modes and defaults in [`defineConfig`](/solid-start/reference/config/define-config#serialization). +- CSP implications and nonce examples live in the [Security guide](/solid-start/guides/security#content-security-policy-csp). diff --git a/src/routes/solid-start/advanced/session.mdx b/src/routes/solid-start/advanced/session.mdx index ff7da4df6..3cf6c64ef 100644 --- a/src/routes/solid-start/advanced/session.mdx +++ b/src/routes/solid-start/advanced/session.mdx @@ -1,5 +1,19 @@ --- -title: "Sessions" +title: Sessions +use_cases: >- + user sessions, authentication state, preferences storage, stateful + interactions, login persistence +tags: + - sessions + - cookies + - authentication + - state + - storage + - persistence +version: "1.0" +description: >- + Manage user sessions with encrypted cookies in SolidStart. Maintain + authentication state and user preferences between requests. --- Sessions allow web applications to maintain state between user requests. diff --git a/src/routes/solid-start/advanced/websocket.mdx b/src/routes/solid-start/advanced/websocket.mdx index 63762cd9a..11ca0a5dc 100644 --- a/src/routes/solid-start/advanced/websocket.mdx +++ b/src/routes/solid-start/advanced/websocket.mdx @@ -1,5 +1,19 @@ --- title: WebSocket endpoint +use_cases: >- + real-time updates, chat applications, live notifications, multiplayer games, + collaborative editing, streaming data +tags: + - websocket + - real-time + - streaming + - experimental + - server + - events +version: "1.0" +description: >- + Set up WebSocket endpoints in SolidStart for real-time bidirectional + communication. Handle connections, messages, and events. --- WebSocket endpoint may be included by passing the ws handler file you specify in your start config. @@ -29,21 +43,21 @@ Inside the ws file, you can export an eventHandler function to manage WebSocket import { eventHandler } from "vinxi/http"; export default eventHandler({ - handler() {}, - websocket: { - async open(peer) { - console.log("open", peer.id, peer.url); - }, - async message(peer, msg) { - const message = msg.text(); - console.log("msg", peer.id, peer.url, message); - }, - async close(peer, details) { - console.log("close", peer.id, peer.url); - }, - async error(peer, error) { - console.log("error", peer.id, peer.url, error); - }, - }, + handler() {}, + websocket: { + async open(peer) { + console.log("open", peer.id, peer.url); + }, + async message(peer, msg) { + const message = msg.text(); + console.log("msg", peer.id, peer.url, message); + }, + async close(peer, details) { + console.log("close", peer.id, peer.url); + }, + async error(peer, error) { + console.log("error", peer.id, peer.url, error); + }, + }, }); ``` diff --git a/src/routes/solid-start/building-your-application/api-routes.mdx b/src/routes/solid-start/building-your-application/api-routes.mdx index 11aee0548..3ee6d1489 100644 --- a/src/routes/solid-start/building-your-application/api-routes.mdx +++ b/src/routes/solid-start/building-your-application/api-routes.mdx @@ -1,9 +1,25 @@ --- -title: "API routes" +title: API routes +use_cases: >- + rest api, graphql endpoints, trpc setup, webhooks, oauth callbacks, pdf + generation, third-party integrations +tags: + - api + - rest + - graphql + - trpc + - endpoints + - server + - http +version: "1.0" +description: >- + Create API routes in SolidStart for REST, GraphQL, or tRPC endpoints. Handle + HTTP methods, sessions, and external integrations. --- While Server Functions can be a good way to write server-side code for data needed by your UI, sometimes you need to expose API routes. Some reasons for wanting API Routes include: + - There are additional clients that want to share this logic. - Exposing a GraphQL or tRPC endpoint. - Exposing a public-facing REST API. @@ -30,24 +46,25 @@ While you can name this directory anything, it is common to name it `api` to ind ```tsx title="routes/api/test.ts" export function GET() { - // ... + // ... } export function POST() { - // ... + // ... } export function PATCH() { - // ... + // ... } export function DELETE() { - // ... + // ... } ``` API routes get passed an `APIEvent` object as their first argument. This object contains: + - `request`: [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object representing the request sent by the client. - `params`: Object that contains the dynamic route parameters. For example, if the route is `/api/users/:id`, and the request is made to `/api/users/123`, then `params` will be `{ id: 123 }`. - `fetch`: An internal `fetch` function that can be used to make requests to other API routes without worrying about the `origin` of the URL. @@ -57,7 +74,7 @@ In order to handle all methods, you can define a handler function that binds mul ```tsx title="routes/api/all.ts" async function handler() { - // ... + // ... } export const GET = handler; @@ -72,9 +89,9 @@ import type { APIEvent } from "@solidjs/start/server"; import store from "./store"; export async function GET({ params }: APIEvent) { - console.log(`Category: ${params.category}, Brand: ${params.brand}`); - const products = await store.getProducts(params.category, params.brand); - return products; + console.log(`Category: ${params.category}, Brand: ${params.brand}`); + const products = await store.getProducts(params.category, params.brand); + return products; } ``` @@ -93,15 +110,15 @@ import { getCookie } from "vinxi/http"; import store from "./store"; export async function GET(event: APIEvent) { - const userId = getCookie("userId"); - if (!userId) { - return new Response("Not logged in", { status: 401 }); - } - const user = await store.getUser(event.params.userId); - if (user.id !== userId) { - return new Response("Not authorized", { status: 403 }); - } - return user; + const userId = getCookie("userId"); + if (!userId) { + return new Response("Not logged in", { status: 401 }); + } + const user = await store.getUser(event.params.userId); + if (user.id !== userId) { + return new Response("Not authorized", { status: 403 }); + } + return user; } ``` @@ -137,26 +154,26 @@ const schema = buildSchema(` // Define GraphQL Resolvers const rootValue = { - hello: () => { - return { - message: "Hello World" - }; - }, - goodbye: () => { - return "Goodbye"; - } + hello: () => { + return { + message: "Hello World", + }; + }, + goodbye: () => { + return "Goodbye"; + }, }; // request handler const handler = async (event: APIEvent) => { - // get request body - const body = await new Response(event.request.body).json(); + // get request body + const body = await new Response(event.request.body).json(); - // pass query and save results - const result = await graphql({ rootValue, schema, source: body.query }); + // pass query and save results + const result = await graphql({ rootValue, schema, source: body.query }); - // send query result - return result; + // send query result + return result; }; export const GET = handler; @@ -179,9 +196,9 @@ import { string } from "valibot"; const t = initTRPC.create(); export const appRouter = t.router({ - hello: t.procedure.input(wrap(string())).query(({ input }) => { - return `hello ${input ?? "world"}`; - }) + hello: t.procedure.input(wrap(string())).query(({ input }) => { + return `hello ${input ?? "world"}`; + }), }); export type AppRouter = typeof appRouter; @@ -194,7 +211,10 @@ import { createTRPCProxyClient, httpBatchLink, loggerLink } from "@trpc/client"; import type { AppRouter } from "./router"; export const client = createTRPCProxyClient<AppRouter>({ - links: [loggerLink(), httpBatchLink({ url: "http://localhost:3000/api/trpc" })] + links: [ + loggerLink(), + httpBatchLink({ url: "http://localhost:3000/api/trpc" }), + ], }); ``` @@ -206,12 +226,12 @@ import { fetchRequestHandler } from "@trpc/server/adapters/fetch"; import { appRouter } from "~/lib/router"; const handler = (event: APIEvent) => - fetchRequestHandler({ - endpoint: "/api/trpc", - req: event.request, - router: appRouter, - createContext: () => ({}) - }); + fetchRequestHandler({ + endpoint: "/api/trpc", + req: event.request, + router: appRouter, + createContext: () => ({}), + }); export const GET = handler; diff --git a/src/routes/solid-start/building-your-application/css-and-styling.mdx b/src/routes/solid-start/building-your-application/css-and-styling.mdx index 8fb11d3a0..aa2d79460 100644 --- a/src/routes/solid-start/building-your-application/css-and-styling.mdx +++ b/src/routes/solid-start/building-your-application/css-and-styling.mdx @@ -1,8 +1,22 @@ --- -title: "CSS and styling" +title: CSS and styling +use_cases: >- + styling components, css modules, scoped styles, component styling, design + system setup, visual customization +tags: + - css + - styling + - modules + - components + - design + - vite +version: "1.0" +description: >- + Style your SolidStart components with CSS, CSS modules, and other styling + solutions. Implement scoped styles and design systems. --- -SolidStart is a standards-based framework that, instead of modifying the behavior of the [`<style>` tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style), strives to build on top of it. +SolidStart is a standards-based framework that, instead of modifying the behavior of the [`<style>` tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style), strives to build on top of it. ## Styling components @@ -21,37 +35,36 @@ To use the CSS in the component, you can define the CSS in the `Card.css` file a ```css title="Card.css" .card { - background-color: #446b9e; + background-color: #446b9e; } h1 { - font-size: 1.5em; - font-weight: bold; + font-size: 1.5em; + font-weight: bold; } p { - font-size: 1em; - font-weight: normal; + font-size: 1em; + font-weight: normal; } ``` - ```tsx title="Card.tsx" import "./Card.css"; const Card = (props) => { - return ( - <div class="card"> - <h1>{props.title}</h1> - <p>{props.text}</p> - </div> - ); + return ( + <div class="card"> + <h1>{props.title}</h1> + <p>{props.text}</p> + </div> + ); }; ``` ### CSS modules for scoped styles -SolidStart also supports [vite's CSS modules](https://vitejs.dev/guide/features.html#css-modules). +SolidStart also supports [vite's CSS modules](https://vitejs.dev/guide/features.html#css-modules). Through [CSS modules](https://github.com/css-modules/css-modules), you can scope certain CSS to a component and use the CSS class in multiple components to style them differently. For this feature to work, the `.css` file must be named with the `.module.css` extension. @@ -59,17 +72,17 @@ This convention also works for `.scss` and `.sass` files, which can be named wit ```css title="Card.module.css" .card { - background-color: #446b9e; + background-color: #446b9e; } div.card > h1 { - font-size: 1.5em; - font-weight: bold; + font-size: 1.5em; + font-weight: bold; } div.card > p { - font-size: 1em; - font-weight: normal; + font-size: 1em; + font-weight: normal; } ``` @@ -84,16 +97,16 @@ The import object can be thought of as `humanClass: generatedClass` and within t import styles from "./Card.module.css"; const Card = (props) => { - return ( - <div class={styles.card}> - <h1>{props.title}</h1> - <p>{props.text}</p> - </div> - ); + return ( + <div class={styles.card}> + <h1>{props.title}</h1> + <p>{props.text}</p> + </div> + ); }; ``` ## Other ways to style components -SolidStart is built on top of Solid, meaning styling is not limited to CSS. +SolidStart is built on top of Solid, meaning styling is not limited to CSS. To see other ways to style components, see the [styling section in the Solid documentation](/guides/styling-your-components). 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..74c1104aa --- /dev/null +++ b/src/routes/solid-start/building-your-application/data-fetching.mdx @@ -0,0 +1,57 @@ +--- +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/data-fetching/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/data-fetching/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. + +:::caution[Modifying headers after streaming] +Once streaming begins, response headers (including status and cookies) are sent and cannot be changed. +Any header-modifying logic within a server function, such as redirects or APIs like `useSession` that set cookies, must run before streaming starts; +otherwise, this error will occur: +`Cannot set headers after they are sent to the client.` + +To avoid this, disable streaming for queries that may modify headers by enabling the [`deferStream`](/solid-router/reference/data-apis/create-async#deferstream) option. + +```tsx +const user = createAsync(() => getCurrentUserQuery(), { deferStream: true }); +``` + +::: 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 <For each={users()}>{(user) => <li>{user.name}</li>}</For>; -} -``` - -```tsx tab title="JavaScript" {5-8} -// src/routes/users.jsx -import { For, createResource } from "solid-js"; - -export default function Page() { - const [users] = createResource(async () => { - const response = await fetch("https://example.com/users"); - return (await response.json()); - }); - - return <For each={users()}>{(user) => <li>{user.name}</li>}</For>; -} -``` - -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 <For each={users()}>{(user) => <li>{user.name}</li>}</For>; -} -``` - -```tsx tab title="JavaScript" {5, 8, 11} -// /routes/users.jsx -import { For } from "solid-js"; -import { createAsync, query } from "@solidjs/router"; - -const getUsers = query(async () => { - const response = await fetch("https://example.com/users"); - return (await response.json()); -}, "users"); - -export const route = { - preload: () => getUsers(), -}; - -export default function Page() { - const users = createAsync(() => getUsers()); - - return <For each={users()}>{(user) => <li>{user.name}</li>}</For>; -} -``` - -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 <For each={users()}>{(user) => <li>{user.name}</li>}</For>; -} -``` - -```tsx tab title="JavaScript" {6} -// /routes/users.jsx -import { For } from "solid-js"; -import { createAsync, query } from "@solidjs/router"; - -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 <For each={users()}>{(user) => <li>{user.name}</li>}</For>; -} -``` 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 ( + <div> + <p>Current name: {props.data.product?.name}</p> + <form + action={updateProductAction.with(props.params.id as string)} + method="post" + > + <input name="name" placeholder="New name" /> + <button>Save</button> + </form> + </div> + ); +} +``` + +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/building-your-application/head-and-metadata.mdx b/src/routes/solid-start/building-your-application/head-and-metadata.mdx index e7c8c3627..24fdb5734 100644 --- a/src/routes/solid-start/building-your-application/head-and-metadata.mdx +++ b/src/routes/solid-start/building-your-application/head-and-metadata.mdx @@ -1,15 +1,25 @@ --- -title: "Head and metadata" +title: Head and metadata +use_cases: >- + seo optimization, page titles, meta tags, og tags, social sharing, search + engine visibility, dynamic metadata +tags: + - seo + - metadata + - head + - title + - meta + - og-tags +version: "1.0" +description: >- + Manage SEO and metadata in SolidStart with dynamic titles, meta tags, and Open + Graph tags for better search visibility. --- SolidStart does not come with a metadata library. In cases where you want to customize the content in the `head` of your `document`, you can use the `@solidjs/meta` library. -<div id="npm"> -```bash frame="none" -npm i @solidjs/meta -``` -</div> +<div id="npm">```bash frame="none" npm i @solidjs/meta ```</div> The common elements used in the [`head`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head) are: @@ -26,16 +36,16 @@ When applying metadata to a specific route, you can use the `Title`: import { Title } from "@solidjs/meta"; export default function About() { - return ( - <> - <Title>About -

About

- - ); + return ( + <> + About +

About

+ + ); } ``` -These tags will be applied for that specific route only and will be removed from `document.head` once a user navigates away from the page. +These tags will be applied for that specific route only and will be removed from `document.head` once a user navigates away from the page. `routeData` can also be used here to create titles and SEO metadata that is specific to the dynamic parts of the route. ## Adding a site suffix in Title @@ -44,7 +54,7 @@ Custom components can be created to wrap the `Title` component to add a site-spe ```tsx {2} export default function MySiteTitle(props) { - return {props.children} | My Site; + return {props.children} | My Site; } ``` @@ -52,12 +62,12 @@ export default function MySiteTitle(props) { import MySiteTitle from "~/components/MySiteTitle"; export default function About() { - return ( - <> - About -

About

- - ); + return ( + <> + About +

About

+ + ); } ``` @@ -71,14 +81,14 @@ import { RouteSectionProps } from "@solidjs/router"; import { createResource, Show } from "solid-js"; export default function User(props: RouteSectionProps) { - const [user] = createResource(() => fetchUser(props.params.id)); - - return ( - - {user()?.name} -

{user()?.name}

- - ); + const [user] = createResource(() => fetchUser(props.params.id)); + + return ( + + {user()?.name} +

{user()?.name}

+ + ); } ``` @@ -92,23 +102,17 @@ Since these tags may want to be used across multiple routes, they can be added i ```tsx { 5-15 } export default function Root() { - return ( - - - - - - - - - - ); + return ( + + + + + + + + + + ); } ``` @@ -119,20 +123,14 @@ This overrides the `Meta` tags used within the `Head` component. import MySiteTitle from "~/components/MySiteTitle"; export default function About() { - return ( - <> - About - - - -

About

- - ); + return ( + <> + About + + + +

About

+ + ); } ``` diff --git a/src/routes/solid-start/building-your-application/route-prerendering.mdx b/src/routes/solid-start/building-your-application/route-prerendering.mdx index 34461ea25..e4290c360 100644 --- a/src/routes/solid-start/building-your-application/route-prerendering.mdx +++ b/src/routes/solid-start/building-your-application/route-prerendering.mdx @@ -1,34 +1,53 @@ --- -title: "Route pre-rendering" +title: Route Pre-rendering +use_cases: >- + static site generation, ssg, blog sites, documentation, marketing pages, + performance optimization, seo improvement +tags: + - prerender + - ssg + - static + - performance + - build + - seo +version: "1.0" +description: >- + Pre-render SolidStart routes to static HTML for faster loads and better SEO. + Perfect for blogs, docs, and marketing sites. --- -SolidStart offers a way to pre-render pages at build time. -The easiest way to accomplish this is by passing a list of routes to be pre-rendered to the `routes` option. +Route pre-rendering powers Static Site Generation (SSG) by producing static HTML pages during the build process. +This results in faster load times and better SEO, making it especially useful for content-rich sites such as documentation, blogs, and marketing pages. +Static files are served without server-side processing at runtime. + +Configure prerendering for specific routes using the `routes` option ```js { 6 } import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ - server: { - prerender: { - routes: ["/", "/about"] - } - } + server: { + prerender: { + routes: ["/", "/about"], + }, + }, }); ``` -When you wish for all your routes to be pre-rendered, you can pass `true` to the `crawlLinks` option: +Or to pre-render all routes, you can pass `true` to the `crawlLinks` option ```js { 6 } import { defineConfig } from "@solidjs/start/config"; export default defineConfig({ - server: { - prerender: { - crawlLinks: true - } - } + server: { + prerender: { + crawlLinks: true, + }, + }, }); ``` -For more information on prerender options, check out [Nitro's documentation](https://nitro.build/config#prerender) +For advanced pre-rendering options, refer to [Nitro's documentation](https://nitro.build/config#prerender). + +[SolidBase](https://solidbase.dev) simplifies SSG development with built-in support for fast, pre-rendered Markdown and MDX pages. diff --git a/src/routes/solid-start/building-your-application/routing.mdx b/src/routes/solid-start/building-your-application/routing.mdx index b7ac8acf9..0bf55774c 100644 --- a/src/routes/solid-start/building-your-application/routing.mdx +++ b/src/routes/solid-start/building-your-application/routing.mdx @@ -1,5 +1,19 @@ --- -title: "Routing" +title: Routing +use_cases: >- + page navigation, url structure, nested layouts, dynamic paths, route + organization, site architecture +tags: + - routing + - navigation + - pages + - layouts + - dynamic + - filesystem +version: "1.0" +description: >- + Build your SolidStart app with file-based routing. Create pages, nested + layouts, and dynamic routes with simple file structure. --- Routing serves as a key component of web applications. @@ -268,21 +282,20 @@ export default function UsersLayout(props: RouteSectionProps) { ```jsx tab title="JavaScript" {3-7} export const route = { - preload() { - // define preload function - } + preload() { + // define preload function + }, }; export default function UsersLayout(props) { - return ( -

Users

- {props.children} -

- ); + return ( +

Users

+ {props.children} +

+ ); } ``` - [api-routes]: /core-concepts/api-routes [fileroutes]: /api/FileRoutes diff --git a/src/routes/solid-start/building-your-application/static-assets.mdx b/src/routes/solid-start/building-your-application/static-assets.mdx index 655978293..06e9b2117 100644 --- a/src/routes/solid-start/building-your-application/static-assets.mdx +++ b/src/routes/solid-start/building-your-application/static-assets.mdx @@ -1,12 +1,26 @@ --- -title: "Static assets" +title: Static assets +use_cases: >- + images, fonts, documents, favicon, robots.txt, service workers, media files, + public resources +tags: + - assets + - images + - public + - static + - media + - files +version: "1.0" +description: >- + Manage static assets in SolidStart using the public directory or imports. + Serve images, fonts, documents, and media files. --- Within SolidStart there are two ways to import static assets into your project: using the public directory and using imports. ## Public directory -Rich web applications use assets to create visuals. +Rich web applications use assets to create visuals. In SolidStart, the `/public` directory can be used to store static assets. These assets are served at the exact path they are in, relative to the public directory: @@ -26,17 +40,18 @@ If you would like to reference an asset in the public directory, you can use the ```tsx { 5 } export default function About() { - return ( - <> -

About

- - ); + return ( + <> +

About

+ + ); } ``` This is ideal when you want to have human-readable, stable references to static assets. This can be useful for assets such as: + - documents - service workers - images, audio, and video @@ -52,18 +67,18 @@ Vite provides a way to import assets directly into your Solid components: import logo from "./solid.png"; export default function About() { - return ( - <> -

About

- // Renders - Solid logo

- - ); + return ( + <> +

About

+ // Renders + Solid logo

+ + ); } ``` -When you use imports, Vite will create a hashed filename. +When you use imports, Vite will create a hashed filename. For example, `solid.png` will become `solid.2d8efhg.png`. ## Public directory versus imports @@ -71,8 +86,8 @@ For example, `solid.png` will become `solid.2d8efhg.png`. The public directory and imports are both valid ways to include static assets in your project. The driver to use one over the other is based on your use case. -For dynamic updates to your assets, using the public directory is the best choice. +For dynamic updates to your assets, using the public directory is the best choice. It allows you to maintain full control over the asset URL paths, ensuring that the links remain consistent even when the assets are updated. -When using imports, the filename is hashed and therefore will not be predictable over time. +When using imports, the filename is hashed and therefore will not be predictable over time. This can be beneficial for cache busting but detrimental if you want to send someone a link to the asset. diff --git a/src/routes/solid-start/data.json b/src/routes/solid-start/data.json index aac47ac2c..7457ff697 100644 --- a/src/routes/solid-start/data.json +++ b/src/routes/solid-start/data.json @@ -3,6 +3,7 @@ "pages": [ "index.mdx", "getting-started.mdx", + "migrating-from-v1.mdx", "building-your-application", "advanced", "guides" diff --git a/src/routes/solid-start/getting-started.mdx b/src/routes/solid-start/getting-started.mdx index 3cd0f1761..760e8209e 100644 --- a/src/routes/solid-start/getting-started.mdx +++ b/src/routes/solid-start/getting-started.mdx @@ -1,5 +1,19 @@ --- -title: "Getting started" +title: Getting started +use_cases: >- + new project, initial setup, project creation, starter template, first app, + quick start, bootstrapping +tags: + - setup + - installation + - starter + - template + - quickstart + - init +version: "1.0" +description: >- + Start your first SolidStart project with templates and step-by-step setup. + Create, configure, and run your Solid application. --- The easiest way to get started with Solid is to use the SolidStart starter. @@ -7,25 +21,33 @@ This starter contains a collection of templates that can be used to quickly boot **1. Install SolidStart** -Once you have created a directory for your new application, you can initialize SolidStart with the following command: +To start a new project you can initialize SolidStart with the following command: ```package-create solid@latest ``` +This will create a new directory for your project based on the name you enter. + **2. Choose a template** When you run the command above, SolidStart will prompt you to choose a template for your new application. -You can see a [list of these options in the SolidStart repository](https://github.com/solidjs/solid-start/tree/main/examples). +You can see a [list of these options in the templates repository](https://github.com/solidjs/templates/tree/main/solid-start-v1). ```bash frame="terminal" -? Which template do you want to use? › - Use arrow-keys. Return to submit. -❯ bare - hackernews - with-auth - with-mdx - with-tailwindcss - with-vitest +◆ Which template would you like to use? +│ ● basic +│ ○ bare +│ ○ with-solidbase +│ ○ with-auth +│ ○ with-authjs +│ ○ with-drizzle +│ ○ with-mdx +│ ○ with-prisma +│ ○ with-solid-styled +│ ○ with-tailwindcss +│ ... +└ ``` Following the prompts, you might be asked questions like whether you want to use Server Side Rendering or TypeScript. @@ -36,6 +58,7 @@ Choose your desired options to continue. Once you have chosen your template and configuration options, you can navigate to the directory you created and run the following command to install dependencies: ```package-install-local + ``` After this command has finished, your new SolidStart application is ready to go! @@ -52,11 +75,12 @@ Your application should now be running locally on port 3000. You can view it by navigating to [http://localhost:3000](http://localhost:3000). :::note - SolidStart uses [Vinxi](https://vinxi.vercel.app/) both for starting a development server with [Vite](https://vitejs.dev/) and for building and starting a production server with [Nitro](https://nitro.build/). +SolidStart uses [Vinxi](https://vinxi.vercel.app/) both for starting a development server with [Vite](https://vitejs.dev/) and for building and starting a production server with [Nitro](https://nitro.build/). When you run your application, you are actually running `vinxi dev` under the hood. You can read more about the [Vinxi CLI and how it is configured in the Vinxi documentation](https://vinxi.vercel.app/api/cli.html). + ::: ## Project files @@ -79,14 +103,15 @@ src/ For example, if you chose to use JavaScript rather than TypeScript, your file extensions will be `.jsx` instead of `.tsx`. Each directory and file in this structure serves a specific purpose in your SolidStart application: + - `public/` - contains the publicly-accessible assets for your application. -This is where images, fonts, and other files that you want to be accessible to the public should be placed. + This is where images, fonts, and other files that you want to be accessible to the public should be placed. - `src/` - where your Start application code will live. -It is aliased to `~/` for importing in your code. + It is aliased to `~/` for importing in your code. - `src/routes/` - any files or pages will be located in this directory. -You can learn more about the [`routes` folder in the routing section](/solid-start/building-your-application/routing). + You can learn more about the [`routes` folder in the routing section](/solid-start/building-your-application/routing). - [`src/entry-client.tsx`](/solid-start/reference/entrypoints/entry-client) - this file is what loads and _hydrates_ the JavaScript for our application on the client side (in browser). -In most cases, you will **not** need to modify this file. + In most cases, you will **not** need to modify this file. - [`src/entry-server.tsx`](/solid-start/reference/entrypoints/entry-server) - this file will handle requests on the server. -Like `entry-client.tsx`, in most cases you will **not** need to modify this file. + Like `entry-client.tsx`, in most cases you will **not** need to modify this file. - [`app.tsx`](/solid-start/reference/entrypoints/app) - this is the HTML root of your application both for client and server rendering. You can think of this as the shell inside which your application will be rendered. diff --git a/src/routes/solid-start/guides/data-fetching.mdx b/src/routes/solid-start/guides/data-fetching.mdx index 5a1a4c38a..859a1f6bb 100644 --- a/src/routes/solid-start/guides/data-fetching.mdx +++ b/src/routes/solid-start/guides/data-fetching.mdx @@ -1,18 +1,25 @@ --- -title: "Data fetching" +title: Data fetching +use_cases: >- + api calls, database queries, loading states, error handling, preloading data, + client fetching, orm integration +tags: + - fetch + - data + - api + - async + - loading + - query + - database +version: "1.0" +description: >- + Master data fetching in SolidStart with practical examples. Handle loading + states, errors, preloading, and database queries. --- -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/reference/data-apis/query) 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 +61,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 +114,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 +169,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 +229,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 +287,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 +392,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..6d0d21eff 100644 --- a/src/routes/solid-start/guides/data-mutation.mdx +++ b/src/routes/solid-start/guides/data-mutation.mdx @@ -1,5 +1,20 @@ --- -title: "Data mutation" +title: Data mutation +use_cases: >- + form submission, data updates, crud operations, user input handling, database + writes, api posts, validation, optimistic ui +tags: + - forms + - actions + - mutations + - validation + - database + - api + - crud +version: "1.0" +description: >- + Learn how to handle form submissions, validate data, and perform mutations + with SolidStart actions. Complete guide with examples. --- This guide provides practical examples of using actions to mutate data in SolidStart. @@ -12,7 +27,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 +501,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/guides/security.mdx b/src/routes/solid-start/guides/security.mdx index 7f0593955..8d663ff89 100644 --- a/src/routes/solid-start/guides/security.mdx +++ b/src/routes/solid-start/guides/security.mdx @@ -1,5 +1,20 @@ --- title: Security +use_cases: >- + production apps, user input handling, authentication, public apis, preventing + attacks, secure deployments, compliance +tags: + - security + - xss + - csrf + - cors + - csp + - middleware + - protection +version: "1.0" +description: >- + Secure your SolidStart apps against XSS, CSRF attacks. Configure CSP headers, + CORS policies, and implement security best practices. --- ## XSS (Cross Site Scripting) @@ -9,12 +24,13 @@ However, this protection does not apply when using [`innerHTML`](/reference/jsx- To protect your application from XSS attacks: +- Set a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). +- Validate and sanitize user inputs, especially form inputs on the server and client. - Avoid using `innerHTML` when possible. If necessary, make sure to sanitize user-supplied data with libraries such as [DOMPurify](https://github.com/cure53/DOMPurify). -- Validate and sanitize user inputs, especially form inputs on the server and client. -- Set a [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP). - Sanitize attributes containing user-supplied data within `

` element itself and its children. +- When URLs are provided or constructed via user input validate its `origin` and `protocol` (to avoid evaluating code via `javascript:` URLs) using the [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) API. It is highly recommended to read the [Cross Site Scripting Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html) for further guidance. @@ -22,12 +38,14 @@ It is highly recommended to read the [Cross Site Scripting Prevention Cheat Shee To configure the `Content-Security-Policy` HTTP header, a [middleware](/solid-start/advanced/middleware) can be used. +If you enforce a strict CSP, configure SolidStart to use JSON serialization mode to avoid `unsafe-eval` requirements. See [defineConfig serialization](/solid-start/reference/config/define-config#serialization). Note that `unsafe-eval` is only required for `serialization.mode: "js"`. + ### With nonce (recommended) If you want to use a [strict CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP#strict_csp) with nonces: 1. Create a middleware that configures the CSP header. -It must then be registered using the [`onRequest`](/solid-start/advanced/middleware#onrequest) event. + It must then be registered using the [`onRequest`](/solid-start/advanced/middleware#onrequest) event. 2. Create a nonce using a cryptographic random value generator, such as the [`randomBytes`](https://nodejs.org/api/crypto.html#cryptorandombytessize-callback) function from the `crypto` module. 3. Store the nonce in the [`locals`](/solid-start/advanced/middleware#locals) object. 4. Configure SolidStart to use the nonce in your [`entry-server.tsx`](/solid-start/reference/entrypoints/entry-server) file. @@ -44,7 +62,7 @@ export default createMiddleware({ const csp = ` default-src 'self'; - script-src 'nonce-${nonce}' 'strict-dynamic' 'unsafe-eval'; + script-src 'nonce-${nonce}' 'strict-dynamic'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; @@ -135,7 +153,7 @@ export default createMiddleware({ ## CSRF (Cross-Site Request Forgery) -To prevent CSRF attacks, a middleware can be used to block untrusted requests: +To prevent basic CSRF attacks, a middleware can be used to block untrusted requests: ```tsx import { createMiddleware } from "@solidjs/start/middleware"; @@ -193,6 +211,7 @@ export default createMiddleware({ ``` This example demonstrates a basic CSRF protection that verifies the `Origin` and `Referer` headers, blocking requests from untrusted origins. +**Please note both of these headers can be forged.** Additionally, consider implementing a more robust CSRF protection mechanism, such as the [Double-Submit Cookie Pattern](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#alternative-using-a-double-submit-cookie-pattern). For further guidance, you can look at the [Cross-Site Request Forgery Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html). diff --git a/src/routes/solid-start/guides/service-workers.mdx b/src/routes/solid-start/guides/service-workers.mdx index 711500abb..e15aeb6f9 100644 --- a/src/routes/solid-start/guides/service-workers.mdx +++ b/src/routes/solid-start/guides/service-workers.mdx @@ -1,5 +1,18 @@ --- -title: "Service workers" +title: Service workers +use_cases: >- + offline support, pwa, caching, background sync, push notifications, + performance optimization +tags: + - service-workers + - pwa + - offline + - caching + - performance +version: "1.0" +description: >- + Register and configure service workers in SolidStart for offline support, + caching strategies, and progressive web app features. --- To register a service worker: diff --git a/src/routes/solid-start/index.mdx b/src/routes/solid-start/index.mdx index ffe1e2823..47e27bec5 100644 --- a/src/routes/solid-start/index.mdx +++ b/src/routes/solid-start/index.mdx @@ -1,5 +1,22 @@ --- -title: Overview +title: SolidStart Docs +nav_title: Overview +titleTemplate: ":title" +use_cases: >- + getting started, new projects, learning solidstart, framework overview, + architecture decisions +tags: + - overview + - introduction + - getting-started + - features + - ssr + - csr + - ssg +version: "1.0" +description: >- + SolidStart meta-framework overview: Build modern web apps with fine-grained + reactivity, isomorphic routing, and flexible rendering. --- # Overview diff --git a/src/routes/solid-start/migrating-from-v1.mdx b/src/routes/solid-start/migrating-from-v1.mdx new file mode 100644 index 000000000..9ebc51f8f --- /dev/null +++ b/src/routes/solid-start/migrating-from-v1.mdx @@ -0,0 +1,98 @@ +--- +title: Migrating from v1 +use_cases: >- + existing project, migration, upgrade +tags: + - setup + - installation + - starter + - template + - quickstart + - init +version: "2.0" +description: >- + Migrate your SolidStart project from v1 to v2. +--- + +This is a migration guide of how to upgrade your v1 SolidStart app to our new v2 version. + +Please note that some third-party packages may not be compatible with v2 yet. + +## Migration steps + +### Update dependencies + +```package-install +@solidjs/start@2.0.0-alpha.2 @solidjs/vite-plugin-nitro-2 vite@7 +``` + +```package-remove +vinxi +``` + +### Configuration files + +- Remove `app.config.ts` +- Create `vite.config.ts` + +```tsx title="vite.config.ts" +import { solidStart } from "@solidjs/start/config"; +import { defineConfig } from "vite"; +import { nitroV2Plugin } from "@solidjs/vite-plugin-nitro-2"; + +export default defineConfig(() => { + return { + plugins: [ + solidStart({ + middleware: "./src/middleware/index.ts", + }), + nitroV2Plugin(), + ], + }; +}); +``` + +Compile-time environment variables are now handled by Vite's environment API. + +```tsx title="vite.config.ts" +// ... +export default defineConfig(({ mode }) => { + const env = loadEnv(mode, process.cwd(), ""); + + return { + // ... + environments: { + ssr: { + define: { + "process.env.DATABASE_URL": JSON.stringify(env.DATABASE_URL), + }, + }, + }, + }; +}); +``` + +Update the build/dev commands to use native Vite instead of vinxi. + +```json +"scripts": { + "dev": "vite dev", + "build": "vite build", + "start": "vite preview" +} +``` + +### Environment types + +Only the `types` entry is new in v2. Everything else can remain unchanged. + +```json +"compilerOptions": { + "types": ["@solidjs/start/env"] +} +``` + +## Server runtime helpers + +- Replace all imports from `vinxi/http` with `@solidjs/start/http` +- Optional: update the middleware syntax to the newer [H3 syntax](https://h3.dev/guide/basics/middleware) diff --git a/src/routes/solid-start/reference/client/client-only.mdx b/src/routes/solid-start/reference/client/client-only.mdx index e35088e58..625312a82 100644 --- a/src/routes/solid-start/reference/client/client-only.mdx +++ b/src/routes/solid-start/reference/client/client-only.mdx @@ -1,37 +1,71 @@ --- title: clientOnly +use_cases: >- + browser apis, window access, document manipulation, third-party widgets, maps, + charts, avoiding ssr issues +tags: + - client-only + - browser + - ssr + - rendering + - components +version: "1.0" +description: >- + Render components exclusively on the client side in SolidStart. Handle browser + APIs and bypass SSR for specific components. --- -Wrapping components in `clientOnly` will cause them render _only_ in the client. -This can useful for components that interact directly with the DOM, such as jQuery, since they can not render on the server. -It works similar to [`lazy`](/reference/component-apis/lazy) but will only render _after hydration_ and will never load on the server. +The `clientOnly` function allows components or pages to render exclusively on the client side, bypassing server-side rendering (_SSR_). +This is useful for code that relies on the browser-specific APIs, such as `window` or `document`. -To use `clientOnly`, isolate the desired component with DOM interactions in a file: +## How to Use `clientOnly` in Components -```tsx -const location = window.document.location; +1. **Isolate Client-Only Logic**: Create a separate file for the component that depends on browser-specific features, such as DOM or browser APIs. -export default function ClientOnlyComponent() { - return <div>{location.href}</div>; -} -``` + ```tsx title="ClientOnlyComponent" + export default function ClientOnlyComponent() { + const location = document.location.href; + return <div>Current URL: {location}</div>; + } + ``` + +2. **Import with `clientOnly`**: Use `clientOnly` to dynamically import the isolated component in your parent component or page. + + ```tsx title="IsomorphicComponent.tsx" + import { clientOnly } from "@solidjs/start"; + + const ClientOnlyComp = clientOnly(() => import("./ClientOnlyComponent")); -Once isolated, it can then be imported dynamically using `clientOnly`: + export default function IsomorphicComponent() { + return <ClientOnlyComp />; + } + ``` -```tsx +3. **Add a Fallback (Optional)**: Provide a `fallback` prop to display content while the client-only component is loading. + + ```tsx + <ClientOnlyComp fallback="{<div">Loading...</div>} /> + ``` + +## Disabling SSR for Entire Pages + +To disable SSR for an entire page, apply `clientOnly` at the page level. This ensures the page renders only on the client. + +```tsx title="routes/page.tsx" import { clientOnly } from "@solidjs/start"; -const ClientOnlyComp = clientOnly(() => import("../ClientOnlyComp")); +export default clientOnly(async () => ({ default: Page }), { lazy: true }); -function IsomorphicComp() { - return <ClientOnlyComp />; +function Page() { + // This code runs only on the client + return <div>Client-only page content</div>; } ``` -**Note:** The `<ClientOnlyComp />` can take a fallback prop for when it is loading. - ## Parameters -| Argument | Type | Description | -| -------- | --------------- | ------------------------------------ | -| fn | `() => Promise` | Function to be run client-side only. | +| Argument | Type | Description | +| --------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `fn` | `() => Promise<{ default: () => JSX.Element }>` | A function that dynamically imports a component to be rendered only on the client side. | +| `options` | `{ lazy?: boolean }` | An optional object to configure loading behavior. Set `lazy: false` for eager loading | +| `props` | `Record<string, any> & { fallback?: JSX.Element }` | Props passed to the component, including an optional `fallback` for rendering while the component loads. | diff --git a/src/routes/solid-start/reference/client/data.json b/src/routes/solid-start/reference/client/data.json index f27722264..e44a88a71 100644 --- a/src/routes/solid-start/reference/client/data.json +++ b/src/routes/solid-start/reference/client/data.json @@ -1,8 +1,4 @@ { "title": "Client", - "pages": [ - "client-only.mdx", - "mount.mdx", - "start-client.mdx" - ] -} \ No newline at end of file + "pages": ["client-only.mdx", "mount.mdx", "start-client.mdx"] +} diff --git a/src/routes/solid-start/reference/client/mount.mdx b/src/routes/solid-start/reference/client/mount.mdx index 33c7dd77b..3180530de 100644 --- a/src/routes/solid-start/reference/client/mount.mdx +++ b/src/routes/solid-start/reference/client/mount.mdx @@ -1,8 +1,21 @@ --- title: mount +use_cases: >- + app initialization, entry point setup, bootstrapping, client rendering, + hydration control +tags: + - mount + - hydration + - rendering + - initialization + - entry-client +version: "1.0" +description: >- + Bootstrap your SolidStart application with mount. Automatically handles + hydration for SSR or client-only rendering modes. --- -`mount` is a method that calls either [`hydrate`](/reference/rendering/hydrate) (server rendering) or [`render`](/reference/rendering/render) (client rendering) depending on the configuration. +`mount` is a method that calls either [`hydrate`](/reference/rendering/hydrate) (server rendering) or [`render`](/reference/rendering/render) (client rendering) depending on the configuration. It is used in [`entry-client.tsx`](/solid-start/reference/entrypoints/entry-client) to bootstrap an application. ```tsx diff --git a/src/routes/solid-start/reference/client/start-client.mdx b/src/routes/solid-start/reference/client/start-client.mdx index 88eeecb89..277b51ce5 100644 --- a/src/routes/solid-start/reference/client/start-client.mdx +++ b/src/routes/solid-start/reference/client/start-client.mdx @@ -1,8 +1,18 @@ --- -title: "StartClient" +title: StartClient +use_cases: "client entry setup, app wrapper configuration, root component setup" +tags: + - client + - entry + - components + - configuration +version: "1.0" +description: >- + StartClient component wraps your SolidStart application root. Essential for + proper client-side initialization and mounting. --- -`StartClient` is a component that wraps the application root. +`StartClient` is a component that wraps the application root. It can be passed to [`mount`](/solid-start/reference/client/start-client) in the [`entry-client.tsx`](/solid-start/reference/entrypoints/entry-client). ```tsx diff --git a/src/routes/solid-start/reference/config/data.json b/src/routes/solid-start/reference/config/data.json index 95790d793..90d3e8706 100644 --- a/src/routes/solid-start/reference/config/data.json +++ b/src/routes/solid-start/reference/config/data.json @@ -1,6 +1,4 @@ { "title": "Config", - "pages": [ - "define-config.mdx" - ] -} \ No newline at end of file + "pages": ["define-config.mdx"] +} diff --git a/src/routes/solid-start/reference/config/define-config.mdx b/src/routes/solid-start/reference/config/define-config.mdx index 5ba824c13..d8c7d637f 100644 --- a/src/routes/solid-start/reference/config/define-config.mdx +++ b/src/routes/solid-start/reference/config/define-config.mdx @@ -1,5 +1,19 @@ --- title: defineConfig +use_cases: >- + app configuration, deployment setup, build optimization, platform targeting, + vite plugins, nitro presets +tags: + - configuration + - vite + - nitro + - deployment + - build + - plugins +version: "1.0" +description: >- + Configure SolidStart apps with defineConfig. Set up Vite plugins, Nitro + presets, and deployment targets for any platform. --- The `defineConfig` helper is from `@solidjs/start/config` and is used within [`app.config.ts`](/solid-start/reference/entrypoints/app-config). @@ -21,11 +35,12 @@ export default defineConfig({ }); ``` -The `vite` option can also be a function that can be customized for each Vinxi router. +The `vite` option can also be a function that can be customized for each Vinxi router. In SolidStart, 3 routers are used: + - `server` - server-side routing -- `client` - for the client-side routing +- `client` - for the client-side routing - `server-function` - server functions. ```tsx @@ -42,13 +57,48 @@ export default defineConfig({ }); ``` +## Serialization + +SolidStart serializes server function payloads so they can move between server and client. You can configure the serializer mode to balance performance, payload size, and Content Security Policy (CSP) constraints. + +```tsx +import { defineConfig } from "@solidjs/start/config"; + +export default defineConfig({ + serialization: { + mode: "json", + }, +}); +``` + +### Modes + +- `json`: Uses `JSON.parse` on the client. This is the safest option for strict CSP because it avoids `eval`. Payloads can be slightly larger. +- `js`: Uses Seroval's JS serializer for smaller payloads and better performance, but it relies on `eval` during client-side deserialization and requires `unsafe-eval` in CSP. + +### Defaults + +- SolidStart v1 defaults to `js` for backwards compatibility. +- SolidStart v2 defaults to `json` for CSP compatibility. + +### Supported types (default) + +SolidStart enables Seroval plus a default set of web platform plugins. These plugins add support for: + +- `AbortSignal`, `CustomEvent`, `DOMException`, `Event` +- `FormData`, `Headers`, `ReadableStream` +- `Request`, `Response` +- `URL`, `URLSearchParams` + +Seroval supports additional value types. The compatibility list is broader than what SolidStart enables by default, so treat it as a superset. See the full list in the [Seroval compatibility docs](https://github.com/lxsmnsyc/seroval/blob/main/docs/COMPATIBILITY.md). + ## Configuring Nitro -SolidStart uses [Nitro](https://nitro.build/) to run on a number of platforms. -The `server` option exposes some Nitro options including the build and deployment presets. +SolidStart uses [Nitro](https://nitro.build/) to run on a number of platforms. +The `server` option exposes some Nitro options including the build and deployment presets. An overview of all available presets is available in the [Deploy section of the Nitro documentation](https://nitro.build/deploy). - Some common ones include: +Some common ones include: **Servers** @@ -85,7 +135,7 @@ export default defineConfig({ #### Special note -SolidStart uses async local storage. +SolidStart uses async local storage. Netlify, Vercel, and Deno support this out of the box but if you're using Cloudflare you will need to specify the following: ```js @@ -103,7 +153,6 @@ export default defineConfig({ Within `wrangler.toml` you will need to enable node compatibility: - ``` compatibility_flags = [ "nodejs_compat" ] ``` @@ -116,6 +165,7 @@ compatibility_flags = [ "nodejs_compat" ] | solid | object | | Configuration object for [vite-plugin-solid](https://github.com/solidjs/vite-plugin-solid) | | extensions | string[] | ["js", "jsx", "ts", "tsx"] | Array of file extensions to be treated as routes. | | server | object | | Nitro server config options | +| serialization | object | | Serialization settings for server function payloads. | | appRoot | string | "./src" | The path to the root of the application. | | routeDir | string | "./routes" | The path to where the routes are located. | | middleware | string | | The path to an optional [middleware](/solid-start/advanced/middleware) file. | diff --git a/src/routes/solid-start/reference/data.json b/src/routes/solid-start/reference/data.json index 06ea1be4f..46e12d0dc 100644 --- a/src/routes/solid-start/reference/data.json +++ b/src/routes/solid-start/reference/data.json @@ -1,10 +1,4 @@ { "title": "Reference", - "pages": [ - "entrypoints", - "config", - "routing", - "client", - "server" - ] -} \ No newline at end of file + "pages": ["entrypoints", "config", "routing", "client", "server"] +} diff --git a/src/routes/solid-start/reference/entrypoints/app-config.mdx b/src/routes/solid-start/reference/entrypoints/app-config.mdx index cb6b4ece4..837a7f5f0 100644 --- a/src/routes/solid-start/reference/entrypoints/app-config.mdx +++ b/src/routes/solid-start/reference/entrypoints/app-config.mdx @@ -1,5 +1,15 @@ --- title: app.config.ts +use_cases: "initial setup, project configuration, build settings, deployment configuration" +tags: + - configuration + - setup + - app-config + - defineconfig +version: "1.0" +description: >- + Configure your SolidStart app with app.config.ts. Central configuration file + for Vite, Vinxi, and Nitro build settings. --- The `app.config.ts` is the root of every SolidStart app and the main point of configuration. diff --git a/src/routes/solid-start/reference/entrypoints/app.mdx b/src/routes/solid-start/reference/entrypoints/app.mdx index 88932bfe3..c94a47b92 100644 --- a/src/routes/solid-start/reference/entrypoints/app.mdx +++ b/src/routes/solid-start/reference/entrypoints/app.mdx @@ -1,5 +1,19 @@ --- title: app.tsx +use_cases: >- + routing setup, app structure, layout definition, navigation setup, entry point + configuration +tags: + - routing + - app + - entry + - layout + - navigation + - components +version: "1.0" +description: >- + Define your SolidStart app's entry point and routing structure. Set up + navigation, layouts, and isomorphic application logic. --- The `App` component is the isomorphic (shared on server and browser) entry point into your application. diff --git a/src/routes/solid-start/reference/entrypoints/data.json b/src/routes/solid-start/reference/entrypoints/data.json index 9f9e25082..bfc52c7bb 100644 --- a/src/routes/solid-start/reference/entrypoints/data.json +++ b/src/routes/solid-start/reference/entrypoints/data.json @@ -1,9 +1,4 @@ { "title": "Entrypoints", - "pages": [ - "app-config.mdx", - "app.mdx", - "entry-client.mdx", - "entry-server.mdx" - ] -} \ No newline at end of file + "pages": ["app-config.mdx", "app.mdx", "entry-client.mdx", "entry-server.mdx"] +} diff --git a/src/routes/solid-start/reference/entrypoints/entry-client.mdx b/src/routes/solid-start/reference/entrypoints/entry-client.mdx index 42130e6ed..be69033c2 100644 --- a/src/routes/solid-start/reference/entrypoints/entry-client.mdx +++ b/src/routes/solid-start/reference/entrypoints/entry-client.mdx @@ -1,8 +1,22 @@ --- title: entry-client.tsx +use_cases: >- + browser initialization, client-only code, service workers, mounting app, spa + setup +tags: + - entry + - client + - browser + - initialization + - mount + - startup +version: "1.0" +description: >- + Configure browser entry point for SolidStart apps. Set up client-side + initialization, mount components, and register service workers. --- -`entry-client.tsx` is where an application starts in the browser. +`entry-client.tsx` is where an application starts in the browser. It does this by passing [`<StartClient>`](/solid-start/reference/client/start-client) and a DOM Element (the mounting point), to the [`mount`](/solid-start/reference/client/mount) function. ```tsx @@ -11,5 +25,5 @@ import { mount, StartClient } from "@solidjs/start/client"; mount(() => <StartClient />, document.getElementById("app")!); ``` -This file is an ideal place to run any client specific code that is needed on startup, such as registering service workers. +This file is an ideal place to run any client specific code that is needed on startup, such as registering service workers. This is important if you are performing client-only rendering or using other modes of server-side rendering. diff --git a/src/routes/solid-start/reference/entrypoints/entry-server.mdx b/src/routes/solid-start/reference/entrypoints/entry-server.mdx index ba9e09adf..69d881844 100644 --- a/src/routes/solid-start/reference/entrypoints/entry-server.mdx +++ b/src/routes/solid-start/reference/entrypoints/entry-server.mdx @@ -1,10 +1,24 @@ --- title: entry-server.tsx +use_cases: >- + server initialization, ssr setup, html document structure, meta tags, server + bootstrap +tags: + - entry + - server + - ssr + - initialization + - document + - html +version: "1.0" +description: >- + Define server entry point and HTML document structure for SolidStart. + Configure SSR modes and set up server-side rendering bootstrap. --- `entry-server.tsx` is where an application starts on the server. This happens by `entry-server.tsx` providing a document component to [`<StartServer>`](/solid-start/reference/server/start-server) and passing it into [`createHandler`](/solid-start/reference/server/create-handler) for server side rendering. - A typical `entry-server.tsx` for a new project looks like this: +A typical `entry-server.tsx` for a new project looks like this: ```tsx import { createHandler, StartServer } from "@solidjs/start/server"; diff --git a/src/routes/solid-start/reference/routing/data.json b/src/routes/solid-start/reference/routing/data.json index 78da7ad05..2fbd5efaa 100644 --- a/src/routes/solid-start/reference/routing/data.json +++ b/src/routes/solid-start/reference/routing/data.json @@ -1,6 +1,4 @@ { "title": "Routing", - "pages": [ - "file-routes.mdx" - ] -} \ No newline at end of file + "pages": ["file-routes.mdx"] +} diff --git a/src/routes/solid-start/reference/routing/file-routes.mdx b/src/routes/solid-start/reference/routing/file-routes.mdx index 929ece30a..acbe98fc0 100644 --- a/src/routes/solid-start/reference/routing/file-routes.mdx +++ b/src/routes/solid-start/reference/routing/file-routes.mdx @@ -1,5 +1,19 @@ --- title: FileRoutes +use_cases: >- + file-based routing, automatic route generation, spa routing, route + configuration +tags: + - routing + - files + - routes + - navigation + - filesystem + - spa +version: "1.0" +description: >- + Automatically generate routes from file structure in SolidStart. Create route + configurations from files in the /src/routes directory. --- `FileRoutes` is a component that creates a [`Route`](/solid-router/reference/components/route) for each file in the `/src/routes` directory. diff --git a/src/routes/solid-start/reference/server/create-handler.mdx b/src/routes/solid-start/reference/server/create-handler.mdx index 1bf21a54d..03400e270 100644 --- a/src/routes/solid-start/reference/server/create-handler.mdx +++ b/src/routes/solid-start/reference/server/create-handler.mdx @@ -1,5 +1,19 @@ --- title: createHandler +use_cases: >- + ssr mode configuration, server startup, streaming setup, async rendering, + performance tuning +tags: + - handler + - ssr + - server + - streaming + - async + - rendering +version: "1.0" +description: >- + Configure server-side rendering modes in SolidStart. Choose between sync, + async, or streaming SSR for optimal performance and UX. --- The `createHandler` is used to start the server in [`entry-server.tsx`](/solid-start/reference/entrypoints/entry-server). diff --git a/src/routes/solid-start/reference/server/create-middleware.mdx b/src/routes/solid-start/reference/server/create-middleware.mdx index 5d2b3204f..edc17f9b6 100644 --- a/src/routes/solid-start/reference/server/create-middleware.mdx +++ b/src/routes/solid-start/reference/server/create-middleware.mdx @@ -1,5 +1,19 @@ --- title: createMiddleware +use_cases: >- + request interception, logging, authentication checks, cors setup, response + modification, api middleware +tags: + - middleware + - request + - response + - lifecycle + - interceptor + - hooks +version: "1.0" +description: >- + Add middleware to SolidStart request lifecycle. Intercept requests and + responses for logging, auth, CORS, and custom processing. --- `createMiddleware` creates a configuration object for SolidStart that specifies when middleware functions are executed during the request lifecycle. diff --git a/src/routes/solid-start/reference/server/get-server-function-meta.mdx b/src/routes/solid-start/reference/server/get-server-function-meta.mdx index 9ce998d4b..a4b4f7df6 100644 --- a/src/routes/solid-start/reference/server/get-server-function-meta.mdx +++ b/src/routes/solid-start/reference/server/get-server-function-meta.mdx @@ -1,5 +1,19 @@ --- title: getServerFunctionMeta +use_cases: >- + server function identification, parallel processing, worker management, + caching, multi-core apps +tags: + - server + - functions + - metadata + - parallel + - workers + - cache +version: "1.0" +description: >- + Get stable IDs for server functions across parallel instances. Enable caching + and state management in multi-core SolidStart apps. --- `getServerFunctionMeta` returns a function-specific id string, that is stable across all instances when server functions are run in parallel on multiple CPU cores or workers. diff --git a/src/routes/solid-start/reference/server/get.mdx b/src/routes/solid-start/reference/server/get.mdx index 9a011bdef..67b468e9f 100644 --- a/src/routes/solid-start/reference/server/get.mdx +++ b/src/routes/solid-start/reference/server/get.mdx @@ -1,8 +1,22 @@ --- title: GET +use_cases: >- + http caching, rest api, data fetching, cache headers, seo optimization, cdn + caching +tags: + - http + - get + - cache + - api + - rest + - fetch +version: "1.0" +description: >- + Create cacheable GET server functions in SolidStart. Leverage HTTP cache + headers for improved performance and SEO optimization. --- -`GET` helps to create a server function which is accessed via an [HTTP GET request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET). +`GET` helps to create a server function which is accessed via an [HTTP GET request](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET). When this function is called, arguments are serialized into the URL, thus allowing the use of [HTTP cache-control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) headers. For example, `GET` can be used to make a streaming promise with a 60 second cache life: diff --git a/src/routes/solid-start/reference/server/http-header.mdx b/src/routes/solid-start/reference/server/http-header.mdx index 2a0dd7ad3..bec110da1 100644 --- a/src/routes/solid-start/reference/server/http-header.mdx +++ b/src/routes/solid-start/reference/server/http-header.mdx @@ -1,5 +1,19 @@ --- title: HttpHeader +use_cases: >- + security headers, cors configuration, cache control, seo headers, custom + headers, api responses +tags: + - headers + - http + - response + - security + - cors + - meta +version: "1.0" +description: >- + Set custom HTTP headers in SolidStart responses. Configure security, caching, + CORS, and SEO headers for server-rendered pages. --- `HttpHeader` provides a way to set headers on HTTPs response sent by the server. @@ -25,7 +39,7 @@ export default function NotFound() { } ``` -As a page is rendered, you may want to add additional HTTP headers to the response and the `HttpHeader` component will do that for you. +As a page is rendered, you may want to add additional HTTP headers to the response and the `HttpHeader` component will do that for you. By passing it a `name` and `value`, they will get added to the `Response` headers sent back to the browser. When streaming responses with [`renderToStream`](/reference/rendering/render-to-stream), HTTP headers can only be added before the stream is first flushed. diff --git a/src/routes/solid-start/reference/server/http-status-code.mdx b/src/routes/solid-start/reference/server/http-status-code.mdx index 71b9d9b3a..cc22c8ce6 100644 --- a/src/routes/solid-start/reference/server/http-status-code.mdx +++ b/src/routes/solid-start/reference/server/http-status-code.mdx @@ -1,5 +1,19 @@ --- title: HttpStatusCode +use_cases: >- + error pages, 404 handling, seo optimization, api responses, error boundaries, + status codes +tags: + - status + - http + - errors + - "404" + - seo + - response +version: "1.0" +description: >- + Set HTTP status codes for SolidStart pages. Handle 404s, errors, and optimize + SEO with proper status codes in server responses. --- `HttpStatusCode` sets the HTTP status code for the page response while server-side rendering. @@ -13,13 +27,13 @@ import { HttpStatusCode } from "@solidjs/start"; ## Setting a 404 status code for the unmatched routes As a page is rendered, you may want to set the status code to the `Response` depending on what happens. -The `HttpStatusCode` component does this for you by taking the `code` passed in and setting it to the `Response` status in the browser. +The `HttpStatusCode` component does this for you by taking the `code` passed in and setting it to the `Response` status in the browser. -Since `HttpStatusCode` is just a component, it can be used with [`ErrorBoundary`](/reference/components/error-boundary), [`Show`](/reference/components/show), [`Switch`](/reference/components/switch-and-match) or any of the other JSX control-flow components. +Since `HttpStatusCode` is just a component, it can be used with [`ErrorBoundary`](/reference/components/error-boundary), [`Show`](/reference/components/show), [`Switch`](/reference/components/switch-and-match) or any of the other JSX control-flow components. This means the same logic used when deciding what to render can inform what status code you are setting, allowing that logic to sit together. Status codes are important tools for things like caching and SEO, so it is a good practice to send meaningful status codes. - For example, for a `NotFound` page, you should send a `404` status code. +For example, for a `NotFound` page, you should send a `404` status code. ```tsx {6} title="routes/*404.tsx" import { HttpStatusCode } from "@solidjs/start"; @@ -36,11 +50,11 @@ export default function NotFound() { ## Setting a 404 status code for missing pages for dynamic routes -When using dynamic params in routes, setting a 404 status code if the given parameter for a segment points to a missing resource is important. -Usually, the param is discovered to be missing when doing an async request with that parameter. +When using dynamic params in routes, setting a 404 status code if the given parameter for a segment points to a missing resource is important. +Usually, the param is discovered to be missing when doing an async request with that parameter. Errors can be thrown from inside these fetchers and caught by the nearest [`<ErrorBoundary>`](/reference/components/error-boundary) component from where the data is accessed. -`<HttpStatusCode>` pairs very well with error boundaries because you can inspect the error in the ErrorBoundary's fallback. +`<HttpStatusCode>` pairs very well with error boundaries because you can inspect the error in the ErrorBoundary's fallback. If the fetcher throws an error indicating the data was not found, you can render `<HttpStatusCode code="{404}" />`. Note that when streaming responses [`renderStream`](/reference/rendering/render-to-stream), the HTTP Status can only be included if added _before_ the stream first flushed. diff --git a/src/routes/solid-start/reference/server/start-server.mdx b/src/routes/solid-start/reference/server/start-server.mdx index 4d0fd3965..285ad8b08 100644 --- a/src/routes/solid-start/reference/server/start-server.mdx +++ b/src/routes/solid-start/reference/server/start-server.mdx @@ -1,5 +1,19 @@ --- -title: "StartServer" +title: StartServer +use_cases: >- + server bootstrap, document setup, html structure, ssr configuration, server + initialization +tags: + - server + - bootstrap + - document + - ssr + - initialization + - html +version: "1.0" +description: >- + Bootstrap SolidStart server with document components. Convert document + functions to static HTML for server-side rendering setup. --- `StartServer` takes a function returning a document component and converts it to a static document which can be used in [`createHandler`](/solid-start/reference/server/create-handler) to bootstrap the server. diff --git a/src/routes/solid-start/reference/server/use-server.mdx b/src/routes/solid-start/reference/server/use-server.mdx index 87dbad035..e228d2373 100644 --- a/src/routes/solid-start/reference/server/use-server.mdx +++ b/src/routes/solid-start/reference/server/use-server.mdx @@ -1,16 +1,43 @@ --- title: '"use server"' +use_cases: >- + server-only logic, api endpoints, database operations, secure operations, data + fetching, server actions, rpc calls, authentication logic +tags: + - server + - rpc + - api + - data-fetching + - actions + - security + - database +version: "1.0" +description: >- + Create server-only functions in SolidStart using 'use server' directive. + Handle database operations, API calls, and secure logic on the server. --- -`"use server"` will enable functions that only run on the server. +`"use server"` enables functions or files to be executed only on the server. Server functions allow client components to call code that is executed in the server context. ```tsx +// Function-level const logHello = async (message: string) => { "use server"; console.log(message); }; ``` +Or when using at the top of a file. + +```tsx +// File-level +"use server"; + +const logHello = async (message: string) => { + console.log(message); +}; +``` + **Note:** `"use server"` functions must be marked async or return a promise. ## Basic usage @@ -44,35 +71,35 @@ 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} const getUser = query((id) => { - "use server"; - return db.getUser(id); + "use server"; + return db.getUser(id); }, "users"); const updateUser = action(async (id, data) => { - "use server" - await db.setUser(id, data); - throw redirect("/", { revalidate: getUser.keyFor(id) }); + "use server"; + await db.setUser(id, data); + throw redirect("/", { revalidate: getUser.keyFor(id) }); }); - ``` -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 Server functions allow the serialization of many different data types in the response, using the Seroval serializer. -The full list is available [in Seroval's source code](https://github.com/lxsmnsyc/seroval/blob/main/docs/compatibility.md#supported-types). +For supported types, defaults, and CSP tradeoffs, see the [Serialization guide](/solid-start/advanced/serialization). +Configure serialization mode and CSP behavior in [`defineConfig`](/solid-start/reference/config/define-config#serialization). ## Meta information diff --git a/src/solidbase-theme/Layout.tsx b/src/solidbase-theme/Layout.tsx index ba9b62e1e..8c88005ff 100644 --- a/src/solidbase-theme/Layout.tsx +++ b/src/solidbase-theme/Layout.tsx @@ -6,17 +6,13 @@ import { NotFound } from "~/ui/not-found"; import { I18nProvider } from "~/i18n/i18n-context"; import { useThemeListener } from "@kobalte/solidbase/client"; import { usePace } from "@kobalte/solidbase/default-theme/pace.js"; -import { Title } from "@solidjs/meta"; -import { useProjectTitle } from "~/ui/use-project"; export default function (props: RouteSectionProps) { useThemeListener(); usePace(); - const projectTitle = useProjectTitle(); return ( <I18nProvider> - <Title>{projectTitle()}</Title> <ErrorBoundary fallback="{()"> <NotFound />}> <Layout>{props.children}</Layout> </ErrorBoundary> diff --git a/src/solidbase-theme/mdx-components.tsx b/src/solidbase-theme/mdx-components.tsx index 28a3a1107..b00b7f05b 100644 --- a/src/solidbase-theme/mdx-components.tsx +++ b/src/solidbase-theme/mdx-components.tsx @@ -234,7 +234,7 @@ export const pre = (props: ParentProps) => { export const code = (props: ParentProps) => { return ( <code - class="not-prose inline-block rounded-lg bg-blue-200 px-1 py-0.5 !font-mono text-[0.8em] font-semibold leading-snug text-slate-900 dark:bg-slate-600/60 dark:text-white" + class="not-prose inline-flex rounded-lg bg-blue-200 px-1 py-0.5 !font-mono text-[0.8em] font-semibold leading-snug text-slate-900 dark:bg-slate-600/60 dark:text-white" {...props> {props.children} diff --git a/src/ui/button-link.tsx b/src/ui/button-link.tsx index e9058e12d..5bfe0d0b5 100644 --- a/src/ui/button-link.tsx +++ b/src/ui/button-link.tsx @@ -1,3 +1,4 @@ +import { splitProps } from "solid-js"; import { A, type RouterLinkProps } from "./i18n-anchor"; type ButtonLinkProps = RouterLinkProps & { @@ -5,16 +6,18 @@ type ButtonLinkProps = RouterLinkProps & { }; export const ButtonLink = (props: ButtonLinkProps) => { + const [localProps, otherProps] = splitProps(props, ["variant"]); + return ( <A addLocale classList="{{" rounded-full bg-blue-300 py-2 px-4 text-sm font-semibold text-slate-900 hover:bg-blue-200 focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-300/50 active:bg-blue-500 : - props.variant="==" primary , + localProps.variant="==" primary , rounded-full bg-slate-800 py-2 px-4 text-sm font-semibold text-white hover:bg-slate-700 focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/50 active:text-slate-300 : - props.variant="==" secondary , + localProps.variant="==" secondary , } - {...props + {...otherProps /> ); }; diff --git a/src/ui/callout.tsx b/src/ui/callout.tsx index 9878c4266..4f9fd060d 100644 --- a/src/ui/callout.tsx +++ b/src/ui/callout.tsx @@ -1,4 +1,3 @@ -import { Alert } from "@kobalte/core"; import { Icon } from "solid-heroicons"; import { mergeProps, type JSX, Show, untrack } from "solid-js"; import { @@ -91,7 +90,7 @@ export function Callout(props: CalloutProps) { const IconComponent = icons[iconType]; return ( - <Alert.Root +><div class="{`my-6" flex w-full rounded-3xl border p-4 $ styles[mergedProps.type].container } @ -112,6 +111,6 @ export function Callout(props CalloutProps { {mergedProps.children></div> </div> - </Alert.Root> + </div> ); } diff --git a/src/ui/docs-layout.tsx b/src/ui/docs-layout.tsx index fda9b86a0..efe630de8 100644 --- a/src/ui/docs-layout.tsx +++ b/src/ui/docs-layout.tsx @@ -1,11 +1,9 @@ import { Show, onMount, JSX } from "solid-js"; import { useLocation } from "@solidjs/router"; -import { Title } from "@solidjs/meta"; import { coreEntries } from "solid:collection"; import { Pagination } from "~/ui/pagination"; import { EditPageLink } from "./edit-page-link"; import { PageIssueLink } from "./page-issue-link"; -import { useProjectTitle } from "./use-project"; interface DocsLayoutProps { entries: typeof coreEntries; @@ -14,7 +12,6 @@ interface DocsLayoutProps { export const DocsLayout = (props: DocsLayoutProps) => { const location = useLocation(); - const projectTitle = useProjectTitle(); const collection = () => location.pathname.includes("/reference/") @@ -41,9 +38,6 @@ export const DocsLayout = (props: DocsLayoutProps) => { return ( <Show when="{props.entries}" keyed> <> - <Show when="{titles()?.title}" fallback="{<Title">SolidDocs</Title>}> - {(title) => <Title>{`${title()} - ${projectTitle()}`}</Title>} - </Show> <article class="expressive-code-overrides mx-auto w-full max-w-2xl overflow-hidden pb-16"> <Show when="{titles()?.parent}"> {(t) => ( @@ -62,7 +56,7 @@ export const DocsLayout = (props: DocsLayoutProps) => { <span class="-mt-[15px] block text-sm xl:hidden"> <EditPageLink /> </span> - <div class="w-full">{props.children}</div> + <div class="w-full px-1">{props.children}</div> <span class="text-sm xl:hidden"> <PageIssueLink /> </span> diff --git a/src/ui/eraser-link/index.tsx b/src/ui/eraser-link/index.tsx index 76bdd6f46..f0e3bfcc0 100644 --- a/src/ui/eraser-link/index.tsx +++ b/src/ui/eraser-link/index.tsx @@ -67,6 +67,7 @@ const EraserLink = ( class="relative inline-block" target="_blank" rel="noopener noreferrer" + aria-label="View diagram on Eraser.io" > <img src="/prx/000/https/github.com/devagrawal09/solid-docs-next/compare/{,_ANDesc=img," @ -74,7 +75,7 @ const EraserLink="(" ? `${workspaceUrl}/preview?${elementParams}&type="embed`" : `${workspaceUrl}/preview } - alt='{""}' + alt="" onLoad="{()"> setIsLoaded(true)} /> {isLoaded() ? ( diff --git a/src/ui/layout.tsx b/src/ui/layout.tsx index 74d52a96e..7d18820c5 100644 --- a/src/ui/layout.tsx +++ b/src/ui/layout.tsx @@ -157,7 +157,10 @@ export const Layout: ParentComponent<{ isError?: boolean }> = (props) => { </Suspense> </div> </Show> - <main class="prose prose-slate w-full flex-auto px-4 pt-2 dark:prose-invert md:max-w-2xl md:pb-16 lg:max-w-none dark:text-slate-300"> + <main + class="prose prose-slate w-full flex-auto px-4 pt-2 dark:prose-invert md:max-w-2xl md:pb-16 lg:max-w-none dark:text-slate-300" + aria-live="polite" +> <Show when="{!useCurrentRouteMetaData().isProjectRoot}" keyed diff --git a/src/ui/layout/mobile-navigation.tsx b/src/ui/layout/mobile-navigation.tsx index 48c028eec..e1714da87 100644 - a/src/ui/layout/mobile-navigation.tsx + b/src/ui/layout/mobile-navigation.tsx @ -24,7 +24,10 @ export const [isOpen setIsOpen="createSignal(false);" export const MobileNavigation="(props:" NavProps=""> { return ( <Dialog.Root open="{isOpen()}" onOpenChange="{setIsOpen}"> - <Dialog.Trigger> + <Dialog.Trigger + aria-label="Open navigation menu" + title="Open navigation menu" +> <Icon path="{bars_3}" class="prose h-6 dark:prose-invert" /> </Dialog.Trigger> <Dialog.Portal> diff --git a/src/ui/logo.tsx b/src/ui/logo.tsx index 3de2faba9..97a1fd58a 100644 --- a/src/ui/logo.tsx +++ b/src/ui/logo.tsx @@ -4,7 +4,6 @@ import { Match, Switch } from "solid-js"; const SolidLogo = (props: { class?: string }) => ( <svg {...props - data-hk="0-0-0-0-0-0-0-0-0-1-0-0-0-0-0-0-0-0-1-1-1-0-1-0" width="100%" height="100%" xmlns="http://www.w3.org/2000/svg" diff --git a/src/ui/search.tsx b/src/ui/search.tsx index 1a2c3e0e8..2e5ef9c94 100644 - a/src/ui/search.tsx + b/src/ui/search.tsx @ -1,4 +1,4 @ -import { OramaClient } from @oramacloud/client ; +import { OramaCloud type SearchResult } from @orama/core ; import { createEffect createSignal @ -16,23 +16,17 @ import { createEventListener } from @solid-primitives/event-listener ; import { isAppleDevice } from @solid-primitives/platform ; function getOramaClient - endpoint - api_key - Record><"endpoint" | "api_key", string | null>) { - return endpoint && api_key - ? new OramaClient({ - endpoint, - api_key, + projectId, + apiKey, +}: Record<"projectId" | "apiKey", string | null>) { + return projectId && apiKey + ? new OramaCloud({ + projectId, + apiKey, }) : null; } -type OramaResult = { - hits: { - document: OramaDocument; - }[]; -}; - type OramaDocument = { content: string; path: string; @@ -41,8 +35,8 @@ type OramaDocument = { }; const client = getOramaClient({ - endpoint: import.meta.env.VITE_ORAMA_ENDPOINT ?? null, - api_key: import.meta.env.VITE_ORAMA_API_KEY ?? null, + projectId: import.meta.env.VITE_ORAMA_PROJECT_ID ?? null, + apiKey: import.meta.env.VITE_ORAMA_PUBLIC_API_KEY ?? null, }); export function Search() { @@ -58,11 +52,22 @@ export function Search() { async () => { const _searchTerm = searchTerm(); if (!_searchTerm) return {}; - const result: OramaResult | null = await client.search({ + const result = (await client.search({ term: _searchTerm, mode: "fulltext", - }); + datasources: [], + })) as SearchResult<OramaDocument>; if (!result) return {}; + + const seen: Record<string, boolean> = {}; + result.hits = result.hits.filter((hit) => { + hit.document.path = hit.document.path.replace("/index#", "#"); + if (!seen[hit.document.path]) { + seen[hit.document.path] = true; + return hit; + } + }); + const groupedHits = result.hits.reduce( (groupedHits, hit) => { const section = hit.document.section.replace( @@ -75,7 +80,7 @@ export function Search() { groupedHits[section].push(hit); return groupedHits; }, - {} as Record<string, OramaResult hits ]> + {} as Record<string, SearchResult><OramaDocument>["hits"]> ); setActive(0); setResultRefs([]); @@ -237,8 +242,10 @@ export function Search() { <For each="{Object.entries(result())}"> {([section, hits]) => ( <section> - <p class="pl-2 pt-2 text-sm text-black/70 dark:text-white/70"> - {section} + <p class="pl-2 pt-2 text-sm capitalize text-black/70 dark:text-white/70"> + {section + .replace(/^Enum$'(.+)'$$/, "$1") + .replace(/-/g, " ")} </p> <ul role="listbox"> <For each="{hits}"> @@ -823,8 +830,7 @@ function KeyboardShortcut(props: { key: string; class?: string }) { return ( <kbd classList="{{" - min-w-6 rounded border border-black/10 bg-slate-100 dark:bg-slate-700 dark:border-slate-700 px-1 pb-px pt-1 text-center font-mono text-xs : - true + min-w-6 rounded border border-black/10 bg-slate-100 dark:bg-slate-700 dark:border-slate-700 px-1 pb-px pt-1 text-center font-mono text-xs : true [props.class ? ] true }> diff --git a/src/ui/use-project.ts b/src/ui/use-project.ts index 089391389..e104929e7 100644 --- a/src/ui/use-project.ts +++ b/src/ui/use-project.ts @@ -1,4 +1,4 @@ -import { createEffect, createSignal, type Accessor } from "solid-js"; +import { createRenderEffect, createSignal, type Accessor } from "solid-js"; import { useMatch } from "@solidjs/router"; import { SUPPORTED_LOCALES } from "~/i18n/config"; import { useI18n } from "~/i18n/i18n-context"; @@ -19,7 +19,7 @@ export function useProjectTitle(): Accessor<string> { const project = useProject(); const i18n = useI18n(); - createEffect(() => { + createRenderEffect(() => { switch (project()) { case "solid-start": setTitle(i18n.t("meta.title.solid_start"));

Welcome to Counter App

Hi, I am {data().name}.

Hello, {store.users[0].username}

I'm JSX!!

I'm JSX!!

My Task List for Today

About

About

About

About

{user()?.name}

{user()?.name}

About

About

Users

Users

About

About

About

About