Fudgel

Write less. Do more.

A lightweight web component library that eliminates pain and boilerplate.

Learning new technologies, tooling, and techniques constantly is an annoyance. Staying on the bleeding edge of technology can be painful. Why keep learning new things? Can't new things look and feel like traditional JavaScript and HTML? Yes, it absolutely can. Fudgel lets you write an HTML template and associate it with a JavaScript class. You call methods from the HTML to do things in the class. Likewise, changes in the class are automatically reflected in the HTML. You don't have to manually redraw or worry about the magic; it just works.

When given a class as a controller, Fudgel will automatically parse the HTML template and set up bindings to your controller's properties. When they change, the HTML is also updated. Fudgel also handles events, passes data as attributes and properties, and fully supports TypeScript. All of this is done while allowing you, the developer, to maintain control; add additional directives, hook into the component's lifecycle, and even handle content projection using slots.

What do you get by using Fudgel?

• One-way data binding (controller to HTML)
• Mustache-like syntax for text and attributes
• Automatic updates when properties change, and only updating affected DOM nodes
• Property update detection and two-way attribute bindings
• Ability to add code during different lifecycle events
• Event handlers, tying events to your controller's methods
• Support for styles, either automatically scoped or within a shadow DOM
• Iterate over objects, arrays, maps, and other iterables
• Conditionally remove elements
• Child element references
• No build system or compilation needed; you can just use vanilla JavaScript
• Works with even the most restrictive Content-Security-Policy directives (JavaScript only, not inline styles).
• Includes support for slots in Shadow DOM, and our custom slot-like element for the Light DOM.
• Full TypeScript support
• Published as both UMD and a module
• Darn small, coming in at under 5k compressed for the Web Component; about 6k if you include everything else
• Fully tree-shakeable, reducing your bundle size when you don't use all of the features

In the above example, a new custom element is defined. Whenever you use the new HTML element <my‑custom‑element>, it will automatically insert "Hello Developer, welcome to Fudgel!" as text. Because of the timeout set up in onInit (a lifecycle method), in five seconds the text automatically changes to "Hello Super Developer, welcome to Fudgel!"

Web components make great additions to your browser-based UI because they basically work everywhere. Self-contained chunks of functionality that can eliminate lots of work on your side. Also, upgrading them or upgrading your existing framework is easier because their dependencies are built into the custom element. The downside is a bit of extra size from the wiring that has to take place, but Fudgel limits that to just the necessities.

Is this a framework? Perhaps, depending on your definition. This provides the structure and removes a lot of hassle when trying to wire up custom elements in order to make web components. It does this by providing many of the features you could see in other frameworks, while keeping the bundle size small. Fudgel adds around 6k (the complete bundle, minified and compressed) to your assets that need to be delivered. This is extraordinaly small when compared to some of the more popular frameworks like Angular or React.

Yes, those numbers are in bytes. As a comparison, your browser requested just this HTML, consuming about 740 bytes. The response headers and HTML were compressed and consumed about 5.2k. The entire framework is equivalent to loading just the HTML for this page! Put another way, this framework is about 1/2 the size of a font used on this site or 1/30 of the logo's download size. It's almost unfair to compare this miniscule framework to other frameworks.

Browser Support

96% of today's web traffic would work with this library. This includes Chrome (computer and Android), Edge, Safari (computer and iOS), Firefox, and others. There's no support for Internet Explorer, QQ Browser, UC Browser for Android, or other really obscure or severely outdated browsers. See the detailed browser features required and supported browser versions and global usage stats at CanIUse.com for the following feature lists: custom elements and CSS, language features. When you do, make sure to scroll to the "Summary" section and select "Intersection". The minimum browser version with full support of all of these features is Chrome 54, Edge 15, Safari 10.1, Firefox 63, Chrome for Android 120 (old versions aren't listed), Safari on iOS 10.3, Samsung Internet 6.2. There's no support for Internet Explorer nor UC Browser for Android, which sum to 1.3% of global traffic.

Goals and Prior Work

Fudgel was designed to make a JavaScript and HTML developer feel comfortable quickly. It does the heavy lifting via automatic bindings and updates while the developer focuses entirely on the interactions. The focus is to create self-contained web components using window.customElements, suitable for inclusion on any project, regardless of other frameworks being used.

This project has received the benefit of having others blaze trails in this area. There's ideas from many other projects as well.

• Slim.js provided the starting point that a lightweight library can contain lots of functionality, such as the automatic bindings and text parser.
• Angular has similar lifestyle hooks and structural directives.
• Alpine.js has event handlers using @ prefixes and modifiers.
• Vue.js is big into using slots for content projection, plus they also have event handlers with modifiers.
• Skruv is a small library that's similar to Slim.js, but it's not as feature-rich. It's the inspiration for the CSS scoping that Fudgel currently uses.

Best Practices

Do not register your custom element in your exported module. That does not allow other developers to resolve conflicts. If your custom element is named "heading-bar" and another library uses the same named element, the conflict is unable to be worked around. Instead, export a function that allows another developer to prefix your element and any other custom elements you require.

In general, you want your element to accept data into the controller using attributes (strings) and properties (any data). Attributes have universal support, where as most support properties. When you need to send data out of your controller, send an event.