Puter

1.0.0 verified Sat Apr 25 auth: no javascript

Puter is a Node.js package for building and managing cloud-based file systems and applications. Version 1.0.0 is the initial stable release, focusing on core file system operations, user authentication, and permission management. It differentiates itself by offering a self-hosted, open-source alternative to proprietary cloud storage platforms with a RESTful API. The package is maintained actively, with monthly releases addressing bugs and feature requests. It supports both CommonJS and ESM, requires Node.js 14+, and includes TypeScript definitions. Compared to similar tools like Minio or AWS SDK, Puter provides a simpler setup for personal cloud environments.

Common errors

error Error: Cannot find module 'puter' ↓

cause The package is not installed or ESM import is used in a non-module Node.js project.

fix

Run 'npm install puter' and ensure 'type': 'module' in package.json or use .mjs extension.

error TypeError: puter.createClient is not a function ↓

cause Using require('puter') returns an ESM module; require() does not support named exports.

fix

Switch to import syntax: import { createClient } from 'puter'. Or use dynamic import: const { createClient } = await import('puter').

error PuterError: 401 Unauthorized - invalid API key ↓

cause API key is missing or incorrect.

fix

Check that PUTER_API_KEY environment variable is set or pass apiKey to createClient().

Warnings

breaking v1.0.0 only supports ESM imports; require() will fail. ↓

fix Use import statements or dynamic import() in CommonJS projects. Set "type": "module" in package.json.

deprecated The method puter.createClient() with object parameter was deprecated in v0.9. Use positional argument or updated signature. ↓

fix Upgrade to v1.0.0 and use createClient({ apiKey, region }) pattern.

gotcha API keys are required for every request; missing keys throw a 401 error. ↓

fix Always set the API key in the client constructor or via environment variable PUTER_API_KEY.

gotcha The uploadFile method expects a Buffer (not a string) as second argument; passing a string causes corruption. ↓

fix If working with text, convert to Buffer: Buffer.from(yourString, 'utf8').

Install

npm install puter

yarn add puter

pnpm add puter

Imports

createClient
wrong
```
const puter = require('puter').createClient
```
correct
```
import { createClient } from 'puter'
```
The package is ESM-only. Use named import for the main factory function.
FSItem
wrong
```
import { FSItem } from 'puter'
```
correct
```
import type { FSItem } from 'puter'
```
FSItem is a TypeScript type/interface; import it with 'import type' to avoid bundling.
PuterClient
wrong
```
import PuterClient from 'puter'
```
correct
```
import { PuterClient } from 'puter'
```
No default export. Use named import for the client class.

Quickstart

Demonstrates client creation, listing files, uploading and downloading a file using PuterNodeClient.

import { createClient } from 'puter';

const client = createClient({
  apiKey: process.env.PUTER_API_KEY ?? '',
  region: 'us-east-1'
});

async function main() {
  // List files in root directory
  const items = await client.listFiles('/');
  console.log('Files:', items);

  // Upload a file
  const buffer = Buffer.from('hello world');
  await client.uploadFile('/remote/hello.txt', buffer);

  // Download a file
  const content = await client.downloadFile('/remote/hello.txt');
  console.log('Downloaded:', content.toString());
}

main().catch(console.error);