How do I manage relative path aliasing in multiple grunt-browserify bundles?

Question

This is tad long but I'll need the code example to illustrate my confusion. After which I am interested to the answer for the following:

1. How do I use require('module') instead of require('../../src/module') or require('./module')?
2. How do I reuse ./index.js in spec/specs.js without duplicating work? (And preventing src/app.js from running as it's an entry module).

I've started several browser based projects already and love browserify and grunt. But each project dies at the same point in my development/learning curve. Once I add testing to the mix and have to manage two browserify bundles (app.js and spec/specs.js) the whole system falls apart. I'll explain:

I use grunt-browserify and set my initial directory:

.
├── Gruntfile.js
├── index.js  (generated via grunt-browserify)      [1]
├── lib
│   ├── jquery
│   │   └── jquery.js                               [2]
│   └── jquery-ui
│       └── jquery-ui.js                            [3]
├── spec
│   ├── specs.js  (generated via grunt-browserify)  [4]
│   └── src
│       ├── spec_helper.js  (entry)
│       └── module_spec.js  (entry)
└── src
    ├── app.js  (entry)
    └── module.js

1. Uses one entry file (src/app.js) and does a code walk to bundle all required modules.
2. Uses browserify-shim to alias jquery.
3. Is just aliased to jquery-ui without a shim (required after you var $ = require('jquery')).
4. Uses all helper and spec files in spec/src as entry modules.

I'll step through my config:

browserify: {
  dist: {
    files: {
      'index.js': ['src/app.js']
    }
  }
}

// in app.js
var MyModule = require('./module'); // <-- relative path required?!

Happy

Now add jquery:

browserify: {
  options: {
    shim: {
      jquery: {
        path: 'lib/jquery/jquery.js',
        exports: '$'
      }
    },
    noParse: ['lib/**/*.js'],
    alias: [
      'lib/jquery-ui/jquery-ui.js:jquery-ui'
    ]
  },
  dist: {
    files: {
      'index.js': ['src/app.js']
    }
  }
}

// in app.js
var $ = require('jquery');
require('jquery-ui');
var MyModule = require('./module');

Happy

Now add specs:

options: {
  shim: {
    jquery: {
      path: 'lib/jquery/jquery.js',
      exports: '$'
    }
  },
  noParse: ['lib/**/*.js'],
  alias: [
    'lib/jquery-ui/jquery-ui.js:jquery-ui'
  ]
},
dist: {
  files: {
    'app.js': 'src/app.js'
  }
},
spec: {
  files: {
    'spec/specs.js': ['spec/src/**/*helper.js', 'spec/src/**/*spec.js']
  }
}

// in app.js
var $ = require('jquery');
require('jquery-ui');
var MyModule = require('./module');

// in spec/src/module_spec.js
describe("MyModule", function() {
  var MyModule = require('../../src/module'); // <-- This looks like butt!!!
});

Sad

To summarize: How do I...

1. Use require('module') instead of require('../../src/module') or require('./module')?
2. reuse ./index.js in spec/specs.js without duplicating work? (And preventing src/app.js from running as it's an entry module).

Answer 1

Simple answer:

The simplest is to use the paths option of browserify. I use it for some months with great success. I have even made a starter kit that uses this feature: https://github.com/stample/gulp-browserify-react-phonegap-starter

var b = browserify('./app', {paths: ['./node_modules','./src/js']});

paths - require.paths array to use if nothing is found on the normal node_modules recursive walk

If you have a file in src/js/modulePath/myModule.js this won't let you write require("myModule") everywhere, but rather require("modulePath/myModule"), from any of your other source files.

Deprecated option?

It does not seem so!

The Browserify module resolution algorithm mirrors the resolution algorithm in NodeJS. The paths option of Browserify is thus the mirror of NODE_PATH env variable behavior for NodeJS. The Browserify author (substack) claims in this SO topic that the NODE_PATH option is deprecated in NodeJS and thus it is also deprecated in Browserify and could be removed in next versions.

I do not agree with this claim.

See the NODE_PATH documentation. It is not mentionned that the option is deprecated. However there is still an interesting mention that does in the direction of substack's claim:

You are highly encouraged to place your dependencies locally in node_modules folders. They will be loaded faster, and more reliably.

And this question has been posted in 2012 on the mailing list.

Oliver Leics: is NODE_PATH deprecated? 
Ben Noordhuis (ex core NodeJS contributor): No. Why do you ask? 

And if something is not removed in NodeJS resolution algorithm, I don't think it will be removed anytime soon from Browserify :)

Conclusion

You can either use paths option or put your code in node_modules like the official documentation and Browserify author recommends.

Personally, I don't like the idea to put my own code in node_modules as I simply keep this whole folder out of my source control. I use the paths option for some months now and did not have any problem at all, and my build speed is pretty good.

The substack's solution of putting a symlink inside node_modules could be convenient but unfortunately we have developers working with Windows here...

I think there's however a case where you don't want to use the paths option: when you are developping a library published on an NPM repository that will be required by other apps. You really don't want these library clients to have to setup special build config just because you wanted to avoid relative path hell in your lib.

Another possible option is to use remapify