puter

library0.0.13jsnpmunverified

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.

aws database auth-security http-networking

npm install puter

package ↗homepage ↗

INSTALL

IMPORT

SIG · PUTER

puter

awsjavascriptv0.0.13

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createClient

✓ import { createClient } from 'puter'

✗ const puter = require('puter').createClient

The package is ESM-only. Use named import for the main factory function.

FSItem

✓ import type { FSItem } from 'puter'

✗ import { FSItem } from 'puter'

FSItem is a TypeScript type/interface; import it with 'import type' to avoid bundling.

PuterClient

✓ import { PuterClient } from 'puter'

✗ import PuterClient from 'puter'

No default export. Use named import for the client class.

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);

Debug

Known issues

breakingv1.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.

affects: >=1.0.0

deprecatedThe 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.

affects: <1.0.0

gotchaAPI 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.

affects: >=0.1.0

gotchaThe 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').

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'puter'

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.

TypeError: puter.createClient is not a function

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').

PuterError: 401 Unauthorized - invalid API key

API key is missing or incorrect.

fix

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

Upgrade

Version history

0.0.13latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/puter ↗

homepagehttps://puter.com ↗