# API DOCS for: `qrl.public.ts`
---

# `QRL`

The `QRL` type represents a lazy-loadable AND serializable resource.

QRL stands for Qwik URL.

Use `QRL` when you want to refer to a lazy-loaded resource. `QRL`s are most often used for code (functions) but can also be used for other resources such as `string`s in the case of styles.

`QRL` is an opaque token that is generated by the Qwik Optimizer. (Do not rely on any properties in `QRL` as it may change between versions.)

## Creating `QRL` references

Creating `QRL` is done using `$(...)` function. `$(...)` is a special marker for the Qwik Optimizer that marks that the code should be extracted into a lazy-loaded symbol.

<docs code="./qrl.examples.tsx#qrl-usage-$"/>

In the above code the Qwik Optimizer detects `$(...)` and transforms the code as shown below:

<docs code="./qrl.examples.tsx#qrl-usage-$-optimized"/>

NOTE: `qrl(...)` is a result of Qwik Optimizer transformation. You should never have to invoke this function directly in your application. The `qrl(...)` function should be invoked only after Qwik Optimizer transformation.

## Using `QRL`s

Use `QRL` type in your application when you want to get a lazy-loadable reference to a resource (most likely a function).

<docs code="./qrl.examples.tsx#qrl-usage-type"/>

In the above example the way to think about the code is that you are not asking for a callback function, but rather a reference to a lazy-loadable callback function. Specifically the function loading should be delayed until it is actually needed. In the above example the function would not load until after a `mousemove` event on `document` fires.

## Resolving `QRL` references

At times it may be necessary to resolve a `QRL` reference to the actual value. This can be performed using `qrlImport(..)` function.

<docs code="./qrl.examples.tsx#qrl-usage-import"/>

NOTE: `element` is needed because `QRL`s are relative and need a base location to resolve against. The base location is encoded in the HTML in the form of `<div q:base="/url">`.

## Question: Why not just use `import()`?

At first glance `QRL` serves the same purpose as `import()`. However, there are three subtle differences that need to be taken into account.

1. `QRL`s must be serializable into HTML.
2. `QRL`s must be resolved by framework relative to `q:base`.
3. `QRL`s must be able to capture lexically scoped variables.
4. `QRL`s encapsulate the difference between running with and without Qwik Optimizer.
5. `QRL`s allow expressing lazy-loaded boundaries without thinking about chunk and symbol names.

Let's assume that you intend to write code such as this:

return <button onClick={() => (await import('./chunk-abc.js')).onClick}>

The above code needs to be serialized into DOM such as:

<div q:base="/build/">
  <button on:click="./chunk-abc.js#onClick">...</button>
</div>

1. Notice there is no easy way to extract chunk (`./chunk-abc.js`) and symbol (`onClick`) into HTML.
2. Notice that even if you could extract it, the `import('./chunk-abc.js')` would become relative to where the `import()` file is declared. Because it is our framework doing the load, the `./chunk-abc.js` would become relative to the framework file. This is not correct, as it should be relative to the original file generated by the bundler.
3. Next the framework needs to resolve the `./chunk-abc.js` and needs a base location that is encoded in the HTML.
4. The QRL needs to be able to capture lexically scoped variables. (`import()` only allows loading top-level symbols which don't capture variables.)
5. As a developer you don't want to think about `import` and naming of the chunks and symbols. You just want to say, this should be lazy.

These are the main reasons why Qwik introduces its own concept of `QRL`.

See: `$`

@public

# `qrlImport`

Lazy-load a `QRL` symbol and return the lazy-loaded value.

See: `QRL`

@param element - Location of the URL to resolve against. This is needed to take `q:base` into account.
@param qrl - QRL to load.
@returns A resolved QRL value as a Promise.
@public

# `$`

Qwik Optimizer marker function.

Use `$(...)` to tell Qwik Optimizer to extract the expression in `$(...)` into a lazy-loadable resource referenced by `QRL`.

See: `implicit$FirstArg` for additional `____$(...)` rules.

In this example `$(...)` is used to capture the callback function of `onmousemove` into lazy-loadable reference. This allows the code to refer to the function without actually loading the function. In this example, the callback function does not get loaded until `mousemove` event fires.

<docs code="./qrl.examples.tsx#qrl-usage-$"/>

In this code the Qwik Optimizer detects `$(...)` and transforms the code into:

<docs code="./qrl.examples.tsx#qrl-usage-$-optimized"/>

## Special Rules

The Qwik Optimizer places special rules on functions that can be lazy-loaded.

1. The expression of the `$(expression)` function must be importable by the system. (expression shows up in `import` or has `export`)
2. If inlined function then all lexically captured values must be:
- importable (vars shows up in `import` or has `export`)
- const (The capturing process differs from JS capturing in that writing to captured variables does not update them, and therefore writes are forbidden. The best practice is that all captured variables are constants.)
- Must be runtime serializable.

<docs code="./qrl.examples.tsx#qrl-capturing-rules"/>

@param expression - Expression which should be lazy loaded
@public

# `implicit$FirstArg`

Create a `____$(...)` convenience method from `___(...)`.

It is very common for functions to take a lazy-loadable resource as a first argument. For this reason, the Qwik Optimizer automatically extracts the first argument from any function which ends in `$`.

This means that `foo$(arg0)` and `foo($(arg0))` are equivalent with respect to Qwik Optimizer. The former is just a shorthand for the latter.

For example these function call are equivalent:

- `component$(() => {...})` is same as `onRender($(() => {...}))`

<docs code="./qrl.examples.tsx#implicit$FirstArg"/>

@param fn - function that should have its first argument automatically `$`.
@public

# `qrl`

Used by Qwik Optimizer to point to lazy-loaded resources.

This function should be used by the Qwik Optimizer only. The function should not be directly referred to in the source code of the application.

See: `QRL`, `$(...)`

@param chunkOrFn - Chunk name (or function which is stringified to extract chunk name)
@param symbol - Symbol to lazy load
@param lexicalScopeCapture - a set of lexically scoped variables to capture.
@public