TypeScript icon, indicating that this package has built-in type declarations

2.0.0 • Public • Published


npm Build Status

This source plugin for Gatsby fetches personal statistics and playlists from Spotify. You can use this to display a list of your favorite artists and tracks, or your public playlists.

gatsby-source-spotify is compatible with gatsby-image. Images are always accessible using the image key of a node. Downloaded images are cached locally to improve build times.


$ npm install gatsby-source-spotify


To use this plugin, you have to provide a client id, a client secret, and a personal refresh token from Spotify. To do this, first create a new Spotify App.

After you created it, click the "Edit Settings" button on the application dashboard, add http://localhost:5071/spotify to the "Redirect URIs" section and hit save.

You can then run gatsby-source-spotify's integrated tool to log in using your Spotify account and to get your refresh token.

$ npx gatsby-source-spotify token <clientId> <clientToken>

"Illegal Scope" error
If you get an "Illegal Scope" error from Spotify, you may need to delete your Spotify app and create a new one, see issue #5.

Put those credentials into your gatsby-config.js and you're good to go 🎉

  resolve: `gatsby-source-spotify`,
  options: {
    clientId: `<CLIENT_ID>`,
    clientSecret: `<CLIENT_SECRET>`,
    refreshToken: `<REFRESH_TOKEN>`,

    fetchPlaylists: true, // optional. Set to false to disable fetching of your playlists
    fetchRecent: true, // optional. Set to false to disable fetching of your recently played tracks
    timeRanges: ['short_term', 'medium_term', 'long_term'], // optional. Set time ranges to be fetched

Time Ranges

According to Spotify, the time ranges are specified as follows:

  • short_term: Data from the last four weeks
  • medium_term: Data from the last six months
  • long_term: All data since the account's creation

Querying Data

For your top artists and tracks, I'd recommend filtering by one time_range and sorting by order. This ensures that you get the correct results.

Example for your top artists with images and genres:

    filter: { time_range: { eq: "medium_term" } }
    sort: { fields: order }
  ) {
    edges {
      node {
        image {
          localFile {
            childImageSharp {
              fluid(maxWidth: 400) {


If you're interested in contributing, please feel free to open a pull request.

Package Sidebar


npm i gatsby-source-spotify

Weekly Downloads






Unpacked Size

21 kB

Total Files


Last publish


  • leolabs