# piral-containers

> Plugin for creating a pilet state container in Piral.

Latest version **1.12.4** (published 2026-09-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install piral-containers
pnpm add piral-containers
yarn add piral-containers
bun add piral-containers
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.12.4 |
| Published | 2026-09-11 |
| First published | 2019-10-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 26.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1932 |
| Author | smapiot |
| Maintainers | florianrappl, manuel.roemer, lschoett |
| Keywords | piral, pilet-api, smapiot, portal, modules, api, plugin, plugin-component, state, containers |

## Links

- npm: https://www.npmjs.com/package/piral-containers
- Repository: https://github.com/smapiot/piral
- Homepage: https://piral.io
- Issues: https://github.com/smapiot/piral/issues
- npm.io page: https://npm.io/package/piral-containers

## Alternatives

- [@reckona/mreact-store](https://npm.io/package/@reckona/mreact-store.md) — 976 weekly downloads
- [regular-state](https://npm.io/package/regular-state.md) — 410 weekly downloads
- [@pacote/flux-actions](https://npm.io/package/@pacote/flux-actions.md) — 65 weekly downloads
- [@pilotlab/lux-debug](https://npm.io/package/@pilotlab/lux-debug.md) — 39 weekly downloads
- [vue-persist-state](https://npm.io/package/vue-persist-state.md) — 19 weekly downloads

## Recent versions

- 1.12.4 (latest) — 2026-09-11
- 1.12.4-beta.fb90a9c (next) — 2026-10-21
- 0.15.0-alpha.4409 (canary) — 2022-07-07
- 1.12.4-beta.b76e5ae — 2026-10-21
- 1.12.4-beta.5c7192f — 2026-10-17
- 1.12.4-beta.ef95646 — 2026-10-17
- 1.12.4-beta.0bc4ce7 — 2026-10-17
- 1.12.4-beta.cf72637 — 2026-10-17
- 1.12.4-beta.92532b1 — 2026-10-16
- 1.12.4-beta.4f77727 — 2026-10-04
- 1.12.4-beta.6cb8b4e — 2026-10-04
- 1.12.4-beta.dc8413a — 2026-10-04
- 1.12.4-beta.d019a51 — 2026-09-29
- 1.12.4-beta.80d7277 — 2026-09-29
- 1.12.4-beta.6c244e5 — 2026-09-09
- … 1142 more at https://npm.io/package/piral-containers/versions

## README

[![Piral Logo](https://github.com/smapiot/piral/raw/main/docs/assets/logo.png)](https://piral.io)

# [Piral Containers](https://piral.io) · [![GitHub License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/smapiot/piral/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/piral-containers.svg?style=flat)](https://www.npmjs.com/package/piral-containers) [![tested with vitest](https://img.shields.io/badge/tested_with-vitest-99424f.svg)](https://vitest.dev/) [![Community Chat](https://img.shields.io/discord/1222632475449229352)](https://discord.gg/kKJ2FZmK8t)

This is a plugin that only has a peer dependency to `piral-core`. What `piral-containers` brings to the table is a set of Pilet API extensions that can be used with `piral` or `piral-core`.

By default, these API extensions are not integrated in `piral`, so you'd need to add them to your Piral instance.

## Why and When

State management is important. While plugins such as `piral-redux` bring in an additional kind of state container they also allow using this state container in pilets. `piral-containers` makes the global app state container accessible by all pilets. Using `piral-containers` every pilet can create its own states within the global store.

Alternatives: Leave every pilet to decide and bundle their own state management. A lightweight, framework-agnostic alternative would be [unistore](https://github.com/developit/unistore).

## Video

We also have a video for this plugin:

@[youtube](https://youtu.be/SOY_8temoEE)

## Documentation

The following functions are brought to the Pilet API.

### `createState()`

Creates a new pilet global state container. The state container will essentially couple to the app shell global state container. It is, however, only available for use inside the pilet.

## Usage

::: summary: For pilet authors

You can use the `createState` function from the Pilet API to create your own sub states in the global state container of the Piral instance.

Example use:

```jsx
import { PiletApi } from '<name-of-piral-instance>';
import { MyPage } from './MyPage';

export function setup(piral: PiletApi) {
  const connect = piral.createState({
    state: {
      count: 0,
    },
    actions: {
      increment(dispatch) {
        dispatch(state => ({
          count: state.count + 1,
        }));
      },
      decrement(dispatch) {
        dispatch(state => ({
          count: state.count - 1,
        }));
      },
    },
  });
  piral.registerPage(
    '/sample',
    connect(({ state, actions }) => <MyPage count={state.count} {...actions} />),
  );
}
```

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import `createContainersApi` from the `piral-containers` package.

```ts
import { createContainersApi } from 'piral-containers';
```

The integration looks like:

```ts
const instance = createInstance({
  // important part
  plugins: [createContainersApi()],
  // ...
});
```

There are no options available.

:::

## License

Piral is released using the MIT license. For more information see the [license file](./LICENSE).

---
_Source: https://npm.io/package/piral-containers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._