diff --git a/src/routes/reference/reactive-utilities/batch.mdx b/src/routes/reference/reactive-utilities/batch.mdx index 539109ecc..1763c9819 100644 --- a/src/routes/reference/reactive-utilities/batch.mdx +++ b/src/routes/reference/reactive-utilities/batch.mdx @@ -9,14 +9,11 @@ function batch(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" @@ -28,8 +25,7 @@ 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 @@ -37,8 +33,7 @@ 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(() => { @@ -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(() => { @@ -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. diff --git a/src/routes/solid-router/concepts/actions.mdx b/src/routes/solid-router/concepts/actions.mdx index 7b9f70013..d194d75de 100644 --- a/src/routes/solid-router/concepts/actions.mdx +++ b/src/routes/solid-router/concepts/actions.mdx @@ -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 diff --git a/src/routes/solid-router/concepts/alternative-routers.mdx b/src/routes/solid-router/concepts/alternative-routers.mdx index 43b47d7d3..4f86f3751 100644 --- a/src/routes/solid-router/concepts/alternative-routers.mdx +++ b/src/routes/solid-router/concepts/alternative-routers.mdx @@ -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. diff --git a/src/routes/solid-router/concepts/catch-all.mdx b/src/routes/solid-router/concepts/catch-all.mdx index 06ab7854b..a08de71c5 100644 --- a/src/routes/solid-router/concepts/catch-all.mdx +++ b/src/routes/solid-router/concepts/catch-all.mdx @@ -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 @@ -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. \ No newline at end of file +Now, if a user navigates to a URL that does not match `/home` or `/about`, the `NotFound` component will be rendered. diff --git a/src/routes/solid-router/concepts/layouts.mdx b/src/routes/solid-router/concepts/layouts.mdx index bc47bb31a..bf6dcf534 100644 --- a/src/routes/solid-router/concepts/layouts.mdx +++ b/src/routes/solid-router/concepts/layouts.mdx @@ -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. 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 926e62f22..a1eb079b0 100644 --- a/src/routes/solid-start/building-your-application/api-routes.mdx +++ b/src/routes/solid-start/building-your-application/api-routes.mdx @@ -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. 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 d12ff5078..8fb11d3a0 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 @@ -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"; 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 01b76439d..e7c8c3627 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 @@ -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: @@ -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 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 9a12c838d..7b4a1aaa1 100644 --- a/src/routes/solid-start/building-your-application/route-prerendering.mdx +++ b/src/routes/solid-start/building-your-application/route-prerendering.mdx @@ -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"; @@ -31,4 +31,4 @@ export default defineConfig({ }); ``` -For more information on prerender options, check out [Nitro's documentation](https://nitro.unjs.io/config#prerender) \ No newline at end of file +For more information on prerender options, check out [Nitro's documentation](https://nitro.unjs.io/config#prerender) diff --git a/src/routes/solid-start/building-your-application/routing.mdx b/src/routes/solid-start/building-your-application/routing.mdx index ea0257c5d..c4ccf8480 100644 --- a/src/routes/solid-start/building-your-application/routing.mdx +++ b/src/routes/solid-start/building-your-application/routing.mdx @@ -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** — define the user interface in your app @@ -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 [``](/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, `` will generate the routes for you based on the file system. Because `` 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"; @@ -37,7 +37,8 @@ export default function App() { ``` The `` 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 `` 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 `` since each component will be lazy-loaded automatically. +Without this, you could see some unexpected hydration errors. `` 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: @@ -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. @@ -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: 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 93a640ade..655978293 100644 --- a/src/routes/solid-start/building-your-application/static-assets.mdx +++ b/src/routes/solid-start/building-your-application/static-assets.mdx @@ -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. \ No newline at end of file +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/index.mdx b/src/routes/solid-start/index.mdx index e1d9c3123..f91a992ea 100644 --- a/src/routes/solid-start/index.mdx +++ b/src/routes/solid-start/index.mdx @@ -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!