{"id":18697,"library":"puter","title":"Puter","description":"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.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install puter","lang":"bash","label":"npm"},{"cmd":"yarn add puter","lang":"bash","label":"yarn"},{"cmd":"pnpm add puter","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only. Use named import for the main factory function.","wrong":"const puter = require('puter').createClient","symbol":"createClient","correct":"import { createClient } from 'puter'"},{"note":"FSItem is a TypeScript type/interface; import it with 'import type' to avoid bundling.","wrong":"import { FSItem } from 'puter'","symbol":"FSItem","correct":"import type { FSItem } from 'puter'"},{"note":"No default export. Use named import for the client class.","wrong":"import PuterClient from 'puter'","symbol":"PuterClient","correct":"import { PuterClient } from 'puter'"}],"quickstart":{"code":"import { createClient } from 'puter';\n\nconst client = createClient({\n  apiKey: process.env.PUTER_API_KEY ?? '',\n  region: 'us-east-1'\n});\n\nasync function main() {\n  // List files in root directory\n  const items = await client.listFiles('/');\n  console.log('Files:', items);\n\n  // Upload a file\n  const buffer = Buffer.from('hello world');\n  await client.uploadFile('/remote/hello.txt', buffer);\n\n  // Download a file\n  const content = await client.downloadFile('/remote/hello.txt');\n  console.log('Downloaded:', content.toString());\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates client creation, listing files, uploading and downloading a file using PuterNodeClient."},"warnings":[{"fix":"Use import statements or dynamic import() in CommonJS projects. Set \"type\": \"module\" in package.json.","message":"v1.0.0 only supports ESM imports; require() will fail.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade to v1.0.0 and use createClient({ apiKey, region }) pattern.","message":"The method puter.createClient() with object parameter was deprecated in v0.9. Use positional argument or updated signature.","severity":"deprecated","affected_versions":"<1.0.0"},{"fix":"Always set the API key in the client constructor or via environment variable PUTER_API_KEY.","message":"API keys are required for every request; missing keys throw a 401 error.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"If working with text, convert to Buffer: Buffer.from(yourString, 'utf8').","message":"The uploadFile method expects a Buffer (not a string) as second argument; passing a string causes corruption.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm install puter' and ensure 'type': 'module' in package.json or use .mjs extension.","cause":"The package is not installed or ESM import is used in a non-module Node.js project.","error":"Error: Cannot find module 'puter'"},{"fix":"Switch to import syntax: import { createClient } from 'puter'. Or use dynamic import: const { createClient } = await import('puter').","cause":"Using require('puter') returns an ESM module; require() does not support named exports.","error":"TypeError: puter.createClient is not a function"},{"fix":"Check that PUTER_API_KEY environment variable is set or pass apiKey to createClient().","cause":"API key is missing or incorrect.","error":"PuterError: 401 Unauthorized - invalid API key"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}