🚀 Inertia Route Helper

Powerful routing helper for Inertia.js v2 & v3 applications

Work seamlessly with Laravel Ziggy or Wayfinder routes, with full support for subfolder deployments, query parameters, subfolder path deduplication, and route validation.

Features • Installation • Usage • API Reference • Examples

✨ Features

🔗 Absolute URL Generation - Automatically prepends your base URL to all routes
📁 Subfolder Deployment Support - Perfect for apps deployed in subfolders
🔍 Query Parameters - Build routes with query strings effortlessly
🎯 Route Validation - Check if routes match the current path
🎨 TypeScript First - Full type safety and IntelliSense support
⚡ Inertia.js v2 & v3 - Works seamlessly with both versions
🔄 Subfolder Deduplication - Prevents URL doubling when routes already include the subfolder path (essential for Inertia v3 deployed apps)
🌐 SSR Safe - Works perfectly with server-side rendering
🪶 Lightweight - Minimal bundle size
⚙️ Configurable - Customize behavior to fit your needs
📦 Modular Architecture - One function per file for easy reading
🔧 Separate Init Module - /init import for setup, main import for usage
✅ Fully Tested - Comprehensive test coverage
📚 Complete Documentation - Detailed API reference and examples

📖 Documentation

Quick Start Guide - Get started in 5 minutes
Complete API Reference - Full documentation of all functions
Examples - Framework-specific examples
CHANGELOG - Version history and updates

📦 Installation

npm install @tunbudi06/inertia-route-helper

yarn add @tunbudi06/inertia-route-helper

pnpm add @tunbudi06/inertia-route-helper

🚀 Quick Start

Installation

npm install @tunbudi06/inertia-route-helper

Setup

Just pass props - the helper automatically finds initialPage.props.baseUrl:

// resources/js/app.tsx (React) or resources/js/app.ts (Vue/Svelte)
import { createInertiaApp } from '@inertiajs/react'; // or vue3/svelte
import { initRouteHelper } from '@tunbudi06/inertia-route-helper/init';

createInertiaApp({
    resolve: (name) => {
        // Your page resolver
    },
    setup({ el, App, props }) {
        // Just pass props - super simple!
        initRouteHelper(props);
        
        // Mount your app...
    },
});

💡 Import from /init: Import initialization functions from /init for cleaner separation. Route helper functions from main import.

Laravel Setup (Required)

Share your base URL with Inertia:

// app/Http/Middleware/HandleInertiaRequests.php

public function share(Request $request): array
{
    return array_merge(parent::share($request), [
        'baseUrl' => rtrim(config('app.url'), '/'),
    ]);
}

Basic Usage

import { route, routeUrl, buildRoute } from '@tunbudi06/inertia-route-helper';
import { dashboard, profile } from '@/routes'; // Your Ziggy/Wayfinder routes

// Get the full route object with absolute URL
const dashboardRoute = route(dashboard());
console.log(dashboardRoute.url); // https://example.com/dashboard

// Get just the URL string
const profileUrl = routeUrl(profile({ id: 123 }));
console.log(profileUrl); // https://example.com/profile/123

// Build route with query parameters
const searchUrl = buildRoute('/search', {
  query: { q: 'inertia', page: 2 },
  fragment: 'results'
});
console.log(searchUrl); // https://example.com/search?q=inertia&page=2#results

📚 API Reference

Initialization

`initRouteHelper(data)`

Initialize the route helper with Inertia props. Automatically extracts baseUrl from various data structures.

💡 Import from /init: This function is available from @tunbudi06/inertia-route-helper/init for better tree shaking.

Parameters:

data - Can be props from createInertiaApp, Svelte $page store, or any object containing baseUrl

Supports:

props.initialPage.props.baseUrl (React/Vue createInertiaApp)
page.props.baseUrl (Svelte $page store)
data.baseUrl (direct object)

import { initRouteHelper } from '@tunbudi06/inertia-route-helper/init';

