basetag
v2.1.0
Published
A better way to import NodeJS modules
Downloads
27,091
Maintainers
Readme
basetag
creates a $
symlink in your local node_modules
so that you can:
😓 Turn this:
const balls = require('../../../../baseball/balls'); // ❌
🤯 Into this:
const balls = require('$/baseball/balls'); // ✅
Usage 🛠
Install as a dev dependency:
npm install --save-dev basetag
Create a $
symlink in your local node_modules
by running:
npx basetag link --hook
Upgrade existing require
s and import
s to the basetag way:
# require('../../baseball') => require('$/baseball')
npx basetag rebase
⚠️ Unfortunately, npm does not like basetag very much
npm will remove the
$
on everynpm install <package>
To fix this issue there are some solutions:
Fix #1
Use the postinstall
script to run basetag after every npm install
package.json
"scripts": {
"postinstall": "npx basetag link"
}
Fix #2
Use the --hook
flag (which sets up an npm hook that runs basetag after every npm install <package>
You only have to do this once (unless you delete your
node_modules
folder). But, you can also use this in connection with Fix #1.
npx basetag link --hook
Docs 📚
basetag has a few commands that can be run via npx basetag <command>
link [--absolute] [--hook]
— creates a relative$
symlink--absolute
creates an absolute symlink rather than relative--hook
sets up basetag to run after everynpm install ...
rebase
- upgradesrequire
s andimport
s to use the package-relative$/
- TODO
debase
- downgradesrequire
s andimport
s to use file-relative../
s
Why? ⚡️
What does basetag
solve?
In Node.js applications we sometimes want to import local modules that are in different far away subdirectories.
This can lead to very messy looking require
statements.
Using basetag you can import modules with $/
as the project base path.
If you're not convinced, check out the example below...
🤯 The modern basetag way:
const balls = require('$/baseball/balls'); // ✅
😓 The traditional (often messy) way:
const balls = require('../../../../baseball/balls'); // ❌
How? 💭
How do I use basetag
?
It's really all described above and there's not much to it.
Look at the code in test/example/
for an executable example.
A larger project can have many nested subfolders as shown in the directory structure below.
Of course a real project would have more files in those subdirectories but for simplicity we'll leave those out.
Using basetag you can reference modules from the base example/
path, rather than using relative directories (i.e. ../../..
).
example/
├── its/
│ └── baseballs/
│ └── all/
│ └── the/
│ └── way/
│ └── down.js
├── somewhere/
│ └── deep/
│ └── and/
│ └── random.js
└── index.js
How does basetag
work?
It's rather simple.
By running basetag, a symlink is created that points from node_modules/$
to your project base path.
Everytime you use a require
with $/…
Node.js will look inside the $
package (i.e. our new symlink).
The lookup is routed natively to your project files.
To Node.js, both methods of requiring look the same, because the files are literally the same files. Both methods can be used in the same project and Node.js will cache imports correctly.
Compatibility
basetag
supports macOS, Linux, and Windows as of version 1.1.0
.