Nova Telescope Menu Laravel Package

Getting Started

Prerequisites. Nova 4.x, laravel/telescope installed and migrated (php artisan telescope:install && php artisan migrate), and a working Telescope::auth() gate. The package is a thin Nova menu-link provider — it does not install or configure Telescope for you.

Install and wire it up.

composer require hmmm-hmmm-hmmm/nova-telescope-menu
php artisan vendor:publish --provider="HmmmHmmmHmmm\NovaTelescopeMenu\NovaTelescopeMenuServiceProvider"
php artisan nova:cache && php artisan config:clear

Look here first, in this order:

1. vendor/hmmm-hmmm-hmmm/nova-telescope-menu/src/ — read the provider. With 0 stars and a single 2023 release there is no meaningful documentation; the provider (usually <100 lines, calling Nova::mainMenu(...) or registering a MenuSection) is the spec.
2. The published config file (config/nova-telescope-menu.php or similar) — typically just enabled, label, path, and target.
3. app/Providers/NovaServiceProvider.php → mainMenu() — confirm your own menu section isn't already shadowing the package's entry.

First use case. You have a staging/production-adjacent environment where Telescope is enabled and locked down by a gate, and you're tired of pasting /telescope into the URL bar after every Nova login. Refresh the Nova sidebar, confirm the "Telescope" item appears, click it, and confirm the destination resolves to your telescope.path rather than a hard-coded /telescope.

Implementation Patterns

Gate it, don't just enable it. The package adds a link; Telescope's own authorization still governs the destination. Two separate layers must agree, or you get a visible menu item that 403s:

// app/Providers/TelescopeServiceProvider.php
protected function gate(): void
{
    Gate::define('viewTelescope', fn ($user) => $user->hasRole('admin'));
}

// config/nova-telescope-menu.php — only render the menu item for those users
'enabled' => fn () => auth()->user()?->hasRole('admin') ?? false,

If the config only accepts a boolean, wrap it in your own NovaServiceProvider::mainMenu() instead of touching vendor config — see the DIY pattern below.

Match the link to Telescope's real path. Telescope's route is driven by config('telescope.path') / TELESCOPE_PATH, not by APP_URL. In multi-tenant or subdirectory deployments the package default silently points at the wrong URL. Set the path explicitly, or derive it:

'path' => config('telescope.path', 'telescope'),

Open in a new tab. Telescope is a Livewire app living outside Nova's Inertia SPA. A plain in-app navigation dumps the user out of the Nova shell and "back" behaves badly. If the config exposes a target option, use _blank; if not, that's a five-line fork.

DIY fallback pattern (recommended). Given the package's maturity, the honest pattern most teams land on is a MenuSection in NovaServiceProvider:

use Laravel\Nova\Menu\MenuSection;
use Laravel\Nova\Menu\MenuItem;

public function mainMenu(NovaRequest $request): array
{
    return array_filter([
        MenuSection::dashboard(Main::class),

        $request->user()->can('viewTelescope')
            ? MenuSection::make('Telescope', [
                  MenuItem::externalLink('Open Telescope', url(config('telescope.path')))
                      ->openInNewTab(),
              ])->icon('chip')->collapsable()
            : null,
    ]);
}

This gives you ordering control, an icon that matches your design system, per-user visibility, and zero third-party surface area.

Prefer a Nova Tool over a menu link when you need in-app context. If you want Telescope embedded and themed inside Nova rather than as an external link, wrap it in php artisan nova:tool and @include the Telescope layout; the menu-link approach fundamentally can't do that.

Multiple Telescope panels. If you run separate Telescope instances per service, register one section with several MenuItem::externalLink() entries rather than installing the package twice.

Gotchas and Tips

• Maintenance risk is the headline. 0 stars, 0 dependents, one release (Nov 2023), no issue history to speak of. Assume no Nova 5 / Laravel 11+ compatibility guarantees. Vendor the provider into app/Nova/ rather than leaning on the package long-term — the code is small enough to own in an afternoon.
• Nova caches the menu. php artisan nova:cache after every change to menu registration, config, or the published config file. A stale menu is the #1 "it's installed but not showing up" cause. Pair with php artisan optimize:clear when debugging.
• Config cache + closures. If the config file uses closures for enabled, config:cache will fail or silently serialise badly. Keep env-derived booleans in config/*.php as plain values, or gate in mainMenu().
• Two gates, two failures. Nova's viewNova gate and Telescope's viewTelescope gate are independent. A menu item visible to a user who lacks viewTelescope produces a confusing 403 outside Nova with no path back — always align them.
• Trailing-slash and scheme mismatches. url(config('telescope.path')) inherits APP_URL. Behind a load balancer, set TrustProxies correctly or the link renders as http:// and breaks the session.
• No assets to publish, no migrations. If vendor:publish prints nothing, that's expected — check the provider for the actual tag (--tag=nova-telescope-menu-config is the common convention) rather than assuming the package is broken.
• Debugging checklist: php artisan route:list | grep telescope (does the route exist?), Nova::mainMenu() output via ray()/dd() in a fresh request, config('telescope.path'), and finally the browser network tab — a 404 means path mismatch, a 403 means the gate.
• Extension points are minimal by design. Ordering is controlled by array position in mainMenu(), not by the package. If you need separators, icons, or nested sections alongside the Telescope entry, wrap it: MenuSection::make('Dev Tools', [$packageItem, $horizonItem]).
• Never enable in production without a gate. Telescope records requests, queries, and jobs by default; an ungated menu item in a shipped app is a data-exposure incident waiting to happen. Set TELESCOPE_ENABLED=false in prod and flip per-user via the gate rather than per-environment.