Utility Helpers

Relevant source files

The following files were used as context for generating this wiki page:

• src/helpers/path-helpers.ts
• types/helpers.d.ts
• src/vite-plugin-routes.ts
• README.md
• examples/example/src/pages/AboutPage.vue
• src/helpers/dev-helpers.ts (referenced via types)
• src/helpers/ssr-helpers.ts (referenced via types)

Utility Helpers in wouter-vue provide a foundation of stateless logic and specialized tools designed to facilitate path normalization, component resolution, and environment-specific behaviors. These helpers ensure that the routing engine remains lightweight (~2KB) while providing robust support for SSR, development warnings, and complex path matching.

The utility layer is divided into specialized modules including path manipulation, Vue-specific property resolution, and build-time route generation via Vite. Sources: README.md:10, types/helpers.d.ts:1-12

Path Manipulation and Validation

The path helper module is responsible for cleaning and resolving URLs to ensure consistent matching across different browser and server environments. It handles the removal of artifacts such as query strings and hashes which are not relevant for route matching but are necessary for full path reconstruction.

Path Normalization Logic

The normalizePath function standardizes strings for active state detection. It enforces a consistent trailing slash policy where the root is always / and other paths have trailing slashes removed.

This diagram illustrates the sequential transformation of a URL string into a normalized path for route comparison. Sources: src/helpers/path-helpers.ts:13-31

Target Resolution

Functions in this section manage the flexibility between href and to props, which is a common requirement when migrating from other routing libraries like vue-router.

Function	Purpose	Logic
resolveTargetPath	Extracts the URI	Prioritizes to or href based on a boolean toggle.
validateTargetPathProps	Dev-mode linting	Warns if both props are present or if neither is provided.
shouldIgnoreNavigationClick	Event filtering	Detects meta keys (Ctrl, Alt, etc.) or right-clicks to allow browser default behavior.

Sources: src/helpers/path-helpers.ts:40-84

Development and SSR Support

wouter-vue includes specialized utilities to detect the execution environment and provide developer feedback without bloating the production bundle.

• Environment Detection: Helpers like isSSR, isBrowser, and isDev allow components to conditionally execute logic (e.g., accessing window.location).
• Developer Warnings: devWarn provides formatted console output during development to catch configuration errors early.
• SSR Path Parsing: parseSsrPath handles the extraction of routing information from server requests.

Sources: types/helpers.d.ts:10-12

Build-Time Route Automation

The vite-plugin-routes.ts utility acts as a bridge between the filesystem and the application bundle. It automates the creation of route configurations by scanning specific directories.

Route Generation Workflow

The plugin can compress numeric route patterns (e.g., Route1.vue, Route2.vue) into a template-based array to significantly reduce the entry-point size for applications with hundreds of routes.

This sequence shows how the utility automates route discovery and optimizes the final bundle during the Vite build process. Sources: src/vite-plugin-routes.ts:114-220

Plugin Configuration

The following options control the behavior of the route generation helper:

Option	Type	Default	Description
dir	string	src/pages/routes	The source directory for route components.
pattern	RegExp	/Route(\d+)\.vue$/	Regex to identify valid route files.
compress	boolean	true	Enables template-based compression for numeric routes.
minify	boolean	true	Removes line breaks from the generated JS file.

Sources: src/vite-plugin-routes.ts:20-65

Vue Integration Helpers

These utilities bridge the routing logic with Vue's reactivity system and slot API.

• Slot Resolution: resolveSlot and resolveSlotWithParams handle the rendering of component children, allowing the router to pass dynamic parameters into scoped slots. Sources: types/helpers.d.ts:9
• Reactive Data Passing: The useRouteData and useParams composables leverage internal helpers to retrieve merged hierarchical data from the routing tree. Sources: examples/example/src/pages/AboutPage.vue:88-94, types/helpers.d.ts:13

// Example: Using path-helpers to validate props
// Sources: [src/helpers/path-helpers.ts:51-61]
export function resolveTargetPath(
  props: { href?: string; to?: string },
  preferTo: boolean = false
): string {
  if (preferTo) {
    return props.to || props.href || ''
  }
  return props.href || props.to || ''
}

Summary

The Utility Helpers provide the essential infrastructure for wouter-vue, handling tasks ranging from low-level string normalization in path-helpers.ts to high-level build automation in vite-plugin-routes.ts. By abstracting these concerns, the core router maintains its high-performance profile and small footprint while offering features like SSR support and development-time validation.