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_:

``js
const balls = require('../../../../baseball/balls'); // ❌
`

🤯 Into _this_:

`js
const balls = require('$/baseball/balls'); // ✅
`

Usage 🛠

Install as a dev dependency:

`bash
npm install --save-dev basetag
`

Create a $ symlink in your local node_modules by running:

`bash
npx basetag link --hook
`

Upgrade existing requires and imports to the basetag way:

`bash


require('../../baseball') => require('$/baseball')


npx basetag rebase
`

---

> ⚠️ Unfortunately, npm does not like basetag very much
>
> npm will remove the $ on every npm install

_To fix this issue there are some solutions:_

$3

Use the postinstall script to run basetag after every npm install

package.json

`
"scripts": {
"postinstall": "npx basetag link"
}
`

$3

Use the --hook flag (which sets up an npm hook that runs basetag after every npm install

> 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

- 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:_

`js
const balls = require('$/baseball/balls'); // ✅
`

😓 _The traditional (often messy) way:_

`js
const balls = require('../../../../baseball/balls'); // ❌
`

How? 💭

$3

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
`

$3

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