{"id":15142,"library":"musickit-typescript","title":"MusicKit TypeScript Types","description":"This package provides TypeScript type definitions for Apple's MusicKit JS library. It enables developers to use TypeScript with the MusicKit JS API, offering compile-time type checking and improved IDE autocompletion, which is crucial as the official MusicKit JS library might lack comprehensive native types. The current stable version is 1.2.4. As a type definition package, its release cadence is typically tied to updates or community needs concerning the MusicKit JS library itself rather than following a fixed schedule. It serves as a community-driven effort to enhance the developer experience for those integrating Apple Music into web applications using TypeScript.","status":"active","version":"1.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/wsmd/musickit-typescript","tags":["javascript","Apple","apple-music","MusicKit.d.ts","MusicKit","types","typescript","typings"],"install":[{"cmd":"npm install musickit-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add musickit-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add musickit-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides type definitions for the MusicKit JS library, which must be loaded at runtime for the types to be meaningful.","package":"musickit","optional":false}],"imports":[{"note":"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.","wrong":"import { MusicKit } from 'musickit-typescript';","symbol":"MusicKit (global object)","correct":"const musicInstance = MusicKit.getInstance();"},{"note":"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.","wrong":"import { API } from 'musickit-typescript';","symbol":"MusicKit.API (type)","correct":"let api: MusicKit.API;"},{"note":"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.","wrong":"import { Player } from 'musickit-typescript';","symbol":"MusicKit.Player (type)","correct":"function initializePlayer(player: MusicKit.Player) { /* ... */ }"}],"quickstart":{"code":"npm install --save-dev musickit-typescript\n\n// Then, update your tsconfig.json:\n// Make sure 'node_modules/musickit-typescript' is included in 'typeRoots'\n// alongside 'node_modules/@types' to ensure TypeScript finds the definitions.\n{\n  \"compilerOptions\": {\n    \"typeRoots\": [\n      \"node_modules/musickit-typescript\",\n      \"node_modules/@types\"\n    ],\n    \"target\": \"es2018\",\n    \"module\": \"esnext\",\n    \"lib\": [\"dom\", \"esnext\"]\n  },\n  \"include\": [\"src/**/*.ts\"]\n}\n\n// Example usage in your TypeScript file (assuming MusicKit JS is loaded in HTML):\n// Make sure to define your developer token or get it from your backend\ndeclare const MusicKit: MusicKit.MusicKitInstance;\nconst developerToken = process.env.APPLE_MUSIC_DEV_TOKEN ?? 'YOUR_DEVELOPER_TOKEN_HERE';\n\nasync function initMusicKit() {\n  try {\n    await MusicKit.configure({\n      developerToken: developerToken,\n      app: {\n        name: 'My Awesome App',\n        build: '1.0.0'\n      }\n    });\n    const music = MusicKit.getInstance();\n    console.log('MusicKit initialized successfully:', music);\n    if (music.isAuthorized) {\n      console.log('User is authorized.');\n    } else {\n      console.log('User is not authorized. Requesting authorization...');\n      await music.authorize();\n      console.log('User authorized!');\n    }\n    const player: MusicKit.Player = music.player;\n    console.log('Current playback state:', player.playbackState);\n  } catch (error) {\n    console.error('Failed to initialize MusicKit:', error);\n  }\n}\n\ninitMusicKit();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Incorrect or missing 'typeRoots' configuration in `tsconfig.json` can prevent TypeScript from finding the global `MusicKit` types, leading to 'Cannot find name' errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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\"]`.","cause":"TypeScript compiler cannot locate the global MusicKit type definitions.","error":"TS2304: Cannot find name 'MusicKit'."},{"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`.","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.","error":"ReferenceError: MusicKit is not defined"},{"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; } }`.","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.","error":"TS2339: Property 'someNewMethod' does not exist on type 'MusicKit.Something'."}],"ecosystem":"npm"}