# Best Practices

## Inline operations in templates

Qwik optimizer can better optimize the reactivity of the application if the operations are inlined in the template.

```tsx title="Suboptimal implementation"
// Don't do this!
export default component$(() => {
  const signal = useSignal(0);
  const isBiggerThanZero = signal.value > 0 ? 'Bigger than zero' : 'Smaller than zero';
  return (
    <div>
      <button onClick$={() => signal.value++}>+</button>
      <button onClick$={() => signal.value--}>-</button>
      <div>{isBiggerThanZero} - Current value: { signal.value }</div>
    </div>
  );
});
```

The above implementation will cause the whole template to be re-rendered when the signal changes. This is because the `isBiggerThanZero` is not inlined in the template.

```tsx title="Optimal Implementation"
export default component$(() => {
  const signal = useSignal(0);
  return (
    <div>
      <button onClick$={() => signal.value++}>+</button>
      <button onClick$={() => signal.value--}>-</button>
        <div>
          {signal.value > 0 ? 'Bigger than zero' : 'Smaller than zero'} - Current
          value: {signal.value}
        </div>
    </div>
  );
});
```

## Moving signal reads to `useTask$` or `useComputed$`

This is similar to the tip above.

Every time Qwik "reads" a signal/store value
the function that the "read" is happening at, will re-run again
on every change to that signal.

That’s why it’s better to "read" values (and track them)
inside of `useTask$` or `useComputed$` functions instead of inside component functions,
whenever possible.

Because otherwise, your component function will re-run
on each change.

```tsx title="Suboptimal implementation"
// Don't do this!
export default component$(() => {
  const count = useSignal(1);
  const doubleCount = count.value*2;
  return (
    <div>{doubleCount}</div>
  );
});
```

The above implementation will cause the whole template to be re-rendered when the signal changes.

Below, only the `useComputed$` function will re-run on any `count.value` change:

```tsx title="Optimal Implementation"
export default component$(() => {
  const count = useSignal(1);
  const dobuleCount = useComputed$(() => count.value*2);
  return (
    <div>{doubleCount.value}</div>
  );
});
```

For async derived values (like search suggestions), use `useComputed$` with an async function and abort in-flight work on each keystroke:

```tsx title="Async derived value with cancellation"
export default component$(() => {
  const query = useSignal('');
  const results = useComputed$(async ({ abortSignal }) => {
    const q = query.value;
    const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, {
      signal: abortSignal,
    });
    return res.json();
  }, { initial: [] });

  return <div>{results.value.length} results</div>;
});
```

## Use `useVisibleTask$()` as a last resort

Although convenient, `useVisibleTask$()` runs code eagerly and blocks the main thread, preventing user interaction until the task is finished. You can think of it as an escape hatch.

When in doubt, instead of "useVisibleTask$()" use:
- `useTask$()` -> perform code execution in SSR mode.
- `useOn()` -> listen to events on the root element of `the current component`.
- `useOnWindow()` -> listen to events on the `window` object.
- `useOnDocument()` -> listen to events on the `document` object.

Sometimes though, it is the only way to achieve the result.

In that case, you can add `// eslint-disable-next-line qwik/no-use-visible-task` to the line before "useVisibleTask$" to remove the warning.

### Register DOM events with `useOn()`, `useOnWindow()`, or `useOnDocument()`

Qwik allows to register event listeners in a declarative way, using the `useOn()` or using JSX.

When using `useVisibleTask$()` to programmatically register events, we are downloading and executing JavaScript eagerly, even if the event is not triggered.

```tsx title="Suboptimal implementation"
// Don't do this!
useVisibleTask$(({ cleanup }) => {
  const listener = (event) => {
    const mouseEvent = event as MouseEvent;
    console.log(mouseEvent.x, mouseEvent.y);
  };
  document.addEventListener('mousemove', listener);

  cleanup(() => {
    document.removeEventListener('mousemove', listener);
  });
});
```

