FicusJS

6.3.0 verified Fri May 01 auth: no javascript

FicusJS is a set of lightweight functions for building modern web applications using web components. The current stable version is 6.3.0, released regularly with active maintenance. It provides features like fast custom elements, renderers (htm, lit-html, uhtml, Preact), local state, finite state machines, application stores, event bus, i18n, and more. Key differentiators: small footprint, no build step required, works with native ES modules, and ships TypeScript types. It is designed to be extensible and framework-agnostic, supporting multiple rendering libraries.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module <path>/ficusjs/index.js from <path> not supported. ↓

cause The package is ESM-only since v6; using require() to load it.

fix

Replace require() with ES import syntax, or use dynamic import().

error 'html' is not exported from 'ficusjs' ↓

cause Renderers were moved to separate packages in v6.

fix

Import html from '@ficusjs/renderers' instead.

error Property 'store' does not exist on type 'CustomElement' ↓

cause In TypeScript, the store mixin adds 'store' to the element but types may not reflect it automatically.

fix

Define a custom interface extending the mixin return type, or use type assertion.

Warnings

breaking In v6.0.0, the package switched to pure ESM. CommonJS require() will fail. ↓

fix Use ES import syntax (import { ... } from 'ficusjs') or upgrade to a build pipeline that supports ESM.

breaking In v6.0.0, renderers were moved to separate packages (@ficusjs/renderers). Direct import from 'ficusjs' no longer works. ↓

fix Install @ficusjs/renderers and import from there.

deprecated The 'withState' mixin is deprecated since v5.2.0, use 'withStore' instead. ↓

fix Replace withStore mixin for state management.

breaking In v4.0.0, the `createCustomElement` signature changed: the second argument is now an object instead of a function. ↓

fix Use createCustomElement('tag', { ... }) instead of createCustomElement('tag', () => ({ ... })).

gotcha When using TypeScript, you must set 'skipLibCheck': true or manually configure types. The package exports types but may have strict dependencies. ↓

fix Add `"skipLibCheck": true` to tsconfig.json or install @types/ficusjs if needed.

Install

npm install ficusjs

yarn add ficusjs

pnpm add ficusjs

Imports

createCustomElement
wrong
```
const createCustomElement = require('ficusjs')
```
correct
```
import { createCustomElement } from 'ficusjs'
```
Package is ESM-only; use import statements. CommonJS require not supported.
createStore
wrong
```
import createStore from 'ficusjs/create-store'
```
correct
```
import { createStore } from 'ficusjs'
```
Path exports are not provided; all exports are from the main entry point.
html
wrong
```
import { html } from 'ficusjs'
```
correct
```
import { html } from '@ficusjs/renderers'
```
Renderers are in separate packages like @ficusjs/renderers. html is not directly exported from ficusjs.

Quickstart

Creates a custom element with a local store and htm renderer, incrementing a counter on button click.

import { createCustomElement, withStore } from 'ficusjs'
import { html, renderer } from '@ficusjs/renderers'

const store = {
  state: { count: 0 },
  increment() {
    this.state.count++
    this.emit()
  }
}

createCustomElement('my-counter', withStore(store, {
  renderer,
  render() {
    return html`
      <div>
        <p>Count: ${this.state.count}</p>
        <button onclick="${() => this.store.increment()}">+1</button>
      </div>
    `
  }
}))