@stencil/store

Store is a lightweight shared state library by the stencil core team. It implements a simple key/value map that efficiently re-renders components when necessary.

• Lightweight
• Zero dependencies
• Simple API, like a reactive Map
• Best performance

Installation

npm

npm install @stencil/store --save-dev

Yarn

yarn add @stencil/store --dev

pnpm

pnpm add @stencil/store --save-dev

Example

store.ts:

import { createStore } from "@stencil/store";

const { state, onChange } = createStore({
  clicks: 0,
  seconds: 0,
  squaredClicks: 0
});

onChange('clicks', value => {
  state.squaredClicks = value ** 2;
});

export default state;

component.tsx:

import { Component, h } from '@stencil/core';
import state from '../store';

@Component({
  tag: 'app-profile',
})
export class AppProfile {

  componentWillLoad() {
    setInterval(() => state.seconds++, 1000);
  }

  render() {
    return (
      <div>
        <p>
          <MyGlobalCounter />
          <p>
            Seconds: {state.seconds}
            <br />
            Squared Clicks: {state.squaredClicks}
          </p>
        </p>
      </div>
    );
  }
}

const MyGlobalCounter = () => {
  return (
    <button onClick={() => state.clicks++}>
      {state.clicks}
    </button>
  );
};

API

createStore<T>(initialState)

Create a new store with the given initial state. The type is inferred from initialState, or can be passed as the generic type T.

Returns a store object with the following properties.

store.state

The state object is proxied, i. e. you can directly get and set properties and Store will automatically take care of component re-rendering when the state object is changed.

note

Proxy objects are not supported by IE11 (not even with a polyfill), so you need to use the store.get and store.set methods of the API if you wish to support IE11.

info

As of Stencil v3, legacy browser support is deprecated, and will be removed in a future major version of Stencil.

store.on(event, listener)

Add a listener to the store for a certain action.

store.onChange(propName, listener)

Add a listener that is called when a specific property changes.

store.get(propName)

Get a property's value from the store.

store.set(propName, value)

Set a property's value in the store.

store.reset()

Reset the store to its initial state.

store.use(...subscriptions)

Use the given subscriptions in the store. A subscription is an object that defines one or more of the properties get, set or reset.

Testing

Like any global state library, state should be reset between each spec test. Use the dispose() API in the beforeEach hook.

import store from '../store';

beforeEach(() => {
  store.dispose();
});