Routing

Routing in Qwik City is file-system based like Next.js, SvelteKit, SolidStart or Remix. Files and directories in the src/routes have a role in the routing of your application.

• 📂 Directories: Define the URL segments to match by the router.
• 📄 index.tsx/mdx files: Define a page and/or an endpoint.
• 🖼️ layout.tsx files: Define nested layout and/or a middleware.

Directory-based routing

Only the directory names are used to match the incoming requests to pages/endpoint/middleware.

For example, if you have a file at src/routes/some/path/index.tsx, it will be mapped to the URL path https://example.com/some/path.

src/
└── routes/
    ├── contact/
    │   └── index.mdx         # https://example.com/contact
    ├── about/
    │   └── index.md          # https://example.com/about
    ├── docs/
    │   └── [id]/
    │       └── index.ts      # https://example.com/docs/1234
    │                         # https://example.com/docs/anything
    ├── [...catchall]/
    │   └── index.tsx         # https://example.com/anything/else/that/didnt/match
    │
    └── layout.tsx            # This layout is used for all pages

• [id] is a directory that represents a dynamic route segment, in this example id is the string parameter accessible by useLocation().params.id.
• [...catchall] is a directory that represents a dynamic catch-all route, in this example catchall is the string parameter accessible by useLocation().params.catchall.
• index.tsx|mdx files are the pages/endpoints/middleware.
• layout.tsx files are the layouts.

Dynamic route segments

Special named directories with square brackets, such as [paramName] and [...catchAll] can be used to match route segments which are dynamic:

