Dashboard

Supply dashboard content: top tracks, trending artists, curated playlists, and more.

Dashboard Providers

Dashboard providers supply Nuclear's home screen with content like charts, trending artists, new releases, and curated playlists. When you open the player, Nuclear calls each registered dashboard provider and assembles the results into an overview. Without a dashboard provider, the dashboard shows an empty state prompting the user to enable a plugin.

Plugins can either add a new dashboard provider, or consume dashboard data from existing providers.

---

Implementing a provider

Minimal example

You register dashboard providers with api.Providers.register() just like any other provider. It needs an id, kind: 'dashboard', a name, a metadataProviderId, and a list of capabilities declaring which content it can supply:

import type { DashboardProvider, NuclearPlugin, NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';

const provider: DashboardProvider = {
  id: 'acme-dashboard',
  kind: 'dashboard',
  name: 'Acme Music',

  metadataProviderId: 'acme-metadata',
  capabilities: ['topTracks', 'newReleases'],

  async fetchTopTracks() {
    // Call your API, return Track[]
  },
  async fetchNewReleases() {
    // Call your API, return AlbumRef[]
  },
};

const plugin: NuclearPlugin = {
  onEnable(api: NuclearPluginAPI) {
    api.Providers.register(provider);
  },
  onDisable(api: NuclearPluginAPI) {
    api.Providers.unregister('acme-dashboard');
  },
};

export default plugin;

Always unregister your provider in onDisable. If you don't, it stays registered and Nuclear will keep calling it after the plugin is disabled.

Capabilities

Capabilities tell Nuclear which content your provider can fetch. Nuclear only calls methods for capabilities you declare. If you don't list 'topArtists', fetchTopArtists is never called even if you define it.

Capability	Method called	Returns	Widget
'topTracks'	fetchTopTracks()	Track[]	Track table with playback controls
'topArtists'	fetchTopArtists()	ArtistRef[]	Artist card row
'topAlbums'	fetchTopAlbums()	AlbumRef[]	Album card row
'editorialPlaylists'	fetchEditorialPlaylists()	PlaylistRef[]	Playlist card row
'newReleases'	fetchNewReleases()	AlbumRef[]	Album card row

Nuclear only calls methods for declared capabilities. Declare only the ones you actually implement.

Note that fetchTopTracks returns full Track[] objects, not TrackRef[]. The dashboard track table needs complete track data (title, artist, duration, thumbnail) to render without additional lookups.

---

The metadataProviderId field

Every dashboard provider must specify a metadataProviderId. This tells Nuclear which metadata provider can look up the entities your dashboard returns.

When a user clicks an artist or album on the dashboard, Nuclear navigates to a detail page. It needs to know which metadata provider can fetch that entity's full details, that's what metadataProviderId is for. If you set it to a provider that doesn't exist or can't resolve your IDs, artist and album links from the dashboard will fail.

Typically, your plugin registers both a metadata provider and a dashboard provider, and they share the same underlying API. Point metadataProviderId at your metadata provider's id.

---

Attributed results

When multiple dashboard providers are registered, Nuclear will render results from all of them. The API wraps each provider's data in an AttributedResult<T>:

type AttributedResult<T> = {
  providerId: string;
  metadataProviderId: string;
  providerName: string;
  items: T[];
};

Each attributed result carries the provider's name and IDs, so Nuclear can render labeled sections (e.g. "Top Tracks - Acme Music") and route navigation to the correct metadata provider.

---

Using dashboard data

Plugins can consume dashboard data from all registered providers via api.Dashboard.*:

export default {
  async onEnable(api: NuclearPluginAPI) {
    const topTracks = await api.Dashboard.fetchTopTracks();

    for (const result of topTracks) {
      console.log(`${result.providerName}: ${result.items.length} tracks`);
    }
  },
};

Consumer reference

api.Dashboard.fetchTopTracks(providerId?: string): Promise<AttributedResult<Track>[]>
api.Dashboard.fetchTopArtists(providerId?: string): Promise<AttributedResult<ArtistRef>[]>
api.Dashboard.fetchTopAlbums(providerId?: string): Promise<AttributedResult<AlbumRef>[]>
api.Dashboard.fetchEditorialPlaylists(providerId?: string): Promise<AttributedResult<PlaylistRef>[]>
api.Dashboard.fetchNewReleases(providerId?: string): Promise<AttributedResult<AlbumRef>[]>

All methods accept an optional providerId. If omitted, Nuclear queries all registered dashboard providers and returns an array with one AttributedResult per provider. If provided, only that provider is queried.

---