Perlite

hyperactiv 🌋 + lit-html ☄️ + extensions 🌊 = perlite 💎.

Perlite is a simple and declarative way to create rich client-side widgets designed with server-side apps in mind. Completely based on native/vanilla Javascript standards and doesn't require additional build steps or compilation. Plays well with server-side rendered apps and micro-frontends. For more details read the description.

🚩 Table of contents

• Description & Features.
• Installation
  • NPM
  • CDN
  • Distribution
• Examples
  • TodoMVC
  • Simple Shop
  • 7GUIs
• Basic usage
  • Widget declaration
  • Widget creation
  • Widget multiple instantiation
  • Widget container
  • Widget state
    • Reactivity
    • Actions
  • Widget template
    • Template syntax
    • Text bindings
    • Using expressions
    • Attribute bindings
    • Event listeners
    • Template fragments
    • Control flow
      • Conditions
      • Looping
    • Rendering
  • Widget lifecycle events
  • Widget API
    • $widget.target: HTMLElement | Node;
    • $widget.state: ProxyConstructor;
    • $widget.model: object;
    • $widget.effect(fn: () => void, opts?: object): () => void;
    • $widget.on(type: string, fn: (e: CustomEvent) => void, opts?: object | boolean): () => void;
    • $widget.render(): void;
    • $widget.destroy(): void;
    • $widget.ctx(fn: (...ctx: any[]) => any): any;
  • Widget container API
    • $$widgets[index: number]: Widget;
    • $$widgets.target: NodeList | Node[];
    • $$widgets.state(fn: (state: ProxyConstructor) => void): void;
    • $$widgets.effect(fn: (state: ProxyConstructor) => () => void, opts?: object): (() => void)[];
    • $$widgets.on(type: string, fn: (e: CustomEvent) => void, opts?: object | boolean): (() => void)[];
    • $$widgets.render(): void;
    • $$widgets.destroy(): void;
    • $$widgets.ctx(fn: (...ctx: any[]) => any): any;
    • $$widgets.forEach(fn: (widget: Widget, index: number, widgets: Widget[]) => void): any;
• Advanced usage
  • Setting the initial widget state during SSR
  • Directives
    • Lit-html directives
    • Lists & keys
    • Event listener modifiers
    • Refs & decorators
  • Custom directive
  • Widget context
  • Widget nesting
  • Shared state
  • Styling
  • Transitions
  • Utilities
• Structuring your project
• Tooling
• Typescript support
• Browsers support
• License

💡 Description & Features

Unlike the other frontend frameworks, eg. React, Vue, Angular or Svelte, which are mostly created for building SPA/RIA applications, Perlite's main goal is to make the life of developers of classical server-side applications a little bit easier and the modern front-end development techniques more accessible. Without extra knowledge of building tools and other dark sides of the frontend ecosystem . 👾

Perlite gives you a combination of the best ideas from the most popular SPA frameworks, like UI is a function of a state (React), reactive state driven development (Vue), observables (Angular) and lack of Virtual DOM (Svelte).

Perlite focuses on building standalone UI widgets placed across different parts of the server-generated page and provides handy tools to manage these widgets and interact between them.

Built on top lit-html - an efficient, expressive, extensible HTML templating library and hyperactiv - a super tiny reactive library. This means that your widgets will have a reactive state with direct object mutations, super-fast DOM updates, and low memory consumption.

The full bundle size of Perlite library is just 8.8Kb (min+gz). In addition, it's optimized for tree-shaking, so you can reduce the final size if not all features are used. At the same time, Perlite is full-featured enough to fulfill its purposes and no additional tools you needed in most of the cases.

📦 Installation

NPM

npm i --save perlite

or

yarn add perlite

and use it

import { html } from 'perlite';

CDN

If you are not using NPM, in modern browsers, you can import bundled ES module from CDN:

import { html } from 'https://unpkg.com/perlite@latest/dist/perlite.min.mjs';

or

just add a regular script-tag to your html for legacy browsers:

<script src="https://unpkg.com/perlite@latest/dist/perlite.min.js"></script>

and use it via global namespace:

const { html } = window.perlite;

CDNs: UNPKG | jsDelivr.

Distribution

• dist/index.js - UMD output
• dist/index.mjs - ESM output
• dist/index.min.js - UMD output (minified)
• dist/index.min.mjs - ESM output (minified)
• dist/perlite.js - IIFE bundle
• dist/perlite.mjs - ESM bundle
• dist/perlite.min.js - IIFE bundle (minified)
• dist/perlite.min.mjs - ESM bundle (minified)

🕹 Examples

TodoMVC

TodoMVC

• single widget app;
• multiple fragments;
• store with actions for todos list with side-effect to the sessionStorage;
• based on ES dev server and NPM.

Simple Shop

Simple shop

• server-generated page (actually a static file);
• multiple client-side widget