This is a passion project I was theorycrafting and implementing for the last two years.

https://wraplet.dev

https://github.com/wraplet/wraplet

The goal was to make a low-footprint framework that would:

1. Take full advantage of OOP with declarative dependency structures, where objects' implementations can be freely switched out.
2. Take full advantage of TypeScript, which infers types based on these structures.
3. Could work with **any** DOM structure (elements, classes, attributes, etc.: you should be able to bind your behaviors to anything that is out there).
4. Removes the hassle of lifecycle management.

I wanted to have the flexibility of writing vanilla JS but in an environment of the best programming patterns that would prevent the code from becoming a mess over the long term.

This is not an alternative for React but rather for jQuery. According to w3techs market share of jQuery is still significant: https://w3techs.com/technologies/details/js-jquery

Wraplet allows for a gradual migration to a much more maintainable structure, but it also works for new projects that render HTML server-side (I think Wraplet fits popular CMSes especially well).

I think there was an uncovered middle ground between imperative jQuery code and full SPA solutions. This is what Wraplet covers.

The docs have many interactive examples.

Actually, I made a separate library: `exhibitionjs` just to showcase `wraplet`.

If you also develop online docs and don't like dependency on external sandbox providers, you can look it up at: https://exhibitionjs.wraplet.dev/ Of course, it's wraplet-powered.

Ok, that was me; now it's time for an AI slop, because it's actually pretty decent at readable descriptions, or at least better than me.

AI SLOP STARTS

Introduction

wraplet is a small JavaScript/TypeScript framework for projects that still work directly with the actual DOM (server-rendered apps, jQuery legacy, multipage sites, plain HTML, libraries shipping DOM components, etc.).

Instead of replacing the DOM with a virtual rendering layer, wraplet lets you bind class instances ("wraplets") to real DOM nodes and gives you:

• a predictable lifecycle (construct -> initialize -> destroy),
• a typed, declarative dependency system between components (required/optional, single/multiple),
• automatic event listener cleanup via NodeManager,
• automatic wraplet creation/destruction when DOM nodes appear/disappear (NodeTreeManager),
• components that are trivial to unit test - each wraplet is just a class around a node.

Pros:

• Plays well with backend-rendered HTML. No "the framework owns the page" mindset.
• TypeScript-first. Types describe component structure, not just APIs.
• Tests are boring (in a good way). A wraplet is a class with a node. new MyWraplet(element), call methods, assert. No JSDOM-heavy framework setup.
• Encapsulation by default. Parents talk to children through methods like setError("..."), not by reaching into their internal nodes.
• Gradual adoption. You can migrate a single jQuery-based widget without touching the rest of the app.

Where it's a good fit:

• progressive modernization of legacy jQuery / server-rendered UIs (PHP, Rails, Django, Laravel, etc.),
• libraries that ship reusable DOM-bound components,
• projects where a full SPA would be overkill,
• teams that prefer classes, encapsulation, and explicit relationships.

Where it's not a good fit:

Apps already happily built on React/Vue/Svelte - wraplet is not competing with them; it's solving a different problem.

TypeScript as a first class citizen

Most "DOM-binding" libraries treat TypeScript as a coat of paint on top of a runtime API. Wraplet tries to use TypeScript as the actual architecture layer - the place where you express what a component is, what it depends on, and what shape those dependencies have. The runtime then derives behavior from that.

The component is a generic class parameterized by the wrapped DOM node

In the simplest case, the type describes what type of node is wrapped by the wraplet:

import { AbstractWraplet } from "wraplet";

class Button extends AbstractWraplet<HTMLButtonElement> {
  protected async onInitialize() {
    // `this.node` is HTMLButtonElement, not Element, not unknown.
    this.node.disabled = false;

    this.nodeManager.addListener("click", (e) => {
      // `e` is properly typed as MouseEvent.
    });
  }
}

But the real fun begins when we introduce dependencies with the `DependentWraplet`.

The dependency map is the type

A wraplet that has children declares them through a plain object that is also a literal type:

import {
  AbstractDependentWraplet,
  type WrapletDependencyMap,
  type DependencyManager,
} from "wraplet";

const map = {
  submit: {
    selector: "[data-js-form__submit]",
    Class: SubmitButton,
    required: true,
    multiple: false,
  },
  fields: {
    selector: "[data-js-form__field]",
    Class: Field,
    required: true,
    multiple: true,
  },
  errorBox: {
    selector: "[data-js-form__error]",
    Class: ErrorBox,
    required: false,
    multiple: false,
  },
} satisfies WrapletDependencyMap;

class Form extends AbstractDependentWraplet<HTMLFormElement, typeof map> {
  protected async onInitialize() {
    this.d.submit;    // SubmitButton          (required + single)
    this.d.fields;    // WrapletSet<Field>     (required + multiple)
    this.d.errorBox;  // ErrorBox | null       (optional + single)
  }
}

A few things worth highlighting from a TS perspective:

• satisfies WrapletDependencyMap keeps the literal types (concrete Class references, concrete required/multiple booleans) while still validating the object against the framework's contract.
• typeof map is then passed as a generic parameter to AbstractDependentWraplet, so the framework can compute the type of this.d per-key:
  • required: true, multiple: false - T
  • required: false, multiple: false - T | null
  • required: true, multiple: true - WrapletSet<T>
  • required: false, multiple: true - WrapletSet<T> (possibly empty)
• Renaming a key in the map updates the type of this.d.<key> everywhere. Renaming a child wraplet class propagates through the parent's type. "Find usages" actually finds usages.

The dependency map effectively becomes a typed schema of your component tree. The runtime DependencyManager queries the DOM, instantiates the right classes, and hands them back to you typed exactly as the map describes.

Async lifecycle with typed extension points

onInitialize and onDestroy are well-defined hooks; listeners and child wraplets are tied to that lifecycle, so cleanup is automatic. Lifecycle listeners on dependencies are also typed to the dependency they are attached to:

dm.addDependencyInitializedListener("fields", async (field) => {
  // `field` is `Field`, inferred from the map key "fields".
});

Custom injectors - typed too

If for some reason a child shouldn't receive its own DOM node directly (e.g. you want to wrap it in something), you can declare a custom injector on a dependency. The injector's callback is typed against the wraplet's expected constructor input, so a mismatch is a compile error rather than a runtime surprise.

What this enables practically

• Refactoring with confidence: changing the structure of a component (adding/removing a child, switching from single to multiple, making something optional) is a typed change. The compiler walks you through the consequences.
• Encapsulation by types, not by convention: parents only see the public methods of their children. There's no implicit "reach into the inner DOM of my child" ? you'd have to add a public method on the child wraplet, which is exactly what you want.
• Tests are just new MyWraplet(node): no framework runtime to boot, no JSX renderer, no JSDOM gymnastics beyond having a node. Types make sure the test is constructing the component correctly.

AI SLOP ENDS

Writing this framework (and docs with examples) was a bumpy road, but I hope it will be useful for some of you. If you are still reading this, thanks for sticking with me. 😄