lit-sm: A Simple State Management Library for Lit

Overview

lit-sm is a lightweight state management library designed to work seamlessly with the Lit library (formerly known as LitElement). It provides a straightforward method to integrate shared state management into your Lit-based web components. This README will guide you through the installation, usage, and key features of lit-sm.

Installation

You can easily integrate lit-sm into your project by following these simple steps:

1. Install the package using npm or yarn:

   npm install lit-sm
   # or
   yarn add lit-sm

2. Import the necessary functions and classes in your project:

import { createSharedStateMixin } from 'lit-sm';

Getting Started

lit-sm provides a mixin that you can use to add shared state functionality to your LitElement-based components. Here's how you can get started:

Define your initial state in a separate module (e.g., state.ts):

import { createSharedStateMixin } from 'lit-sm';
import { v4 as uuidv4 } from 'uuid';

// Define the initial state interface
interface sharedState {
  x: number;
  //...
}

const initialState: sharedState = {
  x: 0
  //...
};

// Export the shared state mixin
export const SharedTestStateMixin = createSharedStateMixin(initialState);

Import and use the shared state mixin in your LitElement components (e.g., element.ts):

import { LitElement, html } from 'lit';
import { customElement, property } from 'lit/decorators.js';
import { SharedTestStateMixin } from './state.js';

@customElement('root-element')
export class RootElement extends SharedTestStateMixin(LitElement) {

  @property()
  lit_sm_storage = 'test';

  render() {
  return html`
        <div id="rootElement">
          <div>${this.sharedState.x}</div>
          <button
            @click=${() => this.sharedState.x++}>
            increment
          </button>
        </div>
    `;
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'root-element': RootElement;
  }
}

Key Features

Shared State

lit-sm allows you to easily share state across components that use the same mixin. This means that you can manage and synchronize state between different components without complex setup.

State Persistence

You can enhance your components by adding the lit_sm_storage property to them. When this property is provided, the shared state will be automatically saved and loaded from it. This feature is especially usefull when developing widgets for the webwriter.

Disabling Declaration Files (TypeScript Users)

If you are using TypeScript and want to use lit-sm, make sure to disable the generation of declaration files in your tsconfig.json:

{
  "compilerOptions": {
    "declaration": false
    //...
  }
}

Unfortunately, typescript is not able to generate declaration files when using this library. This is due to the fact that the mixin is dynamically generated at runtime. Maybe this will be possible in a future version of TypeScript. (tested version: 5.2)

License

lit-sm is licensed under the MIT License or the ISC License, whichever is more suitable for your use case.

Contributing

If you want to contribute to this project, feel free to open an issue or submit a pull request. The docs for developers can be found here.

Copyright

© Luis Kugel 2023