diff --git a/packages/docs/public/_redirects b/packages/docs/public/_redirects index 326b660ba94..e5bc37e4161 100644 --- a/packages/docs/public/_redirects +++ b/packages/docs/public/_redirects @@ -69,4 +69,4 @@ /docs/components/inline-components/ /docs/core/overview/ 308 /docs/think-qwik/ /docs/concepts/think-qwik/ 308 /docs/env-variables/ /docs/guides/env-variables/ 308 -/docs/components/ /docs/core/ 308 +/docs/components/* /docs/core/:splat 308 diff --git a/packages/docs/src/components/on-this-page/on-this-page.tsx b/packages/docs/src/components/on-this-page/on-this-page.tsx index 35d7923cc44..f791225736f 100644 --- a/packages/docs/src/components/on-this-page/on-this-page.tsx +++ b/packages/docs/src/components/on-this-page/on-this-page.tsx @@ -100,7 +100,7 @@ const makeEditPageUrl = (url: string): string => { if (index !== -1 && index + 1 >= segments.length) { // These are directory paths without subpaths, map to their overview pages if (componentIndex !== -1) { - return 'docs/(qwik)/components/overview'; + return 'docs/(qwik)/core/overview'; } else if (conceptIndex !== -1) { return 'docs/(qwik)/concepts/think-qwik'; } diff --git a/packages/docs/src/routes/docs/(qwik)/concepts/reactivity/index.mdx b/packages/docs/src/routes/docs/(qwik)/concepts/reactivity/index.mdx index c33c87154f7..16486c339a9 100644 --- a/packages/docs/src/routes/docs/(qwik)/concepts/reactivity/index.mdx +++ b/packages/docs/src/routes/docs/(qwik)/concepts/reactivity/index.mdx @@ -46,7 +46,7 @@ Qwik uses proxies for a few reasons: Because of the above constraints, Qwik uses proxies to keep track of the reactivity graph. -- Use [`useStore()`](/docs/(qwik)/components/state/index.mdx#usestore) to create a store proxy. +- Use [`useStore()`](/docs/(qwik)/core/state/index.mdx#usestore) to create a store proxy. - The proxy notices the reads and creates subscriptions that are serializable. - The proxy notices the writes and uses the subscription information to invalidate the relevant components. diff --git a/packages/docs/src/routes/docs/(qwik)/core/events/index.mdx b/packages/docs/src/routes/docs/(qwik)/core/events/index.mdx index 7c0cfaf4f29..77839ba4c89 100644 --- a/packages/docs/src/routes/docs/(qwik)/core/events/index.mdx +++ b/packages/docs/src/routes/docs/(qwik)/core/events/index.mdx @@ -57,7 +57,7 @@ export default component$(() => { ``` -You can also use `bind:propertyName` to conveniently have a [two-way binding](/docs/(qwik)/components/rendering/index.mdx#bind-attribute) between a signal and an input element. +You can also use `bind:propertyName` to conveniently have a [two-way binding](/docs/(qwik)/core/rendering/index.mdx#bind-attribute) between a signal and an input element. Notice that `onClick$` ends with [`$`](/docs/(qwik)/advanced/dollar/index.mdx). This is a hint to both the [Optimizer](/docs/(qwik)/advanced/optimizer/index.mdx) and the developer that a special transformation occurs at this location. The presence of the `$` suffix implies a lazy-loaded boundary here. The code associated with the `click` handler is not loaded into the JavaScript Virtual Machine (VM) until the user activates the click event. However, to avoid delays during the first interaction, it is eagerly loaded into the browser cache. diff --git a/packages/docs/src/routes/docs/(qwik)/core/state/index.mdx b/packages/docs/src/routes/docs/(qwik)/core/state/index.mdx index 1671c0448ca..228e9b79355 100644 --- a/packages/docs/src/routes/docs/(qwik)/core/state/index.mdx +++ b/packages/docs/src/routes/docs/(qwik)/core/state/index.mdx @@ -123,7 +123,7 @@ export default component$(() => { > **NOTE** For reactivity to work as expected, make sure to keep a reference to the reactive object and not only to its properties. e.g. doing `let { count } = useStore({ count: 0 })` and then mutating `count` won't trigger updates of components that depend on the property. -Because [`useStore()`](/docs/(qwik)/components/state/index.mdx#usestore) tracks deep reactivity, that means that Arrays and Objects inside the store will also be reactive. +Because [`useStore()`](/docs/(qwik)/core/state/index.mdx#usestore) tracks deep reactivity, that means that Arrays and Objects inside the store will also be reactive. ```tsx @@ -225,10 +225,10 @@ In Qwik, there are two ways to create computed values, each with a different use 1. `useComputed$()`: `useComputed$()` is the preferred way of creating computed values. Use it when the computed value can be derived synchronously purely from the source state (current application state). For example, creating a lowercase version of a string or combining first and last names into a full name. -2. [`useResource$()`](/docs/(qwik)/components/state/index.mdx#useresource): `useResource$()` is used when the computed value is asynchronous or the state comes from outside of the application. For example, fetching the current weather (external state) based on a current location (application internal state). +2. [`useResource$()`](/docs/(qwik)/core/state/index.mdx#useresource): `useResource$()` is used when the computed value is asynchronous or the state comes from outside of the application. For example, fetching the current weather (external state) based on a current location (application internal state). -In addition to the two ways of creating computed values described above, there is also a lower-level ([`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask)). This way does not produce a new signal, but rather modifies the existing state or produces a side effect. +In addition to the two ways of creating computed values described above, there is also a lower-level ([`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask)). This way does not produce a new signal, but rather modifies the existing state or produces a side effect. ### `useComputed$()` @@ -390,7 +390,7 @@ The state `resource.loading` can be one of the following: - `false` - the data is not yet available. - `true` - the data is available. (Either resolved or rejected.) -The callback passed to [`useResource$()`](/docs/(qwik)/components/state/index.mdx#useresource) runs right after the [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) callbacks complete. Please refer to the [Lifecycle](../tasks/index.mdx#lifecycle) section for more details. +The callback passed to [`useResource$()`](/docs/(qwik)/core/state/index.mdx#useresource) runs right after the [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) callbacks complete. Please refer to the [Lifecycle](../tasks/index.mdx#lifecycle) section for more details. #### `` diff --git a/packages/docs/src/routes/docs/(qwik)/core/styles/index.mdx b/packages/docs/src/routes/docs/(qwik)/core/styles/index.mdx index 784ec1f878e..a030bbafcdc 100644 --- a/packages/docs/src/routes/docs/(qwik)/core/styles/index.mdx +++ b/packages/docs/src/routes/docs/(qwik)/core/styles/index.mdx @@ -479,7 +479,7 @@ The problem with this approach is that we will load styles twice. 1. The styles are inserted into the HTML as part of the SSR. 2. Then when the component is invalidated and needs to be re-rendered, the styles are loaded again because they are inlined. -What is needed is to load the styles independently from the component. This is what [`useStyles$()`](/docs/(qwik)/components/styles/index.mdx#usestyles) is for. There are two scenarios: +What is needed is to load the styles independently from the component. This is what [`useStyles$()`](/docs/(qwik)/core/styles/index.mdx#usestyles) is for. There are two scenarios: 1. The component is rendered on the server and the styles are inserted into `` as part of the SSR. - Adding a new instance of a component to the application does not require that we load the styles as they are already included as part of SSR. diff --git a/packages/docs/src/routes/docs/(qwik)/core/tasks/index.mdx b/packages/docs/src/routes/docs/(qwik)/core/tasks/index.mdx index 985237321b4..e2cd73705c9 100644 --- a/packages/docs/src/routes/docs/(qwik)/core/tasks/index.mdx +++ b/packages/docs/src/routes/docs/(qwik)/core/tasks/index.mdx @@ -93,7 +93,7 @@ When the user interacts with the application, it resumes on the client-side, con `useTask$()` registers a hook to be executed upon component creation, it will run at least once either in the server or in the browser, depending on where the component is initially rendered. -Additionally, this task can be reactive and will re-execute when **tracked** [state](/docs/(qwik)/components/state/index.mdx) changes. +Additionally, this task can be reactive and will re-execute when **tracked** [state](/docs/(qwik)/core/state/index.mdx) changes. **Notice that any subsequent re-execution of the task will always happen in the browser**, because reactivity is a browser-only thing. @@ -323,7 +323,7 @@ export default component$(() => { ## `useVisibleTask$()` -Sometimes a task needs to run only on the browser and after rendering, in that case, you should use `useVisibleTask$()`. The `useVisibleTask$()` is similar to `useTask$()` but it only runs on the browser and after initial rendering. `useVisibleTask$()` registers a hook to be executed when the component becomes visible in the viewport, it will run at least once in the browser, and it can be reactive and re-execute when some **tracked** [state](/docs/(qwik)/components/state/index.mdx) changes. +Sometimes a task needs to run only on the browser and after rendering, in that case, you should use `useVisibleTask$()`. The `useVisibleTask$()` is similar to `useTask$()` but it only runs on the browser and after initial rendering. `useVisibleTask$()` registers a hook to be executed when the component becomes visible in the viewport, it will run at least once in the browser, and it can be reactive and re-execute when some **tracked** [state](/docs/(qwik)/core/state/index.mdx) changes. `useVisibleTask$()` has these properties: diff --git a/packages/docs/src/routes/docs/(qwik)/faq/index.mdx b/packages/docs/src/routes/docs/(qwik)/faq/index.mdx index b0627736b36..47d8d44c3cc 100644 --- a/packages/docs/src/routes/docs/(qwik)/faq/index.mdx +++ b/packages/docs/src/routes/docs/(qwik)/faq/index.mdx @@ -72,7 +72,7 @@ We also have an interactive [tutorial](../../tutorial/welcome/overview/) to get ## What are all those `$` signs? -You might have noticed there are more [`$`](../advanced/dollar/index.mdx) signs than usual in Qwik apps, such as: [`component$()`](/docs/(qwik)/components/overview/index.mdx#component), [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask), and `
console.log('click')} />`. It serves as a marker for a lazy-load boundary. Qwik breaks your application into small chunks; these pieces are smaller than the component itself. For event handlers, hooks, etc. The `$` signals to both the [optimizer](../advanced/optimizer/index.mdx) and the developer when it's happening. +You might have noticed there are more [`$`](../advanced/dollar/index.mdx) signs than usual in Qwik apps, such as: [`component$()`](/docs/(qwik)/core/overview/index.mdx#component), [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask), and `
console.log('click')} />`. It serves as a marker for a lazy-load boundary. Qwik breaks your application into small chunks; these pieces are smaller than the component itself. For event handlers, hooks, etc. The `$` signals to both the [optimizer](../advanced/optimizer/index.mdx) and the developer when it's happening. **Example:** diff --git a/packages/docs/src/routes/docs/(qwik)/getting-started/index.mdx b/packages/docs/src/routes/docs/(qwik)/getting-started/index.mdx index f6f3081dbd6..834629baf67 100644 --- a/packages/docs/src/routes/docs/(qwik)/getting-started/index.mdx +++ b/packages/docs/src/routes/docs/(qwik)/getting-started/index.mdx @@ -142,7 +142,7 @@ export default component$(() => { > > - Your `joke` route default component is surrounded by an existing layout. See [Layout](/docs/layout/) for more details on what layouts are and how to work with them. > - index.tsx, layout.tsx in routes folder, root.tsx and all entry files need **export default**. For other components you can use export const and export function -> - For more details about how to author components, see the [Component API](/docs/(qwik)/components/overview/index.mdx) section. +> - For more details about how to author components, see the [Component API](/docs/(qwik)/core/overview/index.mdx) section. ### 2. Loading Data @@ -623,9 +623,9 @@ For more on just how much you can achieve with Qwik, check out the dedicated doc - [Project structure](/docs/(qwikcity)/project-structure/index.mdx) - [Directory-based routing](/docs/(qwikcity)/routing/index.mdx#directory-based-routing) -- [Component](/docs/(qwik)/components/overview/index.mdx) +- [Component](/docs/(qwik)/core/overview/index.mdx) - [Route loaders](/docs/(qwikcity)/route-loader/index.mdx) - [Form actions](/docs/(qwikcity)/action/index.mdx) && [zod validation](/docs/(qwikcity)/action/index.mdx#validation-and-type-safety) -- [State management](/docs/(qwik)/components/state/index.mdx) -- [Tasks](/docs/(qwik)/components/tasks/index.mdx#use-usetask-when-you-need-to) +- [State management](/docs/(qwik)/core/state/index.mdx) +- [Tasks](/docs/(qwik)/core/tasks/index.mdx#use-usetask-when-you-need-to) - [Preloading](/docs/(qwikcity)/advanced/speculative-module-fetching/index.mdx) diff --git a/packages/docs/src/routes/docs/(qwikcity)/advanced/menu/index.mdx b/packages/docs/src/routes/docs/(qwikcity)/advanced/menu/index.mdx index e54811fc887..82d3b2e9b9c 100644 --- a/packages/docs/src/routes/docs/(qwikcity)/advanced/menu/index.mdx +++ b/packages/docs/src/routes/docs/(qwikcity)/advanced/menu/index.mdx @@ -63,7 +63,7 @@ Use `menu.md` to declare the menu structure. ## Components -- [Basics](/docs/(qwik)/components/basics/index.mdx) +- [Basics](/docs/(qwik)/core/basics/index.mdx) ``` ## Retrieving Menu Structure @@ -90,7 +90,7 @@ The example above will return: items: [ { text: "Basics", - href: "/docs/(qwik)/components/basics" + href: "/docs/(qwik)/core/basics" } ], }, diff --git a/packages/docs/src/routes/docs/menu.md b/packages/docs/src/routes/docs/menu.md index 0f59c68e70a..d77d6583a3f 100644 --- a/packages/docs/src/routes/docs/menu.md +++ b/packages/docs/src/routes/docs/menu.md @@ -9,14 +9,14 @@ ## Components -- [Overview]() -- [State]() -- [Events]() -- [Tasks & Lifecycle]() -- [Context]() -- [Slots]() -- [Rendering]() -- [Styling]() +- [Overview]() +- [State]() +- [Events]() +- [Tasks & Lifecycle]() +- [Context]() +- [Slots]() +- [Rendering]() +- [Styling]() - [API Reference](/api/qwik/) ## Qwik City diff --git a/packages/docs/src/routes/tutorial/component/basic/index.mdx b/packages/docs/src/routes/tutorial/component/basic/index.mdx index 0395ccccf63..aefffe1d563 100644 --- a/packages/docs/src/routes/tutorial/component/basic/index.mdx +++ b/packages/docs/src/routes/tutorial/component/basic/index.mdx @@ -10,6 +10,6 @@ updated_at: '2023-06-25T19:43:33Z' created_at: '2022-08-02T12:07:45Z' --- -Components are the building blocks of a Qwik application. Components are declared using [`component$()`](/docs/(qwik)/components/overview/index.mdx#component) and at a minimum need to return a JSX Element. +Components are the building blocks of a Qwik application. Components are declared using [`component$()`](/docs/(qwik)/core/overview/index.mdx#component) and at a minimum need to return a JSX Element. Create a component that returns `Hello World!` diff --git a/packages/docs/src/routes/tutorial/component/lite/index.mdx b/packages/docs/src/routes/tutorial/component/lite/index.mdx index a206b800aa2..eb37730f939 100644 --- a/packages/docs/src/routes/tutorial/component/lite/index.mdx +++ b/packages/docs/src/routes/tutorial/component/lite/index.mdx @@ -15,8 +15,8 @@ created_at: '2023-02-11T08:04:18Z' One of Qwik's super powers lies in its lazy-loading features. Each component will generate a separate Symbol which is downloaded on demand. This allows you to build a large application with many components and only download the components that are needed for the current view. -But for some cases you may want to load a component together with the parent component. For example, if you have a `` component that is always used with the `` component, you may want to load the `` component with the `` component. This is called an [inline component](/docs/(qwik)/components/overview/index.mdx#inline-components). +But for some cases you may want to load a component together with the parent component. For example, if you have a `` component that is always used with the `` component, you may want to load the `` component with the `` component. This is called an [inline component](/docs/(qwik)/core/overview/index.mdx#inline-components). -In this example, the `` and a `` components are prepared for you. The `` component is declared using the [`component$()`](/docs/(qwik)/components/overview/index.mdx#component) method and is a Qwik component. Remove the [`component$()`](/docs/(qwik)/components/overview/index.mdx#component) to convert `` to a [inline component](/docs/(qwik)/components/overview/index.mdx#inline-components). +In this example, the `` and a `` components are prepared for you. The `` component is declared using the [`component$()`](/docs/(qwik)/core/overview/index.mdx#component) method and is a Qwik component. Remove the [`component$()`](/docs/(qwik)/core/overview/index.mdx#component) to convert `` to a [inline component](/docs/(qwik)/core/overview/index.mdx#inline-components). Open the `Symbols` tab and notice that the `` component is no longer an independent export, but instead is bundled as part of the `` component. diff --git a/packages/docs/src/routes/tutorial/context/basic/index.mdx b/packages/docs/src/routes/tutorial/context/basic/index.mdx index 04556d35eee..2e3b6bfb31d 100644 --- a/packages/docs/src/routes/tutorial/context/basic/index.mdx +++ b/packages/docs/src/routes/tutorial/context/basic/index.mdx @@ -17,8 +17,8 @@ The code to use a context is divided into three parts: - `createContextId()`: this creates a serializable ID for the context. Make sure that this ID is unique within your application. - `useContextProvider()`: In a parent component, call this method to publish the context value. All children (and grandchildren) that are descendants of this component will be able to retrieve the context. -- [`useContext()`](/docs/(qwik)/components/context/index.mdx#usecontext) to retrieve the context and use it in any component. +- [`useContext()`](/docs/(qwik)/core/context/index.mdx#usecontext) to retrieve the context and use it in any component. -In this example, we would like to pass the `TodosStore` to the `` component. Update the code to use [`useContext()`](/docs/(qwik)/components/context/index.mdx#usecontext) to retrieve the value. +In this example, we would like to pass the `TodosStore` to the `` component. Update the code to use [`useContext()`](/docs/(qwik)/core/context/index.mdx#usecontext) to retrieve the value. Contexts typically are stores, and as such, they must be serializable. diff --git a/packages/docs/src/routes/tutorial/events/synchronous-sync/index.mdx b/packages/docs/src/routes/tutorial/events/synchronous-sync/index.mdx index 709301b7ed1..d9545e0f0c8 100644 --- a/packages/docs/src/routes/tutorial/events/synchronous-sync/index.mdx +++ b/packages/docs/src/routes/tutorial/events/synchronous-sync/index.mdx @@ -65,4 +65,4 @@ For this reason, we recommended breaking up the event handlers into two parts: - **Your task:** Convert the `onClick$` from asynchronous event to synchronous event by using [`useVisibleTask$`](/docs/(qwik)/components/tasks/index.mdx#usevisibletask) lifecycle and [normal event registration](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener). + **Your task:** Convert the `onClick$` from asynchronous event to synchronous event by using [`useVisibleTask$`](/docs/(qwik)/core/tasks/index.mdx#usevisibletask) lifecycle and [normal event registration](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener). diff --git a/packages/docs/src/routes/tutorial/events/synchronous-visible/index.mdx b/packages/docs/src/routes/tutorial/events/synchronous-visible/index.mdx index 5f0b2e7ade3..02682257a78 100644 --- a/packages/docs/src/routes/tutorial/events/synchronous-visible/index.mdx +++ b/packages/docs/src/routes/tutorial/events/synchronous-visible/index.mdx @@ -24,4 +24,4 @@ There are two ways of processing events synchronously: This example shows how to eagerly execute code and set up a classical event handler with no restrictions but with the cost of eager execution. -**Your task:** Convert the `onClick$` from asynchronous event to synchronous event by using [`useVisibleTask$`](/docs/(qwik)/components/tasks/index.mdx#usevisibletask) lifecycle and [normal event registration](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener). +**Your task:** Convert the `onClick$` from asynchronous event to synchronous event by using [`useVisibleTask$`](/docs/(qwik)/core/tasks/index.mdx#usevisibletask) lifecycle and [normal event registration](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener). diff --git a/packages/docs/src/routes/tutorial/hooks/use-signal/index.mdx b/packages/docs/src/routes/tutorial/hooks/use-signal/index.mdx index 6a73feda81a..5a569026b69 100644 --- a/packages/docs/src/routes/tutorial/hooks/use-signal/index.mdx +++ b/packages/docs/src/routes/tutorial/hooks/use-signal/index.mdx @@ -15,7 +15,7 @@ updated_at: '2023-06-26T13:18:25Z' created_at: '2022-11-20T08:50:32Z' --- -Use `useSignal()` to store any single value similar to `useStore()`. `useSignal` is heavily optimized when it comes to re-rendering components. It is able to skip re-renderings of parent components even when the signal itself is defined in the parent. `useSignal` works with all [primitive types](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) as well as with not nested / flat objects. If you need to store arrays or complex objects use [useStore](/docs/(qwik)/components/state/index.mdx#usestore) instead. +Use `useSignal()` to store any single value similar to `useStore()`. `useSignal` is heavily optimized when it comes to re-rendering components. It is able to skip re-renderings of parent components even when the signal itself is defined in the parent. `useSignal` works with all [primitive types](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) as well as with not nested / flat objects. If you need to store arrays or complex objects use [useStore](/docs/(qwik)/core/state/index.mdx#usestore) instead. Some examples would be: diff --git a/packages/docs/src/routes/tutorial/hooks/use-task/index.mdx b/packages/docs/src/routes/tutorial/hooks/use-task/index.mdx index e6cf6096486..bda2746e5b6 100644 --- a/packages/docs/src/routes/tutorial/hooks/use-task/index.mdx +++ b/packages/docs/src/routes/tutorial/hooks/use-task/index.mdx @@ -10,14 +10,14 @@ updated_at: '2023-06-25T19:43:33Z' created_at: '2022-12-19T12:14:17Z' --- -Use [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) to execute a function before the initial render and whenever the tracking values change. The function executes before rendering, but it can't delay rendering, so if [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) is asynchronous, the rendering will happen before the [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) is fully executed. +Use [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) to execute a function before the initial render and whenever the tracking values change. The function executes before rendering, but it can't delay rendering, so if [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) is asynchronous, the rendering will happen before the [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) is fully executed. ## Tracking store changes -The [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) hook receives a `track()` function used for setting up subscriptions that will automatically rerun the [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) hook. The set of `track()` properties resets on each [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) execution, therefore it is important to always use `track()` to set up subscriptions anew. Because of this it is possible for the [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) to subscribe to different properties over time. +The [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) hook receives a `track()` function used for setting up subscriptions that will automatically rerun the [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) hook. The set of `track()` properties resets on each [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) execution, therefore it is important to always use `track()` to set up subscriptions anew. Because of this it is possible for the [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) to subscribe to different properties over time. ## Cleanup -The [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) hook can return a cleanup callback. This is useful for cleaning up any resources before new execution. +The [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) hook can return a cleanup callback. This is useful for cleaning up any resources before new execution. ### Example diff --git a/packages/docs/src/routes/tutorial/hooks/use-visible-task/index.mdx b/packages/docs/src/routes/tutorial/hooks/use-visible-task/index.mdx index c59679aabb2..b96035778c9 100644 --- a/packages/docs/src/routes/tutorial/hooks/use-visible-task/index.mdx +++ b/packages/docs/src/routes/tutorial/hooks/use-visible-task/index.mdx @@ -25,7 +25,7 @@ Qwik is resumable. Resumability means that the application starts on the server `useVisibleTask$()` is a client-only method. (There is no equivalent on the server.) -> **NOTE** See [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) for behavior that needs to be executed on both client and server. +> **NOTE** See [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) for behavior that needs to be executed on both client and server. ## When is `useVisibleTask$()` executed? diff --git a/packages/docs/src/routes/tutorial/introduction/resource/index.mdx b/packages/docs/src/routes/tutorial/introduction/resource/index.mdx index 38645fe139f..9dbbe79a79c 100644 --- a/packages/docs/src/routes/tutorial/introduction/resource/index.mdx +++ b/packages/docs/src/routes/tutorial/introduction/resource/index.mdx @@ -16,17 +16,17 @@ created_at: '2022-08-02T12:07:45Z' For this tutorial, we would like to fetch the list of repositories for a given GitHub organization. To aid you, we have added the `getRepositories()` function to the bottom of the file. Your task is to use the `getRepositories()` function to fetch the list of repositories whenever the user updates the `org` input. -Qwik provides [`useResource$()`](/docs/(qwik)/components/state/index.mdx) and `` to help you fetch and display data from the server. When fetching data the application can be in one of three states: +Qwik provides [`useResource$()`](/docs/(qwik)/core/state/index.mdx) and `` to help you fetch and display data from the server. When fetching data the application can be in one of three states: - `pending`: the data is being fetched from the server => Render `loading...` indicator. - `resolved`: the data has successfully been fetched from the server => Render the data. - `rejected`: the data could not be fetched from the server due to an error => Render the error. -Use [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function to set up how the data is fetched from the server. Use `` to display the data. +Use [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function to set up how the data is fetched from the server. Use `` to display the data. ## Fetching data -Use [`useResource$()`](/docs/(qwik)/components/state/index.mdx) to set up how the data is fetched from the server. +Use [`useResource$()`](/docs/(qwik)/core/state/index.mdx) to set up how the data is fetched from the server. ```jsx const reposResource = useResource$(({ track, cleanup }) => { @@ -45,11 +45,11 @@ Use [`useResource$()`](/docs/(qwik)/components/state/index.mdx) to set up how th }); ``` -The [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function returns a `ResourceReturn` object, which is a Promise-like object that can be serialized by Qwik. The [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function allows you to `track` store properties so that the [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function can be reactive on store changes. The `cleanup` function allows you to register code that needs to be run to release resources from the previous run. Finally, the [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function returns a promise that will resolve to the value. +The [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function returns a `ResourceReturn` object, which is a Promise-like object that can be serialized by Qwik. The [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function allows you to `track` store properties so that the [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function can be reactive on store changes. The `cleanup` function allows you to register code that needs to be run to release resources from the previous run. Finally, the [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function returns a promise that will resolve to the value. ## Rendering data -Use `` to display the data of [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function. The `` allows you to render different content depending if the resource is `pending`, `resolved` or `rejected`. +Use `` to display the data of [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function. The `` allows you to render different content depending if the resource is `pending`, `resolved` or `rejected`. On the server the `` does not render `loading` state, instead, it pauses rendering until the resource is resolved and will always render as either `resolved` or `rejected`. (On the client, the `` renders all states including `pending`.) diff --git a/packages/docs/src/routes/tutorial/introduction/store/index.mdx b/packages/docs/src/routes/tutorial/introduction/store/index.mdx index 624929abe22..df51791a990 100644 --- a/packages/docs/src/routes/tutorial/introduction/store/index.mdx +++ b/packages/docs/src/routes/tutorial/introduction/store/index.mdx @@ -9,14 +9,14 @@ updated_at: '2023-06-25T19:43:33Z' created_at: '2022-08-02T12:07:45Z' --- -Use [`useStore()`](/docs/(qwik)/components/state/index.mdx#usestore) to store the state of the component. The store's purpose is to: +Use [`useStore()`](/docs/(qwik)/core/state/index.mdx#usestore) to store the state of the component. The store's purpose is to: 1. store the state of the component 2. present the state as a proxy that can observe read/writes to the store 3. serialize the state of the store into JSON on application pause. 4. observe which properties of the store are used in a component template and create subscriptions to the store. The subscriptions are then used to automatically update the component template if a store changes. -Stores are declared inside the component's function using the [`useStore()`](/docs/(qwik)/components/state/index.mdx#usestore) function. Wrap the `github` assignment in the `useStore(...)` function call to create a store. +Stores are declared inside the component's function using the [`useStore()`](/docs/(qwik)/core/state/index.mdx#usestore) function. Wrap the `github` assignment in the `useStore(...)` function call to create a store. > **NOTE** > In this example, the store never changes. Therefore there is no way to observe automatic template re-rendering. In the next example, we will add a listener to the `` to demonstrate automatic template re-rendering. diff --git a/packages/docs/src/routes/tutorial/qrl/optimizer/index.mdx b/packages/docs/src/routes/tutorial/qrl/optimizer/index.mdx index 39b23815d29..85cac1bb105 100644 --- a/packages/docs/src/routes/tutorial/qrl/optimizer/index.mdx +++ b/packages/docs/src/routes/tutorial/qrl/optimizer/index.mdx @@ -11,7 +11,7 @@ created_at: '2022-08-02T12:07:45Z' For the application to be resumable it needs to have lots of entry points. For example, clicking on button `A` is a different entry point than clicking on button `B`. When we implement an application we don't usually think about entry points and so we typically end up with just one entry point or the `main()` function. -The Optimizer does its job by looking for functions that end in `$` character. For example, the Optimizer will transform a call to [`component$()`](/docs/(qwik)/components/overview/index.mdx#component) into an entry point. Notice that the name of the function doesn't matter only that it ends with the `$`. +The Optimizer does its job by looking for functions that end in `$` character. For example, the Optimizer will transform a call to [`component$()`](/docs/(qwik)/core/overview/index.mdx#component) into an entry point. Notice that the name of the function doesn't matter only that it ends with the `$`. Every time you see `$` you should think, there is a lazy-loaded boundary here. The implication is that the lazy-loaded content may require lazy-loading and hence can't be accessed synchronously. diff --git a/packages/docs/src/routes/tutorial/reactivity/explicit/index.mdx b/packages/docs/src/routes/tutorial/reactivity/explicit/index.mdx index 64aa84359fb..8ed32328efb 100644 --- a/packages/docs/src/routes/tutorial/reactivity/explicit/index.mdx +++ b/packages/docs/src/routes/tutorial/reactivity/explicit/index.mdx @@ -11,12 +11,12 @@ updated_at: '2023-06-25T19:43:33Z' created_at: '2022-08-02T12:07:45Z' --- -In addition to implicit reactivity created by the templates, Qwik supports explicit execution of code when a property changes. This is achieved through the [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) hook. [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) hooks execute before the component renders and can be asynchronous. The hook can also have a clean-up function that is invoked on the next hook execution or when the component is removed. +In addition to implicit reactivity created by the templates, Qwik supports explicit execution of code when a property changes. This is achieved through the [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) hook. [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) hooks execute before the component renders and can be asynchronous. The hook can also have a clean-up function that is invoked on the next hook execution or when the component is removed. In this example clicking on `+1` updates `count` immediately. What we would like is to update the `delay count` after a 2-second delay. If `count` is updated before the 2 seconds are up then the timer is restarted. -Notice that the [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) callback receives a `track` function. Use the `track` function to tell Qwik which properties should trigger the task's watcher. The `track` function creates subscriptions in the store. On each invocation of [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) the subscriptions are cleared, so it is important to always set up a new set of subscriptions. This is useful if the set of subscriptions changes during the function's lifetime. +Notice that the [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) callback receives a `track` function. Use the `track` function to tell Qwik which properties should trigger the task's watcher. The `track` function creates subscriptions in the store. On each invocation of [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) the subscriptions are cleared, so it is important to always set up a new set of subscriptions. This is useful if the set of subscriptions changes during the function's lifetime. -The [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) callback function can return a cleanup function. The clean-up function is invoked on the next [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) callback execution or when the component is removed. In our case, the cleanup function is used for returning code which clears the `setTimeout`. +The [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) callback function can return a cleanup function. The clean-up function is invoked on the next [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) callback execution or when the component is removed. In our case, the cleanup function is used for returning code which clears the `setTimeout`. -The [`useTask$()`](/docs/(qwik)/components/tasks/index.mdx#usetask) callbacks execute before the component is rendered. This allows them to be used to compute values used in rendering. The function runs on both server and client. The server execution sets up subscriptions that are then serialized and available to the client. This saves the client from having to download all of the components and execute them at least once to recover the subscription information for the system. +The [`useTask$()`](/docs/(qwik)/core/tasks/index.mdx#usetask) callbacks execute before the component is rendered. This allows them to be used to compute values used in rendering. The function runs on both server and client. The server execution sets up subscriptions that are then serialized and available to the client. This saves the client from having to download all of the components and execute them at least once to recover the subscription information for the system. diff --git a/packages/docs/src/routes/tutorial/reactivity/resource/index.mdx b/packages/docs/src/routes/tutorial/reactivity/resource/index.mdx index 8dbc5b8b99b..40198718b89 100644 --- a/packages/docs/src/routes/tutorial/reactivity/resource/index.mdx +++ b/packages/docs/src/routes/tutorial/reactivity/resource/index.mdx @@ -16,17 +16,17 @@ created_at: '2022-08-02T12:07:45Z' For this tutorial, we would like to fetch the list of repositories for a given GitHub organization. To aid you, we have added the `getRepositories()` function to the bottom of the file. Your task is to use the `getRepositories()` function to fetch the list of repositories whenever the user updates the `org` input. -Qwik provides [`useResource$()`](/docs/(qwik)/components/state/index.mdx) and `` to help you fetch and display data from the server. When fetching data the application can be in one of three states: +Qwik provides [`useResource$()`](/docs/(qwik)/core/state/index.mdx) and `` to help you fetch and display data from the server. When fetching data the application can be in one of three states: - `pending`: the data is being fetched from the server => Render `loading...` indicator. - `resolved`: the data has successfully been fetched from the server => Render the data. - `rejected`: the data could not be fetched from the server due to an error => Render the error. -Use [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function to set up how the data is fetched from the server. Use `` to display the data. +Use [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function to set up how the data is fetched from the server. Use `` to display the data. ## Fetching data -Use [`useResource$()`](/docs/(qwik)/components/state/index.mdx) to set up how the data is fetched from the server. +Use [`useResource$()`](/docs/(qwik)/core/state/index.mdx) to set up how the data is fetched from the server. ```jsx const reposResource = useResource$(({ track, cleanup }) => { @@ -45,11 +45,11 @@ Use [`useResource$()`](/docs/(qwik)/components/state/index.mdx) to set up how th }); ``` -The [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function returns a `ResourceReturn` object, which is a Promise-like object that can be serialized by Qwik. The [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function allows you to `track` store properties so that the [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function can be reactive on store changes. The `cleanup` function allows you to register a code that needs to be run to release resources from the previous run. Finally, the [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function returns a promise that will resolve to the value. +The [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function returns a `ResourceReturn` object, which is a Promise-like object that can be serialized by Qwik. The [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function allows you to `track` store properties so that the [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function can be reactive on store changes. The `cleanup` function allows you to register a code that needs to be run to release resources from the previous run. Finally, the [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function returns a promise that will resolve to the value. ## Rendering data -Use `` to display the data of the [`useResource$()`](/docs/(qwik)/components/state/index.mdx) function. The `` allows you to render different content depending if the resource is `pending`, `resolved` or `rejected`. +Use `` to display the data of the [`useResource$()`](/docs/(qwik)/core/state/index.mdx) function. The `` allows you to render different content depending if the resource is `pending`, `resolved` or `rejected`. On the server the `` does not render `loading` state, instead, it pauses rendering until the resource is resolved and will always render as either `resolved` or `rejected`. (On the client, the `` renders all states including `pending`.) diff --git a/packages/docs/src/routes/tutorial/store/basic/index.mdx b/packages/docs/src/routes/tutorial/store/basic/index.mdx index 67a32430aeb..bbc67d9327f 100644 --- a/packages/docs/src/routes/tutorial/store/basic/index.mdx +++ b/packages/docs/src/routes/tutorial/store/basic/index.mdx @@ -19,7 +19,7 @@ Qwik tracks application state for two reasons: The component on the right doesn't work yet because `counter` is just a plain object with no subscriptions. As a result, Qwik doesn't know when `counter.count` changes, and therefore doesn't know to re-render the `` component. -> **Your task:** Wrap `counter` in [`useStore()`](/docs/(qwik)/components/state/index.mdx#usestore) to enable dependency tracking and automatic re-rendering. +> **Your task:** Wrap `counter` in [`useStore()`](/docs/(qwik)/core/state/index.mdx#usestore) to enable dependency tracking and automatic re-rendering. ## Serialization diff --git a/packages/docs/src/routes/tutorial/store/recursive/index.mdx b/packages/docs/src/routes/tutorial/store/recursive/index.mdx index 73e9f26b6c3..1f6f7e30244 100644 --- a/packages/docs/src/routes/tutorial/store/recursive/index.mdx +++ b/packages/docs/src/routes/tutorial/store/recursive/index.mdx @@ -16,8 +16,8 @@ This example features a store that contains other objects rather than just primi Because `useStore()` tracks deep reactivity by default, Arrays and Objects inside the store will also be reactive. -For [`useStore()`](/docs/(qwik)/components/state/index.mdx#usestore) to track all nested properties, it needs to allocate a lot of [Proxy](/docs/(qwik)/concepts/reactivity/index.mdx#proxy) objects. This can be a performance issue if you have a lot of nested properties. +For [`useStore()`](/docs/(qwik)/core/state/index.mdx#usestore) to track all nested properties, it needs to allocate a lot of [Proxy](/docs/(qwik)/concepts/reactivity/index.mdx#proxy) objects. This can be a performance issue if you have a lot of nested properties. In that case, you can pass the additional argument: `{deep: false}` to `useStore` to only track the top-level properties. -> **Your task:** Add `{deep: false}` as a second argument to the [`useStore()`](/docs/(qwik)/components/state/index.mdx#usestore) function and modify event handlers to assign new values to the top-level properties of the store. +> **Your task:** Add `{deep: false}` as a second argument to the [`useStore()`](/docs/(qwik)/core/state/index.mdx#usestore) function and modify event handlers to assign new values to the top-level properties of the store. diff --git a/packages/docs/src/routes/tutorial/style/scoped/index.mdx b/packages/docs/src/routes/tutorial/style/scoped/index.mdx index 7f35cf0f1ea..037c1210716 100644 --- a/packages/docs/src/routes/tutorial/style/scoped/index.mdx +++ b/packages/docs/src/routes/tutorial/style/scoped/index.mdx @@ -9,7 +9,7 @@ updated_at: '2023-06-25T19:43:33Z' created_at: '2022-08-02T12:07:45Z' --- -In previous sections, we have discussed how styles can be loaded lazily as they are needed using [`useStyles$()`](/docs/(qwik)/components/styles/index.mdx#usestyles) hook. Browser styles are global and apply to all DOM elements, for this reason, Qwik also provides a way to load styles that are specific to a specific component. This is achieved by generating a unique class for each component and then inserting that unique class id into the stylesheet. +In previous sections, we have discussed how styles can be loaded lazily as they are needed using [`useStyles$()`](/docs/(qwik)/core/styles/index.mdx#usestyles) hook. Browser styles are global and apply to all DOM elements, for this reason, Qwik also provides a way to load styles that are specific to a specific component. This is achieved by generating a unique class for each component and then inserting that unique class id into the stylesheet. Use `useStylesScoped$()` to load and scope the style to a specific component only. diff --git a/packages/docs/src/routes/tutorial/style/styles/index.mdx b/packages/docs/src/routes/tutorial/style/styles/index.mdx index c1aa79bd408..60e1ff6ef8c 100644 --- a/packages/docs/src/routes/tutorial/style/styles/index.mdx +++ b/packages/docs/src/routes/tutorial/style/styles/index.mdx @@ -10,7 +10,7 @@ updated_at: '2023-06-25T19:43:33Z' created_at: '2022-08-02T12:07:45Z' --- -Styling is an important part of the design of a web application. Qwik is responsible for loading the style information when a component is mounted. Use [`useStyles$()`](/docs/(qwik)/components/styles/index.mdx#usestyles) to tell Qwik which style should be loaded. +Styling is an important part of the design of a web application. Qwik is responsible for loading the style information when a component is mounted. Use [`useStyles$()`](/docs/(qwik)/core/styles/index.mdx#usestyles) to tell Qwik which style should be loaded. ## Why not inline styles? @@ -32,7 +32,7 @@ The problem with this approach is that we will load styles twice. 1. The styles are inserted into the HTML as part of the SSR. 2. Then when the component is invalidated and needs to be re-rendered, the styles are loaded again because they are inlined. -What is needed is to load the styles independently from the component. This is what [`useStyles$()`](/docs/(qwik)/components/styles/index.mdx#usestyles) is for. There are two scenarios: +What is needed is to load the styles independently from the component. This is what [`useStyles$()`](/docs/(qwik)/core/styles/index.mdx#usestyles) is for. There are two scenarios: 1. The component is rendered on the server and the styles are inserted into `` as part of the SSR. > Adding a new instance of a component to the application does not require that we load the styles as they are already included as part of SSR. diff --git a/packages/docs/test-urls.js b/packages/docs/test-urls.js index 1a9666012d7..1893ef1768e 100644 --- a/packages/docs/test-urls.js +++ b/packages/docs/test-urls.js @@ -97,7 +97,7 @@ function makeEditPageUrl(url) { if (index !== -1 && index + 1 >= segments.length) { // These are directory paths without subpaths, map to their overview pages if (componentIndex !== -1) { - return 'docs/(qwik)/components/overview'; + return 'docs/(qwik)/core/overview'; } else if (conceptIndex !== -1) { return 'docs/(qwik)/concepts/think-qwik'; }