bay.js

Bay.js is a frontend library designed to facilitate the creation of reusable web-components, as well as to add state and interactivity to HTML. To see it in action, you can visit bayjs.dunkerley.dev and explore its examples.

• Optional build step: Simply add a script tag to get started.
• Strict Content Security Policy (CSP) compatibility, even without a build step.
• Versatile rendering: Regular DOM or web-component formats.
• Zero dependencies for lightweight implementation.
• Single-file bundling capability for streamlined components.
• Seamless integration with frameworks designed for rendering web-components.
• URL-based templates: Enable server-side rendering (SSR) or PHP-based templates.
• Utilize <template> in the DOM as a template source.
• Component creation from JavaScript strings for dynamic customization.
• User-friendly syntax for effortless development.

The current source and regenerated local distributions store state as raw values and encode ordinary ${...} text/attribute output, including nested values. These changes have not been published. Existing applications need these migrations:

• Use ${$bay.html(trustedMarkup)} for intentionally trusted HTML. decode alone now produces text; the trust helper does not sanitize its input.
• Replace :click="this.pick('${this.name}')" with :click="this.pick(this.name)". Dynamic handler source is rejected.
• Use data attributes to carry loop values into static handlers. Attribute fragments from this-attribute require explicit trusted HTML.
• Stop pre-encoding state for normal output. URL values and executable HTML contexts have separate restrictions.

See the release and security migration notes for template migration, compatibility changes and remaining limitations. Website previews and bundled components have been migrated. Published CDN/npm releases remain unchanged until a release is published.

Bay.js can be used via a script tag or importing as a module.

<script src="//cdn.jsdelivr.net/npm/@dunks1980/bay.js/bay.min.js"></script>

Script tag example

<script type="module" src="main.js"></script>

// In main.js
import bay from '//cdn.jsdelivr.net/npm/@dunks1980/bay.js/bay.min.mjs';
bay();

You may want to add a version number like this to prevent breaking changes: '//cdn.jsdelivr.net/npm/@dunks1980/bay.js@< VERSION >/bay.min.mjs' the version number is optional and can be acquired from going to the npm package page. Or if using node_modules: './node_modules/@dunks1980/bay.js/bay.min.mjs';
ES Module example

npm i @dunks1980/bay.js
import bay from '@dunks1980/bay.js';
bay();

NPM example

The npm entry point resolves to bay.mjs for both main and module. Explicit file imports, including bay.js and components/*.mjs, remain available. Use bay.js or bay.min.js as classic browser scripts; those files initialize Bay automatically. ES module imports export the bay initializer shown above.

No CommonJS build is provided. CommonJS code can load the initializer with const { default: bay } = await import('@dunks1980/bay.js') inside an async function. Synchronous require() is not a portable, supported entry point; on Node 24 it returns a module namespace with .default, rather than a callable Bay function. Calling the initializer still requires a browser DOM.

import bay from ...

bay({
  text: `<h1 :style="margin: 1rem;">Settings</h1>`,
});

<template id="my-template">
  %{text} <!-- becomes: --> <h1 :style="margin: 1rem;">Settings</h1> 
</template>

<my-component bay="#my-template" message="Hello world!"></my-component>

Settings can only be set with ES or NPM modules, must be strings, and they can only be set once before creating components. Settings variables can be used anywhere within the templates.
Settings example

There are a few ways to define a component in bay.js:

In your html create an inline template and apply bay attribute and any other props:

<template bay="my-component-name" message>
  <h1>${this.message}</h1>
</template>

<my-component-name message="Hello world!"></my-component-name>

In your html create an inline template and supply bay.js the templates id:

<template id="my-template">
  <h1>${this.message}</h1>
</template>

<my-component bay="#my-template" message="Hello world!"></my-component>

Create a file and supply bay.js the url (don't wrap file contents in template). The file extension can be anything you like as long as its contents are in the HTML format:

<my-component bay="/url/to/my/components.html" message="Hello world!"></my-component>
<!-- or -->
<my-component bay="/url/to/my/components.php" message="Hello world!"></my-component>

<!-- in component file -->
<h1>${this.message}</h1>

Pass bay.js the imported template:

import my_component from "./../component_imports/my_component.html?raw";
import bay from "@dunks1980/bay.js";
bay();
bay.create("my-component", my_component, ["message"]);

Or create template and pass it: ( $ and ` within the string will need \ escaping if string literal)

import bay from "@dunks1980/bay.js";
bay();
bay.create("my-component", `<h1>\${this.message}</h1>`, ["message"]);

<!-- Anywhere in the HTML including other components -->
<my-component message="Hello world!"></my-component>

In your html create an inline element with a template inside, then add bay-hydrate to the containing element:

<div bay-hydrate>
  <h1>This will be replaced once bay creates the component.</h1>
  <template>
    <h1>${this.message}</h1>
    <script>this.message = 'Hello World!'</script>
  </template>
</div>

Props will not be available using this method, but you can use settings. Content is rendered to the main DOM so styles will not be encapsulated and <style> tags defined within the template will have no effect.

In your html create an inline element with a template inside, then add bay="dsd" to the element and shadowrootmode="open" to the template element:

<my-component bay="dsd">
  <template shadowrootmode="open">
    <dsd>
      <h1 id="title">loading...</h1>
    </dsd>
    <noscript>
      <h1 id="title">${this.header_text}</h1>
    </noscript>
    <script mounted>
      this.header_text = "Hello World";
    </script>
  </template>
</my-component>

Elements will be visible while Bay is loading but not if they are wrapped in noscript tags. DSD elements and their children will be removed once the component is created and noscript elements will be removed but their content will remain and their content will be parsed and diffed. Props will not be available using this method, but you can use settings. Content is rendered to the main DOM so styles will not be encapsulated.

A component can be used anywhere in the HTML but inline templates must be in the body of the document. "my-component" can be anything you like but it must have a dash in the name per the custom element spec.

Native state values: Map and Set use stable wrappers that preserve native method results and chaining. Their keys and values keep their original identities. Existing Map.set() and Set.add() calls trigger updates; delete() and clear() do not. Date retains its original identity and native methods, but date mutations do not trigger updates. Reassign the state property after a non-reactive mutation (for example, this.date = this.date) to request an update. Mutating an object stored inside a collection is not automatically reactive. Plain objects and arrays continue to be reactive.