Reference / @open-music-sdk/react

@open-music-sdk/react

The Apple Music API for a React app: everything in @open-music-sdk/browser, plus a provider that holds the client and the listener's token, hooks for the client, Apple's sign-in and the preview player, and query builders for TanStack Query.

Installation

pnpm add @open-music-sdk/react react

React 19 is a peer dependency. TanStack Query is not a dependency: the query builders give you what useQuery and useInfiniteQuery take, without importing it. The developer token comes from a route on your server: tokenEndpoint in @open-music-sdk/server. A Next.js app uses server on the server and this package in its client components.

Documentation

• The documentation site: guides for each client and server, concepts, and the reference
• Reference for this package
• Which package to install
• Sign a listener in, and the security model for where the provider keeps the token
• Set up your client and Read and write with TanStack Query
• Play song previews

Example

In your client components, rendered inside TanStack Query's QueryClientProvider, where showError stands for your own code:

import { MusicProvider, createBrowserClient, useConnect, useMusicQueries } from "@open-music-sdk/react";
import { useQuery } from "@tanstack/react-query";

// Create the client once, outside the component tree.
const music = createBrowserClient({ tokenUrl: "/api/music/token", storefront: "us" });
export const App = () => <MusicProvider music={music}><Connect /><Album id="1613600183" /></MusicProvider>;

function Connect() {
  const { isReady, error, connect } = useConnect({ app: { name: "Vinyl Collector Simulator" } }); // the token goes to the provider
  // Enabled once Apple's script is ready, or has failed to load: a click then loads it again.
  return <button disabled={!isReady && error === undefined} onClick={() => void connect().catch(showError)}>Connect Apple Music</button>;
}

function Album({ id }: { id: string }) {
  const { data: album } = useQuery(useMusicQueries().catalog.getAlbum(id)); // needs the developer token only
  return <h1>{album?.attributes?.name}</h1>;
}

What's in it

Export	What it does
<MusicProvider music>	Holds the client and the listener's token, in React state and nowhere else
useMusic()	The provider's client, bound to the listener while a token is held: one object for every component
useMusicUserToken()	[token, setToken]: the token the provider holds, and how to set or forget it
useConnect(options)	Apple's sign-in, as createConnect in browser runs it: isReady, error, connect() and disconnect()
usePreviewPlayer(options?)	A preview player for the component: its state, and load, play, pause, next, previous, seek and setVolume
musicQueries(music, scope?), useMusicQueries()	Every read function of the catalog and the library, as a query for useQuery or, for a list, useInfiniteQuery
Everything in browser	createBrowserClient, createConnect, and everything it re-exports: see its README

Only the built file that holds the provider and the hooks carries the "use client" directive. So musicQueries, isAppleMusicError or artworkImage imported from this package can also be used in a route handler, a server component or a prefetch. The Next sample imports them so, and next build passes in CI.

Namespaces

• schemas

Interfaces

• tInfiniteQuery
• tMusicProviderProps
• tMusicQueries
• tQuery
• tUseConnect
• tUsePreviewPlayer
• tUsePreviewPlayerOptions

Type Aliases

• tQueries
• tQueryOf

Functions

• MusicProvider
• musicQueries
• useConnect
• useMusic
• useMusicQueries
• useMusicUserToken
• usePreviewPlayer