Skip to content

Commit

Permalink
docs: Fix broken links in guide pages (#248)
Browse files Browse the repository at this point in the history
  • Loading branch information
painotpi committed Mar 4, 2022
1 parent 888aab4 commit 4386c09
Show file tree
Hide file tree
Showing 3 changed files with 8 additions and 8 deletions.
2 changes: 1 addition & 1 deletion docs/pages/guide/bootstrap.mdx
Expand Up @@ -8,7 +8,7 @@ import { Counter } from '../../src/components/counter/counter';

Qwik is designed to have the smallest amount of code which needs to be run on the client to bootstrap the application. The size of bootstrap code has a direct impact on application [time to interactive](https://web.dev/interactive/).

The bootstrapping code is known as `qwikloader` and is tiny (around 500 bytes minified) and can bootstrap in under one millisecond. The purpose of `qwikloader` is to set up global browser event listeners for your application, such as `click` events. If an event fires, the `qwikloader` looks for a corresponding `on:click` attribute which contains a [QRL](./QRL.md). The QRL tells `qwikloader` where to download the handler for the `click` event.
The bootstrapping code is known as `qwikloader` and is tiny (around 500 bytes minified) and can bootstrap in under one millisecond. The purpose of `qwikloader` is to set up global browser event listeners for your application, such as `click` events. If an event fires, the `qwikloader` looks for a corresponding `on:click` attribute which contains a [QRL](./components/qrl.mdx). The QRL tells `qwikloader` where to download the handler for the `click` event.

## Bootstrapping

Expand Down
8 changes: 4 additions & 4 deletions docs/pages/guide/lazy-loading.mdx
Expand Up @@ -4,7 +4,7 @@ title: Lazy-Loading

# Fine-Grained Lazy-Loading

After [resumability](./RESUMABLE.md), fine-grained lazy-loading is the next important goal to achieve low [time to interactive](https://web.dev/interactive/) score.
After [resumability](./resumable-vs-replayable.mdx), fine-grained lazy-loading is the next important goal to achieve low [time to interactive](https://web.dev/interactive/) score.

## Frameworks lack lazy-loading primitives

Expand All @@ -24,13 +24,13 @@ Lazy loading directly impacts the amount of code which needs to be downloaded, p

One of the biggest places where fine-grained lazy-loading can be applied is in the area of event handlers. Applications typically have many event handlers to support user interaction. Most of these event handlers do not get exercised during typical user interactions, but must still be downloaded just-in-case. The event handlers are in the form of closures which close over the dependencies of the event handler further increasing the download size. Additionally most frameworks require that templates be rendered for the framework to attach the event handlers to the DOM.

In practice this means that [heap-centric](./RESUMABLE.md) frameworks must execute all of the templates so that they can collect the event handlers and attach them to the DOM, just in case the user will perform an interaction. A developer could place dynamic imports in the event handlers, but in practice this is complicated because event bubbling is synchronous making composing event handlers hard. It also means that a heap-centric framework must download and execute all of the templates currently visible to the user. All of these complications slow down [time to interactive](https://web.dev/interactive/) and do not directly help the developer to do the right thing.
In practice this means that [heap-centric](./resumable-vs-replayable.mdx) frameworks must execute all of the templates so that they can collect the event handlers and attach them to the DOM, just in case the user will perform an interaction. A developer could place dynamic imports in the event handlers, but in practice this is complicated because event bubbling is synchronous making composing event handlers hard. It also means that a heap-centric framework must download and execute all of the templates currently visible to the user. All of these complications slow down [time to interactive](https://web.dev/interactive/) and do not directly help the developer to do the right thing.

Qwik stores event handlers as string annotations in the DOM. This has several advantages:

- No template needs to be downloaded and rendered in order for the framework to know where the event handlers need to be registered.
- No event handler code needs to be downloaded before it is needed.
- Global event handler registration can be performed saving on event registration during [bootstrap](./BOOTSTRAP.md).
- Global event handler registration can be performed saving on event registration during [bootstrap](./bootstrap.mdx).
- All event handlers automatically have lazy loaded boundaries. This guides the developer to do the high performance thing by default.

## Lazy loading components
Expand All @@ -51,7 +51,7 @@ Let's say that the framework has determined that only the `<middle>` component n

The reverse is also true. Let's say that `<middle>` has a button with a `click` handler. Clicking the button will cause the application to change state (which may be a store in the Redux pattern). Most current frameworks don't directly track state and so there is no way of knowing which other components need to be invalidated due to execution of the event handler. The only thing the framework can do is to re-render the whole application from the root just-in-case there is a component which depends on the state. We can say that the current approach causes "parent component-coupling".

> Yes, there are some frameworks which track data-flow through subscriptions (reactive frameworks), and such frameworks would know which exact component needs to be updated. The problem is that setting up these subscriptions necessitates the creation of closures which in turn need references to the components. Creation of these subscriptions forces all of the components to be materialized negating any benefits. (see: [Qwik reactivity](./REACTIVITY.md))
> Yes, there are some frameworks which track data-flow through subscriptions (reactive frameworks), and such frameworks would know which exact component needs to be updated. The problem is that setting up these subscriptions necessitates the creation of closures which in turn need references to the components. Creation of these subscriptions forces all of the components to be materialized negating any benefits. (see: [Qwik reactivity](./reactivity/overview.mdx))
Child and parent component-coupling means that in practice all of the currently visible application must be downloaded and present for the application to be user interactive. As applications get bigger and more complicated this requirements means that the application startup gets slower over time.

Expand Down
6 changes: 3 additions & 3 deletions docs/pages/guide/mental-model.mdx
Expand Up @@ -20,10 +20,10 @@ Because of the above goals, some design decisions may feel foreign compared to t

Qwik applications consist of `Component`s and `Entity`s.

- **Component:** Qwik application UIs are built from a collection of Qwik `Component`s. `Component`s can communicate with each other only through `Props`, `Entity`s, and by listening to or emitting/broadcasting `Event`s. (See [reactivity](./REACTIVITY.md).) No other form of communication is allowed as it would go against the goals outlined above.
- **Component:** Qwik application UIs are built from a collection of Qwik `Component`s. `Component`s can communicate with each other only through `Props`, `Entity`s, and by listening to or emitting/broadcasting `Event`s. (See [reactivity](./reactivity/overview.mdx).) No other form of communication is allowed as it would go against the goals outlined above.
- **Entity:** `Entity`s represent application data or shared behavior between `Component`s and the application backend. `Entity`s do not have UI representation and must be injected into a `Component` to have their data rendered. `Entity`s can perform communication with the server or other external resources.

A Qwik application is a graph of `Component`s and `Entity`s that define data flow. The Qwik framework will hydrate `Component`s/`Entity`s on an as-needed basis to achieve the desired outcome. To do this, the Qwik framework must understand the data flow between `Component`s and `Entity`s to know which `Component` or `Entity` needs to be rehydrated and when. Most other frameworks do not have this understanding and need to re-render the whole application on any data update resulting in too much code that must be downloaded. (See [lazy loading](./LAZY_LOADING.md).)
A Qwik application is a graph of `Component`s and `Entity`s that define data flow. The Qwik framework will hydrate `Component`s/`Entity`s on an as-needed basis to achieve the desired outcome. To do this, the Qwik framework must understand the data flow between `Component`s and `Entity`s to know which `Component` or `Entity` needs to be rehydrated and when. Most other frameworks do not have this understanding and need to re-render the whole application on any data update resulting in too much code that must be downloaded. (See [lazy loading](./lazy-loading.mdx).)

### Example

Expand All @@ -42,7 +42,7 @@ Above is a `Component`/`Entity` dependency graph of a hypothetical application.
A `Component` or `Entity` consists of:

- **`Props`:** These are a hash of key/value strings (`{[key:string]:string}`), which tell Qwik about the `Component` or `Entity`.
- **`Component`:** These are just the DOM attributes of the `Component`'s host element. If the attributes change, then the `Component` gets notified. These `Props` are serialized into the [host element](./HOST_ELEMENT.md).
- **`Component`:** These are just the DOM attributes of the `Component`'s host element. If the attributes change, then the `Component` gets notified. These `Props` are serialized into the [host element](./components/host-element.mdx).
- **`Entity`:** The `Props` for an `Entity` are usually serialized into a `EntityKey`, which uniquely identifies an entity instance. The `EntityKey` is constant for the lifetime of the entity. (For example `issue:org123:proj456:789` might identify an issue with id `789` in `org123/proj456`.)
- **`State`:** A `Component` or `Entity` can have a `State` which is a `JSON` serializable object. If an application is dehydrated then the `State` is serialized into the DOM/HTML so that it can be quickly rehydrated on the client.
- **Transient State:** is state that is only stored inside the instance of a `Component` or `Entity`. This state can include references to any other object. However, the transient state will not be serialized and therefore anything stored on the instance as transient state will have to be recomputed on rehydration.
Expand Down

0 comments on commit 4386c09

Please sign in to comment.