Symbiote.js

Tired of pointless re-renders? Bloated bundles? Chaotic data flow? Magic abstractions and black boxes? Done with frameworks that add complexity instead of removing it?

Miss the vanilla flavor, but still want great DX?

Symbiote.js is here to you

So, what's the big idea?

We believe in using modern, standard web technologies, not reinventing them. Symbiote.js simply adds a touch of modern developer experience (DX) on top of vanilla Custom Elements. You get reactive data bindings, flexible HTML-based templates, powerful state management, built-in routing, SSR support -- all with minimal boilerplate and zero build-step requirement.

Here are the three most important differences between Symbiote.js and other frameworks:

1. Natural DOM Extension Philosophy

Unlike frameworks that wrap your code in complex abstractions (virtual DOM, JSX compilers, proprietary syntax), Symbiote.js works directly with the native DOM API. For you, this means:

• No Black Boxes: What you write is what the browser runs. No mandatory compilation steps, no additional magic.
• Native Speed: It leverages the browser's own optimizations.
• No Framework Lock-in: It plays nicely with any other web technology you want to use.
• Feather-Light: It won't weigh your pages down.
• Zero Dependencies: It's entirely built on native web platform features.
• Real DOM Elements: Symbiote components are Custom Elements, interact with them just like any other DOM node.
• The Classic Trio: Just HTML, CSS, and JavaScript. Everything you need for solid, enterprise-ready work.
• Use the DOM API When You Need It: It's no longer considered an anti-pattern.
• Extensible: Easily add any features you need to your application's base class.

2. Runtime-Agnostic HTML Templates

Symbiote.js offers outstanding flexibility in how you customize and compose your UI. Templates are just standard HTML strings that can be defined or reused anywhere - client-side or server-side:

• Just HTML: Use standard tags and attributes with a simple binding syntax for reactivity.
• html Helper Function: Automatically transforms JS object declarations into HTML binding attributes.
• Plays Well With Others: Works seamlessly with any templating system or server-side technology.
• Loosely Coupled: More flexibility for customizations. One change doesn't break everything.
• Ready for SSR: A perfect fit for server-side rendering (SSR) and static site generation (SSG).
• Integrates with Anything: Easily use it alongside React, Vue, Angular, or any other framework.

3. App-wide State Management

Symbiote.js offers a fresh take on how components communicate and manage state:

• Transparent Reactivity:
• Powerful Data-Binding Syntax: Connect data and action handlers from any local or external data context with minimal boilerplate.
• Natural Data Flow: Leverage the DOM structure itself to naturally model your application's state.
• Compose with Ease: Components can share common properties effortlessly, much like native radio buttons. No prop-drilling or extra wrappers required.
• Loosely Coupled State: Components can share state without being tightly bound to one another.
• Global Data Contexts: Create app-wide data sources that any component or template can access by name prefix.
• Isomorphic State Management: Access data values on the server and the client in the exact same way, without any additional component logic.
• Simple Pub/Sub Pattern: Use fundamental data-bricks to build robust data flows of any complexity.
• Universal: Isomorphic state management that resolves proper data in browser or Node.js environment.

Other Features

Itemize API

Render dynamic lists declaratively:

<div itemize="users">
  <template>
    <span>{{name}}</span> -- <span>{{role}}</span>
    <button ${{onclick: '^removeUser'}}>Remove</button>
  </template>
</div>

• Efficient reactive updates: Just update the source data.
• Each item - is a component: Created automatically and connected to the proper data context.
• Custom items: Use item-tag attribute to delegate rendering to a dedicated component.
• Auto-animated removals: Items with CSS transitions animate out automatically, zero JS needed.
• List nesting: Nested lists are supported for structured data.
• Optional keyed updates: Keyed processor for efficient reordering and minimal DOM mutations.

Server Side Rendering

Use same-code isomorphic components on server and client. Just one flag isoMode = true for efficient hydration. One SSR class for server-side markup generation. Streaming is also supported. Light DOM styles and Declarative Shadow DOM -- all handled automatically during SSR output.

SSR -- simpler than ever before

Built-in SPA Router

Full-featured client-side routing, right out of the box -- no extra dependencies needed:

• Path-based routes with :param extraction
• Route guards for authentication and access control
• Lazy loading of route components
• Named routing context -- bind route data directly in templates

CSS-Driven Animations

Exit transitions with zero JS animation code. The animateOut helper sets a [leaving] attribute, waits for CSS transitionend, then removes the element. Works automatically with the Itemize list rendering API.

Enterprise-Grade Security

• Trusted Types compatible -- template writes use a named 'symbiote' policy when the API is available.
• Full CSP compliance -- works with the strictest Content Security Policy headers.

Agentic Web Ready

WebMCP is supported out of the box and allows to expose actual application state as a set of MCP tools.

TypeScript Support

Symbiote.js leverages a JSDoc declaration approach alongside *.d.ts files for complex and global types. This allows you to have robust type security without a mandatory transpilation step. It also enables you to seamlessly use the source code module-by-module in either JavaScript or TypeScript projects with zero additional setup.

Ecosystem

Symbiote.js stays close to the platform, so it works seamlessly with any popular library or CSS framework - there is no forced Shadow DOM isolating your components from the rest of the page. Need Three.js for 3D, D3 or Chart.js for data visualization, or any CSS utility library? Just use them as you normally would - no adapters, no wrappers, no compatibility layers.

For those who want a batteries-included starting point, there is JSDA-Kit - a ready-made toolkit built around Symbiote.js that lets you spin up a new web project in under a minute. JSDA-Kit works as a static site generator (SSG) for JAMStack sites, or as a lightweight framework for more complex dynamic applications - with built-in SSR, esbuild-powered bundling, automatic import maps, and a zero-config CLI. One scaffold command and you're up and running.

Where It Really Shines

• Building rich multipart widgets
• Crafting complex interactive components
• Micro-frontend architectures
• Creating reusable component libraries
• High-performance web apps
• Framework-agnostic solutions
• Meta-applications
• JamStack / Hybrid sites
• AI-ready solutions

Give It a Spin

<script type="importmap">
  {
    "imports": {
      "@symbiotejs/symbiote": "https://esm.run/@symbiotejs/symbiote"
    }
  }
</script>

<script type="module">
  import Symbiote, { html } from '@symbiotejs/symbiote';

  export class MyComponent extends Symbiote {
    count: 0,
    onIncrement() {
      this.$.count++;
    }
  }

  // Define template:
  MyComponent.template = html`
    <h2>{{count}}</h2>
    <button ${{onclick: 'onIncrement'}}>Click me!</button>
  `;

  // Register new tag name:
  MyComponent.reg('my-component');
</script>

Use the component anywhere in your HTML:
<my-component></my-component>

This little HTML example has everything you need to get a Symbiote.js app running. No build tools, no installation, no local server -- just open it in a browser. And of course, you can use it with TypeScript, bundlers, linters, and all that good stuff.

Live Code Playground

Want to Learn More?