JSPM

Smart way to manage ids for forntend javascript and typescript projects.

Table of contents

• Table of contents
• Introduction
• Features
• Get Started
  • How to install
  • Create Input File
  • Generate
  • Implementation
• Command-line
• Use Cases
  • With Astro component
• Contributing
• License

Introduction

ElementID is an ID management tool for your frontend Nodejs (javascript or typescript) projects. You can share id values between different modules using ElementID without any conflict. ElementID is a dev dependency. It provides unique or custom values to your production build according to the input IDs. ElementID has a caching system that helps to make id values static.

Features

• ⚔️ No IDs conflict anymore
• 🎉 Zero dependencies in production
• 📈 Increase your productivity
• 💪 Generate unique IDs with powerful the nanoid generator
• 👀 Auto generate with watch mode
• 💽 Static unique values using caching
• 💻 Powerful CLI tool
• 📜 Simple input configuration with .toml

Get Started

How to install

We recommend installing ElementID as a dev dependency

npm i -D elementid

Create Input File

First, you declare your project IDs in .toml format. The ElementID can generates two types of id values.

• Unique values - If you want a unique value for your declared id, you should assign an empty string ("") for it.

yellowBtnId = ""
redBtnId = ""

• Custom values - If you want a custom value for your declared id, you should assign your custom value for it.

greenBtnId = "my_custom_value_1"
blueBtnId = "my_custom_value_2"

we recommend the Even Better TOML extension for VS Code users to create the .toml file

Generate

The ElementID has a powerful CLI tool for generating IDs according to your input. If your input file path is ./my_ids.toml, you can use the following command to generate IDs.

elementid ./my_ids.toml

Please read the command line section for more CLI options.

Implementation

The ElementID generates a javascript(.js) and a type declaration(.d.ts) files in node_modeules/elementid/dist/ directory. you can use them as followings.

// ES6 syntax
import { yellowBtnId, redBtnId, greenBtnId } from "elementid";

const yellowBtn = document.getElementById(yellowBtnId);
const redBtn = document.querySelector(`#${greenBtnId}`);

// CommonJS syntax
const ids = require("elementid");

const yellowBtn = document.getElementById(ids.blueBtnId);
const redBtn = document.querySelector(`#${ids.redBtnId}`);

Command-line

Usage: elementid <input file> [options]

Options:
  -w, --watch       Watch changes of input file                            [boolean]
  -f, --force       Generate unique ids without cacheing                   [boolean]
  -l, --length      Length of the unique id values
                    (default = 8, options = 5, 6, 7, 8, 9, 10)              [number]
  --version         Show version number                                    [boolean]
  -h, --help        Show help                                              [boolean]

Examples:
  elementid ids.js                      with the input file
  elementid ids.js --length=7           with the input file and length option
  elementid src/my_ids.js --watch       with the input file and watch option

Use Cases

With Astro component

Astro is a static site generator. Astro has it has own component to build a static site. Astro component has four sections to generate HTML, CSS, and Javascript. Read more about astro components.

• HTML content helper
• HTML content
• Scripts
• Styles

If you want to make a dynamic web page with Astro, you need to get access to the DOM elements. getElementById() is a popular method to get access to the DOM elements from javascript. But in Astro, you can not share the same id between HTML content and Script sections.

You can hardcode ID values in HTML content and Script sections. But it is not a good idea because these values can be spelling errors, and can conflict with each other.

The ElementID helps you to solve this problem. You can access the same id values with ElementID in the HTML content helper section and Script sections. Check out the following example for how to use ElementID in Astro.

---
import { myBtnId } from "elementid";
---

<div>
    <button id={myBtnId}>Click ME!</button>
</div>

<script>
    import { myBtnId } from "elementid";

    myBtn = document.getElementById(myBtnId);
    myBtn.addeventlistener("click",()=>{
        console.log("click my button");
    });
</script>

Contributing

If you want to open a issue, create a Pull Request or simply want to know how you can run it on your local machine, please read the Contributing guide.

License

ElementID is MIT licensed.