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 supports the following filetypes for routes
In the Qwik City routes directory, folder-path
plus 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 is 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 define an index.[filetype]
where [filetype] can be one of .ts
, .tsx
, .js
, .jsx
, .md
, or .mdx
.
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 look like this:
src/
└── routes/
├── contact/
│ └── index.tsx # https://example.com/contact
├── about/
│ └── index.tsx # https://example.com/about
├── store/
│ └── index.tsx # https://example.com/store
└── index/
└── index.tsx # https://example.com/index
At first, this may seem like extra work, but there are advantages to this approach. One advantage is being able to define component files in a route directory without them being rendered. Consider the following:
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.