How to Properly Reference SP.js in a Master Page

So I know this has been talked about a ton already, but because I made this mistake again today, I wanted to blog about it and make sure that we’re all on the same page.

In SharePoint, there is often a right way to do things and ‘another’ way of doing the same thing. By ‘right’, I mean, it will work in most scenarios and is the generally accepted convention.

Let’s talk specifically about SP.js. If you’re doing any work with JSOM, often times you’ll need to reference one or all of the following files:

  • /_layouts/15/sp.runtime.js
  • /_layouts/15/sp.userprofiles.js
  • /_layouts/15/sp.js
  • /_layouts/15/SP.taxonomy.js

You want to avoid referencing them in this way:

<script src="/_layouts/15/sp.js" type="text/javascript"></script>

The above will load sp.js successfully, and it will often go hand in hand with the following:

SP.SOD.executeFunc('sp.js', 'SP.ClientContext', ready);
function ready() {
    // some code here

Now the above will work from your custom code perspective, but what you might find is some strangeness with respect to other elements in SharePoint. In our case, we had issues with the ribbon, because the effect of the script tag above was to load sp.js TWICE which was likely interrupting the initial call leveraged by the ribbon.

Removing the sp.js file all together was not a good workaround, since we couldn’t control the speed with which sp.js file was being loaded. Our executeFunc call was passing because the SP.ClientContext was partially loaded.

So you want to make sure you load your sp.js in this manner:

<SharePoint:ScriptLink ID="ScriptLink21" Name="sp.js" runat="server" OnDemand="false" LoadAfterUI="true" Localizable="false" />

The above code does a few things differently that are VERY important:

  1. Ensures that the script is loaded only once
  2. Adds a rev tag to the script load to ensure freshness of the file: /_layouts/15/sp.userprofiles.debug.js?rev=p1e1MK16xqhzgHSFHZEOOA%3D%3D
  3. Ensures that other dependencies have been loaded first

Would be interested in hearing how others are referencing this crucial file!

, ,

15 Responses to “How to Properly Reference SP.js in a Master Page”

  1. Nishant Rana December 10, 2013 at 9:29 am #

    Thanks Shereen it was really helpful.

  2. Shereen Qumsieh December 10, 2013 at 3:03 pm #

    You are most welcome!

  3. chintan May 2, 2014 at 9:24 am #

    Great! I am new to JSOM. You saved my tons of time.

  4. chintan May 2, 2014 at 9:26 am #

    Shereen, You didn’t mention /layout/sp.js” path at all. Will tab will take sp.js from layout folder?

    Pls. let me know.

  5. Clem June 4, 2014 at 2:14 pm #

    Is loading SP.js necessary? SharePoint loads it automatically with each site?

  6. Clem June 9, 2014 at 1:03 pm #

    The issue with this is that the master page links are loaded AFTER all web parts have been loaded. If you have a web part page with your master and your web parts rely on SP.js, this is too late. The web parts won’t have access to the clientcontext since SP.js hasn’t loaded yet.

  7. Ricardo June 12, 2014 at 7:50 pm #

    This is what i was forgetting today, the “LoadAfterUI” tag, it’s surprising how many answers i found for that other solution (delay your script until sp.js loads) until I saw yours.


  8. Shereen Qumsieh July 15, 2014 at 5:24 pm #

    We have quite a few custom web parts that are built and rely on this, and no issues with sp.js not being ready yet. How are you wiring up your web parts? What issues specifically are you running into?

  9. Shereen Qumsieh July 15, 2014 at 5:29 pm #

    We find that we do need to load it, as it’s not always present. I don’t recall every scenario. Do you find that you can access the jsom api without issue every where in a sp site without having to load this file? I’ll dig into this again and update this post with what I find.

  10. Shereen Qumsieh July 15, 2014 at 5:31 pm #

    It should take it from the layouts folder yes.

  11. Gordon November 10, 2014 at 4:15 pm #

    Hi Shereen,

    Appreciate your blog!

    It looks as though your example of referencing SP.taxonomy.js and the other 3 files above applies to SP 2013. Will the SP.SOD.Execute and SharePoint Scriptlink calls also work in the SP 2010 environment?

  12. D November 26, 2014 at 7:51 pm #

    thanks this saved me a lot of time

  13. Mike Norrie August 4, 2015 at 2:55 pm #

    I use a standard masterpage (seattle) calling my code using SP.SOD.executeFunc(‘sp.js’, ‘SP.ClientContext’, functionname); and have no problems at all until….

    I need to use another webpart on the same page that also uses SP.SOD.executeFunc(‘sp.js’, ‘SP.ClientContext’, funcitonname); then it falls in a heap.

    It only calls one of the functions as the second call cancels out the first.

    Anyone have any ideas as to how to solve this? I’ve had to put all the calls into the one function but I’d love to separate them to create separate reusable webparts.

  14. Shereen Qumsieh August 4, 2015 at 4:05 pm #

    Hi Mike, so are those two separate functions you are trying to call?


  1. How to Properly Reference SP.js in a Master Page | SharePoint ... | ARB Security Solutions - SharePoint Security Solutions - October 31, 2013

    […] Another SharePoint Blog Post From SharePoint Development – Google Blog Search: […]

Leave a Reply