Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 18 additions & 38 deletions src/routes/reference/reactive-utilities/batch.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,11 @@ 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.
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.

Batching improves performance by avoiding unnecessary recalculation.
Suppose you have a downstream memo `down` that depends on
multiple upstream signals `up1`, `up2`, and `up3`:
Suppose you have a downstream memo `down` that depends on multiple upstream signals `up1`, `up2`, and `up3`:

```ts
import { createSignal, createMemo, createEffect } from "solid-js"
Expand All @@ -28,17 +25,15 @@ const down = createMemo(() => up1() + up2() + up3())
createEffect(() => console.log(down())) // outputs 6
```

If you directly update all of the upstream signals outside of batch mode,
then `down` will recompute every time.
If you directly update all of the upstream signals outside of batch mode, then `down` will recompute every time.

```ts
setUp1(4) // recomputes down, outputs 9
setUp2(5) // recomputes down, outputs 12
setUp3(6) // recomputes down, outputs 15
```

If instead you update the upstream signals within a `batch`, then `down`
will update only once at the end:
If instead you update the upstream signals within a `batch`, then `down` will update only once at the end:

```ts
batch(() => {
Expand All @@ -48,33 +43,21 @@ batch(() => {
}) // recomputes down, outputs 30
```

The impact is even more dramatic if you have *m* downstream computations
(memos, effects, etc.) that each depend 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.
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:
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)
* 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:
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:

```ts
batch(() => {
Expand All @@ -88,9 +71,6 @@ batch(() => {
}) // recomputes down, outputs 36
```

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.
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.
It also means that, if `fn` is asynchronous, only the updates before the first `await` will be batched.
2 changes: 1 addition & 1 deletion src/routes/solid-router/concepts/actions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Actions are Solid Router’s solution to this problem.

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 submission.
This flexibility makes actions a powerful tool for managing and tracking data submissions.

### How actions work

