Qwik City - Routing

Routing is a way to map public URLs for a site to specific components declared in your application.

Qwik City uses directory-based routing. This means that the structure of your routes directory drives the public-facing URLs that the user will see for your application. However, it differs slightly from traditional file based routing, which we will discuss shortly.

Directory Based Routing

Qwik City support the follwing filetypes for routes

In the Qwik City routes directory, folders + an index file map to a URL path. For example, if the user sees https://example.com/some/path, the component exported at src/routes/some/path/index (either .mdx or .tsx) will be shown.

- src/
  - routes/
    - some/
      - path/
        - index.tsx       # https://example.com/some/path

Note that the leaf file at the end of the route named index. This is important. In other meta-frameworks you may be familiar with, there is a distinction made between pages and data endpoints or api routes. In Qwik City, there is no distinction, they are all endpoints.

To define an endpoint, you must a define an index.[filetype] where [filetype] can be one of:

While the following directory structure:

- src/
  - routes/
    - contact.tsx
    - about.tsx
    - store.tsx
    - index.tsx

may work in other meta-frameworks that use file based routing, Qwik City will not register a route for any non-index files. In Qwik City, the equivalent file structure would looks like this:

- src/
  - routes/
    - contact/
      - index.tsx
    - about/
      - index.tsx
    - store/
      - index.tsx
    - index/
      - index.tsx

At first this may seem like extra work, but there are advantages to this approach. One advantage is being able define component files in a route directory without them being rendered. Consider the follwing:

- src/
  - routes/
    - index.tsx                 # https://example.com/
    - some/           
      - index.tsx               # https://example.com/some
      - path/
        - index.tsx             # https://example.com/some/path
        - other_component.tsx   # this file is ignored and not mapped to any URL because it is not an index.

The other_component.tsx file can be imported and used inside of path/index.tsx, but is otherwise ignored by Qwik City.

Implementing a Component

To return HTML for a specific route you will need to implement a component. For .tsx files the component must be exported as default. Alternatively, you can use .mdx extension discussed later.

export default component$(() => {
  return (
    <H1>
      Hello World!
    </H1>
  );
});

`@qwik-city-plan`

Qwik City stores route information in files on disk. This is great for developer ergonomics but not useful for creating bundles and chunks. Additionally, in some environments - such as edge functions - there is no file system that can be accessed. For this reason, it is necessary to serialize the route information into a single file. This is done through the @qwik-city-plan import.

import cityPlan from '@qwik-city-plan';

The @qwik-city-plan import is synthetic, meaning that it is created as part of the build step. It contains all of the information in the /src/routes folder in JavaScript format. The synthetic import is provided by the qwikCity() vite plugin available from @builder.io/qwik-city/vite.

Advanced routing

Qwik City also supports:

These are discussed later.