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.


    npm i gatsby-source-spotify

    DownloadsWeekly Downloads






    Unpacked Size

    21 kB

    Total Files


    Last publish


    • leolabs