# Qwik Docs Site ⚡️

## Development Builds

### Client only

During development, the index.html is not a result of server-side rendering, but rather the Qwik app is built using client-side JavaScript only. This is ideal for development with Vite and its ability to reload modules quickly and on-demand. However, this mode is only for development and does not showcase "how" Qwik works since JavaScript is required to execute, and Vite imports many development modules for the app to work.

```
pnpm dev
```

### Server-side Rendering (SSR) and Client

Server-side rendered index.html, with client-side modules prefetched and loaded by the browser. This can be used to test out server-side rendered content during development, but will be slower than the client-only development builds.

```
pnpm dev.ssr
```

## Production Builds

A production build should generate the client and server modules by running both client and server build commands.

```
pnpm build
```

### LLM Files

The docs build also generates these public LLM-facing files:

- `dist/llms.txt`
- `dist/llms-ctx.txt`
- `dist/llms-ctx-full.txt`
- curated markdown mirrors, such as `dist/docs/getting-started.md`

You can regenerate them directly with:

```
pnpm generate.llms
```

To emit links for a different host or subdomain, set `QWIK_LLMS_BASE_URL` when generating:

```
QWIK_LLMS_BASE_URL=https://v2.qwik.dev pnpm generate.llms
```

On Cloudflare Pages, the generator also falls back to `CF_PAGES_URL`, so preview deployments can emit links for their deployment URL automatically. Set `QWIK_LLMS_BASE_URL` in the Pages production environment if you want production builds to emit a custom domain instead of the default `*.pages.dev` URL.

`pnpm build` runs the site build first and then writes the generated LLM files into `dist/`.
The generation is chained to the `build.client` script (`vite build && pnpm generate.llms`), so the files exist in `dist/` before the server build runs. This ensures the Cloudflare Pages adapter discovers them as static paths and the Worker serves them correctly.

If you add or want to expose a new docs or API page in the LLM outputs, update the curated manifest in `scripts/generate-llms.ts`.

For each new entry, add:

- `section`
- `title`
- `pathname`
- `sourcePath`
- `description`
- optional `optional` flag

After updating the manifest, run:

```
pnpm generate.llms
```

or just:

```
pnpm build
```

Notes:

- Editing an existing page that is already in the manifest is automatic; rebuilding regenerates the LLM files from the latest source.
- Adding a brand new page to the LLM surface is not automatic yet; it must be added to the manifest on purpose.

### Client Modules

Production build that creates only the client-side modules that are dynamically imported by the browser.

```
pnpm build.client
```

### Server Modules

Production build that creates the server-side render (SSR) module that is used by the server to render the HTML.

```
pnpm build.ssr
```

## Cloudflare Pages

Cloudflare's [wrangler](https://github.com/cloudflare/wrangler) CLI can be used to preview a production build locally. To start a local server, run:

```
pnpm serve
```

Then visit [http://localhost:8787/](http://localhost:8787/)

### Deployments

[Cloudflare Pages](https://pages.cloudflare.com/) are deployable through their [Git provider integrations](https://developers.cloudflare.com/pages/platform/git-integration/).

If you don't already have an account, then [create a Cloudflare account here](https://dash.cloudflare.com/sign-up/pages). Next go to your dashboard and follow the [Cloudflare Pages deployment guide](https://developers.cloudflare.com/pages/framework-guides/deploy-anything/).

Within the projects "Settings" for "Build and deployments", the "Build command" should be `pnpm build`, and the "Build output directory" should be set to `dist`.

### Function Invocation Routes

Cloudflare Page's [function-invocation-routes config](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes) can be used to include, or exclude, certain paths to be used by the worker functions. Having a `_routes.json` file gives developers more granular control over when your Function is invoked.
This is useful to determine if a page response should be Server-Side Rendered (SSR) or if the response should use a static-site generated (SSG) `index.html` file.

By default, the Cloudflare pages adaptor _does not_ include a `public/_routes.json` config, but rather it is auto-generated from the build by the Cloudflare adaptor. An example of an auto-generate `dist/_routes.json` would be:

```
{
  "include": [
    "/*"
  ],
  "exclude": [
    "/_headers",
    "/_redirects",
    "/build/*",
    "/favicon.ico",
    "/manifest.json",
    "/service-worker.js",
    "/about"
  ],
  "version": 1
}
```

In the above example, it's saying _all_ pages should be SSR'd. However, the root static files such as `/favicon.ico` and any static assets in `/build/*` should be excluded from the Functions, and instead treated as a static file.

In most cases the generated `dist/_routes.json` file is ideal. However, if you need more granular control over each path, you can instead provide you're own `public/_routes.json` file. When the project provides its own `public/_routes.json` file, then the Cloudflare adaptor will not auto-generate the routes config and instead use the one committed within the `public` directory.

## Algolia search

STILL WIP

resource: https://docsearch.algolia.com/

### Crawler

Setup in https://crawler.algolia.com/

### Debug local site with crawler settings

To crawl localhost site for testing index settings for content hierarchy. use this docker command

```shell
# create apiKey via https://www.algolia.com/account/api-keys
touch .env
# APPLICATION_ID=APPLICATION_ID
# API_KEY=API_KEY
docker run -it --rm --env-file=.env -e "CONFIG=$(cat ./packages/docs/algolia.json | jq -r tostring)" algolia/docsearch-scraper
```

see guide of [DocSearch-legacy docker command](https://docsearch.algolia.com/docs/legacy/run-your-own#run-the-crawl-from-the-docker-image)

> In mac machines, docker containers can't access host's network directly, a workaround is to use host.docker.internal`
