README.md

basetag ⚾️

basetag lets you use local modules relative to your Node.js project base path

Usage · Docs · Why? · How? · License

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 requires and imports to the basetag way:

# require('../../baseball') => require('$/baseball')
npx basetag rebase

---

⚠️ Unfortunately, npm does not like basetag very much

npm will remove the $ on every npm 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 every npm install ...
• rebase - upgrades requires and imports to use the package-relative $/
• TODO debase - downgrades requires and imports 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.

License ⚖️

MIT