What makes this library special?

• Multiplatform: You can use it with Node.js, Deno on the server, or with client-side JavaScript.
• Comprehensive Spotify Auth support: It can handle all Spotify Auth flows and automatically refreshes access tokens.
• Modern: It leverages modern web APIs like native fetch, crypto, URLSearchParams and doesn’t require any external dependencies.
• Lightweight and treeshakable: It’s designed to be as small as possible (exact size TBD).
• TypeScript first: It’s built with TypeScript and provides great support for it out of the box.
• Great docs: The library comes with extensive documentation and lots of examples to help you get started.

Installation

NPM npm.js/soundify-web-api

npm i soundify-web-api

Unfortunately, the soundify package on the NPM was already taken ;(

// For nodejs (server-side)
import { ... } from "soundify-web-api"

// For client-side javascript
import { ... } from "soundify-web-api/web"

Deno deno.land/x/soundify

// Import from denoland (recomended)
import { ... } from "https://deno.land/x/soundify/mod.ts"

// Import from github repo main branch 
import { ... } from "https://raw.githubusercontent.com/MellKam/soundify/main/mod.ts";

Gettings started

Let’s write “Hello world!” with soundify.

import { getCurrentUserProfile, SpotifyClient } from "soundify-web-api";

const client = new SpotifyClient("YOUR_ACCESS_TOKEN");

const user = await getCurrentUserProfile(client);
console.log(user);

If your Access Token is valid it will output something like this

{
  "id": "31xofk5q7l22rvsbff7yiechyx6i",
  "display_name": "Soundify",
  "type": "user",
  "uri": "spotify:user:31xofk5q7l22rvsbff7yiechyx6i",
  // etc...
}

But how to get your Access Token?

If you just want to get a token quickly you can go to the Spotify Console. Then navigate to any endpoint and click on “GET TOKEN”. You will be prompted to select scopes and then redirected to authentification. You will then have your token in the “OAuth Token” field.

Or you can try running one of our examples with a simple http server that will give you your token. With node examples/node-express-auth or with deno examples/deno-oak-auth

Authorization

If you have no experience with Spotify Auth you can read more about it in the Spotify Authorization Guide.

Flows

Authorization flows are organized into separate namespaces, with each namespace containing all the necessary functions and classes to implement a specific authorization flow. This allows for easy importing of a specific flow.

For instance, the following code imports different authorization flows:

// Importing the Authorization Code flow
import { AuthCode } from "soundify-web-api"

// Importing the Authorization Code flow with PKCE
import { PKCEAuthCode } from "soundify-web-api"

// Importing the Client Credentials flow
import { ClientCredentials } from "soundify-web-api"

// Importing the Implicit Grant flow
import { ImplicitGrant } from "soundify-web-api"

You can take a look at the examples to see how to use each authorization flow.

• Authorization Code flow - examples/node-express-auth, examples/next-ssr, examples/deno-oak-auth
• Authorization Code flow with PKCE - examples/react-pkce-auth
• Client Credentials flow - TBD
• Implicit Grant flow - examples/react-implicit-grant

AuthProvider

As you saw earlier, you can simply pass the Access Token to SpotifyClient. But after some time (1 hour to be exact), it will expire and you’ll need to deal with it yourself. Somehow get a new Access Token and set it on the client.

import { SpotifyClient } from "soundify-web-api"

const client = new SpotifyClient("ACCESS_TOKEN")
// ...
// Oops, token expires :(
client.setAuthProvider("NEW_ACCESS_TOKEN")

But if you don’t want to deal with all that, you can just create an AuthProvider and pass it instead of the Access Token.

import { AuthCode, SpotifyClient } from "soundify-web-api";

const authProvider = new AuthCode.AuthProvider({
  client_id: "YOUR_SPOTIFY_CLIENT_ID",
  client_secret: "YOUR_SPOTIFY_CLIENT_SECRET",
  refresh_token: "YOUR_REFRESH_TOKEN",
});

const client = new SpotifyClient(authProvider);

You can create an AuthProvider from AuthCode, PKCEAuthCode, ClientCredentials flows. Implicit grant does not allow you to implement such a thing.

Auth Scopes

You will use auth scopes when creating an authorization url using the getAuthURL function. You can pass scopes just as raw strings. It will be easy becase you will have autofill for them :)

import { AuthCode } from "soundify-web-api";

AuthCode.getAuthURL({
  scopes: ["user-read-email", ...],
  ...
})

Or you can use the AUTH_SCOPES const object, which is used as an enum

import { AuthCode, AUTH_SCOPES } from "soundify-web-api";

AuthCode.getAuthURL({
  scopes: [AUTH_SCOPES.USER_READ_EMAIL],
  ...
})

If you need to set all scopes, it may be much easier to use AUTH_SCOPES and take all values from it.

import { AuthCode, AUTH_SCOPES } from "soundify-web-api";

AuthCode.getAuthURL({
  scopes: Object.values(AUTH_SCOPES),
  ...
})

Be careful with scopes, because many fields and endpoints may not be available because the auth scope is not set.

All contributions are very welcome ❤️