The above implementation causes more JavaScript to load eagerly, rather than responding precisely to user events. Increased upfront JavaScript loading results in slower app performance. See [below](#delaying-core-execution) for more details.

Instead, use the `useOnDocument()` hook to register events on the `document` object, this way Qwik will not execute any JS until the event is triggered.

```tsx title="Optimal Implementation"
useOnDocument(
  'mousemove',
  $((event) => {
    const mouseEvent = event as MouseEvent;
    console.log(mouseEvent.x, mouseEvent.y);
    // No manual clean up required!
  })
);
```

## Avoid accessing the location from the `window` object

Don't access `window.location` directly, use `useLocation()` hook instead.

```tsx title="Suboptimal implementation"
// Don't do this!
useVisibleTask$(()=> {
    if (window.location.href).includes('foo') {
        //... do the thing
    }
})
// or
useTask$(() => {
  if (isBrowser) {
        if (window.location.href).includes('foo') {
        //... do the thing
    }
  }
})
```

Many actions related to location information can be executed during the initial server-side render, resulting in pure HTML without any JavaScript overhead.

Forcing this logic to run on the client side introduces increased upfront JavaScript and leads to eager loading.

```tsx title="Optimal Implementation"
// Do this!
const location = useLocation();

if (location.url.href.includes('foo')) {
  // Do the thing
}
```

### Exception

When using SSG for purely static files, it's inevitable to rely on the server without current location information during the build time.

However, exercise caution! If the required information (such as query parameters) isn't needed until a user event occurs, incorporate the check within your event handling code.

This approach helps to prevent eager loading of JavaScript and improves performance.

See: [useLocation() Docs](/docs/api.md#uselocation)

## Delaying Core Execution
At load time we want to execute as little as possible to free main thread for other priority. With Qwik you can even delay the framework execution (called "core"), but there are some rules to follow.

Some things to keep in mind before checking the rules :
- Delaying core execution usually comes at the price of devX, this is an advance performance trick.
- Like other chunks, core will be preloaded so the app doesn't have to load it at execution time.

### useVisibleTask$

`useVisibleTask$` will **always** execute core before its callback is called.

```jsx
// Requires core when component is visible in the viewport
useVisibleTask$(() => {
  console.log('Hello core');
});

// Requires core on requestIdleCallback
useVisibleTask$(
  () => console.log('Hello core'),
  { strategy: 'document-idle' }
);
```

In **some** cases you can replace `useVisibleTask$` with either `useOn` or `useTask$`

#### useOn

Replace `useVisibleTask$` with `useOn('qvisible')` / `useOn('qidle')` if

- You only need to trigger a callback once
- The code must run on the client

`useOn`, `useOnDocument` & `useOnWindow` execute core if they use a variable from the component scope :

```jsx title="Comparing core execution"
import { libId } from 'library';
const globalId = 'global-id';
const Component = component$(() => {
  const ref = useSignal();
  const id = useId();

  // Executes core at load time
  useOnDocument('qidle', $(() => console.log(ref)));
  // Executes core at load time
  useOnDocument('qidle', $(() => console.log(id)));
  // Does not execute core at load time
  useOnDocument('qidle', $(() => console.log(globalId)));
  // Does not execute core at load time
  useOnDocument('qidle', $(() => console.log(libId)));
  // Does not execute core at load time
  useOnDocument('qidle', $(() => console.log('id')));

  return (
    <p ref={ref}></p>
    <p id={id}></p>
    <p id={globalId}></p>
    <p id={libId}></p>
    <p id="id"></p>
  )
})
```

#### useTask$

Replace `useVisibleTask$` with `useTask$` if

- You need to listen on state changes
- The code can execute on the server

```jsx
const Component = component$(() => {
  const search = useSignal();
  // Does not execute until `search` changes
  useTask$(({ track }) => {
    track(search);
    console.log(search.value);
  });
  return <input bind:value={search} type="search" />;
});
```

#### useOn + useTask$

A classic usecase of `useVisibleTask$` is to start listening on browser specific event:

```jsx
const isMobile = useSignal(false);
useVisibleTask$(({ cleanup }) => {
  const query = window.matchMedia('(max-width: 400px)');
  const handler = (event) => {
    isMobile.value = event.matches;
  };
  query.addEventListener('change', handler);
  cleanup(() => query.removeEventListener('change', handler));
});
```

In this case we actually need core when the handler is triggered. Here is how to delay core execution :

```jsx
const isMobile = useSignal(false);
// On idle, start listening on the event
useOnDocument(
  'qidle',
  sync$(() => {
    const query = window.matchMedia('(max-width: 400px)');
    const handler = (event) => {
      // Forward the event to the document
      const copy = new event.constructor('media-query:(max-width: 400px)', event);
      document.dispatchEvent(copy);
    };
    // Store mediaQuery & handler to cleanup later
    document['cleanup:media-query:(max-width: 400px)'] = () => {
      query.removeEventListener('change', handler)
    };
    query.addEventListener('change', handler);
  })
);

// useOnDocument execute core when it actually needs it
useOnDocument(
  'media-query:(max-width: 400px)',
  $((event) => {
    isMobile.value = event.matches;
  })
);

// useTask$ is used to cleanup event listeners
useTask$(({ cleanup }) => {
  cleanup(() => {
    if (!document['cleanup:media-query:(max-width: 400px)']) return;
    document['cleanup:media-query:(max-width: 400px)']();
    delete document['cleanup:media-query:(max-width: 400px)'];
  });
});
```

As we can see, this is a LOT of work, and it's not a great dev experience ! But if you're building a library or just trying to go as lean as possible, this is possible.
