Inertia Props Stats

A Laravel package that measures the size of InertiaJS props and provides statistics about them. This tool helps you monitor and optimize your Inertia payloads during development.

What it does

This package:

• Measures payload size: Calculates the size of your Inertia props in KB
• Warns about large payloads: Logs a warning, and sends one to Ray, when props exceed the configured threshold
• Detects duplicate keys: Identifies when the same key is used in both shared and page props
• Development-only: Only measures in non-production environments
• Ray integration: Sends the threshold warning to Ray when the app has it installed

The package reports:

• Total payload size (shared + page props)
• Component-specific props size
• Configured threshold
• Amount exceeded (if applicable)
• Duplicate keys between shared and page props
• A per-prop size breakdown, for the stats panel

How it measures

Inertia resolves props inside Response::toResponse(), so nothing is resolved while the page is being rendered. This package therefore measures in a middleware, after Inertia has built the page object, and reads the props Inertia already resolved.

That matters: measuring by resolving the props again runs every shared prop a second and third time per response. A shared prop that queries the database, calls an API, or builds a large object graph then costs three times what the page itself needs.

Installation

Install the package via Composer:

composer require webhubworks/inertia-props-stats

Publish the configuration file (optional):

php artisan vendor:publish --tag="inertia-props-stats-config"

This will create a config/inertia-props-stats.php file where you can customize:

return [
    'enabled' => env('INERTIA_PAYLOAD_SIZE_MEASUREMENT_ENABLED', true),

    'props' => env('INERTIA_PROPS_STATS_SHARE_PROPS', false),

    'payload_size' => [
        'threshold_in_kb' => (int) env('INERTIA_PAYLOAD_SIZE_THRESHOLD_IN_KB', 500),
    ],

    'throw_exception' => [
        'on_duplicate_keys' => env('INERTIA_PROPS_THROW_EXCEPTION_ON_DUPLICATE_KEYS', true),
    ],
];

Configuration options:

• enabled: Measure at all (never measures in production)
• props: Share the measurements with the frontend as _inertiaPayload* page props, which is what the stats panel reads. Off by default, because as props they ride along on every Inertia response and into the browser's history state. Turn it on while you work with the panel.
• payload_size.threshold_in_kb: Size in KB above which the warning fires
• throw_exception.on_duplicate_keys: Throw when a page prop and a shared prop use the same key

Recommended thresholds:

• Soft limit: 100-200KB
• Hard limit: 500KB

Vue.js Component

An example Vue.js component is included in resources/js/components/inertia-props-stats/ that you can copy and paste into your main app.

The panel reads the _inertiaPayload* props, so it needs props turned on:

INERTIA_PROPS_STATS_SHARE_PROPS=true

This component:

• Monitors the _inertiaPayloadTotalSizeInKb prop
• Displays an expandable stats panel when the payload exceeds the threshold
• Shows detailed payload statistics including size, threshold, and duplicate keys
• Provides a cleaner UI for development environments with more detailed error messages

To use it, copy the component to your Vue.js application and include it in your main layout:

<script setup>
import InertiaPropsStatsPanel from '@/components/InertiaPropsStatsPanel.vue'
</script>

<template>
  <div>
    <InertiaPropsStatsPanel />
    <!-- Your app content -->
  </div>
</template>

Note: The component requires lucide-vue-next for icons. Install it with:

npm install lucide-vue-next

License

The MIT License (MIT). Please see the license file for more information.