Expand Down
2 changes: 1 addition & 1 deletion src/routes/solid-router/concepts/alternative-routers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ render(

## Memory mode

Unlike the default router and hash, memory router does not interact with the browser's URL.
Unlike the default router and hash, the memory router does not interact with the browser's URL.
This means that while the URL in the browser's address bar will change, the router will not navigate to the new route.
This gives you the ability to control the router's state and history in memory which can be useful for testing purposes.

Expand Down
4 changes: 2 additions & 2 deletions src/routes/solid-router/concepts/catch-all.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ title: Catch-all routes
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 a asteriks `*` as the path at the end of the route list.
To create a catch-all route, place a route with an asterisk (`*`) as the path at the end of the route list.
Optionally, you can name the parameter to access the unmatched part of the URL.

```jsx
Expand All @@ -24,4 +24,4 @@ const App = () => (
);
```

Now, if a user navigates to a URL that does not match `/home` or `/about`, the `NotFound` component will be rendered.
Now, if a user navigates to a URL that does not match `/home` or `/about`, the `NotFound` component will be rendered.
2 changes: 1 addition & 1 deletion src/routes/solid-router/concepts/layouts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ render(
);
```

With the root-level layout, `props.children` will be replaced with the content of current route.
With the root-level layout, `props.children` will be replaced with the content of the current route.
This means that while the words "Header" and "Footer" will be displayed on every page, the content between them will change depending on the current route.
For example, when the route is `/hello-world`, you will see the text "Hello world!" between the header and footer.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ While Server Functions can be a good way to write server-side code for data need
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.
- Exposing a public-facing REST API.
- Writing webhooks or auth callback handlers for OAuth.
- Having URLs not serving HTML, but other kinds of documents like PDFs or images.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ This is because, behind the scenes, classes defined in CSS modules are renamed t
When classes are hard coded using the class attribute (`class="card"`), Solid is not aware that it should rename `card` to something different.

To fix this, you can import classes used in your CSS module.
The import object can be thought of as `humanClass: generatedClass` and within the component, they key (ie. the class on the element) is used to get the unique, generated class name.
The import object can be thought of as `humanClass: generatedClass` and within the component, the key (ie. the class on the element) is used to get the unique, generated class name.

```jsx
import styles from "./Card.module.css";
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ export default function 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.
`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
## Adding a site suffix in Title

Custom components can be created to wrap the `Title` component to add a site-specific prefix to all the titles:

Expand Down Expand Up @@ -112,7 +112,7 @@ export default function Root() {
}
```

If you need to add route specific information inside your route, much like the `Title` component, you can use the `Meta` component within the desired route.
If you need to add route-specific information inside your route, much like the `Title` component, you can use the `Meta` component within the desired route.
This overrides the `Meta` tags used within the `Head` component.

```tsx
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: "Route pre-rendering"
---

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.
The easiest way to accomplish this is by passing a list of routes to be pre-rendered to the `routes` option.

```js { 6 }
import { defineConfig } from "@solidjs/start/config";
Expand Down Expand Up @@ -31,4 +31,4 @@ export default defineConfig({
});
```

For more information on prerender options, check out [Nitro's documentation](https://nitro.unjs.io/config#prerender)
For more information on prerender options, check out [Nitro's documentation](https://nitro.unjs.io/config#prerender)
14 changes: 8 additions & 6 deletions src/routes/solid-start/building-your-application/routing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: "Routing"
---

Routing serves as a key component to web applications.
Routing serves as a key component of web applications.
Within SolidStart, there are two types:

- **UI routes** &mdash; define the user interface in your app
Expand All @@ -16,11 +16,11 @@ SolidStart uses file based routing which is a way of defining your routes by cre
This includes your pages and API routes.

SolidStart traverses your `routes` directory, collects all of the routes, and then makes them accessible using the [`<FileRoutes />`](/solid-start/reference/routing/file-routes).
This component will only include your UI routes, and not your API routes.
This component will only include your UI routes, not your API routes.
Rather than manually defining each `Route` inside a `Router` component, `<FileRoutes />` will generate the routes for you based on the file system.

Because `<FileRoutes />` returns a routing config object, you can use it with the router of your choice.
In this example we use [`solid-router`](/solid-router):
In this example, we use [`solid-router`](/solid-router):

```tsx {7-9} title="app.tsx"
import { Suspense } from "solid-js";
Expand All @@ -37,7 +37,8 @@ export default function App() {
```

The `<Router />` component expects a `root` prop which functions as the root layout of your entire app.
You will want to make sure `props.children` is wrapped in `<Suspense />` because each component will be lazy loaded automatically for you. Without this you may see some unexpected hydration errors.
You will want to make sure `props.children` is wrapped in `<Suspense />` since each component will be lazy-loaded automatically.
Without this, you could see some unexpected hydration errors.

`<FileRoutes />` will generate a route for each file in the `routes` directory and its subdirectories. For a route to be rendered as a page, it must default export a component.
This component represents the content that will be rendered when users visit the page:
Expand Down Expand Up @@ -84,7 +85,8 @@ If you want to create nested layouts you can create a file with the same name as
|-- article-2.tsx // example.com/blog/article-2
```

In this case the `blog.tsx` file will act as a layout for the articles in the `blog` folder. You can reference the child content
In this case, the `blog.tsx` file will act as a layout for the articles in the `blog` folder.
You can reference the child's content
by using `props.children` in the layout.

<TabsCodeBlocks>
Expand Down Expand Up @@ -113,7 +115,7 @@ export default function BlogLayout(props) {
By default, the component that is rendered for a route comes from the default export of the `index.tsx` file in each folder.
However, this can make it difficult to find the correct `index.tsx` file when searching, since there will be multiple files with that name.

To avoid this, you can rename the `index.tsx` file to the name of the folder it is in, enclosed in parenthesis.
To avoid this, you can rename the `index.tsx` file to the name of the folder it is in, enclosed in parentheses.

This way, it will be treated as the default export for that route:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -69,10 +69,10 @@ For example, `solid.png` will become `solid.2d8efhg.png`.
## Public directory versus imports

The public directory and imports are both valid ways to include static assets in your project.
The driver to using one over the other is based on your use case.
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.
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.
This can be beneficial for cache busting but detrimental if you want to send someone a link to the asset.
This can be beneficial for cache busting but detrimental if you want to send someone a link to the asset.
2 changes: 1 addition & 1 deletion src/routes/solid-start/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ SolidStart features the following capabilities:

Before you start using SolidStart, you should have a basic understanding of web development.
This includes knowledge of HTML, CSS, and JavaScript.
With SolidStart being a Solid meta-framework, we recommend knowing Solid prior to digging in to these docs (or at least [taking the Solid tutorial](https://www.solidjs.com/tutorial)).
With SolidStart being a Solid meta-framework, we recommend learning Solid prior to reading these docs (or at least [taking the Solid tutorial](https://www.solidjs.com/tutorial)).

## SolidStart 1.0 is here!

Expand Down
Loading