Skip to content

Commit

Permalink
Add readme navigation (#9)
Browse files Browse the repository at this point in the history
* Refine readme

* Update header

* Update header

* Update wording

* Add actions to ignore file

* Bump version
  • Loading branch information
janniks committed Apr 21, 2020
1 parent ccfa22f commit c00a524
Show file tree
Hide file tree
Showing 3 changed files with 52 additions and 18 deletions.
3 changes: 2 additions & 1 deletion .npmignore
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
test/
.github
test

# Created by https://www.gitignore.io/api/node,macos
# Edit at https://www.gitignore.io/?templates=node,macos
Expand Down
65 changes: 49 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,58 @@
# ⚾️ basetag
`basetag` lets you require local modules relative to your NodeJS applications base path.
<h1 align="center" style="font-weight: bold !important">basetag ⚾️</h1>

<p align="center">
<strong>basetag</strong> lets you require local modules relative to your Node.js project base path
</p>

<p align="center">
<a href="https://github.com/janniks/basetag/actions">
<img src="https://github.com/janniks/basetag/workflows/build/badge.svg" alt="Build status" />
</a>
<a href="https://www.npmjs.org/package/basetag">
<img src="https://img.shields.io/npm/v/basetag.svg" alt="Package version" />
</a>
<a href="https://npmcharts.com/compare/basetag?minimal=true">
<img src="https://img.shields.io/npm/dm/basetag.svg" alt="Downloads per month" />
</a>
<a href="https://npmcharts.com/compare/basetag?minimal=true">
<img src="https://img.shields.io/npm/dt/basetag.svg" alt="Total downloads" />
</a>
<a href="https://github.com/janniks/basetag/blob/master/LICENSE">
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" />
</a>
<a href="https://twitter.com/intent/follow?screen_name=jnnksbrt">
<img src="https://img.shields.io/twitter/follow/jnnksbrt.svg?label=Follow%20@jnnksbrt" alt="Follow @jnnksbrt on Twitter" />
</a>
</p>

<h3 align="center">
<a href="#installation-">Installation</a>
<span> · </span>
<a href="#why-%EF%B8%8F">Why?</a>
<span> · </span>
<a href="#how-">How?</a>
<span> · </span>
<a href="#license-%EF%B8%8F">License</a>
</h3>

## Installation 🛠

`npm i -S basetag`

☝️ and that's it!
You can use `basetag`.
No need to `require('basetag')` anywhere.
You can now use the `$` basetag prefix.
No need to require basetag itself anywhere.

## Why? ⚡️

**What does `basetag` solve?**

In NodeJS applications we sometimes want to import local modules that are in different far away subdirectories.
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.
`basetag` allows you to import modules using `$/` as the applications base path.
If you're not convincedcheck out the example below...
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:_
🤯 _The modern **basetag** way:_

```js
const balls = require('$/baseball/balls') //
Expand All @@ -35,11 +69,10 @@ const balls = require('../../../../baseball/balls') // ❌
### 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/`](test/example/) for a real-life example.

Look at the code in [`test/example/`](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. `../../..`).
Using basetag you can reference modules from the base `example/` path, rather than using relative directories (i.e. `../../..`).

```
example/
Expand All @@ -59,12 +92,12 @@ example/
### How does `basetag` work?

It's rather simple.
After installing `basetag` as a dependency a `postinstall` script creates a symlink that points from `node_modules/$` to your projects base directory.
Everytime you use a `require` with `$/…` NodeJS will look inside the `$` package (i.e. our new symlink).
The lookup is routed natively to your projects files.
After installing basetag as a dependency a `postinstall` script creates a symlink 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 NodeJS, 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 NodeJS will cache imports correctly.
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.

## License ⚖️

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "basetag",
"version": "0.2.0",
"version": "1.0.0",
"description": "A better way to import NodeJS modules",
"main": "postinstall.js",
"scripts": {
Expand Down

0 comments on commit c00a524

Please sign in to comment.