Don’t force users to install node modules globally when you can avoid that

How often have you seen instructions for installing a project that are something like this?

git clone https://wherever/the/project/is
cd cloned_folder
npm install -g gulp # <-- 😱

(or, instead of gulp, any other utility that the project requires for development)

This is not a good idea. You’re installing the same version of a utility globally, and perhaps the project has not been tested with that version. Things might break or even worse, work not-so-well in a strange, undebuggable way!

Don’t do it.

A better way is to use npm scripts, which belong to the project, and specify development dependencies in package.json, so when you run npm install, it also installs devDependencies locally to the projects’ node_modules folder. This keeps everything under control and does not pollute other people’s computers global space.

So, for example, if a project was asking users to run npm install -g gulp, they should do this instead:

  1. Install gulp locally as a development dependency, saving it to package.json:
    npm install --save-dev gulp
  2. Add a new entry to the scripts array in package.json:
    "build": "gulp"
  3. Ask users to run
    npm install

    the first time. And

    npm run build

    each time they need to build the project

The reason this works is because when npm runs a script, it modifies the current PATH variable to add node_modules/.bin, which contains any binaries that you installed as part of your modules. So your computer will search for binaries starting in the .bin folder, before searching in any other default location for binaries in your computer (e.g. /usr/bin)

You can find more documentation about this behaviour in the run-script page of the npm manual. I really encourage you to read it as it has lots of good stuff and Things You Wished Had Known Before 🙂

And in case it makes things clearer, this is how a hypothetical package.json would look before:

{
  devDependencies: {}
}

And after:

{
  devDependencies: {
    "gulp": "12.34.56"
  },
  scripts: {
    "build": "gulp"
  }
}

With this, the devDependency is clearly stated on the package.json file, the project developer will be developing with that version, and will not get surprises! (and the users of the module won’t either).

Another advantage of this approach is that you are not tying the project to a specific utility.

If you decide to use grunt instead of gulp later on, you just need to do whatever changes you need (Gruntfile instead of Gulpfile, edit package.json etc), and yet users of the project will still start the build process with npm run build.

It’s invisible to them (except perhaps running npm install again)!

You’re hiding internals that they do not necessarily need to know about, so it’s a good abstraction. Seriously—you won’t even need to update your getting started guide! Good stuff.

Hope that helps!

If you want to learn even more cool npm scripts tricks, I recommend Kate’s talk and accompanying post. Actually, I just realised she explained the same thing I did, so here’s her take, haha!

A three.js npm template

rotating demo cube

I can’t imagine dropping a series of <script> tags on a page to build a minimally complex website anymore. I’ve got used to browserify and so I can’t go back to building my fancy 3D thingies like it was 2012 all over again.

So I made this minimal template that sets the bare minimum you might need to build a three.js powered site using browserify via gulp. That lets you use any other npm-based modules and libraries you want! So your code should not be messy and/or a tremendously big file with everything tucked on it.

There’s also some extra help like a file watcher… and not much more, really.

Do let me know if you use it for something cool… or if you can/want to help on this issue! 😀

Tools for the 21st century musician

That is the title of the talk I gave yesterday at Full Frontal in Brighton. The video is still not out but here are the slides (and the source for the slides, with all the source for the examples).

If you were in my Web Audio workshop in Berlin, this talk followed the same style, except I refined some points and sadly forgot a couple. I also showed the Web Audio Editor in Firefox DevTools, which I didn’t in Berlin because Jordan was going to talk about it after me.

I had a little bit of a surprise at the end of the talk, when I “presented” for the first time a little project we’ve been working on for a while: OpenMusic. And I have “quoted” the presented word because the work has always been in GitHub in the open, so if you followed me in GitHub you might have seen all the repos popping up and wonder what the hell is Sole doing lately.

So, just in case you weren’t in the conference, OpenMusic aims to be a nice collection of interoperable/reusable Web Audio modules and components. This is an idea that Angelina sort of had when they saw my audio tags talk last year, and has been brewing in the back of our minds until a couple of months ago when the A-HA! moment finally happened.

And so I’ve been pulling apart components and pieces from my existing Web Audio-based code, because I realised I was doing the same thing over and over and I wanted to do new things but I didn’t want to do the same thing yet again. So, small npm based modules it is. And a bunch of them!

I’m a bit short on time lately (and I’m being very generous on this description), so some of the modules are a bit too rushed and a tad obscure, but they should work and have some minimal documentation already, and they’ll get better. Be kind while I deconstruct my hacks–or better yet, start deconstructing yours too! =)

Thanks to Remy for inviting me to this ultra cool conference… and accidentally triggering the A-HA moment!

Keeping clean

A week or so ago James Coglan tweeted this:

It reflects perfectly why I didn’t get too much into Python other than writing isolated scripts that worked well with themselves and didn’t require extra packages, because installing them was a pain and different in each system (compiling, package managers, other package managers, eggs, pip, bla, bla). And then there was the virtualenv solution, but that adds another layer of managing that I have to deal with. I just want to get things done and be able to distribute them in a manner that makes it easy for other people to use my software.

This reminded me that I had to spend a whole afternoon a while ago trying to make some brew-installed packages operate in harmony with other libraries/binaries in my system. It was so tedious and fuzzy I can’t even remember what the problem was actually. Just the notion that installing all the software and making it all available into a global scope === bad, because different versions will require other different versions. And either everything works in harmony and life is beautiful, or you spent a rainy afternoon feeling miserable because of the weather and the incompatible binaries.
Continue reading “Keeping clean”

tween.js r14

tween.js r14 is really more of a “cleaning house” revision than anything else. No new features have been added, but the library should be a little bit more usable now and lead by example by using better code examples that aim to be efficient JS and CSS wise:

  • Include license header on the minified files too (hyandell)
  • Make examples more efficient by using requestAnimationFrame‘s own timer instead of calling Date.now again (Robert Eisele)
  • Make it explicit that you can install tween.js with npm and bower (sole)

As usual, you can download it/clone from github or install with npm:

npm install tween.js

And as a “new thing”, although it was always here, installing via bower is also possible:

bower install tween.js

You can also read more instructions and code samples on getting the library.

Cheers to whoever told me you could install any package using git with bower. I believe it was the magnificent Edna Piranha! So thanks Edna!