# @appium/strongbox

> Persistent storage for Appium extensions

Latest version **2.0.1** (published 2026-09-24) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @appium/strongbox
pnpm add @appium/strongbox
yarn add @appium/strongbox
bun add @appium/strongbox
```

## Health

**Score 80/100 (A)** — status: active.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-09-24 |
| First published | 2023-04-07 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | ^20.19.0 \|\| ^22.12.0 \|\| >=24.0.0 |
| Dependencies | 1 |
| Unpacked size | 65.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 22042 |
| Author | https://github.com/appium |
| Maintainers | jlipps, nick.mokhnach, kazucocoa |
| Keywords | android, automation, firefoxos, ios, javascript, selenium, testing, webdriver |

## Links

- npm: https://www.npmjs.com/package/@appium/strongbox
- Repository: https://github.com/appium/appium
- Homepage: https://appium.io
- Issues: https://github.com/appium/appium/issues
- npm.io page: https://npm.io/package/@appium/strongbox

## Dependencies (1)

- [env-paths](https://npm.io/package/env-paths.md) 4.0.0

## Alternatives

- [@snazzah/davey](https://npm.io/package/@snazzah/davey.md) — 1.5M weekly downloads
- [@vendure/testing](https://npm.io/package/@vendure/testing.md) — 8.3K weekly downloads
- [vue-simple-context-menu](https://npm.io/package/vue-simple-context-menu.md) — 6.6K weekly downloads
- [cypress-webpack-preprocessor-v5](https://npm.io/package/cypress-webpack-preprocessor-v5.md) — 2.1K weekly downloads
- [@backstage/plugin-catalog-backend-module-puppetdb](https://npm.io/package/@backstage/plugin-catalog-backend-module-puppetdb.md) — 1.3K weekly downloads

## Recent versions

- 2.0.1 (latest) — 2026-09-24
- 3.0.0-beta.1 (beta) — 2026-10-05
- 1.0.0-rc.1 (rc) — 2025-08-14
- 3.0.0-beta.0 — 2026-09-19
- 2.0.0 — 2026-08-24
- 1.1.3 — 2026-07-25
- 1.1.2 — 2026-06-18
- 1.1.1 — 2026-04-23
- 1.1.0 — 2026-04-09
- 1.0.2 — 2026-03-08
- 1.0.1 — 2026-01-26
- 1.0.0 — 2025-08-18
- 0.3.4 — 2025-06-01
- 0.3.3 — 2024-07-10
- 0.3.2 — 2023-12-18
- … 4 more at https://npm.io/package/@appium/strongbox/versions

## README

# @appium/strongbox

> Persistent storage for Appium extensions

## Summary

This package is intended to be used in [Appium](https://appium.io) extensions which need to persist data between Appium runs.  An example of such data may be a device token or key.  

`@appium/strongbox` provides a simple and extensible API for managing such data, while abstracting the underlying storage mechanism.

_Note:_ This module is not intended for storing sensitive data.

## Usage

First, create an instance of `Strongbox`:

```ts
import {strongbox} from '@appium/strongbox';

const box = strongbox('my-pkg');
```

This instance corresponds to a unique collection of data.

From here, create a placeholder for data (you will need to provide the type of data you intend to store):

```ts
const item = await box.createItem<string>('my unique name');
```

...or, if you already have the data on-hand:

```ts
const item: Buffer|string = getSomeData();

const item = await box.createItemWithContents('my unique name', data);
```

Either way, you can read its contents:

```ts
// if the item doesn't exist, this result will be undefined
const contents = await item.read();
```

Or write new data to the item:

```ts
await item.write('new stuff');
```

To list persisted items without knowing their names in advance:

```ts
const items = await box.listItems();
```

`listItems` does not read each file’s contents; call `read()` on an item when you need them. Item order follows the filesystem directory walk (not lexicographic). It returns every item in one array; for large containers that can use a lot of memory, prefer async iteration, which streams directory entries with `opendir` instead of buffering all names first:

```ts
for await (const item of box) {
  // ...
}
```

The last-read contents of the `Item` will be available on the `contents` property, but the value of this property is only current as of the last `read()`:

```ts
const {contents} = item;
```

## API

In lieu of actual documentation, look at the type definitions that this package ships.

## Customization

1. Create a class that implements the `Item` interface:

    ```ts
    import {strongbox, Item} from '@appium/strongbox';
    import {Foo, getFoo} from 'somewhere/else';

    class FooItem implements Item<Foo> {
      // ...
    }
    ```

2. Provide this class as the `defaultCtor` option to `strongbox()`:

    ```ts
    const box = strongbox('my-pkg', {defaultCtor: FooItem});
    ```

3. Use like you would any other `Strongbox` instance:

    ```ts
    const foo: Foo = getFoo();
    const item = await box.createItemWithValue('my unique name', Foo);
    ```

## Default Behavior, For the Curious

Out-of-the-box, a `Strongbox` instance corresponds to a directory on-disk, and each `Item` (returned by `createItem()/createItemWithContents()`) corresponds to a file within that directory.  

The directory of the `Strongbox` instance is determined by the [env-paths](https://www.npmjs.com/package/env-paths) package, and is platform-specific.

## License

Copyright © 2023 OpenJS Foundation. Licensed Apache-2.0

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