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. QRLs are most often used for code (functions) but can also be used for other resources such as strings 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.

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

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 QRLs

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

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.

NOTE: element is needed because QRLs 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. QRLs must be serializable into HTML.
2. QRLs must be resolved by framework relative to q:base.
3. QRLs must be able to capture lexically scoped variables.
4. QRLs encapsulate the difference between running with and without Qwik Optimizer.
5. QRLs 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.

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

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.

@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($(() => {...}))

@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