Registry / type-stubs / musickit-typescript

musickit-typescript

library1.2.4jsnpmunverified

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.

type-stubs

npm install musickit-typescript

github ↗package ↗

INSTALL

IMPORT

SIG · MUSICKIT-TYPESCRIP

musickit-typescript

type-stubsjavascriptv1.2.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MusicKit (global object)

✓ const musicInstance = MusicKit.getInstance();

✗ import { MusicKit } from 'musickit-typescript';

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)

✓ let api: MusicKit.API;

✗ import { API } from 'musickit-typescript';

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)

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

✗ import { Player } from 'musickit-typescript';

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.

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();

Debug

Known issues

gotchaIncorrect 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.

affects: >=1.0.0

gotchaVersion 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.

affects: >=1.0.0

gotchaThis 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.

affects: >=1.0.0

Errors

Common errors & fixes

TS2304: Cannot find name 'MusicKit'.

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

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'.

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; } }`.

Upgrade

Version history

1.2.4latest on npm

Audit

Dependencies

musickitrequiredProvides type definitions for the MusicKit JS library, which must be loaded at runtime for the types to be meaningful.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wsmd/musickit-typescript ↗

packagehttps://www.npmjs.com/package/musickit-typescript ↗