There's a really interesting section in the Browserify Handbook:

avoiding ../../../../../../..

Not everything in an application properly belongs on the public npm and the overhead of setting up a private npm or git repo is still rather large in many cases. Here are some approaches for avoiding the ../../../../../../../ relative paths problem.

node_modules

People sometimes object to putting application-specific modules into node_modules because it is not obvious how to check in your internal modules without also checking in third-party modules from npm.

The answer is quite simple! If you have a .gitignore file that ignores node_modules:

node_modules

You can just add an exception with ! for each of your internal application modules:

node_modules/*
!node_modules/foo
!node_modules/bar

Please note that you can't unignore a subdirectory, if the parent is already ignored. So instead of ignoring node_modules, you have to ignore every directory inside node_modules with the node_modules/* trick, and then you can add your exceptions.

Now anywhere in your application you will be able to require('foo') or require('bar') without having a very large and fragile relative path.

If you have a lot of modules and want to keep them more separate from the third-party modules installed by npm, you can just put them all under a directory in node_modules such as node_modules/app:

node_modules/app/foo
node_modules/app/bar

Now you will be able to require('app/foo') or require('app/bar') from anywhere in your application.

In your .gitignore, just add an exception for node_modules/app:

node_modules/*
!node_modules/app

If your application had transforms configured in package.json, you'll need to create a separate package.json with its own transform field in your node_modules/foo or node_modules/app/foo component directory because transforms don't apply across module boundaries. This will make your modules more robust against configuration changes in your application and it will be easier to independently reuse the packages outside of your application.

symlink

Another handy trick if you are working on an application where you can make symlinks and don't need to support windows is to symlink a lib/ or app/ folder into node_modules. From the project root, do:

ln -s ../lib node_modules/app

and now from anywhere in your project you'll be able to require files in lib/ by doing require('app/foo.js') to get lib/foo.js.

custom paths

You might see some places talk about using the $NODE_PATH environment variable or opts.paths to add directories for node and browserify to look in to find modules.

Unlike most other platforms, using a shell-style array of path directories with $NODE_PATH is not as favorable in node compared to making effective use of the node_modules directory.

This is because your application is more tightly coupled to a runtime environment configuration so there are more moving parts and your application will only work when your environment is setup correctly.

node and browserify both support but discourage the use of $NODE_PATH.

The big picture

It seems "really bad" but give it time. It is, in fact, really good. The explicit require()s give a total transparency and ease of understanding that is like a breath of fresh air during a project life cycle.

Think of it this way: You are reading an example, dipping your toes into Node.js and you've decided it is "really bad IMO." You are second-guessing leaders of the Node.js community, people who have logged more hours writing and maintaining Node.js applications than anyone. What is the chance the author made such a rookie mistake? (And I agree, from my Ruby and Python background, it seems at first like a disaster.)

There is a lot of hype and counter-hype surrounding Node.js. But when the dust settles, we will acknowledge that explicit modules and "local first" packages were a major driver of adoption.

The common case

Of course, node_modules from the current directory, then the parent, then grandparent, great-grandparent, etc. is searched. So packages you have installed already work this way. Usually you can require("express") from anywhere in your project and it works fine.

If you find yourself loading common files from the root of your project (perhaps because they are common utility functions), then that is a big clue that it's time to make a package. Packages are very simple: move your files into node_modules/ and put a package.json there. Voila! Everything in that namespace is accessible from your entire project. Packages are the correct way to get your code into a global namespace.

Other workarounds

I personally don't use these techniques, but they do answer your question, and of course you know your own situation better than I.

You can set $NODE_PATH to your project root. That directory will be searched when you require().

Next, you could compromise and require a common, local file from all your examples. That common file simply re-exports the true file in the grandparent directory.

examples/downloads/app.js (and many others like it)

var express = require('./express')

examples/downloads/express.js

module.exports = require('../../')

Now when you relocate those files, the worst-case is fixing the one shim module.

And what about:

var myModule = require.main.require( './path/to/module' ) ;

It requires the file as if it were required from the main js file, so it works pretty well as long as your main js file is at the root of your project... and that's something I appreciate.

IMHO, the easiest way is to define your own function as part of GLOBAL object. Create projRequire.js in the root of you project with the following contents:

var projectDir = __dirname;

module.exports = GLOBAL.projRequire = function(module) {
  return require(projectDir + module);
}

In your main file before requireing any of project-specific modules:

// init projRequire
require('./projRequire');

After that following works for me:

// main file
projRequire('/lib/lol');

// index.js at projectDir/lib/lol/index.js
console.log('Ok');

---

@Totty, I've comed up with another solution, which could work for case you described in comments. Description gonna be tl;dr, so I better show a picture with structure of my test project.

I like to make a new node_modules folder for shared code, then let node and require do what it does best.

for example:

- node_modules // => these are loaded from your package.json
- app
  - node_modules // => add node-style modules
    - helper.js
  - models
    - user
    - car
- package.json
- .gitignore

For example, if you're in car/index.js you can require('helper') and node will find it!

How node_modules Work

node has a clever algorithm for resolving modules that is unique among rival platforms.

If you require('./foo.js') from /beep/boop/bar.js, node will look for ./foo.js in /beep/boop/foo.js. Paths that start with a ./ or ../ are always local to the file that calls require().

If however you require a non-relative name such as require('xyz') from /beep/boop/foo.js, node searches these paths in order, stopping at the first match and raising an error if nothing is found:

/beep/boop/node_modules/xyz
/beep/node_modules/xyz
/node_modules/xyz

For each xyz directory that exists, node will first look for a xyz/package.json to see if a "main" field exists. The "main" field defines which file should take charge if you require() the directory path.

For example, if /beep/node_modules/xyz is the first match and /beep/node_modules/xyz/package.json has:

{
  "name": "xyz",
  "version": "1.2.3",
  "main": "lib/abc.js"
}

then the exports from /beep/node_modules/xyz/lib/abc.js will be returned by require('xyz').

If there is no package.json or no "main" field, index.js is assumed:

/beep/node_modules/xyz/index.js

You could define something like this in your app.js:

requireFromRoot = (function(root) {
    return function(resource) {
        return require(root+"/"+resource);
    }
})(__dirname);

and then anytime you want to require something from the root, no matter where you are, you just use requireFromRoot instead of the vanilla require. Works pretty well for me so far.

Here is the actual way I'm doing for more than 6 months. I use a folder named node_modules as my root folder in the project, in this way it will always look for that folder from everywhere I call an absolute require:

• node_modules
  • myProject
    • index.js I can require("myProject/someFolder/hey.js") instead of require("./someFolder/hey.js")
    • someFolder which contains hey.js

This is more useful when you are nested into folders and it's a lot less work to change a file location if is set in absolute way. I only use 2 the relative require in my whole app.

Have a look at node-rfr.

It's as simple as this:

var rfr = require('rfr');
var myModule = rfr('projectSubDir/myModule');

Assuming your project root is the current working directory, this should work:

// require built-in path module
path = require('path');

// require file relative to current working directory
config = require( path.resolve('.','config.js') );

There's a good discussion of this issue here.

I ran into the same architectural problem: wanting a way of giving my application more organization and internal namespaces, without:

• mixing application modules with external dependencies or bothering with private npm repos for application-specific code
• using relative requires, which make refactoring and comprehension harder
• using symlinks or changing the node path, which can obscure source locations and don't play nicely with source control

In the end, I decided to organize my code using file naming conventions rather than directories. A structure would look something like:

• npm-shrinkwrap.json
• package.json
• node_modules
  • ...
• src
  • app.js
  • app.config.js
  • app.models.bar.js
  • app.models.foo.js
  • app.web.js
  • app.web.routes.js
  • ...

Then in code:

var app_config = require('./app.config');
var app_models_foo = require('./app.models.foo');

or just

var config = require('./app.config');
var foo = require('./app.models.foo');

and external dependencies are available from node_modules as usual:

var express = require('express');

In this way, all application code is hierarchically organized into modules and available to all other code relative to the application root.

The main disadvantage is of course that in a file browser, you can't expand/collapse the tree as though it was actually organized into directories. But I like that it's very explicit about where all code is coming from, and it doesn't use any 'magic'.

Imho the easiest way to achieve this is by creating a symbolic link on app startup at node_modules/app (or whatever you call it) which points to ../app. Then you can just call require("app/my/module"). Symbolic links are available on all major platforms.

However, you should still split your stuff in smaller, maintainable modules which are installed via npm. You can also install your private modules via git-url, so there is no reason to have one, monolithic app-directory.

i created a node module called "rekiure"

it allows you to require without the use of relative paths

https://npmjs.org/package/rekuire

it is super easy to use

I was having trouble with this same issue, so I wrote a package called include.

Include handles figuring out your project's root folder by way of locating your package.json file, then passes the path argument you give it to the native require() without all of the relative path mess. I imagine this not as a replacement for require(), but a tool for requiring handling non-packaged / non-third-party files or libraries. Something like

var async = require('async'),
    foo   = include('lib/path/to/foo')

I hope this can be useful.

I use process.cwd() in my projects. For example:

var Foo = require(process.cwd() + '/common/foo.js');

It might be worth noting that this will result in requireing an absolute path, though I have yet to run into issues with this.

In your own project you could modify any .js file that is used in the root directory and add its path to a property of the process.env variable. For example:

// in index.js
process.env.root = __dirname;

Afterwards you can access the property everywhere:

// in app.js
express = require(process.env.root);

Couldn't the examples directory contain a node_modules with a symbolic link to the root of the project project -> ../../ thus allowing the examples to use require('project'), although this doesn't remove the mapping, it does allow the source to use require('project') rather than require('../../').

I have tested this, and it does work with v0.6.18.

Listing of project directory:

$ ls -lR project
project:
drwxr-xr-x 3 user user 4096 2012-06-02 03:51 examples
-rw-r--r-- 1 user user   49 2012-06-02 03:51 index.js

project/examples:
drwxr-xr-x 2 user user 4096 2012-06-02 03:50 node_modules
-rw-r--r-- 1 user user   20 2012-06-02 03:51 test.js

project/examples/node_modules:
lrwxrwxrwx 1 user user 6 2012-06-02 03:50 project -> ../../

The contents of index.js assigns a value to a property of the exports object and invokes console.log with a message that states it was required. The contents of test.js is require('project').

Some time ago I created module for loading modules relative to pre-defined paths.

https://github.com/raaymax/irequire

You can use it instead of require.

irequire.prefix('controllers',join.path(__dirname,'app/master'));
var adminUsersCtrl = irequire("controllers:admin/users");
var net = irequire('net');

Maybe it will be usefull for someone..

I don't think you need to solve this in the manner you described. Just sed if you want to change the same string in a large amount of files. In your example,

find . -name "*.js" -exec sed -i 's/\.\.\/\.\.\//\.\.\//g' {} +

would have ../../ changed to ../

Alternatively, you can require a configuration file that stores a variable containing the path to the library. If you store the following as config.js in the example directory

var config = {};
config.path = '../../';

and in your example file

myConfiguration = require('./config');
express = require(config.path);

You'll be able to control the configuration for every example from one file.

It's really just personal preference.

We are about to try a new way to tackle this problem.

Taking examples from other known projects like spring and guice, we will define a "context" object which will contain all the "require" statement.

This object will then be passed to all other modules for use.

For example

var context = {}

context.module1 = require("./module1")( { "context" : context } )
context.module2 = require("./module2")( { "context" : context } )

This requires us to write each module as a function that receives opts, which looks to us as a best practice anyway..

module.exports = function(context){ ... }

and then you will refer to the context instead of requiring stuff.

var module1Ref = context.moduel1;

If you want to, you can easily write a loop to do the require statements

var context = {};
var beans = {"module1" : "./module1","module2" : "./module2" }; 
for ( var i in beans ){
    if ( beans.hasOwnProperty(i)){
         context[i] = require(beans[i])(context);
    }
};

This should make life easier when you want to mock (tests) and also solves your problem along the way while making your code reusable as a package.

You can also reuse the context initialization code by separating the beans declaration from it. for example, your main.js file could look like so

var beans = { ... }; // like before
var context = require("context")(beans); // this example assumes context is a node_module since it is reused.. 

This method also applies to external libraries, no need to hard code their names every time we require them - however it will require a special treatment as their exports are not functions that expect context..

Later on we can also define beans as functions - which will allow us to require different modules according to the environment - but that it out of this thread's scope.