MusicKit TypeScript Types

Common errors

• TS2304: Cannot find name 'MusicKit'.

  cause TypeScript compiler cannot locate the global MusicKit type definitions.
  fix Verify that your `tsconfig.json` file includes `"node_modules/musickit-typescript"` in the `typeRoots` array. For example: `"typeRoots": ["node_modules/musickit-typescript", "node_modules/@types"]`.

• ReferenceError: MusicKit is not defined

  cause The MusicKit JavaScript library has not been loaded in the runtime environment (e.g., browser or Node.js). This package only provides types, not the runtime code.
  fix Ensure that the official Apple MusicKit JS library is loaded via a script tag in your HTML document (or equivalent method for your environment) before your application code attempts to access `MusicKit`.

• TS2339: Property 'someNewMethod' does not exist on type 'MusicKit.Something'.

  cause The type definitions are out of sync with a newer version of the MusicKit JS library, or a custom extension to MusicKit JS is being used without corresponding type augmentation.
  fix Check for an updated version of `musickit-typescript`. If an update is not available or the method is custom, you may need to create a local declaration file (`.d.ts`) to augment the existing types, for example: `declare namespace MusicKit { interface Something { someNewMethod(): void; } }`.

Warnings

• gotcha Incorrect or missing 'typeRoots' configuration in `tsconfig.json` can prevent TypeScript from finding the global `MusicKit` types, leading to 'Cannot find name' errors.
  Fix: Ensure that `typeRoots` in your `tsconfig.json` includes `"node_modules/musickit-typescript"` alongside `"node_modules/@types"` (if present) to correctly inform the TypeScript compiler about where to find these ambient declarations.
• gotcha Version mismatches between `musickit-typescript` and the actual MusicKit JS library (loaded at runtime) can lead to type inconsistencies. New features in MusicKit JS might lack types, or deprecated features might still be typed.
  Fix: Regularly check the `musickit-typescript` GitHub repository or `npm` for updates. If issues arise, cross-reference the types with the official MusicKit JS documentation to identify discrepancies.
• gotcha This package only provides type definitions, not the MusicKit JS library itself. Failure to load the actual MusicKit JS library in your HTML (or equivalent) will result in runtime errors despite successful compilation.
  Fix: Ensure that the official MusicKit JS library is properly loaded into your application's environment before attempting to use the `MusicKit` global object at runtime. This typically involves including a `<script>` tag for the MusicKit JS SDK in your HTML.

Install

• npm install musickit-typescript npm
• yarn add musickit-typescript yarn
• pnpm add musickit-typescript pnpm

Imports

• MusicKit (global object)
  wrong:

  import { MusicKit } from 'musickit-typescript';

  correct:

  const musicInstance = MusicKit.getInstance();

  The 'musickit-typescript' package provides ambient global types. Once configured in `tsconfig.json`, the `MusicKit` global object and its associated types become available without explicit import statements. Attempting to import `MusicKit` directly from the package will result in a module not found error or an empty object.
• MusicKit.API (type)
  wrong:

  import { API } from 'musickit-typescript';

  correct:

  let api: MusicKit.API;

  Specific types provided by this package, such as `MusicKit.API` or `MusicKit.Player`, are accessed via the globally available `MusicKit` namespace. They are not top-level exports from the `musickit-typescript` module itself.
• MusicKit.Player (type)
  wrong:

  import { Player } from 'musickit-typescript';

  correct:

  function initializePlayer(player: MusicKit.Player) { /* ... */ }

  Similar to `MusicKit.API`, types like `MusicKit.Player` are part of the global `MusicKit` namespace. They are meant for type annotations and compile-time checking, not for runtime import.

Quickstart

This quickstart demonstrates how to install the types and configure `tsconfig.json`. It then shows how to access the global `MusicKit` object and use its types for initialization and basic player interaction, assuming the MusicKit JS library is loaded in the browser.

npm install --save-dev musickit-typescript

// Then, update your tsconfig.json:
// Make sure 'node_modules/musickit-typescript' is included in 'typeRoots'
// alongside 'node_modules/@types' to ensure TypeScript finds the definitions.
{
  "compilerOptions": {
    "typeRoots": [
      "node_modules/musickit-typescript",
      "node_modules/@types"
    ],
    "target": "es2018",
    "module": "esnext",
    "lib": ["dom", "esnext"]
  },
  "include": ["src/**/*.ts"]
}

// Example usage in your TypeScript file (assuming MusicKit JS is loaded in HTML):
// Make sure to define your developer token or get it from your backend
declare const MusicKit: MusicKit.MusicKitInstance;
const developerToken = process.env.APPLE_MUSIC_DEV_TOKEN ?? 'YOUR_DEVELOPER_TOKEN_HERE';

async function initMusicKit() {
  try {
    await MusicKit.configure({
      developerToken: developerToken,
      app: {
        name: 'My Awesome App',
        build: '1.0.0'
      }
    });
    const music = MusicKit.getInstance();
    console.log('MusicKit initialized successfully:', music);
    if (music.isAuthorized) {
      console.log('User is authorized.');
    } else {
      console.log('User is not authorized. Requesting authorization...');
      await music.authorize();
      console.log('User authorized!');
    }
    const player: MusicKit.Player = music.player;
    console.log('Current playback state:', player.playbackState);
  } catch (error) {
    console.error('Failed to initialize MusicKit:', error);
  }
}

initMusicKit();