# piral-base

> The base library for creating a Piral instance.

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

## Install

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

## 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-12-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 793.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1932 |
| Author | smapiot |
| Maintainers | florianrappl |
| Keywords | portal, smapiot, modules, microfrontend, spa, base, functional |

## Links

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

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2.3.1

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K 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
- … 1087 more at https://npm.io/package/piral-base/versions

## README

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

# [Piral Base](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-base.svg?style=flat)](https://www.npmjs.com/package/piral-base) [![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 the base library that is required for any Piral instance. It is independent of React, a state container, or anything else. It only brings functionality for loading and evaluating pilets.

## Documentation

For details on the provided API check out the [documentation at the Piral website](https://docs.piral.io) or [on GitHub](https://github.com/smapiot/piral/tree/main/docs).

## Getting Started

Creating your own Piral app based on `piral-base` is in general **not recommended**.

The only exception is when a Piral-fork that is based on another technology than React should be created. In any other case please look at `piral-core` library or the full `piral` framework.

More information can be found in our [documentation at the Piral website](https://docs.piral.io).

## Available Options

By default, the loading of pilets assumes standard metadata. In general, however, the `loadPilet` option allows to bring in other ways.

### Full Loader Override

One example of using `loadPilet` to extend Piral beyond its initial capabilities is to use SystemJS for loading the pilets.

```js
startLoadingPilets({
  // ...
  loadPilet(meta) {
    return System.import(meta.name)
      .catch((err) => {
        // error
        return {};
      })
      .then((moduleContent) => ({
        ...meta,
        ...moduleContent,
      }))
      .then((pilet: Pilet) => {
        if (typeof pilet.setup !== 'function') {
          pilet.setup = () => {};
        }

        return pilet;
      });
  },
});
```

Another example is to define loader overrides using the `spec` identifier.

### Spec-Specific Loader Overrides

The `loaders` option can be passed in an object where the spec to override is provided as key:

```js
startLoadingPilets({
  // ...
  loaders: {
    'esm': (meta) => {
      // ...
      return pilet;
    },
    'systemjs': (meta) => {
      // ...
      return pilet;
    }
  },
});
```

The spec key is defined by the API response via the `spec` field. This is mostly used with custom specified pilet formats indicated via the `v:x` version marker. A version marker such as `//@pilet v:x(esm)` would lead to use the `esm` override given as an example above.

The two options, `loadPilet` and `loaders` are not exclusive. The `loadPilet` option defines the default, while `loaders` define spec-dependent overrides.

## License

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

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