Debugging

Because widgets are web pages, you can debug them with Safari’s Web Inspector — full access to the DOM, styles, console and network, live, while the widget runs on your desktop.

Open the inspector

In Safari, enable the Develop menu: Settings → Advanced → Show features for web developers.
With your widget running, open Safari’s Develop menu.
Choose NepTunes Widget, then your widget, then Open Web Inspector.

From there you can edit CSS and see it update instantly, set breakpoints in your script, and watch the console.

Watch state changes

Log the state object to understand exactly what you receive:

NepTunes.on('statechange', (state) => {
  console.log('state', state);
});

Common gotchas

Handle the no-track state. NepTunes.track (and state.track) is null when nothing is playing. Guard every access to track.title, track.artist, etc.
Test light and dark artwork. Album art varies wildly — make sure your text stays legible over both. A subtle scrim or text shadow helps.
Respect capabilities. Hide controls the current player can’t support (see Permissions).

Shadows and transparency

Widgets render on a transparent background. To cast a drop shadow, leave room for it with body padding and keep backgrounds transparent:

html, body {
  height: 100%;
  width: 100%;
  overflow: visible;
  background: transparent;
}
body {
  padding: 20px;            /* room for the shadow */
}
.widget {
  height: 100%;
  width: 100%;
  border-radius: 12px;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
}

← Permissions Publishing guidelines →