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.