Documentation Index
Fetch the complete documentation index at: https://docs.laravelshopper.dev/llms.txt
Use this file to discover all available pages before exploring further.
The dashboard is the first screen after login. It shows store health at a glance: revenue trends, key metrics, recent orders, top products, and an onboarding guide that auto-dismisses once the store is configured.
Components
The dashboard is composed of five Livewire components, each with independent caching and a focused responsibility.
RevenueChart
Displays monthly revenue as a bar chart for the last 12 months. Data is grouped by month in a single aggregated query and cached with flexible TTL (fresh for 5 minutes, stale up to 30 minutes).
The chart supports a currency filter. When you have multiple active currencies, a dropdown lets you switch between them. The Y-axis and tooltip are formatted using Intl.NumberFormat with the store’s locale and currency symbol.
The revenue query supports MySQL, PostgreSQL, and SQLite with database-specific date expressions.
StatCards
Shows four summary cards comparing the current month to the previous month:
| Card | Metric | Scope |
|---|
| Revenue | Sum of price_amount on paid orders | Current currency |
| Products | Total product count, monthly new products for trend | All types |
| Orders | Count of paid orders, monthly count for trend | All currencies |
| Customers | Count of users with the customer scope, monthly new customers for trend | All |
RecentOrders
A table of the 7 most recent orders, excluding orders with Cancelled or Archived status. Each row shows the order number, first product with thumbnail, total amount, payment status badge, and links to the order detail page.
TopSellingProducts
Ranks the top 6 products by total quantity sold across paid orders. Variant sales are aggregated back to the parent product. Each row shows the product thumbnail, name, total units sold, and average review score.
SetupGuide
An interactive checklist that guides new stores through the essential configuration steps. It appears on first login and auto-detects completion by querying the database:
| Step | Completed when | Permission |
|---|
| Add a product | At least one product exists | add_products |
| Create a collection | At least one collection exists | add_collections |
| Set up shipping zones | At least one enabled shipping zone exists | access_setting |
| Set up payment methods | At least one enabled payment method exists | access_setting |
| Configure taxes | At least one tax zone exists | access_setting |
setup_guide_done setting and dispatches a setup-guide-completed event to hide itself. It does not reappear on subsequent visits. The guide can also be dismissed early with the dismiss button.
Caching
Each dashboard component caches its data independently. The cache keys and TTLs are:
| Component | Cache key | Fresh TTL | Stale TTL |
|---|
| RevenueChart | dashboard:revenue:{currency} | 5 min | 30 min |
| StatCards | dashboard:stat-cards:{locale} | 5 min | 30 min |
| RecentOrders | dashboard:recent-orders | 1 min | 5 min |
| TopSellingProducts | dashboard:top-selling-products | 5 min | 30 min |
use Illuminate\Support\Facades\Cache;
Cache::forget('dashboard:revenue:USD');
Cache::forget('dashboard:stat-cards:en');
Cache::forget('dashboard:recent-orders');
Cache::forget('dashboard:top-selling-products');
Access Requirements
The dashboard middleware checks two conditions before rendering the page. The user must be an admin or have the access_dashboard permission. The store must have the email and street_address settings configured (these are set during the initial store setup).
If the settings are missing, the middleware redirects to the store initialization page. If the user lacks permission, a 403 response is returned.
Customizing the Dashboard
Replacing the Entire Page
The dashboard page is registered in the components configuration. Publish the dashboard component config to swap it with your own implementation:
php artisan shopper:component:publish dashboard
config/shopper/components/dashboard.php:
use Shopper\Livewire\Components;
use Shopper\Livewire\Pages;
return [
'pages' => [
'dashboard' => Pages\Dashboard::class,
],
'components' => [
'locale-switcher' => Components\LocaleSwitcher::class,
],
];
'pages' => [
'dashboard' => App\Livewire\Pages\Dashboard::class,
],
namespace App\Livewire\Pages;
use Illuminate\Contracts\View\View;
use Livewire\Component;
final class Dashboard extends Component
{
public function render(): View
{
return view('dashboard.index')
->layout('shopper::components.layouts.app', [
'title' => 'Dashboard',
]);
}
}
Overriding Individual Components
If you want to replace a single widget (for example, swap the revenue chart for a custom report), publish the dashboard Blade view and edit it directly.
First, publish Shopper’s views:
php artisan vendor:publish --tag=shopper-views
resources/views/vendor/shopper/livewire/pages/dashboard.blade.php. The view renders each component via Livewire tags that you can replace:
<livewire:shopper-dashboard.stat-cards />
<livewire:shopper-dashboard.revenue-chart />
<livewire:shopper-dashboard.top-selling-products />
<livewire:shopper-dashboard.recent-orders />
Adding Content via Render Hooks
If you only want to inject content above or below the dashboard without replacing the page or publishing views, use the layout render hooks:
use Shopper\Facades\Shopper;
use Shopper\View\LayoutRenderHook;
Shopper::renderHook(
LayoutRenderHook::DASHBOARD_START,
fn (): string => view('dashboard.store-alert-banner')->render(),
);
Shopper::renderHook(
LayoutRenderHook::DASHBOARD_END,
fn (): string => view('dashboard.custom-reports')->render(),
);
boot method. See the Render Hooks documentation for the full list of available injection points.
