Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/guide/type-safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -335,7 +335,7 @@ import { routeUrl } from 'void/routes';

:::

Links also accept same-page queries and hashes (`?page=2`, `#comments`), and `http://`, `https://`, `mailto:`, and `tel:` URLs. Use absolute paths within your app; relative paths such as `../settings` are rejected. Static path segments accept raw text such as `/café menu` or uppercase percent encoding such as `/caf%C3%A9%20menu`.
Links also accept same-page queries and hashes (`?page=2`, `#comments`), and `http://`, `https://`, `mailto:`, and `tel:` URLs. A `routeUrl()` result takes the same query or hash suffix, so `` `${routeUrl('/users/[id]', { params: { id } })}?tab=activity` `` is checked too. Use absolute paths within your app; relative paths such as `../settings` are rejected. Static path segments accept raw text such as `/café menu` or uppercase percent encoding such as `/caf%C3%A9%20menu`.

With `routing.typedRoutes`, URLs handled only by root dynamic routes (`/[slug]`, `/[...slug]`, or `/[...]`) require `routeUrl()`, for example `routeUrl('/[...slug]', { params: { slug: 'dashboard' } })`. Other declared routes still accept checked URL strings. For a custom 404 page, use [`_not-found`](./pages-routing/errors.md#missing-pages).

Expand Down
3 changes: 2 additions & 1 deletion packages/void/src/codegen/route-types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -188,9 +188,10 @@ export function generateRouteTypes(
' type RoutePathUrl = RoutePatternUrl<CheckedRoutePath<RoutePath | EncodedRoutePath>>;',
);
lines.push(' type BuiltRouteUrl = string & { readonly __voidRouteUrl: true };');
lines.push(' type RouteUrlBase = BuiltRouteUrl | RoutePathUrl;');
lines.push(' type TypedRoutes = RouteTypesConfig extends { typedRoutes: true } ? true : false;');
lines.push(' export type RouteUrl = TypedRoutes extends true');
lines.push(' ? BuiltRouteUrl | RoutePathUrl | `${RoutePathUrl}${"?" | "#"}${string}`');
lines.push(' ? RouteUrlBase | `${RouteUrlBase}${"?" | "#"}${string}`');
lines.push(' : string;');
lines.push(' export type Href = TypedRoutes extends true');
lines.push(
Expand Down
5 changes: 4 additions & 1 deletion packages/void/src/runtime/routing/route-url.ts
Original file line number Diff line number Diff line change
Expand Up @@ -112,13 +112,16 @@ type RoutePathUrl = RoutePatternUrl<CheckedRoutePath<RoutePath | EncodedRoutePat
// Use a structural marker so package and generated declarations agree when a
// helper-built URL crosses into a navigation, form, or stream client.
type BuiltRouteUrl = string & { readonly __voidRouteUrl: true };
// Suffix a shared base so a helper-built URL keeps the same query and hash forms
// as a route path, including when it is typed as `RouteUrl`.
type RouteUrlBase = BuiltRouteUrl | RoutePathUrl;

/** Whether `routing.typedRoutes` is on in the generated route types. */
export type TypedRoutes = RouteTypesConfig extends { typedRoutes: true } ? true : false;

/** The URL of one of the app's routes. A plain string unless `routing.typedRoutes` is on. */
export type RouteUrl = TypedRoutes extends true
? BuiltRouteUrl | RoutePathUrl | `${RoutePathUrl}${'?' | '#'}${string}`
? RouteUrlBase | `${RouteUrlBase}${'?' | '#'}${string}`
: string;

/** Anything a link can point to: a route URL, a same-page query or hash, or an external URL. */
Expand Down
12 changes: 12 additions & 0 deletions packages/void/test/integration/route-url-builder.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,22 @@ const empty: Href = '';
// @ts-expect-error route URLs exclude external links
const external: RouteUrl = 'https://vite.dev';
void [plain, hrefs, unknown, unchecked, relative, protocolRelative, empty, external];
// A query or hash appended to a built or declared route URL stays a route URL.
const paged: RouteUrl = \`\${user}?page=2\`;
const hashed: RouteUrl = \`\${user}#details\`;
const builtPaged: RouteUrl = \`\${routeUrl('/about')}?page=2\`;
// @ts-expect-error a suffix does not replace the route check
const unknownPaged: RouteUrl = '/unknown?page=2';
// @ts-expect-error a suffix needs its own separator
const unseparated: RouteUrl = \`\${user}page=2\`;
declare const router: VoidRouter;
void router.visit('/users/42');
void router.visit(routeUrl('/about'));
void router.visit(\`\${routeUrl('/about')}?page=2\`);
void router.visit(\`\${user}?page=2\`);
void router.visit(\`\${user}#details\`);
void router.visit({ pathname: '/users/:id', params: { id } });
void [paged, hashed, builtPaged, unknownPaged, unseparated];
void router.prefetch(new URL('https://example.com'));
router.flush('#details');
// @ts-expect-error router navigation is checked
Expand Down