// React/Vue - Pass props from createInertiaApp
createInertiaApp({
  setup({ el, App, props }) {
    initRouteHelper(props);
  }
});

// Svelte - Can use props or $page
import { page } from '@inertiajs/svelte';
initRouteHelper(props); // or initRouteHelper($page)

Core Route Functions

`route(routeDefinition)`

Transform a route definition to include absolute URL with base URL prepended.

Parameters:

routeDefinition - Route object with url property (from Ziggy/Wayfinder)

Returns: Route object with absolute URL

import { route } from '@tunbudi06/inertia-route-helper';

const dashboardRoute = route({ url: '/dashboard', method: 'GET' });
// { url: 'https://example.com/dashboard', method: 'GET' }

`routeUrl(routeDefinition)`

Get just the URL string from a route definition.

Parameters:

routeDefinition - Route object with url property

Returns: Absolute URL string

import { routeUrl } from '@tunbudi06/inertia-route-helper';
import { users } from '@/routes';

const url = routeUrl(users.show({ id: 123 }));
// 'https://example.com/users/123'

`buildRoute(path, options?)`

Build a complete URL with query parameters and fragment.

Parameters:

path - Base path (e.g., '/search')
options - Optional configuration
- query? - Query parameters object
- fragment? - Fragment/hash identifier
- absolute? - Whether to include base URL (default: true)

Returns: Complete URL string

import { buildRoute } from '@tunbudi06/inertia-route-helper';

// With query parameters
const url = buildRoute('/search', {
  query: { q: 'test', page: 2 },
  fragment: 'results'
});
// 'https://example.com/search?q=test&page=2#results'

// Relative URL
const relativeUrl = buildRoute('/api/users', { absolute: false });
// '/api/users'

// With array parameters
const filtersUrl = buildRoute('/products', {
  query: { tags: ['new', 'featured'], colors: ['red', 'blue'] }
});
// 'https://example.com/products?tags[]=new&tags[]=featured&colors[]=red&colors[]=blue'

`makeRoute(definition)`

Build route from a RouteDefinition object (convenience wrapper).

Parameters:

definition - Route definition object with url, query, and fragment

Returns: Complete URL string

import { makeRoute } from '@tunbudi06/inertia-route-helper';

const url = makeRoute({
  url: '/posts',
  query: { status: 'published' },
  fragment: 'list'
});
// 'https://example.com/posts?status=published#list'

Navigation Helpers

`isCurrentRoute(path, useHost?, exact?)`

Check if a path matches the current browser location.

Parameters:

path - Path to check (e.g., '/dashboard')
useHost? - Whether to include the baseUrl or not (default: false)
exact? - Whether to match exactly (default: false for partial match)

Returns: true if path matches current location

import { isCurrentRoute } from '@tunbudi06/inertia-route-helper';

// Current URL: https://example.com/dashboard/settings

isCurrentRoute('/dashboard');                      // true (partial match)
isCurrentRoute('/dashboard', false, true);         // false (not exact)
isCurrentRoute('/dashboard/settings', false, true); // true (exact match)

// With useHost=true (check against full URL)
isCurrentRoute('/dashboard', true);                               // true
isCurrentRoute('https://example.com/dashboard', true);            // true
isCurrentRoute('https://example.com/dashboard/settings', true, true); // true (exact)
isCurrentRoute('https://example.com/dashboard', true, true);      // false (not exact)

// Use in components for active navigation
const isActive = isCurrentRoute('/dashboard');

`currentPath()`

Get the current pathname from browser location (SSR-safe).

Returns: Current pathname or empty string on server

import { currentPath } from '@tunbudi06/inertia-route-helper';

const path = currentPath();
// '/dashboard/settings'

`currentUrl()`

Get the complete current URL from browser location (SSR-safe).

Returns: Full URL or empty string on server

import { currentUrl } from '@tunbudi06/inertia-route-helper';

const url = currentUrl();
// 'https://example.com/dashboard/settings?tab=profile#section'

Configuration

`configure(options)`

