Root directory in package.json

Question

My question concerns an existing library that I wish to publish as an NPM module. The library is already in use, and currently required via the local file system.

How can I specify the root directory of my module's files?

If I have a structure like:

.
├── package.json
├── src
|   ├── js
|   └────── lib
|   └───────── my
|   └───────────── thing.js
|   └───────────── that.js

How do I specify that the root of my module, and accessible files is src/js/lib/my/?

I would like to use as follows from an outside project:

var thing = require('my/thing'),
    that = require('my/that');

I saw the "files" property in package.json, is this the right way to go?

Answer 1

For a native solution, see this node issue https://github.com/nodejs/node/issues/14970

The feature request suggests a mainDir field in the package.json next to main.

The more people that vote, the faster/more likely it will be implemented

Answer 2

As the doc says:

The main field is a module ID that is the primary entry point to your program.

So you'll have something like "main": "src/js/lib/my/app.js" in your package.json file.

I would suggest you to create an app.js file and module.exports your different children. For example:

 module.exports.thing = require('./thing');
 module.exports.that = require('./that');

And use them like this:

var mylib = require('mylib')
  , thing = mylib.thing
  , that = mylib.that;

Answer 3

package.json is mainly a file used by npm to install and manage dependencies.

the require construct does not care a lot about package.json so you will not be able to use it to subvert the way require works and make it believe that packages are not where the require loading scheme expects them.

See the documentation on https://nodejs.org/api/modules.html and the loading scheme here: https://nodejs.org/api/modules.html#modules_all_together

you could maybe use the technique that the documentation calls 'Loading from the global folders' and define the NODE_PATH environment variable.

but I advise you to stick to a more standard way : - put your modules in a node_modules directory - or start your module hierarchy in the same directory where your app.js or index.js is located

Answer 4

Now this is ugly workaround and it does pollute the root of your package. But until Jordan's answer works, this feels like the way to achieve what you ask.

Just add a file in the root of your package for each of the modules you want to export using the require with slash notation. Such file will have the same name as the module being exported and it will simply reexport it.

.
├── package.json
├── thing.js       <--
├── that.js        <--
├── src
|   ├── js
|   └────── lib
|   └───────── my
|   └───────────── thing.js
|   └───────────── that.js

For example file ./thing.js will contain:

module.exports = require('./src/js/lib/my/thing');

And so you could require it as:

const thing = require('mypackage/thing');

---

Also as stated in the bug about adding mainDir property into package.json you can just temporarily copy your sources and the package.json file into one directory and publish from there.

Answer 5

Another possibility is to use ECMAScript modules (ES modules), particularly the package exports field in your package.json file.

Given a package.json file with this config:

{
  "name": "my",
  "exports": {
    "./": "./src/js/lib/my/"
  }
}

You should be able to import modules from the library like:

import thing from 'my/thing'
import that from 'my/that'

This is enabled by default since node 13.0.0, but was behind the --experimental-exports flag from 12.13.0.

Note, that the ES Module spec is in the Stability:1 - Experimental stage and subject to change. I have no idea the extent to which this might be compatible with CommonJS modules.

Answer 6

In webpack, you can specify resolve.alias like this:

{
  resolve: {
    alias: {
      'my': 'my/src'
    }
  }
}

or you can specify directions option in package.json

{
  directions: {
    'lib': 'src/lib'
  }
}