Modular

A simple and lightweight module system for JavaScript.

Fast Track ⏱️

Discover the library in less than 5 minutes.

Install Node.js and install SplitText using your favorite package manager.

npm install @gregoire.ciles/modular

yarn add @gregoire.ciles/modular

pnpm add @gregoire.ciles/modular

Then, open your favorite code editor and create new files index.html and index.ts.

<header data-module="header"></header>

import { Modular, Module } from '@gregoire.ciles/modular';

class Header extends Module<HTMLElement> {
  init(): void {
    console.log(this);
  }
}

const modular = new Modular({
  modules: {
    header: Header,
  },
});

modular.init();

Finally, open index.html in your browser and open the console to see the result.

TypeScript Support

Modular is written in TypeScript and provides type definitions.

Note: TypeScript is not required to use Modular.

💡 TIP: Type annotations are very useful and help your IDE understand the type provided by Modular.
The IDEs (VSCode, WebStorm, etc.) will be able to provide you with autocompletion and type hints.

API

Modular

constructor(options: ModularOptions)

Creates a Modular instance and registers provided modules.

options

Name	Type	Default	Description
modules	Record<string, ModuleConstructor>	{}	A map of modules.

init()

Initializes all registered modules.
Calls the init and bind methods on each modules instance.

destroy()

Destroys all initialized modules.
Calls the destroy method on each module instance.

has(moduleName: string): boolean

Find if the collection has a module registered with the given name.

moduleName

The name of the module.
This is the value of the data-module attribute.
For example, if you have <div data-module="header"></div>, the module name is header.

Module

constructor(element: HTMLElement)

Create a new instance of Module.

ID

Unique identifier for the module instance.
This is the value of the data-module-id attribute.

name

Name of the module, used for referencing and querying.

element

The DOM element associated with the module.
This is the element with the data-module attribute.

init()

Initializes the module.
This method is called by Modular.

destroy()

Cleans up and destroys the module.
This method is called by Modular.

bind()

Bind all methods to the module instance.
Automatically called by the Modular class before the init method.

import { Module } from '@gregoire.ciles/modular';

class Header extends Module {
  init(): void {
    this.element.addEventListener('click', this.handleClick);
  }

  bind(): void {
    this.handleClick = this.handleClick.bind(this);
  }

  handleClick(): void {
    console.log(this);
  }
}

call(moduleName: string, methodName: string, ...args: any[]): void

Calls a method on all instances of a specified module by its name.

<div>
  <button data-module="one">One</button>
  <button data-module="two">Two</button>
</div>

import { Modular, Module } from '@gregoire.ciles/modular';

class One extends Module<HTMLButtonElement> {
  init(): void {
    this.element.addEventListener('click', this.handleClick.bind(this));
  }

  handleClick(): void {
    this.call('two', 'method');
  }
}

class Two extends Module<HTMLButtonElement> {
  method(): void {
    console.log(this.name, 'method');
  }
}

const modular = new Modular({
  modules: {
    one: One,
    two: Two,
  },
});

modular.init();

callById(id: number, methodName: string, ...args: any[]): void

Calls a method on a module instance identified by its ID.
The ID is generated by the compiler and is unique for each module instance.
This method is useful when you want to call a method of a specific instance of a module.
This is the element with the data-module-id attribute.
For example, if you have two instances of the same module on the same page, you can call a method of a specific instance.

<div data-module="header" data-module-id="1"></div>
<div data-module="header" data-module-id="2"></div>

import { Module } from '@gregoire.ciles/modular';

class Header extends Module<HTMLDivElement> {
  init(): void {
    this.callById(1, 'method');
  }

  method(): void {
    console.log('method');
  }
}

q<TReturnValue extends HTMLElement | HTMLElement[]>(selectors?: string, context?: HTMLElement): TReturnValue | null

Queries the DOM for elements matching a specific selector within the module's context.

<div data-module="header">
  <div class="logo" data-header="logo"></div>
</div>

import { Module } from '@gregoire.ciles/modular';

class Header extends Module<HTMLDivElement> {
  init(): void {
    const logo = this.q<HTMLElement>('logo');
  }
}

You can also add native selectors like ., #, etc.

<div data-module="header">
  <button class="profile" data-header="button"></button>
  <button class="logout" data-header="button"></button>
</div>

import { Module } from '@gregoire.ciles/modular';

class Header extends Module<HTMLDivElement> {
  init(): void {
    const profileButton = this.q<HTMLButtonElement>('button.profile');
  }
}

parent<T extends HTMLElement>(query: string, target: T): T | undefined

Finds the first parent element of a specified target that matches a given query.

<div data-module="header">
  <div data-header="wrapper">
    <button data-header="item">Item</button>
  </div>
</div>

import { Module } from '@gregoire.ciles/modular';

class Header extends Module<HTMLDivElement> {
  init(): void {
    const item = this.q<HTMLButtonElement>('item');
    const parentItem = this.parent('wrapper', item);
  }
}

getData<T extends HTMLElement>(qualifiedName: string, target?: T): string | null

Retrieves the value of a data attribute from the specified element.

<div data-module="header" data-is-open="false"></div>

import { Module } from '@gregoire.ciles/modular';

class Header extends Module<HTMLDivElement> {
  init(): void {
    console.log(this.getData('is-open')); // false
  }
}

setData<T extends HTMLElement>(qualifiedName: string, value: string, target?: T): void

Sets the value of a data attribute on the specified element.

<div data-module="header" data-is-open="false"></div>

import { Module } from '@gregoire.ciles/modular';

class Header extends Module<HTMLDivElement> {
  init(): void {
    this.setData('is-open', 'true');
    console.log(this.getData('is-open')); // true
  }
}

Credits

© Grégoire Ciles