Configure route helper behavior globally.

Parameters:

options - Configuration object
- baseUrl? - Override base URL
- trailingSlash? - Add trailing slash to URLs (default: false)
- validateRoutes? - Enable route validation (default: false)

import { configure } from '@tunbudi06/inertia-route-helper';

configure({
  baseUrl: 'https://custom-domain.com',
  trailingSlash: true,
  validateRoutes: false
});

Advanced Functions

`setBaseUrl(url)`

Manually set the base URL (for testing or advanced use cases).

Parameters:

url - Base URL string

import { setBaseUrl } from '@tunbudi06/inertia-route-helper';

setBaseUrl('https://example.com');

`getBaseUrl()`

Get the current base URL.

Returns: Current base URL string

import { getBaseUrl } from '@tunbudi06/inertia-route-helper';

const baseUrl = getBaseUrl();
// 'https://example.com'

📖 Usage Examples

Working with Ziggy Routes

import { route, routeUrl } from '@tunbudi06/inertia-route-helper';
import { users, posts } from '@/routes';

// Simple route
const usersUrl = routeUrl(users());
// https://example.com/users

// Route with parameters
const userUrl = routeUrl(users.show({ user: 42 }));
// https://example.com/users/42

// Complex route with parameters
const postUrl = routeUrl(posts.edit({ post: 10, comment: 5 }));
// https://example.com/posts/10/comments/5/edit

Building Routes with Query Parameters

import { buildRoute, makeRoute } from '@tunbudi06/inertia-route-helper';

// Using buildRoute
const productsUrl = buildRoute('/products', {
  query: {
    category: 'electronics',
    sort: 'price',
    order: 'desc',
    page: 2
  }
});
// https://example.com/products?category=electronics&sort=price&order=desc&page=2

// With array parameters
const filtersUrl = buildRoute('/api/items', {
  query: {
    tags: ['featured', 'new', 'sale'],
    price: [10, 100]
  }
});
// https://example.com/api/items?tags[]=featured&tags[]=new&tags[]=sale&price[]=10&price[]=100

// Using makeRoute with RouteDefinition
const searchUrl = makeRoute({
  url: '/search',
  query: { q: 'inertia' },
  fragment: 'results'
});
// https://example.com/search?q=inertia#results

Route Navigation & Validation

import { isCurrentRoute, currentPath, currentUrl } from '@tunbudi06/inertia-route-helper';

// Check if a route is active (for navigation highlighting)
const isActive = isCurrentRoute('/dashboard'); // Partial match
const isExactActive = isCurrentRoute('/dashboard', false, true); // Exact match
const isActiveFullUrl = isCurrentRoute('https://example.com/dashboard', true); // Using full URL

// Get current path
const path = currentPath();
console.log(path); // /dashboard/settings

// Get current full URL
const url = currentUrl();
console.log(url); // https://example.com/dashboard/settings

Configuration

import { configure } from '@tunbudi06/inertia-route-helper';

// Configure the route helper
configure({
  baseUrl: 'https://custom-domain.com', // Override base URL
  trailingSlash: true, // Add trailing slashes to URLs
  validateRoutes: true // Enable route validation (future feature)
});

Manual Base URL Management

import { setBaseUrl, getBaseUrl } from '@tunbudi06/inertia-route-helper';

// Manually set base URL (useful for testing or special cases)
setBaseUrl('https://staging.example.com');

// Get the current base URL
const base = getBaseUrl();
console.log(base); // https://staging.example.com

🎯 API Reference

Core Functions

`route<T>(routeDefinition: T): T`

Wraps a route definition and adds the absolute URL.

const userRoute = route(users.show({ id: 1 }));

`routeUrl<T>(routeDefinition: T): string`

Returns just the absolute URL string for a route.

const url = routeUrl(dashboard());

`buildRoute(path: string, options?): string`

Build a complete URL with query parameters and fragment.

const url = buildRoute('/search', {
  query: { q: 'hello' },
  fragment: 'top',
  absolute: true // default
});