src/routes/blog/index.tsx → /blog
src/routes/user/[username]/index.tsx → /user/:username (/user/foo)
src/routes/post/[...all]/index.tsx → /post/* (/post/2020/id/title)

src/
└── routes/
    ├── blog/
    │   └── index.tsx         # https://example.com/blog
    ├── post/
    │   └── [...all]/
    │       └── index.tsx     # https://example.com/post/2020/id/title
    └── user/
        └── [username]/
            └── index.tsx     # https://example.com/user/foo

The folder [username] can be any of the thousands of users that you have in your database. It would be impractical to create a route for each user. Instead, you need to define a Route Parameter (a part of the URL) that will be used to extract the [username].

import { component$ } from '@builder.io/qwik';
import { useLocation } from '@builder.io/qwik-city';
 
export default component$(() => {
  const loc = useLocation();
  return <div>Hello {loc.params.username}!</div>;
});

index files

Inside the src/routes directory, all files named index are considered pages/endpoint/middleware, Qwik supports the following extensions: .ts, .tsx, .md and .mdx.

Pages/endpoint/middleware are the leaf nodes of the routing tree, ie, the modules that will handle the request and return an HTTP response.

Page index.tsx

When index.tsx or index.ts exports a Qwik component as the default export, Qwik City will render the component and return an HTML response as a webpage.

import { component$ } from '@builder.io/qwik';
 
export default component$(() => {
  return <h1>Hello World</h1>;
});

Endpoint index.ts

A index.ts can also access the HTTP request directly and return a raw HTTP response without involving any Qwik Component. This is done by exporting an onRequest method or onGet, onPost, onPut, onDelete depending on if you only want to handle a specific request given its HTTP method.

import type { RequestHandler } from '@builder.io/qwik-city';
 
export const onGet: RequestHandler = ({ json }) => {
  json(200, { message: 'Hello World' });
};

Notice that in the last example, there is no default export. This is because we are not rendering a Qwik component, but rather we are handling the request directly and returning a JSON response. This is useful to implement RESTful APIs or any other type of HTTP endpoint.

Page + Endpoint

As you can see in Qwik City there is no clear separation between pages and endpoints, in both cases, it's a index.tsx file that exports a Qwik component or an onRequest method. However, it's possible to combine both approaches. For example, you can export a onRequest method that will handle the request, and then render a Qwik component.

import { component$ } from '@builder.io/qwik';
import type { RequestHandler } from '@builder.io/qwik-city';
 
export const onRequest: RequestHandler = ({ headers, query, json }) => {
  headers.set('Cache-Control', 'private');
  if (query.get('format') === 'json') {
    json(200, { message: 'Hello World' });
  }
};
 
export default component$(() => {
  return <h1>Hello World</h1>;
});

In this example, a request handle will always set the Cache-Control header to private and the page will be rendered as an HTML page, but if the request contains a format=json query param, the endpoint will return a JSON response instead.

layout. files

Layout modules are very similar to index files, both can handle requests and render Qwik components, however, layouts are designed to work like a middleware, allowing to share UI and request handling (middleware) to a set of routes.

Usually, different pages need some common request handling and share some UI. For example, picture a dashboard site where all the pages are under the /admin/* directory:

• Shared request handling: The request cookies need to be validated before even rendering the page, otherwise, render a blank 401 page.
• Shared UI: All pages share a common header showing the user's name and profile picture.

Instead of repeating the same code in each route, we can use layouts to automatically reuse common parts, and also to add middleware to the route.

Take this src/routes directory as an example:

src/
└── routes/
    ├── admin/
    │   ├── layout.tsx  <-- This layout is used for all pages under /admin/*
    │   └── index.tsx
    ├── layout.tsx      <-- This layout is used for all pages
    └── index.tsx

Middleware layouts

Since layouts can implement request handling with onRequest or onGet, onPost, onPut, onDelete, they can be used to implement middleware, for example, to validate the request cookies before rendering the page.

For the route https://example.com/admin, the onRequest methods will be executed in the following order:

1. src/routes/layout.tsx's onRequest
2. src/routes/admin/layout.tsx's onRequest
3. src/routes/admin/index.tsx's component

Nested layouts

Layouts also provide a way to add common UI to the rendered page. For example, if we want to add a common header to all the routes, we can add a Header component to the root layout.

For the given example, the Qwik components will be rendered in the following order:

1. src/routes/layout.tsx's component
2. src/routes/admin/layout.tsx's component
3. src/routes/admin/index.tsx's component

<RootLayout>
  <AdminLayout>
    <AdminPage />
  </AdminLayout>
</RootLayout>

SPA Navigation

With Qwik, the distinction between MPA and SPA disappears; every app can be both at the same time. The choice is no longer an architectural design determined at the beginning of the project, instead this decision can be made for every link.

Qwik provides a <Link> component and useNavigate() hook. These can be used to initiate an SPA refresh or navigation between pages.

The Link component is the recommend way to navigate as it uses the HTML <a> tag, which is the most accessible way to move between pages. However, if you need to navigate programmatically, you can use the useNavigate() hook.

import { component$ } from '@builder.io/qwik';
import { Link, useNavigate } from '@builder.io/qwik-city';
 
export default component$(() => {
  const nav = useNavigate();
  return (
    <div>
      <Link href="/about">About (prefered)</Link>
      <button onClick$={() => nav('/about')}>About</button>
    </div>
  );
});

The Link component uses the useNavigate() hook internally.

Refreshing

The Link with the reload prop can be used to refresh the current page. You can also call the nav() function from the useNavigate() hook, without arguments.

import { component$ } from '@builder.io/qwik';
import { Link, routeLoader$, useNavigate } from '@builder.io/qwik-city';
 
export const useServerTime = routeLoader$(() => {
  // This will re-execute in the server when the page refreshes.
  return Date.now();
});
 
export default component$(() => {
  const nav = useNavigate();
  const serverTime = useServerTime();
 
  return (
    <div>
      <Link reload>Refresh (better accesibility)</Link>
      <button onClick$={() => nav()}>Refresh</button>
      <p>Server time: {serverTime.value}</p>
    </div>
  );
});

When the page refreshes, all the matching routeLoader$ and server handlers (onRequest) will re-execute in the server and the UI will re-render accordingly.

While refreshing the page, the isNavigating boolean from useLocation() will be true until the page is fully rendered.

Scroll Restoration

Qwik provides best-in-class scroll restoration for SPA that closely mimics the native browser experience. Your users should receive the exact same experience they've come to expect natively from MPA, except with all the added benefits of SPA.

After you use one of the above methods to navigate, the user is automatically upgraded to SPA. This means that the current page, and the page they came from, now have an SPA context associated with them.

If a user then clicks a regular <a> tag, they will perform a regular navigation. This new page will have no SPA context, and is effectively downgraded back to MPA. You can swap between these however you see fit, and the user's experience will seamlessly switch between MPA and SPA as if it were all the same.

When a user re-visits the SPA-enabled history entries, such as with a refresh, back/forward button, browser session restarts, etc., Qwik will automatically restore their scroll position and bootstrap itself back into the SPA context as needed.

The script required to provide this robust experience never loads, nor is it ever even sent to the user's browser, unless the history entry has had an SPA context. Pure MPA pages never load this script. This is the magic of Qwik.

Scroll restoration in Qwik always occurs synchronously with render. When combined with Qwik's resumable and first-class SSR/MPA nature, the user should never experience scroll flashing.

Qwik's scroll restoration is entirely history based. This is different from many other frameworks which rely on things like sessionStorage.

Qwik's ability to remember and restore scroll positions is extremely robust and will survive everything from browser session restarts to users clearing their browser data, which is not the case for these many other frameworks.

Notes on using pushState() and replaceState() during SPA:

On a page with an SPA context, Qwik will patch the pushState() and replaceState() functions on the history global. This is to ensure that any custom states you add as a developer, also receive the SPA context.

While these are patched, states you push or replace should always be an actual Object type. This is because Qwik needs to be able to automatically append the SPA context to the state as a property.

If you provide a value that is not an object, Qwik will create a new object for state and add your provided value to a new key: { _data: <your_value> }

Qwik will also warn you in the browser's console in dev mode when this occurs.

Request Event

Each request handler, such as onRequest, onGet, onPost, etc., are passed in a RequestEvent object as the first argument to the handler. The RequestEvent object contains utility functions and properties to get and set values to the server's request and response. This object contains the following properties:

• basePathname: The base pathname of the request, which can be configured at build time. Defaults to /.
• cacheControl: Convenience function to set the Cache-Control response header.
• cookie: HTTP request and response cookies. Use the get() method to retrieve a request cookie value. Use the set() method to set a response cookie value.
• env: Platform provided environment variables.
• error: When called, the response will immediately end with the given status code. This could be useful to end a response with 404, and use the 404 handler in the routes directory. See Status codes for which status code should be used.
• getWritableStream: Low-level access to write to the HTTP response stream. Once getWritableStream() is called, the status and headers can no longer be modified and will be sent over the network.
• headers: HTTP response headers.
• html: Convenience method to send an HTML body response. The response will be automatically set the Content-Type header totext/html; charset=utf-8. An html() response can only be called once.
• json: Convenience method to JSON stringify the data and send it in the response. The response will be automatically set the Content-Type header toapplication/json; charset=utf-8. A json() response can only be called once.
• locale: Which locale the content is in. The locale value can be retrieved from selected methods using getLocale().
• method: HTTP request method value.
• next: Call the next request handler. This is useful for middleware.
• params: URL path params which have been parsed from the current url pathname segments. Use query to instead retrieve the query string search params.
• parseBody: This method will check the request headers for a Content-Type header and parse the body accordingly. It supports application/json, application/x-www-form-urlencoded, and multipart/form-data content types. If the Content-Type header is not set, it will return null.
• pathname: URL pathname value. Does not include the protocol, domain, query string (search params) or hash.
• platform: Platform specific data and functions.
• query: URL query string URLSearchParams value. Use params to instead retrieve the route params found in the url pathname.
• redirect: URL to redirect to. When called, the response will immediately end with the correct redirect status and headers. See Redirects for which status code should be used.
• request: HTTP Request.
• send: Send a body response. The Content-Type response header is not automatically set when using send() and must be set manually. A send() response can only be called once.
• sharedMap: Shared Map across all the request handlers. Every HTTP request will get a new instance of the shared map. The shared map is useful for sharing data between request handlers.
• status: HTTP response status code. Sets the status code when called with an argument. Always returns the status code, so calling status() without an argument will can be used to return the current status code.
• text: Convenience method to send an text body response. The response will be automatically set the Content-Type header totext/plain; charset=utf-8. An text() response can only be called once.
• url: HTTP request URL.

Advanced routing

Qwik City also supports:

• Route Parameters
• Nested layouts
• Menus

These are discussed later.