Error Handling & 404 Pages
Relevant source files
The following files were used as context for generating this wiki page:
Error handling and "Not Found" management in wouter-vue is achieved through a combination of pattern matching, catch-all routes, and component-level logic. The system leverages the minimalist routing architecture to provide flexible ways to catch invalid paths or missing data states.
Within this framework, 404 handling is typically implemented by placing a Route component without a defined path at the end of a route list, or by using specific wildcard patterns. This ensures that if no previous routes match the current location, the fallback UI is rendered.
Default 404 Routing Mechanism
The primary method for handling 404 errors in wouter-vue applications is the use of a "catch-all" route. Because routes are evaluated in the order they are defined within a switcher component like AnimatedSwitch or Switch, an undefined path acts as a default case.
Switch-Based Fallbacks
In a standard application setup, the AnimatedSwitch component wraps multiple Route definitions. If the URL does not match any specified paths (e.g., /, /about, /users/:id), the router falls through to the final Route entry.
The diagram shows how the routing logic progresses through defined paths before hitting the fallback component.
Sources: examples/example/src/components/AppRoutes.vue:15-18, README.md:104-118
Wildcard Patterns
While a Route with no path is the most common pattern, wouter-vue also supports wildcard matching (e.g., /*) to explicitly define 404 behavior or redirect invalid nested paths.
Sources: examples/example/README.md:43
The NotFoundPage Component
The NotFoundPage.vue serves as the standard UI for 404 errors in the example implementations. It provides users with contextual information and navigation options to return to a valid application state.
Component Logic and Interaction
The component utilizes the useLocation hook to handle programmatic navigation and standard browser history for "Go Back" functionality.
| Feature | Implementation | Description |
|---|---|---|
| Home Navigation | <Link href="/" /> | Returns the user to the application root. |
| History Navigation | window.history.back() | Uses the browser's history API to return to the previous page. |
| Test Identifier | data-testid="not-found-page" | Used for automated E2E testing validation. |
Sources: examples/example/src/pages/NotFoundPage.vue:14-25, examples/example/test/pages.spec.js:154-162
Data-Level Error Handling
Beyond path-based 404 errors, applications must handle "Not Found" states when a route matches a pattern but the specific data (e.g., a User ID) does not exist in the system.
Dynamic Parameter Validation
In the UserDetailPage.vue, the useParams hook extracts the ID from the URL. The component then performs a lookup against the available data. If the lookup fails, a conditional template renders a "User not found" message instead of the user details.
This sequence illustrates the handling of valid routes that point to non-existent data.
Sources: examples/example/src/pages/UserDetailPage.vue:44-77, examples/example/test/pages.spec.js:147-152
Path Normalization and Validation
wouter-vue includes internal helpers to ensure that paths are compared correctly, preventing false 404s caused by trailing slashes, query parameters, or hashes.
Path Helper Functions
The normalizePath utility is critical for consistent routing. It strips metadata from the path string to ensure that /about?section=1 is correctly matched against the /about route.
- Query Removal: Everything after
?is ignored during matching. - Hash Removal: Everything after
#is ignored. - Trailing Slash: Normalizes
/path/to/pathto ensure consistency.
Sources: src/helpers/path-helpers.ts:13-30
Testing Error States
The project includes automated tests to ensure that error handling remains robust. These tests verify both the rendering of the 404 page and the specific data-not-found states.
test('Not Found Page - проверка контента', async ({ page }) => {
await page.goto('/non-existent-page');
await page.waitForSelector('[data-testid="not-found-page"]');
await expect(page.locator('h1')).toHaveText('Page Not Found');
});
Sources: examples/example/test/pages.spec.js:154-170
Summary
Error handling in wouter-vue is built on the principle of fall-through routing. By placing a default Route at the end of a switcher, developers can easily capture all undefined paths. Additionally, the system provides hooks like useParams to facilitate component-level error handling for scenarios where route patterns match but underlying data is missing. Consistent path normalization further ensures that routing remains predictable despite variations in URL formatting.