tzer

TZer - Web Components Micro Framework

************************** WIP **************************

Purpose

WC is not the most dev-friendly API, but still I ran into cases I need a custom WC without using a framework.

How It Works

TZer rely on decorators declaration to compile the component into a JS CustomElement Class and then bundle all using esbuild.

Features

• 100% native vanilla js code - no libraries!
• Manging attribute easily - with observed attributes.
• Event binding.
• Supporting all WC lifecycles - added multiple callbacks.
• SCSS/SASS.
• Minifying & Optimizing.
• No Shadow Dom - partially encapsulated.
• Supporting imports - from utils folder - WIP
• Seed project generator from cli.

Install

npm i -g tzer
npx tzer init newProject
cd newProject
npm i
npm run dev

Compiling

Run npx tzer compile.

Importing

Import like any other js file.

Config

// tzer.config.ts

import { ExampleComponent } from "./example/component";

export default {
  components: [ExampleComponent]
}

CLI

• tzer init PROJECT_NAME - create a new TZer project.
• tzer generate COMPONENT_NAME - create a new component.

Project NPM Commands

• dev run a dev server, watch & environment
• build build final output
• tzer:build:debug build debuggable output before bundling and renaming
• tzer:build:dev build debuggable output after bundling and renaming

Decorators

@TzerComponent({componentElementTag: string, style: string, domHelpers?: boolean})

Main declaration of a component.

@TzerAttribute({observed?: boolean})

Create an element attribute, with getter and setter.

Attribute can set to observed to invoke the attributeChangedCallback(optional).

@TzerAttributeChangedCallback(attribute?: string)

Trigger whenever an observed attribute has changed.

attribute(optional) the callback will run only for that attribute change, otherwise for all changes.

@TzerConnectedCallback()

Trigger whenever the component has mounted in the document.

@TzerDisconnectedCallback()

Trigger whenever the component has dismounted from the document.

@TzerAdoptedCallback()

Trigger whenever the component has moved to a new document.

@TzerEventBind(eventName: string)

Binds a method to a custom event.

Example Component

// component.ts

import {
  TzerAdoptedCallback,
  TzerAttribute,
  TzerAttributeChangedCallback,
  TzerComponent,
  TzerConnectedCallback,
  TzerDisconnectedCallback, TzerEventBind
} from "tzer";

@TzerComponent({ 
  componentElementTag: 'tzer-example-component',
  style: './src/example/example.scss'
})
export class Example {
  declare container: HTMLElement;
  declare DOM: TzerDOM;

  @TzerAttribute({ observed: true })
  testattr: string | undefined;

  @TzerConnectedCallback()
  connected() {
    console.log('connected!');
  }

  @TzerDisconnectedCallback()
  disconnected() {
    console.log('disconnected!');
  }

  @TzerAdoptedCallback()
  adopted() {
    console.log('adopted!');
  }

  @TzerEventBind('click')
  eventListener() {
    console.log('clicked!');
  }

  @TzerConnectedCallback()
  @TzerAttributeChangedCallback()
  render() {
    this.container.innerHTML = `<p>Hello ${this.testattr}!</p>`;
  }
}