lastfm-nodejs-client

LastFm NodeJs client

A TypeScript client for the Last.fm API. Works in Node.js ≥18 and all modern browsers — no polyfills required.

Why use this

Zero dependencies. The library ships no third-party runtime dependencies. HTTP requests use the native fetch API built into Node.js ≥18, and API signatures are generated with the built-in node:crypto module. Installing it won't bloat your node_modules or introduce supply-chain risk.

Fully typed. Every API response has a hand-written TypeScript interface, so you get autocomplete and type safety straight out of the box — no extra @types packages needed.

Dual ESM + CJS. The package ships both ES module and CommonJS builds, so it works in any Node.js project regardless of whether you use import or require.

Install

pnpm add lastfm-nodejs-client

npm install lastfm-nodejs-client

yarn add lastfm-nodejs-client

bun add lastfm-nodejs-client

// Deno
import LastFmApi from 'jsr:@mannuelf/lastfm-nodejs-client';

Setup

Create a .env file in your project root:

LASTFM_API_BASE_URL="https://ws.audioscrobbler.com/2.0/"
LASTFM_USER="your_username"
LASTFM_API_KEY="your_api_key"
LASTFM_APPNAME="your_app_name"
LASTFM_SHARED_SECRET="your_shared_secret"

Get your API key at last.fm/api/account/create.

Usage

import LastFmApi from 'lastfm-nodejs-client';

const lastFm = LastFmApi();
const { method } = lastFm;

Get a user's top artists

import LastFmApi from 'lastfm-nodejs-client';
import type { TopArtistsResponse } from 'lastfm-nodejs-client';

const lastFm = LastFmApi();
const { method } = lastFm;

const data: TopArtistsResponse = await lastFm.getTopArtists(
  method.user.getTopArtists,
  'your_username',
  'overall', // period: overall | 7day | 1month | 3month | 6month | 12month
  '10', // limit
);

console.log(data.topartists.artist);

Get a user's recent tracks

import LastFmApi from 'lastfm-nodejs-client';
import type { RecentTracksResponse } from 'lastfm-nodejs-client';

const lastFm = LastFmApi();
const { method } = lastFm;

const data: RecentTracksResponse = await lastFm.getRecentTracks(
  method.user.getRecentTracks,
  'your_username',
  '10', // limit
);

console.log(data.recenttracks.track);

Get artist info

import LastFmApi from 'lastfm-nodejs-client';
import type { ArtistInfoResponse } from 'lastfm-nodejs-client';

const lastFm = LastFmApi();
const { method } = lastFm;

const data: ArtistInfoResponse = await lastFm.artist.artistGetInfo(
  method.artist.getInfo,
  'Radiohead',
);

console.log(data.artist);

Get album info

import LastFmApi from 'lastfm-nodejs-client';
import type { AlbumInfoResponse } from 'lastfm-nodejs-client';

const lastFm = LastFmApi();
const { method } = lastFm;

const data: AlbumInfoResponse = await lastFm.album.albumGetInfo(
  method.album.getInfo,
  'Radiohead',
  'OK Computer',
);

console.log(data.album);

Search for a track

import LastFmApi from 'lastfm-nodejs-client';
import type { TrackSearchResponse } from 'lastfm-nodejs-client';

const lastFm = LastFmApi();
const { method } = lastFm;

const data: TrackSearchResponse = await lastFm.track.trackSearch(
  method.track.search,
  'Creep',
  'Radiohead', // optional artist filter
  '5', // limit
);

console.log(data.results.trackmatches.track);

Love a track (authenticated)

Requires a session key (sk) obtained via auth.getMobileSession or auth.getSession.

import LastFmApi from 'lastfm-nodejs-client';

const lastFm = LastFmApi();
const { method } = lastFm;

await lastFm.track.trackLove(method.track.love, 'Radiohead', 'Creep', 'your_session_key');

All available namespaces

Namespace	Methods
album	albumGetInfo, albumGetTags, albumGetTopTags, albumSearch, albumAddTags, albumRemoveTag
artist	artistGetInfo, artistGetSimilar, artistGetTags, artistGetTopAlbums, artistGetTopTags, artistGetTopTracks, artistSearch, artistAddTags, artistRemoveTag, artistGetCorrection
auth	getToken, getSession, getMobileSession
chart	chartTopArtists, chartTopTracks, chartTopTags
geo	geoGetTopArtists, geoGetTopTracks
library	libraryGetArtists
tag	tagGetInfo, tagGetSimilar, tagGetTopAlbums, tagGetTopArtists, tagGetTopTags, tagGetWeeklyChartList, tagTopTracks
track	trackGetInfo, trackGetSimilar, trackGetTags, trackGetTopTags, trackSearch, trackLove, trackUnlove, trackAddTags, trackRemoveTag, trackScrobble, trackUpdateNowPlaying, trackGetCorrection
user	userGetPersonalTags

Legacy flat methods also available: getTopArtists, getTopTracks, getRecentTracks, getLovedTracks, getInfo, getFriends, getUserTopTags, getWeeklyAlbumChart, getWeeklyArtistChart, getWeeklyChartList, getWeeklyTrackChart, getTopAlbums.

Developing

gh repo fork mannuelf/lastfm-nodejs-client

pnpm install
pnpm test
pnpm lint
pnpm build

Why I built this

I was building a scrobbles page at mannuelferreira.com/scrobbles and thought others might find it useful.