Docs for Inertia::once()

Author: pascalbaljet

docs.json

@@ -121,6 +121,7 @@
                             "v2/data-props/partial-reloads",
                             "v2/data-props/deferred-props",
                             "v2/data-props/merging-props",
+                            "v2/data-props/once-props",
                             "v2/data-props/polling",
                             "v2/data-props/prefetching",
                             "v2/data-props/load-when-visible",

v2/data-props/deferred-props.mdx

@@ -109,6 +109,8 @@ export default () => (
 
 </CodeGroup>
 
+## Multiple Deferred Props
+
 If you need to wait for multiple deferred props to become available, you can specify an array to the `data` prop.
 
 <CodeGroup>
@@ -173,3 +175,15 @@ export default () => (
 ```
 
 </CodeGroup>
+
+## Combining with Once Props
+
+You may chain the `once()` modifier onto a deferred prop to ensure the data is resolved only once and remembered by the client across subsequent navigations.
+
+```php
+return Inertia::render('Dashboard', [
+    'stats' => Inertia::defer(fn () => Stats::generate())->once(),
+]);
+```
+
+For more information on once props, see the [once props](/v2/data-props/once-props) documentation.

v2/data-props/merging-props.mdx

@@ -109,7 +109,7 @@ You can also merge props directly on the client side without making a server req
 
 ## Combining with Deferred Props
 
-You can also combine [deferred props](/v2/data-props/deferred-props) with mergeable props to defer the loading of the prop and ultimately mark it as mergeable once it's loaded.
+You may combine [deferred props](/v2/data-props/deferred-props) with mergeable props to defer the loading of the prop and ultimately mark it as mergeable once it's loaded.
 
 ```php
 Route::get('/users', function () {
@@ -122,6 +122,18 @@ Route::get('/users', function () {
 });
 ```
 
+## Combining with Once Props
+
+You may chain the `once()` modifier onto a merge prop to ensure the data is resolved only once and remembered by the client across subsequent navigations.
+
+```php
+return Inertia::render('Users/Index', [
+    'activity' => Inertia::merge(fn () => $user->recentActivity())->once(),
+]);
+```
+
+For more information on once props, see the [once props](/v2/data-props/once-props) documentation.
+
 ## Resetting Props
 
 On the client side, you can indicate to the server that you would like to reset the prop. This is useful when you want to clear the prop value before merging new data, such as when the user enters a new search query on a paginated list.

v2/data-props/once-props.mdx

@@ -0,0 +1,111 @@
+---
+title: Once Props
+---
+
+Some data rarely changes or is expensive to compute. Rather than resolving this data on every request, you may use _once props_. These props are remembered by the client and reused on subsequent pages that include the same prop. This makes them ideal for [shared data](/v2/data-props/shared-data).
+
+## Creating Once Props
+
+To create a once prop, use the `Inertia::once()` method when returning your response. This method receives a callback that returns the prop data.
+
+```php
+return Inertia::render('Settings', [
+    'countries' => Inertia::once(fn () => Country::all()),
+]);
+```
+
+Once the client has received this prop, subsequent requests will skip resolving the callback entirely and the prop will be excluded from the response. The client will automatically reuse the remembered value.
+
+Keep in mind that navigating to a page that doesn't include the once prop will break the chain. The backend will resolve the prop again when you navigate to a page that includes it.
+
+## Sharing Once Props
+
+You may share once props globally using the `Inertia::share()` method.
+
+```php
+Inertia::share('countries', Inertia::once(fn () => Country::all()));
+```
+
+Or use the `shareOnce()` helper method.
+
+```php
+Inertia::shareOnce('countries', fn () => Country::all());
+```
+
+You may also define a dedicated `shareOnce()` method in your middleware.
+
+```php
+class HandleInertiaRequests extends Middleware
+{
+    public function shareOnce(Request $request): array
+    {
+        return [
+            'countries' => fn () => Country::all(),
+        ];
+    }
+}
+```
+
+## Forcing a Refresh
+
+You may force a once prop to be refreshed using the `fresh()` method.
+
+```php
+return Inertia::render('Settings', [
+    'countries' => Inertia::once(fn () => Country::all())->fresh(),
+]);
+```
+
+This method accepts a boolean, allowing you to conditionally refresh the prop.
+
+```php
+return Inertia::render('Settings', [
+    'preferences' => Inertia::once(fn () => $user->preferences)->fresh($user->wasChanged()),
+]);
+```
+
+## Setting an Expiration
+
+You may set an expiration time using the `until()` method. This method accepts a `DateTimeInterface`, `DateInterval` instance, or an integer number of seconds. The prop will be refreshed on a subsequent visit after the expiration time has passed.
+
+```php
+return Inertia::render('Dashboard', [
+    'rates' => Inertia::once(fn () => ExchangeRate::all())->until(now()->addHour()),
+]);
+```
+
+## Custom Keys
+
+You may assign a custom key using the `as()` method. This is useful when you want to share data across multiple pages while using different prop names.
+
+```php
+// Checkout page
+return Inertia::render('Checkout', [
+    'shippingCountries' => Inertia::once(fn () => Country::all())->as('countries'),
+]);
+
+// Settings page
+return Inertia::render('Settings', [
+    'availableCountries' => Inertia::once(fn () => Country::all())->as('countries'),
+]);
+```
+
+Both pages share the same underlying data because they use the same custom key. The prop will only be resolved once, even though the prop names differ.
+
+## Prefetching
+
+Once props work with [prefetching](/v2/data-props/prefetching). The client automatically includes any remembered once props in prefetched responses, so navigating to a prefetched page will already have the once props available.
+
+The prefetch cache also respects once prop expiration. Prefetched pages containing an expired once prop will be invalidated.
+
+## Combining with Other Prop Types
+
+The `once()` modifier may be chained onto [deferred](/v2/data-props/deferred-props), [merge](/v2/data-props/merging-props), and [optional](/v2/data-props/partial-reloads#lazy-data-evaluation) props.
+
+```php
+return Inertia::render('Dashboard', [
+    'countries' => Inertia::defer(fn () => Country::all())->once(),
+    'activity' => Inertia::merge(fn () => $user->recentActivity())->once(),
+    'categories' => Inertia::optional(fn () => Category::all())->once(),
+]);
+```

v2/data-props/partial-reloads.mdx

@@ -163,3 +163,15 @@ Here's a summary of each approach:
 | <span style={{whiteSpace: 'nowrap'}}>`fn () => User::all()`</span> | Always | Optionally | Only when needed |                                                                                                                                                                               |
 | <span style={{whiteSpace: 'nowrap'}}>`Inertia::optional(fn () => User::all())`</span> | Never | Optionally | Only when needed |                                                                                                                                                                               |
 | <span style={{whiteSpace: 'nowrap'}}>`Inertia::always(fn () => User::all())`</span> | Always | Always | Always |                                                                                                                                                                               |
+
+## Combining with Once Props
+
+You may chain the `once()` modifier onto an optional prop to ensure the data is resolved only once and remembered by the client across subsequent navigations.
+
+```php
+return Inertia::render('Users/Index', [
+    'users' => Inertia::optional(fn () => User::all())->once(),
+]);
+```
+
+For more information on once props, see the [once props](/v2/data-props/once-props) documentation.

v2/data-props/shared-data.mdx

@@ -47,6 +47,42 @@ Shared data should be used sparingly as all shared data is included with every r
 
 Page props and shared data are merged together, so be sure to namespace your shared data appropriately to avoid collisions.
 
+## Sharing Once Props
+
+You may share data that is resolved only once and remembered by the client across subsequent navigations using [once props](/v2/data-props/once-props).
+
+```php
+class HandleInertiaRequests extends Middleware
+{
+    public function share(Request $request)
+    {
+        return array_merge(parent::share($request), [
+            'countries' => Inertia::once(fn () => Country::all()),
+        ]);
+    }
+}
+```
+
+Alternatively, you may define a dedicated `shareOnce()` method in the middleware.
+
+```php
+class HandleInertiaRequests extends Middleware
+{
+    public function shareOnce(Request $request): array
+    {
+        return [
+            'countries' => fn () => Country::all(),
+        ];
+    }
+}
+```
+
+You may also share once props manually using the `Inertia::shareOnce()` helper.
+
+```php
+Inertia::shareOnce('countries', fn () => Country::all());
+```
+
 ## Accessing Shared Data
 
 Once you have shared the data server-side, you will be able to access it within any of your pages or components. Here's an example of how to access shared data in a layout component.