Storing unencrypted key-value pairs

This page lists the Key-Value Store's basic methods for storing unencrypted data. Data stored through these methods can be queries through the kvs.query tool.

To store sensitive data in a more secure manner, you'll need to encrypt your stored data instead. This data, however, can't be queried through the kvs.query tool.

To start, import the Forge KVS package in your app, as follows:

1
2
import { kvs } from '@forge/kvs';

Each installation of your app is subject to the API's quotas and limits. See Storage quotas and Storage limits for more details.

Scope requirement

Using the @forge/kvs package requires the storage:app scope in your manifest file:

1
2
permissions:
  scopes:
    - storage:app

See Permissions for more information about scopes.

Legacy version

Legacy versions of the Key-Value Store and Custom Entity Store were originally provided through the storage module of the @forge/api package. For now, we will continue supporting the legacy storage module.

However, as of March 17, 2025, no further feature updates will be provided through this module. Instead, all new KVS and Custom Entity Store feature updates will only be built on modules in the @forge/kvs package. For example, KVS transactions and Custom Entity Store transactions are only available through @forge/kvs.

We strongly recommend using @forge/kvs. Migrating to this package will only change the interface to your app’s data; all data stored through the legacy module will remain intact

kvs.set

Stores a JSON value with a specified key. Forge resolves write conflicts using a last-write-wins strategy.

You can learn more about limits and quotas here.

Method signature

1
2
kvs.set(key: string, value: array | boolean | number | object | string ): Promise<void>;

Example

Sets the key example-key to one of the supported value types.

1
2
// array
kvs.set('example-key', [ 'Hello', 'World' ]);

// boolean
kvs.set('example-key', true);

// number
kvs.set('example-key', 123);

// object
kvs.set('example-key', { hello: 'world' });

// string
kvs.set('example-key', 'Hello world');

kvs.get

Gets a value by key. If the key doesn't exist, the API returns undefined.

Method signature

1
2
kvs.get(key: string): Promise<array | boolean | number | object | string>;

Example

Gets the value associated with the key example-key.

1
2
// Read the value for key `example-key`
await kvs.get('example-key');

kvs.delete

Deletes a value by key, this succeeds whether the key exists or not. Write conflicts are resolved using a last-write-wins strategy.

Method signature

1
2
kvs.delete(key: string): Promise<void>;

Example

Deletes the value associated with the key example-key, if it hasn't already been deleted.

1
2
// Delete the value with the key `example-key`
await kvs.delete('example-key');

kvs.query

Builds a query which returns a set of entities matching the provided list of criteria. See Querying data for more information on building and executing queries.

Method signature

1
2
kvs.query(): Query

Examples

1
2
import { kvs, WhereConditions } from '@forge/kvs';

await kvs.query()
  // Filter the response to only keys that start with the string 'value'
  .where('key', WhereConditions.beginsWith('example'))

  // Limit the result size to 10 values
  .limit(10)

  // Use the cursor provided (returned from a previous invocation)
  .cursor('...')

  // Get a list of results
  .getMany();