Root directory in package.json
Javascriptnode.jsNpmpackage.jsonJavascript Problem Overview
My question concerns an existing library that I wish to publish as an NPM module. The library is already in use, and currently require
d 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?
Javascript Solutions
Solution 1 - Javascript
UPDATE 2020
The issue suggesting mainDir is now closed. Instead there is a new field called exports
which can be used almost like es import maps to map a folder to an export alias:
// ./node_modules/es-module-package/package.json
{
"exports": {
"./my/": "./src/js/lib/my/"
}
}
import thing from 'es-module-package/my/thing.js';
// Loads ./node_modules/es-module-package/src/js/lib/my/thing.js
As suggested in the issue linked in the original answer below it may be possible to map the root to a folder to access import thing from pkg/thing.js
as so:
{
"type": "module",
"main": "./dist/index.js",
"exports": {
"./": "./src/js/lib/my/"
}
}
Original Answer
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
Solution 2 - Javascript
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;
Solution 3 - Javascript
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
Solution 4 - Javascript
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.
Solution 5 - Javascript
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.
Solution 6 - Javascript
Simply publish /install /link the folder intended to be the root
The natural way to achieve that, according to the npm approach, is to publish the folder which is to be the root. There are several ways to do that, depends on the final environment you want to work with:
- npm publish <folder> from your package repo to an npm registry and then install your package in other project as you install other packages. In your case it would be
npm publish src/js/lib/my
. - npm install <folder> in some other project if you want to use your package only locally. In your case you go to the other project and run
npm install relative/path/to/src/js/lib/my
- npm link your folder locally to
node_modules
in other project in case you'd like to have the changes in your original package reflected instantly in other project. In your case you firstcd src/js/lib/my
and runnpm link
and then go to the other project and runnpm link my
.
Prerequisite: in any case above, prior to the publish/install/link, you have to put in your my
folder at least a proper package.json
file. In your case, you have to have the package name defined in the package.json file as "name": "my"
. Typically you'll want there also some other files like README.md or LICENSE.
Remarks to methods 2 & 3
Typically there are problems with package dependencies when you use the package installed this way. To avoid it, first pack the package with npm pack dist
and then install the package in the target project from the packed tarball, i.e. npm install path/to/package-tarball.tgz
.
Automation example
You can automate the publishing process using the prepare
script, combined with build
script and "private": true
field put in the package.json located in the root directory of your package repo. Here is an example with the dist
folder as a package root:
"private": true,
"scripts": {
"build": "rm -rf dist && webpack --mode=production && cat ./package.json | grep -v '\"private\":' > dist/package.json",
"prepare": "npm run build"
},
This way you won't publish the root folder ("private": true
). And when you hit npm publish dist
the automatically invoked prepare
script will trigger dist folder cleanup (rm -rf dist
), package build (webpack --mode=production
) and copy of the package.jsonto the dist folder without the field "private": true (cat ./package.json | grep -v private > dist/package.json
).
Solution 7 - Javascript
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'
}
}