playbooks

home / skills / openagentsinc / openagents / wayfinder-development

wayfinder-development skill

/apps/openagents.com/.agents/skills/wayfinder-development

This skill helps you efficiently reference backend routes from frontend components by guiding imports, route generation, and type-safe usage.

npx playbooks add skill openagentsinc/openagents --skill wayfinder-development

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.2 KB
---
name: wayfinder-development
description: "Activates whenever referencing backend routes in frontend components. Use when importing from @/actions or @/routes, calling Laravel routes from TypeScript, or working with Wayfinder route functions."
license: MIT
metadata:
  author: laravel
---

# Wayfinder Development

## When to Apply

Activate whenever referencing backend routes in frontend components:
- Importing from `@/actions/` or `@/routes/`
- Calling Laravel routes from TypeScript/JavaScript
- Creating links or navigation to backend endpoints

## Documentation

Use `search-docs` for detailed Wayfinder patterns and documentation.

## Quick Reference

### Generate Routes

Run after route changes if Vite plugin isn't installed:
```bash
php artisan wayfinder:generate --no-interaction
```
For form helpers, use `--with-form` flag:
```bash
php artisan wayfinder:generate --with-form --no-interaction
```

### Import Patterns

<!-- Controller Action Imports -->
```typescript
// Named imports for tree-shaking (preferred)...
import { show, store, update } from '@/actions/App/Http/Controllers/PostController'

// Named route imports...
import { show as postShow } from '@/routes/post'
```

### Common Methods

<!-- Wayfinder Methods -->
```typescript
// Get route object...
show(1) // { url: "/posts/1", method: "get" }

// Get URL string...
show.url(1) // "/posts/1"

// Specific HTTP methods...
show.get(1)
store.post()
update.patch(1)
destroy.delete(1)

// Form attributes for HTML forms...
store.form() // { action: "/posts", method: "post" }

// Query parameters...
show(1, { query: { page: 1 } }) // "/posts/1?page=1"
```

## Wayfinder + Inertia

Use Wayfinder with the `<Form>` component:
<!-- Wayfinder Form (React) -->
```typescript
<Form {...store.form()}><input name="title" /></Form>
```

## Verification

1. Run `php artisan wayfinder:generate` to regenerate routes if Vite plugin isn't installed
2. Check TypeScript imports resolve correctly
3. Verify route URLs match expected paths

## Common Pitfalls

- Using default imports instead of named imports (breaks tree-shaking)
- Forgetting to regenerate after route changes
- Not using type-safe parameter objects for route model binding

Overview

This skill integrates Wayfinder route helpers into frontend TypeScript workflows. It activates whenever you reference backend routes from components, imports from @/actions or @/routes, or call Laravel routes from JavaScript/TypeScript. The skill enforces correct import patterns, route generation checks, and practical usage of route helper methods.

How this skill works

It inspects imports and calls that reference Wayfinder-generated modules (e.g., imports from @/actions or @/routes) and validates usage patterns in components. It flags incorrect default imports, missing route regeneration steps, and unsafe parameter usage, and it reminds you of commands to regenerate TypeScript route definitions. The skill also surfaces common method patterns like .url(), .get/.post, and .form() for easier developer use.

When to use it

  • When importing controller actions or route helpers from @/actions or @/routes
  • When generating links or navigation that call Laravel routes from TypeScript/JS
  • When building forms or submitting to backend endpoints from the frontend
  • When changing backend routes and needing to regenerate TypeScript route definitions
  • When using Wayfinder with frameworks like Inertia or client-side form helpers

Best practices

  • Prefer named imports for tree-shaking and correct resolution (avoid default imports)
  • Run php artisan wayfinder:generate after route changes if Vite plugin is not present
  • Use the provided .url() helper for URL strings and .form() for HTML form attributes where available
  • Pass typed parameter objects for route-model binding instead of loose primitives
  • Verify TypeScript imports resolve during CI or preflight checks to catch generation issues early

Example use cases

  • Generate a link: import { show as postShow } from '@/routes/post' and use postShow.url(1) to render an anchor href
  • Submit a form with Inertia: <Form {...store.form()}><input name="title"/></Form> using the store.form() helper
  • Call controller actions in frontend code by importing named action functions from @/actions and invoking show(1) or store.post()
  • Run php artisan wayfinder:generate --with-form after adding form helpers on the backend to keep TypeScript helpers in sync
  • Add query parameters: use show(1, { query: { page: 1 } }) to generate a URL with query string

FAQ

What command do I run after changing routes?

Run php artisan wayfinder:generate (add --with-form to include form helpers). Use this when the Vite plugin isn’t installed.

Why use named imports instead of default imports?

Named imports preserve tree-shaking and ensure the TypeScript resolver finds specific route/action exports; default imports can break resolution and increase bundle size.