Toplevel is a simple node module that wraps node's built-in
require() function and lets you require your code relative to your top level directory rather than relative to the current file.
From node modules:
A module prefixed with '/' is an absolute path to the file. For example, require('/home/marco/foo.js') will load the file at /home/marco/foo.js.
A module prefixed with './' is relative to the file calling require(). That is, circle.js must be in the same directory as foo.js for require('./circle') to find it.
Without a leading '/' or './' to indicate a file, the module is either a "core module" or is loaded from a node_modules folder."
Toplevel hopes to make it easier to require files by reducing the amount you need to know about the project structure.
How it works
The Toplevel module exports a function that takes a single parameter. The parameter is the path that Toplevel will start with to search for the Top file. It starts by looking in the directory for the given path and continues searching up the directory tree until either a Top file is found or there are no more directories. An
Error is thrown if a Top file is never found.
$ pwd /path/to/toplevel $ touch Top $ tree -I node_modules . . ├── lib │ └── example.js ├── test │ └── example_test.js └── Top
Now, any code in subdirectories like lib or test can use Toplevel to require modules relative to the Top file. Toplevel turns paths like
var example = require('../lib/example'); ...
var requireFromTop = require('toplevel')(__dirname) , example = requireFromTop('lib/example'); ...
In the example above, Toplevel will first search /path/to/toplevel/test then /path/to/toplevel where it finds the Top file.
The call to
requireFromTop('lib/example') turns into
Installing and Using Toplevel
$ npm install toplevel
Create an empty Top file in the top level directory of your code.
$ touch Top
Which Top file is being used?
When using Toplevel you'll often want to know which Top file is being used by Toplevel. Toplevel comes with a utility script called
which-top that simply runs the Toplevel search function and tells you which Top level directory it finds.
which-top takes a path as an optional argument. If the path argument isn't supplied it will use the current working directory.
Note: to use the unqualified
which-top as we do below, you will need to install Toplevel globally.
$ which-top /path/to/toplevel/subdir /path/to/toplevel $ cd /path/to/toplevel/subdir $ which-top /path/to/toplevel