Adding javascript files (Waypoints)

The two questions here are:

  1. How does one add Waypoints shortcuts?

  2. Where does one add the custom script?

Below I’ve just gone through each step as understood (or not) in the documentation. It’s not working, so I hope someone can help clarify the ‘Sage method’ where it’s misunderstood, and I can help improve the documentation on it.

I’ve followed the book documentation and theme building documentation. I’ve spent two days reading and learning how to do this. It is still not clear how this I would do this correctly.

Specifically with Waypoints, there is a bower install. The Sage documentation says this is the preferred method of installing if available: bower waypoints install --save

The above appears to work fine. Satisfyingly, waypoints seems to automatically be added to the Sage them bower.json with the addition of this: "waypoints": "~4.0.0"

Is this all that is required, or does it need adding to the manifest and enqueuing?

After that, thing get confusing. Waypoints has shortcut scripts, and also a custom script needs to be written in any case. First question: How does one add the shortcut scripts? These currently reside in the waypoints bower folder: /shortcuts. If my understanding is correct (p31 of theme dev with sage first edition), this is added manually in the manifest like this:

 "sticky.js": {
         "files": ["shortcuts/sticky.js"],
               "external": true,
               "bower": ["waypoints"]

The above adds sticky.js and to the list folder, so this seems to be correct. Looking at those files, waypoints.js and sticky.js are exactly the same, so something is up here? Are one of these, or both supposed to be a merged and minified file?

The above is slightly conflicted with:

(p31) As long as the Bower package you’ve installed has defined the files you want loaded in its bower.json file, you won’t need to add any overrides.

The shortcut is not included in the waypoints bower.json, so the above addition top the manifest seems correct? In a previous post, I mentioned I had added it here and was informed NOT to touch a packages .json file.

Assuming also that the above is, or had worked properly, the documentation seems to say these don’t need enqueuing (because they are bower). This doesn’t make sense to me if the are being mapped to the list folder. I looked at further documentation, which suggest

After this, we have a custom script i.e.:

function stickyExample() {
             var $stickyElement = $('.basic-sticky-example')
             var sticky
             if ($stickyElement.length) {
               sticky = new Waypoint.Sticky({
                 element: $stickyElement[0],
                 wrapper: '<div class="sticky-wrapper waypoint" />'

Where does this go? I would assume it goes in the main.js (I’m using on all pages, so in the common part?)

Thanks in advance for any help on this!

1 Like

Hey there @blitz!

First of all, please do a search before posting (I searched for “waypoints”). We’ve actually covered waypoints specifically before: Is Bower documentation needed? (Can I help?)

Anyways, there are a lot of ways to do it, but if you’re using waypoints on every page I would think you’d just want to include it in main.js, so here’s how I’d do that:

First, bower install waypoints --save
Then, Add waypoints overrides to the bower.json file because their main argument doesn’t include the jQuery version or the sticky that you want:

Then, run gulp and you should have your js compiled into in main.js now.
Finally, add your waypoints code either in the init or finalize anonymous functions in main.js and it should run on every page.

And just so you know, js does not need enqueuing if your scripts from bower are being piped into one of the files already in manifest.json, such as main.js. As soon as you make a new file (stick.js for example), you’ll need to enqueue that wherever you need it. In this case, I’d recommend my approach above. You can also check out my angular post for an example of some more working complex manifest and bower examples.


Is that all good Blitz?

Waypoints threw me off a bit as it appears in Bower twice as “jquery-waypoints” and “waypoints” - even though both packages point to the same place and load the noframework version

(you can see if you look at “bower_components\waypoints\bower.json” it has:
“main”: “lib/noframework.waypoints.js”,

  • but never ever touch anything in bower_components!!!)

What the Roots guys have in their project is their own bower.json, and with this you basically override each bower package’s bower.json.

So in my web_dir\power\wp-content\themes\sage\bower.json I have this code appearing last in the file

"waypoints": {
    "main": [

Hi Julien, thanks for the reply. I did search for waypoints and I did actually comment on the post you mentioned.

I’m going to write this up as a single step by step when I’ve got it nailed!

So, back to topic, if I add:

"waypoints": {
    "main": [

in the overrides, the gulp fails (SyntaxError: Unexpected token). I’m assuming I have added this incorrectly. It looks like there are too many closing brackets to me?

I can make it pass if I add it like this (the bootstrap-sass reference is to show the position in the boilerplate):

"overrides": {
  "waypoints": {
     "main": [
    "bootstrap-sass": {

Is that correct?

If so, what is then supposed to happen? I assume this is supposed to add to the main.js - which is not happening…

Hey Blitz,

I got waypoints working exactly how I said in the directions above in about 3 minutes: (the diff might be more helpful)

If you pull that down and install everything and activate that theme on a default blank install it will totally console.log with waypoints…

To answer your other questions:

yep, I see that now, sorry about that…

yes, in the code you posted above there is an extra bracket, you have to fit it into your overrides object

After you run gulp (my 3rd step), it goes right into your main.js file…

Guess you get a get out of jail free card on this one… :wink:


OMFG - it’s working!

Thank you @JulienMelissas and @buswell

I’m writing this up as a single ‘how to’ article. It makes complete sense now, it’s just very difficult to troubleshoot if things go… sideways :smile:

Let me tackle the CSS bits and I’ll finish writing up. Thanks again!

Honestly Julian you should really have your face on this forum as some kind of popup - you know as mentioned on

(as I learned about from the Pragmatic programmer - amazing amazing thanks to the Roots guys for mentioning it so much and pushing me into reading it)

Before submitting a venting frustrated post you could have a “tell Julian first” button and they’d explain their problem to your bobbing SVG animated head and probably 90% of people would work it out themselves

1 Like

Little Update on this post as it is quite old and maybe some people still have problems with this.

Using Sage 9 this now works like this:

USE BOWER FOR THIS !! --> it was replaced with npm. To import npm modules, use Yarn (as described below)
EDIT WEBPACK-FILES! --> as suggested on github.

$ yarn add waypoints
$ yarn build

Then on top of your js-route-file (i.e. common.js or home.js) import like this

A) if you are using jQuery, which you probably are when using Sage
import 'waypoints/lib/jquery.waypoints.min.js';

B) if you are not using jQuery
import 'waypoints/lib/noframework.waypoints.min.js';

C) if you want to use one of the shortcuts (sticky, inview, infinite scroll, do this (example for inview):
import 'waypoints/lib/shortcuts/inview.min.js';

NOTE: If you are getting Eslint undefined-errors on stuff like “Waypoint” or “inview”, just disable Eslint on these lines. E.g.:

/* eslint-disable*/
var inview = new Waypoint.Inview({
/* eslint-enable*/

Thats it. Now you can use waypoints and its shortcuts.

off topic: I wrote a little snippet for executing effects only when in viewport, using inview-shortcut. Feel free to give me some feedback on this if you like: