# @helia/remote-pinning
[](https://ipfs.tech)
[](https://discuss.ipfs.tech)
[](https://codecov.io/gh/ipfs/helia-remote-pinning)
[](https://github.com/ipfs/helia-remote-pinning/actions/workflows/js-test-and-release.yml?query=branch%3Amain)
> Add remote pinning capabilities to Helia
# About
Remote pinning allows you to delegate the hosting of content to another,
perhaps better connected, node or service on the IPFS network.
Instead of pinning blocks locally, we can use a Remote Pinning Service API
server to pin the blocks, ensuring they are persisted beyond the scope of the
current Helia node.
This is ideal for when creating content in short-lived environments, such as
browsers, for example.
This module exports two functions to help you do this - `createRemotePins`
and `heliaWithRemotePins`.
## createRemotePins
The `createRemotePins` function returns an object that implements the Helia
`Pins` interface.
The returned object can be used to replace the `.pins` property of your Helia
node so you can transparently ensure the longevity of pinned content, or you
can use it directly.
## heliaWithRemotePins
This function takes a Helia instance and some remote pinning config and
returns a Helia node that has been augmented with remote pinning.
You can then use the `.pins` API as normal, and pinned blocks will be pulled
up by the remote pinning service.
## Example
```TypeScript
import { createHelia } from 'helia'
import { heliaWithRemotePins } from '@helia/remote-pinning'
import { unixfs } from '@helia/unixfs'
// this node uses only remote pinning
const helia = heliaWithRemotePins(await createHelia(), {
endpointUrl: `http://localhost:${process.env.PINNING_SERVER_PORT}`, // the URI for your pinning provider, e.g. `http://localhost:3000`
accessToken: process.env.PINNING_SERVICE_TOKEN // the secret token/key given to you by your pinning provider
})
// add a block to Helia
const fs = unixfs(helia)
const cid = await fs.addBytes(Uint8Array.from([0, 1, 2, 3]))
// pin the block
for await(const cid of helia.pins.add(cid, { signal: AbortSignal.timeout(5000) })) {
console.info('pinned', cid)
}
// the block can now be retrieved from the remote pinning service
```
## API differences
The mapping between the Helia pinning API and the remote pinning API is not
perfect. The differences are:
1. The remote pinning API does not give detailed progress information, consequently the only CID yielded from `pins.add` will be the root CID
2. Helia's metadata support is richer than that of the remote pinning API - metadata values can only be strings
3. The remote pinning API accepts several extra arguments to several operations - these can be sent in a type-safe way using the `HeliaWithRemotePins` interface, which is the return type of the exported `heliaWithRemotePins` function
# Install
```console
$ npm i @helia/remote-pinning
```
## Browser `
```
# API Docs
-
# License
Licensed under either of
- Apache 2.0, ([LICENSE-APACHE](https://github.com/ipfs/helia-remote-pinning/blob/main/packages/client/LICENSE-APACHE) / )
- MIT ([LICENSE-MIT](https://github.com/ipfs/helia-remote-pinning/blob/main/packages/client/LICENSE-MIT) / )
# Contribute
Contributions welcome! Please check out [the issues](https://github.com/ipfs/helia-remote-pinning/issues).
Also see our [contributing document](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md) for more information on how we work, and about contributing in general.
Please be aware that all interactions related to this repo are subject to the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
[](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md)