`makeRoute(definition: RouteDefinition): string`

Enhanced route builder with full feature support.

const url = makeRoute({
  url: '/products',
  query: { category: 'books' },
  fragment: 'featured'
});

Navigation Functions

`isCurrentRoute(path: string, useHost?: boolean, exact?: boolean): boolean`

Check if a route matches the current path.

const isActive = isCurrentRoute('/dashboard'); // Partial match (pathname only)
const isExact = isCurrentRoute('/dashboard', false, true); // Exact match (pathname only)
const isActiveFullUrl = isCurrentRoute('https://example.com/dashboard', true); // Using full URL

`currentPath(): string`

Get the current route path (relative).

const path = currentPath(); // '/dashboard/profile'

`currentUrl(): string`

Get the current full URL.

const url = currentUrl(); // 'https://example.com/dashboard/profile'

Configuration Functions

`configure(options: RouteHelperConfig): void`

Configure the route helper behavior.

configure({
  baseUrl: 'https://example.com',
  trailingSlash: true,
  validateRoutes: false
});

`setBaseUrl(url: string): void`

Manually set the base URL.

setBaseUrl('https://api.example.com');

`getBaseUrl(): string`

Get the current base URL.

const base = getBaseUrl();

💡 Examples

React Example

import { Link } from '@inertiajs/react';
import { routeUrl, isCurrentRoute } from '@tunbudi06/inertia-route-helper';
import { dashboard, profile, settings } from '@/routes';

export function Navigation() {
  return (
    <nav>
      <Link 
        href={routeUrl(dashboard())}
        className={isCurrentRoute('/dashboard') ? 'active' : ''}
      >
        Dashboard
      </Link>
      
      <Link 
        href={routeUrl(profile({ id: userId }))}
        className={isCurrentRoute(`/profile/${userId}`, false, true) ? 'active' : ''}
      >
        Profile
      </Link>
      
      <Link href={routeUrl(settings())}>
        Settings
      </Link>
    </nav>
  );
}

Vue Example

<script setup lang="ts">
import { Link } from '@inertiajs/vue3';
import { routeUrl, isCurrentRoute, buildRoute } from '@tunbudi06/inertia-route-helper';
import { posts, search } from '@/routes';

const searchQuery = ref('');

const handleSearch = () => {
  const url = buildRoute('/search', {
    query: { q: searchQuery.value, type: 'posts' }
  });
  router.visit(url);
};
</script>

<template>
  <div>
    <Link 
      :href="routeUrl(posts())" 
      :class="{ active: isCurrentRoute('/posts') }"
    >
      All Posts
    </Link>
    
    <form @submit.prevent="handleSearch">
      <input v-model="searchQuery" placeholder="Search..." />
      <button type="submit">Search</button>
    </form>
  </div>
</template>

Svelte Example

<script lang="ts">
  import { router } from '@inertiajs/svelte';
  import { routeUrl, buildRoute, isCurrentRoute } from '@tunbudi06/inertia-route-helper';
  import { products, categories } from '@/routes';
  
  let selectedCategory = 'all';
  
  function filterProducts(category: string) {
    const url = buildRoute('/products', {
      query: { category, sort: 'popular' }
    });
    router.visit(url);
  }
</script>

<nav>
  <a 
    href={routeUrl(products())} 
    class:active={isCurrentRoute('/products')}
  >
    Products
  </a>
  
  <button on:click={() => filterProducts('electronics')}>
    Electronics
  </button>
</nav>

🌐 Subfolder Deployments

This package is perfect for Laravel apps deployed in subfolders:

// .env
APP_URL=https://example.com/my-app

// The package automatically handles this!

import { routeUrl } from '@tunbudi06/inertia-route-helper';
import { dashboard } from '@/routes';

const url = routeUrl(dashboard());
// Correctly returns: https://example.com/my-app/dashboard
// Not just: https://example.com/dashboard

🔄 Smart Subfolder Deduplication (v3.0.0+)

