repository·main·Indexed 42 days ago
https://github.com/pronextjs/declarative-routingA typesafe and declarative routing system for NextJS, React Router, and QwikCity projects. It automates URL generation via route-tied components, providing typesafe Link components, fetch wrapping functions for API routes, and typed hooks (usePush, useParams, useSearchParams) to access routing data safely. Version 0.1.20.
The makeRoute.tsx file is copied into your ~/declarativeRoutes module during setup. This allows you to own and customize the routing implementation (for example, changing how the .Link component behaves).
Warning: Do not change the parameters of the makeRoute function, as this will break compatibility with the declarative-routing build command.
The makeRoute.tsx file is copied into your ~/declarativeRoutes directory during initialization. This allows you to own and customize the routing logic (e.g., changing how the Link component behaves) without modifying the core package.
Warning: Do not change the parameters of the makeRoute function, as this will break compatibility with the declarative-routing build command.
Declarative routing is a typesafe routing system that moves beyond simple URL validation. While typesafe routing ensures parameters and route handlers are correct, declarative routing ensures your navigation components (like links) are automatically synchronized with your route structure.
Instead of manually constructing URL strings like <Link to={/product/${product.id}}>, you use route-specific components that are typed to the route itself, such as <ProductDetail.Link productId={product.id}>. If a route path or its required parameters change, the component automatically reflects these changes throughout your application, preventing broken links.
// Traditional typesafe routing (manual URL construction)
<Link to={`/product/${product.id}`}>Product</Link>
// Declarative routing (automatic URL generation via typed components)
<ProductDetail.Link productId={product.id}>Product</ProductDetail.Link>This project uses Qwik with QwikCity for directory-based routing and layouts. The core directory structure is as follows:
src/routes: Contains the directory-based routing logic. This includes layout.tsx files for defining hierarchies and index.tsx files for pages. index.ts files are used to define endpoints.src/components: The recommended location for reusable components.public: A directory for static assets like images.The build command automates route generation by scanning your .src/routes/ directory for index.tsx files.
index.tsx, it generates a routeInfo.ts file in the same directory.routeInfo.ts files into ~/declarativeRoutes/index.ts.makeRoute invocations inside ~/declarativeRoutes/index.ts so all routes are available from a single entry point.Manual Edits: You should manually edit routeInfo.ts files to add search schemas if a page supports search parameters. The build command will not automatically detect search schema changes, but it will maintain the link between the route and the central index.
The build command automates route generation by scanning page.tsx and route.tsx files in your directory.
.info.ts file (e.g., page.info.ts or route.info.ts) in the same directory as the route file..info.ts files into @/routes/index.ts.@/routes/index.ts then exports all routes, allowing them to be imported by components throughout your app.Note: You should manually edit .info.ts files to add search schemas for pages or result/body schemas for API routes.
To set up declarative routing in an existing React-Router project, follow these steps:
starter folder as a base.npx declarative-routing init./src/routes, which is the standard directory for React-Router.This process generates helper files in your routes directory, including index.ts for manual route creation and makeRoute.tsx for creating route objects for pages and APIs.
npx declarative-routing initTo set up typesafe routing in a QwikCity project, follow these steps:
starter folder from the repository.npx declarative-routing initroutes directory (defaults to ./src/routes)../src/declarativeRoutes).This process generates a directory containing hooks.ts (providing hooks for params and search params) and index.ts (exporting route objects like HomeRoute, SearchRoute, etc.).
npx declarative-routing initTo set up declarative routing in an existing NextJS project, run the initialization command. This process generates a dedicated routes directory (defaulting to ./src/routes, though you can specify a custom location during the interactive installation) which serves as the source of truth for your typesafe navigation. The initialization also creates a README.md within the routes directory containing specific instructions for your generated routing structure.
npx declarative-routing initTo set up declarative routing in a NextJS project, follow these steps:
starter folder into your project.npx declarative-routing initDuring initialization, you will be prompted for:
./src/routes (the standard NextJS location)../src/routes.No.After initialization, the following files are generated in ./src/routes:
hooks.ts: Contains hooks for accessing route parameters and search parameters.index.ts: Exports the route objects (e.g., Home, Search, PokemonPokemonId).makeRoute.tsx: A helper function for creating route objects for both page and API routes.npx declarative-routing initTo start using the system in a QwikCity application, run the initialization command. This creates a ~/declarativeRoutes directory containing your route definitions and a README.md guide.
When you add new pages or change route paths, you must run the build command to synchronize the ~/declarativeRoutes directory with your actual file structure.
# Initialize the routing system
npx declarative-routing init
# Update routes after adding pages or changing paths
npx declarative-routing buildEach route in your project should have a corresponding routeInfo.ts file to define its schema using Zod. This schema controls the types for path parameters (params) and URL search parameters (search).
For routes like /search that use query strings, use the search key in the Route object:
export const Route = {
name: "Search",
params: z.object({}),
search: z.object({
q: z.string().optional(),
limit: z.coerce.number().optional()
})
};For dynamic routes like /pokemon/[pokemonId], use the params key:
export const Route = {
name: "PokemonPokemonId",
params: z.object({
pokemonId: z.coerce.number()
})
};Note: You can customize the exported name of the route object by changing the name key in routeInfo.ts. After changing the name, run pnpm dr:build to regenerate the files.