README

Introduction

This package generates TypeScript types from your Laravel routes, and provides an extensible client for interacting with the routes in a type safe way. It relies on the fantastic Spatie Typescript Transformer under the hood.

Installation

You can install the package via composer:

composer require vod/laravel-typed-routes

You can publish the config file with:

php artisan vendor:publish --tag="laravel-typed-routes-config"

This is the contents of the published config file:

return [
    'output_path' => 'resources/routes.d.ts',
];

This defines where the generated types will be output.

Generating Types

php artisan typescript:transform-routes

This will generate the types and output them to the path defined in the config file. It's recommended That you run this on save or as a part of your front end dev tooling, so that types are kept up to date.

Setup with Typescript

Setup is easy! In your project, you'll need to setup an rpc client, something as simple as this;

/**
 * This puts together the client with the route types. Depending on where you 
 * publish the routes, and where this file is, you may need to adjust the import.
 * 
 */
import { Routes } from "./types/routes";

//... A basic client, only exposes a basic fetch wrapper;
import { makeBasicClient } from "../../vendor/vod/laravel-typed-routes/js/basicClient";
//... Expects React Query to be installed, and exposes `useQuery` and `useMutation` methods;
import {makeReactQueryClient} from "../../vendor/vod/laravel-typed-routes/js/reactQueryClient";
//... Expects Inertia to be installed, and exposes `useForm` and `visit` methods;
import { makeInertiaClient } from "../../vendor/vod/laravel-typed-routes/js/inertiaClient";
//... Expects React Query and Inertia to be installed, and exposes `useQuery`, `useMutation`, `useForm`, and `usePage` methods;
import { makeFullClient } from "../../vendor/vod/laravel-typed-routes/js/fullClient";

//... Create the client - swap out the client that best suits your needs, or copy any of the clients to extend or modify as you like!
export const routes = makeFullClient<Routes>();

Depending on your project, you will need to adjust the paths for the imports.

Using the client

Route navigation

This library automatically converts routes to a type path. For example, the following laravel routes would be accessible as;

Route::get('/dashboard', [DashboardController::class, 'index'])->name('dashboard');
Route::get('/example/{id}/hello', [ExampleController::class, 'hello'])->name('example.hello');
Route::put('/example/{id}/update', [ExampleController::class, 'update'])->name('example.update');

// Routes are automatically converted to a type path. 
routes.dashboard.get()
routes.example.id(idGoesHere).hello.get()
routes.example.id(idGoesHere).update.put()

The API chosen will determine the methods available. For example, the full client exposes useQuery, useMutation, useForm, and usePage methods, so you can use these methods to interact with the routes like this;

Basic fetch

const response = await routes.example.id(idGoesHere).hello.get().call({
    message: 'Hello, world!',
});

Inertia

 //Inside a component
 //use Form to update data on the route;
 const {submit, data, setData} = routes.example.id(idGoesHere).update.post().useForm({
    message: 'hello world',
});

const goToDashboard = () => {
    /**The "visit" method calls the inertia router with the full path,
     * the appropriate method, and any data you want to pass. */
    routes.dashboard.get().visit({success: true});
}

@tanstack/react-query

//Inside a component
//use Query to fetch data from the route;
const { data, isLoading, error } = routes.example.id(idGoesHere).hello.get().useQuery({
    message: 'Hello, world!',
});

//use Mutation to update data on the route;
const { mutate, isLoading, error } = routes.example.id(idGoesHere).update.put().useMutation({
});

mutate({
    message: 'hello world'
})

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

vod / laravel-typed-routes

Maintainers

Details