When deploying in subfolders, some routing libraries (Ziggy, Wayfinder) may generate route paths that already include the subfolder path. This helper automatically detects and deduplicates to prevent URL doubling:

// baseUrl = 'http://localhost/myapp'

// Route already includes subfolder — automatically deduplicated
const url = routeUrl({ url: '/myapp/dashboard' });
// ✅ 'http://localhost/myapp/dashboard'
// ❌ Not: 'http://localhost/myapp/myapp/dashboard'

// Route without subfolder — works normally
const url2 = routeUrl({ url: '/dashboard' });
// 'http://localhost/myapp/dashboard'

This is especially important for Inertia v3 apps where the base URL's subfolder path may be included in route definitions by default.

🔧 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { 
  RouteDefinition, 
  QueryParams, 
  RouteHelperConfig 
} from '@tunbudi06/inertia-route-helper';

const route: RouteDefinition = {
  url: '/users',
  query: { page: 1, limit: 10 },
  fragment: 'list'
};

const query: QueryParams = {
  search: 'hello',
  filters: ['active', 'verified'],
  page: 1
};

const config: RouteHelperConfig = {
  baseUrl: 'https://example.com',
  trailingSlash: false
};

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

🙏 Acknowledgments

Built for Inertia.js v2 & v3
Works with Ziggy and Wayfinder
Inspired by the Laravel and Inertia.js communities

⬆ back to top

Made with ❤️ by TUNBudi06

Name		Name	Last commit message	Last commit date
.github		.github
.idea		.idea
docs		docs
examples		examples
src		src
test		test
.gitignore		.gitignore
.npmignore		.npmignore
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
TESTING.md		TESTING.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

🚀 Inertia Route Helper

✨ Features

📖 Documentation

📦 Installation

🚀 Quick Start

Installation

Setup

Laravel Setup (Required)

Basic Usage

📚 API Reference

Initialization

initRouteHelper(data)

Core Route Functions

route(routeDefinition)

routeUrl(routeDefinition)

buildRoute(path, options?)

makeRoute(definition)

Navigation Helpers

isCurrentRoute(path, useHost?, exact?)

currentPath()

currentUrl()

Configuration

configure(options)

Advanced Functions

setBaseUrl(url)

getBaseUrl()

📖 Usage Examples

Working with Ziggy Routes

Building Routes with Query Parameters

Route Navigation & Validation

Configuration

Manual Base URL Management

🎯 API Reference

Core Functions

route<T>(routeDefinition: T): T

routeUrl<T>(routeDefinition: T): string

buildRoute(path: string, options?): string

makeRoute(definition: RouteDefinition): string

Navigation Functions

isCurrentRoute(path: string, useHost?: boolean, exact?: boolean): boolean

currentPath(): string

currentUrl(): string

Configuration Functions

configure(options: RouteHelperConfig): void

setBaseUrl(url: string): void

getBaseUrl(): string

💡 Examples

React Example

Vue Example

Svelte Example

🌐 Subfolder Deployments

🔄 Smart Subfolder Deduplication (v3.0.0+)

🔧 TypeScript Support

🤝 Contributing

📝 License

🙏 Acknowledgments

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`initRouteHelper(data)`

`route(routeDefinition)`

`routeUrl(routeDefinition)`

`buildRoute(path, options?)`

`makeRoute(definition)`

`isCurrentRoute(path, useHost?, exact?)`

`currentPath()`

`currentUrl()`

`configure(options)`

`setBaseUrl(url)`

`getBaseUrl()`

`route<T>(routeDefinition: T): T`

`routeUrl<T>(routeDefinition: T): string`

`buildRoute(path: string, options?): string`

`makeRoute(definition: RouteDefinition): string`

`isCurrentRoute(path: string, useHost?: boolean, exact?: boolean): boolean`

`currentPath(): string`

`currentUrl(): string`

`configure(options: RouteHelperConfig): void`

`setBaseUrl(url: string): void`

`getBaseUrl(): string`