# corestore

> A Hypercore factory that simplifies managing collections of cores.

Latest version **7.12.5** (published 2026-09-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install corestore
pnpm add corestore
yarn add corestore
bun add corestore
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 7.12.5 |
| Published | 2026-09-10 |
| First published | 2019-02-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 10 |
| Unpacked size | 28.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 95 |
| Author | Holepunch Inc |
| Maintainers | mafintosh |

## Links

- npm: https://www.npmjs.com/package/corestore
- Repository: https://github.com/holepunchto/corestore
- Issues: https://github.com/holepunchto/corestore/issues
- npm.io page: https://npm.io/package/corestore

## Dependencies (10)

- [b4a](https://npm.io/package/b4a.md) ^1.6.7
- [streamx](https://npm.io/package/streamx.md) ^2.26.0
- [hypercore](https://npm.io/package/hypercore.md) ^11.35.4
- [bare-events](https://npm.io/package/bare-events.md) ^2.8.3
- [which-runtime](https://npm.io/package/which-runtime.md) ^1.2.1
- [ready-resource](https://npm.io/package/ready-resource.md) ^1.1.1
- [hypercore-crypto](https://npm.io/package/hypercore-crypto.md) ^3.4.2
- [hypercore-errors](https://npm.io/package/hypercore-errors.md) ^1.4.0
- [sodium-universal](https://npm.io/package/sodium-universal.md) ^5.0.1
- [hypercore-id-encoding](https://npm.io/package/hypercore-id-encoding.md) ^1.3.0

## Recent versions

- 7.12.5 (latest) — 2026-09-10
- 7.12.4 — 2026-09-07
- 7.12.3 — 2026-09-05
- 7.12.2 — 2026-08-24
- 7.12.1 — 2026-08-24
- 7.12.0 — 2026-07-28
- 7.11.1 — 2026-07-14
- 7.11.0 — 2026-06-23
- 7.10.1 — 2026-06-05
- 7.10.0 — 2026-05-27
- 7.9.2 — 2026-03-21
- 7.9.1 — 2026-03-10
- 7.9.0 — 2026-03-06
- 7.8.0 — 2026-02-05
- 7.7.0 — 2025-11-26
- … 170 more at https://npm.io/package/corestore/versions

## README

# Corestore

### [See the full API docs at docs.pears.com](https://docs.pears.com/helpers/corestore)

Corestore is a Hypercore factory that makes it easier to manage large collections of named Hypercores.

Corestore provides:

1. **Key Derivation** - All writable Hypercore keys are derived from a single master key and a user-provided name.
2. **Session Handling** - If a single Hypercore is loaded multiple times through the `get` method, the underlying resources will only be opened once (using Hypercore 10's new session feature). Once all sessions are closed, the resources will be released.
3. **Storage Management** - Hypercores can be stored in any `hypercore-storage` instance, where they will be keyed by their discovery keys.
4. **Namespacing** - You can share a single Corestore instance between multiple applications or components without worrying about naming collisions by creating "namespaces" (e.g. `corestore.namespace('my-app').get({ name: 'main' })`)

### Installation

`npm install corestore`

> [!NOTE]
> This readme reflects Corestore 7, our latest major version that is backed by RocksDB for storage and atomicity.
> Whilst we are fully validating that, the npm dist-tag for latest is set to latest version of Corestore 7, the previous major, to avoid too much disruption.
> It will be updated to 11 in a few weeks.

### Usage

A corestore instance can be constructed with a `hypercore-storage` instance, or a string. If a string is specified, it will be assumed to be a path to a local storage directory:

```js
const Corestore = require('corestore')

const store = new Corestore('./my-storage')
const core1 = store.get({ name: 'core-1' })
const core2 = store.get({ name: 'core-2' })
```

### API

#### `const store = new Corestore(storage, options = {})`

Create a new Corestore instance.

`storage` can be either a `hypercore-storage` instance or a string.

Options:

```
{
  primaryKey: null, // The primary key to use as the master key for key derivation.
  writable: true,
  treeCache: { maxSize: 8192 }, // Options to use when creating hypercore's default storage
  active: true // Whether to attach downloading cores to existing or future replication streams
}
```

#### `const core = store.get(key | { name: 'a-name', ...hypercoreOpts})`

Loads a Hypercore, either by name (if the `name` option is provided), or from the provided key (if the first argument is a Buffer or String with hex/z32 key, or if the `key` options is set).

If that Hypercore has previously been loaded, subsequent calls to `get` will return a new Hypercore session on the existing core.

All other options besides `name` and `key` will be forwarded to the Hypercore constructor.

#### `const stream = store.replicate(optsOrStream)`

Creates a replication stream that's capable of replicating all Hypercores that are managed by the Corestore, assuming the remote peer has the correct capabilities.

`opts` will be forwarded to Hypercore's `replicate` function.

Corestore replicates in an "all-to-all" fashion, meaning that when replication begins, it will attempt to replicate every Hypercore that's currently loaded and in memory. These attempts will fail if the remote side doesn't have a Hypercore's capability -- Corestore replication does not exchange Hypercore keys.

If the remote side dynamically adds a new Hypercore to the replication stream, Corestore will load and replicate that core if possible.

Using [Hyperswarm](https://github.com/holepunchto/hyperswarm) you can easily replicate corestores

```js
const swarm = new Hyperswarm()

// join the relevant topic
swarm.join(...)

// simply pass the connection stream to corestore
swarm.on('connection', (connection) => store.replicate(connection))
```

#### `const storeB = storeA.session()`

Create a new Corestore session. Closing a session will close all cores made from this session.

#### `const store = store.namespace(name)`

Create a new namespaced Corestore session. Namespacing is useful if you're going to be sharing a single Corestore instance between many applications or components, as it prevents name collisions.

Namespaces can be chained:

```js
const ns1 = store.namespace('a')
const ns2 = ns1.namespace('b')
const core1 = ns1.get({ name: 'main' }) // These will load different Hypercores
const core2 = ns2.get({ name: 'main' })
```

#### `const stream = store.list(namespace)`

Creates a discovery key stream of all cores within a namespace or all cores in general if no namespace is provided.

#### `store.watch((core) => {})`

Register a callback called when new Hypercores are opened. `core` is the internal core for the opened Hypercore. It can be used to create weak references to a Hypercore like so:

```
store.watch(function (core) {
  const weakCore = new Hypercore({ core, weak: true })
})
```

#### `store.unwatch(callback)`

Unregister a callback used with `store.watch(callback)` so it no longer fires.

#### `const handle = store.notifyGroup(topic)`

> [!IMPORTANT]
> This feature is _experimental_. The API is subject to change, and everything may break.

Get a `handle` for updates from all `hypercore`s with the group `topic` set.

#### `const stream = handle.update(opts = {})`

Gets updates for the `topic` the handle is for.

`opts` includes:

```js
{
  since: 0,      // What timestamp to start returning updates from. Default `0` returns all updates
  reverse: true, // Flag to return updates in reverse order. Defaults to `true` so latest returned first
}
```

Stream returns the core's `key`:

```js
for await (const key of handle.updates()) {
  // ...
}
```

#### `handle.destroy()`

Destroys and unregisters the `handle` from its `store`.

#### `handle.on('update', callback)`

Calls the callback whenever a core with the `topic` for the `handle` updates.

#### `await store.suspend()`

Suspend the underlying storage for the Corestore.

#### `await store.resume()`

Resume a suspended Corestore.

#### `const keypair = await store.createKeyPair(name, ns = this.ns)`

Generate a key pair seeded with the Corestore's primary key using a `name` and a `ns` aka namespace. `ns` defaults to the current namespace.

This is useful for creating deterministic key pairs that are unique to a peer.

#### `await store.close()`

Fully close this Corestore instance.

#### `store.on('group-active', (topic) => {})`

> [!IMPORTANT]
> This feature is _experimental_. The API is subject to change, and everything may break.

The `group-active` event emits whenever an opened Hypercore in the store updates. The `topic` is the group topic the core belongs to.

### License

MIT

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