Configuration
As mentioned in the Quick Start section, you can publish the configuration file of Laravext by running the following command:
php artisan vendor:publish --tag=laravext-config
This will create a laravext.php file in your config directory, where you can customize the configuration of Laravext. Here are the ways you can customize it:
Root view (root_view)
The root view is the view that will be used to render the components. By default, it's set to env('LARAVEXT_ROOT_VIEW', 'sections.app'). You can change it to any view you want, as long as it's a valid view in your application.
Nexus directory (nexus_directory)
The nexus directory is the directory where your the Laravext router will use to automagically create the routes. By default, it's set to env("LARAVEXT_NEXUS_DIRECTORY", resource_path('js/nexus')). You can change it to any directory you want, as long as it's a valid directory in your application.
Router is case sensitive (router_is_case_sensitive)
By default, the router is case insensitive (env('LARAVEXT_ROUTER_IS_CASE_SENSITIVE', false)). This means that the router will automatically convert the route name to lowercase. If you want to make the router case sensitive, you can set this to true.
Route cache driver (route_cache_driver)
By default the route cache driver is set to env('LARAVEXT_ROUTER_CACHE_DRIVER', env('CACHE_DRIVER', 'file')). This is used to cache the directory structure, and also data about the URIs (conventions, root views, etc) so you don't have to repeat yourself. You can change it to any cache driver you want, as long as IT'S NOT array, as the conventions will be lost if you cache the routes using the php artisan optimize or the php artisan route:cache.
Route cacher is enabled (route_cacher_is_enabled)
By default this is set to env('LARAVEXT_ROUTER_CACHE_IS_ENABLED', !in_array(env('APP_ENV'), ['local', 'testing'])), so that the route cacher is enabled in production and disabled in local and testing environments. You can change this to true or false if you want to enable or disable the route cacher, although it's recommended to keep it enabled in production for performance reasons.
Router route naming is enabled (router_route_naming_is_enabled)
By default this is set to env('LARAVEXT_ROUTER_ROUTE_NAMING_IS_ENABLED', true). This is used to automatically name the routes generated by the Laravext router. You can change this to true or false if you want to enable or disable the route naming. The route name is based on the path/to/the/component/{that}/the/route/points/to format, where the route name will be path.to.the.component.that.the.route.points.to.
Router url intended is enabled (router_url_intended_is_enabled)
By default this is set to env('LARAVEXT_ROUTER_URL_INTENDED_IS_ENABLED', true). This is used to set wether or not the url.intended value from the session will be pulled from the session and included in the laravext prop. This can be used by the visit function in the client to redirect the user to the intended url after a successful login. You can change this to true or false if you want to enable or disable the url intended. Additionally, the visit function will also accept a options.redirectToUrlIntended to define wether or not the user should be redirected to the intended url after a successful login (by default, this is set to true).
Internally, this value is resolved by the withUrlIntended() method on the Response Factory. If you need more control over how the intended URL is resolved (e.g. a different session key, or peeking instead of pulling it from the session), you can override this method in your own Response Factory. See the Response Factory (response_factory) section below for more details.
Route Registration Method (route_registration_method)
By default, the route registration method is set to null. This is used to change how the routes are declared when calling Route::laravext(...) or Route::nexus(...). You can change it to any method you want, as long as it's a valid method in the router.
Both of these macros mentioned above accept a route_registration_method in the ...$parameters so you have more granular control. Check the Routing section for more details on how to use this.
Strand id length (strand_id_length)
By default this is set to 64. This is used to generate the a random id for each strand section that is rendered in the blade view, this is used internally for hydration purposes. You can change this to any number you want, as long as it's a valid number, just make sure it's long enough to avoid collisions.
File extensions (file_extensions)
By default this is set to ['jsx', 'tsx', 'js', 'ts', 'vue']. This is used to determine the file extensions that the Laravext router will look for when generating the routes and searching for file conventions. In case you want to add more file extensions, you can add them to this array. You can remove this config altogether, as the default ones are also internally set in case somebody removes it from the configuration file.
Version (version)
By default this is set to in_array(env('APP_ENV'), ['local']) ? 'fixed-local-version' : env('LARAVEXT_VERSION'). Assuming that you didn't define a version, Laravext tries to generate a version based on either the config('app.asset_url'), a mix-manifest.json file, or a build/manifest.json file. If you want to set a custom version, you can set it here.
This is used in the cache key for the routing tree. If the version changes, the user's browser is refreshed to get the new version of the application. You probably don't need to change this, but it's here in case you want to. If you're in a local environment, considering that the cache is disabled by default, this won't be used at all, and it's meant for non-local environments.
Force Page Visit (force_page_visit)
By default Laravext behaves an SPA, when possible, so for each link there is no page reload, unless the route is set to use a different view file than the one that was previously loaded, or if the version changed (see the version config above). If you want to force a page visit on each link click, you can set this to true.
Response Factory (response_factory)
By default this is set to \Laravext\ResponseFactory::class. This is the class responsible for building the Nexus page response — collecting props, shared props, route/query parameters, resolving the intended URL, and rendering the final response (including SSR handling).
Just like the route_localizer config, this class is resolved out of the container, so you can swap it out for your own implementation by extending \Laravext\ResponseFactory and pointing this config at your subclass:
'response_factory' => \App\Support\CustomResponseFactory::class,
This is useful if you want to customize how the response is built without having to reimplement (or manually copy) all of ResponseFactory's behavior. For example, a common use case is overriding the withUrlIntended() method to change how the intended URL is resolved:
namespace App\Support;
use Illuminate\Support\Facades\Session;
use Laravext\ResponseFactory;
class CustomResponseFactory extends ResponseFactory
{
public function withUrlIntended()
{
// Peek instead of pull, so the value isn't removed from the session
return config('laravext.router_url_intended_is_enabled')
? Session::get('url.intended')
: null;
}
}
Any public method on ResponseFactory can be overridden this way (e.g. page_data(), render(), share(), etc.), so you have full control over the response lifecycle if the default behavior doesn't fit your needs.
Whatever class you configure here is what both the Laravext facade and the nexus() helper resolve to, so you don't need to change anything else in your application — just extend ResponseFactory, override what you need, and point response_factory at your class.
Localization (localization)
This is an array containing some configurations in case you want to use the localization features of Laravext. This configuration has some comments to briefly explain everything. If you want to see some examples, check the Tools/Localization section of this documentation.
'localization' => [
/**
* Whether or not the localized routing feature is enabled.
*/
'enabled' => false,
/**
* The available locales for the application. By default, it will attempt to use the
* APP_LOCALES environment variable, falling back to English.
*/
'locales' => env('APP_LOCALES') ? explode(',', env('APP_LOCALES')) : config('app.locales', ['en']),
/**
* The base or default locale of the application. This is used to determine the primary
* routes and fallback behaviors.
*/
'default_locale' => env('APP_LOCALE', 'en'),
/**
* Whether or not a language prefix should be added to the URI for localized routes
* (e.g., generating /pt/usuarios instead of just /usuarios).
*/
'add_prefix_to_uri' => true,
/**
* The name of the translation file group located in your lang directory that will
* be used to translate the URI segments.
*/
'translation_file' => 'routes',
/**
* The single class responsible for all localized routing behavior.
* Extend \Laravext\Localization\RouteLocalizer to completely customize how localized route names
* are generated.
*/
'route_localizer' => \Laravext\Localization\RouteLocalizer::class,
],
SSR (ssr)
This is an array containing some configurations in case you want to use a javascript runtime to server side render your javascript. This configuration has some comments to briefly explain everything, but for more details, check the Server Side Rendering/Javascript Runtime section of this documentation.
Here's the default configuration:
/**
* This config is used to determine if the server should render the javascript or not.
*/
'ssr' => [
/**
* If set to true, the server will attempt to server side
* render your javascript, and if set to false, it won't.
*/
'enabled' => env('LARAVEXT_JAVASCRIPT_SERVER_SIDE_RENDERING_ENABLED', false),
/**
* You can also set it as 'only' or 'except' to specify the URIs that should(n't) be SSR'd,
* if for some reason you need this kind of control.
*/
// 'enabled' => 'only',
// 'enabled' => 'except',
/**
* The URIs that should/should not be SSR'd. This validation is dependent on the enabled config.
*
* If enabled is set to 'only', the URIs listed here will be the only ones that will be SSR'd.
* If enabled is set to 'except', the URIs listed here will be the ones that won't be SSR'd.
*
* If enabled is set to true, this config will be ignored.
*
* Internally this is checked using the request()->is(config('laravext.ssr.uris', []))
*/
'uris' => [
// 'example/{uri}/pattern/*',
// 'another-example/{uri}'
],
/**
* The route names that should/should not be SSR'd. This validation is dependent on the enabled config.
*
* If enabled is set to 'only', the route names listed here will be the only ones that will be SSR'd.
* If enabled is set to 'except', the route names listed here will be the ones that won't be SSR'd.
*
* If enabled is set to true, this config will be ignored.
*
* Internally this is checked using the request()->routeIs(config('laravext.ssr.route_names', []))
*/
'route_names' => [
// 'route.name',
// 'route.name_pattern.*'
],
/**
* The URL where the server side rendering will be done.
*/
'url' => env('LARAVEXT_JAVASCRIPT_SERVER_SIDE_RENDERING_URL', 'http://localhost:13714/render'),
// You may want to change this, if needed.
// 'bundle' => env('LARAVEXT_JAVASCRIPT_SERVER_SIDE_RENDERING_BUNDLE', 'app.js'),
],