Nova Telescope Link Laravel Package

Getting Started

mad-web/nova-telescope-link is a small Nova extension that puts a Telescope entry point inside the Nova UI, so you can jump from admin screens into Telescope without keeping a second tab pinned to /telescope. The "smart" part is that the link can carry context (user, tag, filter) rather than being a dumb <a href="/telescope">.

Minimum steps:

composer require mad-web/nova-telescope-link
php artisan telescope:install   # only if Telescope isn't already set up
php artisan migrate

Then register the package's tool in app/Providers/NovaServiceProvider.php:

public function tools()
{
    return [
        // ...
        new \MadWeb\NovaTelescopeLink\TelescopeLink(),
    ];
}

Two things to verify before you copy-paste: the exact class name/namespace and whether the tool takes constructor args (path, label, gate callback). It's a single-purpose package — read src/ first, it's a few minutes of reading and saves you guessing. If there's a publishable config, publish it and commit it:

php artisan vendor:publish --provider="MadWeb\NovaTelescopeLink\NovaTelescopeLinkServiceProvider"

Where to look first, in order: (1) the tool class itself to see what it renders and what URL it builds, (2) whether it respects config('telescope.path'), (3) whether it defines a canSee/authorize method. Those three answers determine whether it's safe to ship.

First real use case: you're in a Nova resource detail page for a customer complaining about a failed checkout. Instead of manually building a Telescope URL, clicking the sidebar link should land you in Telescope already scoped to that user's requests. That's the day-one win — small, but it's the difference between 5 seconds and 45 seconds, twenty times a day.

Implementation Patterns

Gate it before you trust it. Nova tools support visibility callbacks. The most common mistake with any Telescope-integrated package is exposing the link to users who will then hit Telescope's own viewTelescope gate and get a 403 (or worse, who can see it). Wrap it:

public function tools()
{
    return [
        (new \MadWeb\NovaTelescopeLink\TelescopeLink())
            ->canSee(fn ($request) => $request->user()->isAdmin()
                && ! app()->isProduction()),
    ];
}

Alternatively, configure it in the package config if one exists — either way, make the decision explicit in your provider, not implicit in the package default.

Environment-scoped registration. Telescope itself is normally off in production (TELESCOPE_ENABLED=false). Don't register a link that 404s:

public function tools()
{
    return array_filter([
        config('telescope.enabled')
            ? new \MadWeb\NovaTelescopeLink\TelescopeLink()
            : null,
    ]);
}

Tag your requests so the link has something to filter on. The link is only as smart as the data Telescope has. Add tags in a service provider so you can pivot from Nova context into Telescope filters:

// AppServiceProvider::boot()
Telescope::tag(function () {
    return array_filter([
        auth()->check() ? 'user:'.auth()->id() : null,
        request()->route()?->getName(),
        tenant('id') ?? null,
    ]);
});

Then a link that carries ?tag=user:42 becomes genuinely useful for "what happened to this person's session".

Pair it with resource actions. The highest-leverage pattern is not the sidebar link — it's an action or button on a resource detail page that deep-links into Telescope pre-filtered. If the package exposes a URL builder, reuse it; otherwise replicate the URL construction in one place:

// app/Nova/Actions/OpenTelescope.php
public function handle(ActionFields $fields, Collection $models)
{
    $user = $models->first();

    return Action::openInNewTab(
        route('telescope').'?filter[user_id]='.$user->id
    );
}

Use it as the "second window" for a debugging workflow. Typical loop: admin sees a report → open the resource → click the Telescope link → filter by request ID or user → inspect queries/jobs/mail. If your team does this more than occasionally, consider also adding a card to the Nova dashboard that surfaces recent exceptions with a link into Telescope — the package gives you the routing glue, the workflow is yours.

Keep the config in version control. If the package publishes config/nova-telescope-link.php, commit it. Packages of this size rarely ship sane, documented defaults, and you want the path/label/visibility choices to be reviewable in a diff rather than rediscovered per environment.

Gotchas and Tips

• This package is effectively unmaintained. Zero stars, zero dependents. That's not a reason to avoid it — it's a reason to read all of it. It's a thin wrapper; if the Nova or Telescope major version you're on breaks it, you'll be fixing it yourself. Fork it into your org's namespace or, honestly, reimplement the ~30 lines as a local Nova tool. A local tool has no upgrade risk and you own the URL construction.

• Telescope's gate is separate from Nova's auth. Nova handles who sees the link; Telescope::auth() handles who sees Telescope. If you only configure one, you get either a dead link or an unauthorized visitor hitting your Telescope routes. Check both, explicitly, in a test.

• Custom Telescope paths break hardcoded URLs. If someone set TELESCOPE_PATH or the package assumes /telescope, links silently 404. Verify the tool uses config('telescope.path') or route('telescope'), and add an assertion to your smoke test.

• Filter query-string format is Telescope-internal. ?filter[user_id]=, ?tag=, ?type=request — these are not a public API and have shifted across Telescope majors. If you build links by hand, centralize the construction in one helper so a Telescope upgrade is a one-file change.

• Multiple Telescope instances / multi-tenancy. If you run per-tenant Telescope storage or separate instances per environment, the "smart" link must resolve the correct instance. Audit this before rollout; a link that opens the wrong tenant's Telescope is worse than no link.

• Menu changes need a cache clear. Nova caches its menu in some setups, and OPcache will happily serve the old provider. After registering the tool: php artisan optimize:clear and, if you use nova:publish-style caching in CI, re-run it.

• Signed URLs expire. If the link is a signed route (plausible for a "smart" link), long-lived browser tabs will 403 on click. Either re-sign on page load or don't sign at all and rely on the Telescope gate.

• Test it as a non-admin. Log in as a regular Nova user and confirm the link is absent. This is the single highest-value five-minute check for any Nova tool that points at debugging infrastructure.

• Extension point to exploit: if the tool's URL builder is public, use it everywhere — actions, cards, custom tools, notification links. That keeps path config and any signing logic in exactly one place, which is the whole reason to install the package instead of hand-rolling an <a href> in a menu.