A laptop in the clouds projecting holographic panels for storage, AI, and auth, with a red cat on the desk

Puter.js: The SDK That Ate Your Backend and Liked It

The Orange Cat
The Orange Cat

Backend infrastructure is the tax every frontend developer pays for wanting their app to do something useful. You need a server for auth. You need a database for persistence. You need API keys, environment variables, rate-limit management, and a bill that grows every time someone decides to ask your chatbot what the meaning of life is. Puter.js looks at all of that and says: what if you just didn't?

@heyputer/puter.js is the official JavaScript SDK for the Puter platform, an open-source project that bills itself as "The Internet Computer." It provides authentication, cloud file storage, a key-value database, and access to AI models from OpenAI, Anthropic, and Google -- all from a single frontend import. There are no API keys to manage, no servers to deploy, and no configuration files to maintain. Your end-users authenticate with their own Puter accounts, and the credits they spend on AI and storage come from their wallets, not yours.

What You Get Out of the Box

Puter.js is not a single-purpose library. It is a bundled platform SDK that covers five distinct capabilities through a unified API:

  • AI chat and generation across multiple providers (GPT-5-nano, GPT-4o, Claude Opus 4, Claude Sonnet 4, Gemini 2.0 Flash Lite, DALL-E 3, and reasoning models like o1 and o3-mini)
  • Cloud file storage with full read/write operations in each user's personal Puter storage
  • Key-value database for persisting settings, preferences, and application state
  • Authentication with sign-in flows, session management, and user profile access
  • Text-to-speech and OCR for converting between text, audio, and image formats

The "user-pays" model is the most unusual part. Instead of you paying OpenAI or Anthropic for every API call your users make, each user spends credits from their own Puter account. Your app acts as the interface; Puter handles the billing relationship with the end-user.

Getting Started

Installation

The quickest way to start is the CDN script tag:

// In your HTML file
// <script src="https://js.puter.com/v2/"></script>

For npm-based projects:

npm install @heyputer/puter.js
# or
yarn add @heyputer/puter.js

Then import it:

import { puter } from '@heyputer/puter.js';

For CommonJS environments:

const { puter } = require('@heyputer/puter.js');

Talk to Any AI Model in Three Lines

The most immediately impressive feature is the AI module. You can call GPT, Claude, or Gemini through a single method without configuring a single API key.

Asking a Question

const response = await puter.ai.chat(
  'Explain the difference between TCP and UDP in one paragraph.',
  { model: 'gpt-5-nano' }
);

puter.print(response);

Swap gpt-5-nano for claude-sonnet-4 or gemini-2.0-flash-lite and the same code works with a different provider. No separate SDK, no different auth flow, no new billing account.

Generating Images

const image = await puter.ai.chat(
  'A watercolor painting of a lighthouse at sunset',
  { model: 'dall-e-3' }
);

puter.print(image);

Reading Text from Images

const extractedText = await puter.ai.img2txt(imageFile);
puter.print(extractedText);

The OCR capability works with screenshots, photos of documents, or any image file you pass in. Combined with the chat API, you can build document-processing pipelines entirely in the browser.

Your Personal Cloud File System

The storage module gives every authenticated user their own file system in the cloud. Files persist across sessions and devices.

Writing and Reading Files

await puter.fs.write('notes/todo.txt', 'Buy milk. Deploy to production. Pet the cat.');

const content = await puter.fs.read('notes/todo.txt');
puter.print(content);

This is cloud storage with a file-system metaphor. You write to paths, read from paths, and the data lives in the user's Puter account. No S3 buckets, no storage configuration, no CORS headers.

Combining Storage with AI

const document = await puter.fs.read('reports/quarterly.txt');

const summary = await puter.ai.chat(
  `Summarize this document in three bullet points: ${document}`,
  { model: 'claude-sonnet-4' }
);

await puter.fs.write('reports/quarterly-summary.txt', summary);

Read a file from the user's cloud storage, pass it to Claude for summarization, and write the result back. Five lines of code, no backend.

Persistent State Without a Database Server

The key-value store is the simplest persistence layer you will find. It is cloud-backed, so data survives browser clears, device switches, and the heat death of your local storage.

Storing User Preferences

await puter.kv.set('theme', 'dark');
await puter.kv.set('language', 'en');
await puter.kv.set('lastVisited', new Date().toISOString());

const theme = await puter.kv.get('theme');
puter.print(theme); // 'dark'

Building a Chat History

const history: string[] = JSON.parse(
  (await puter.kv.get('chatHistory')) || '[]'
);

history.push('User: What is the weather today?');

const aiResponse = await puter.ai.chat(history.join('\n'), {
  model: 'gpt-5-nano',
});

history.push(`AI: ${aiResponse}`);
await puter.kv.set('chatHistory', JSON.stringify(history));

This pattern gives you a persistent, multi-session chatbot with no database setup. The key-value store handles serialization; you handle the data shape.

Authentication That Handles Itself

Sign-In Flow

const isSignedIn = puter.auth.isSignedIn();

if (!isSignedIn) {
  await puter.auth.signIn();
}

const user = await puter.auth.getUser();
puter.print(`Welcome, ${user.username}`);

Puter manages the entire authentication flow. There is no OAuth configuration, no callback URLs, no token refresh logic. The user signs in with their Puter account, and your app gets access to their storage, database, and AI credits.

Gating Features Behind Auth

async function generateReport(prompt: string): Promise<string> {
  if (!puter.auth.isSignedIn()) {
    await puter.auth.signIn();
  }

  const report = await puter.ai.chat(prompt, { model: 'claude-opus-4' });
  await puter.fs.write('generated-report.txt', report);

  return report;
}

Because auth, AI, and storage all live in the same SDK, composing them feels natural rather than like stitching together three separate services.

Running in Node.js

Puter.js also works server-side. The initialization is slightly different because there is no browser sign-in flow:

const { init } = require('@heyputer/puter.js/src/init.cjs');
const puter = init(process.env.PUTER_AUTH_TOKEN);

const response = await puter.ai.chat('Hello from the server!', {
  model: 'gpt-5-nano',
});

You pass an auth token directly, and the same API surface is available. This is useful for scripts, cron jobs, or Express endpoints that need to interact with a user's Puter data.

Custom Puter Instances

For teams self-hosting the Puter platform, you can point the SDK at your own infrastructure:

globalThis.PUTER_API_ORIGIN = 'https://api.my-puter-instance.com';
globalThis.PUTER_ORIGIN = 'https://gui.my-puter-instance.com';

Since the entire Puter platform is open source under AGPL-3.0, you can run your own instance and have full control over data residency and API availability.

The Tradeoffs

Puter.js is not without constraints. Response times from the AI models can be slower than calling providers directly, since requests route through Puter's infrastructure. Your users need Puter accounts, which adds a registration step that some audiences may resist. The key-value store is useful but is not a relational database -- if you need joins, indexes, or complex queries, you will outgrow it. And the project is young, with the npm package first published in September 2025, so production-grade SLAs and long-term stability guarantees are still forthcoming.

The "user-pays" pricing model is clever but double-edged: it eliminates your API costs, but it also means your users are the ones reaching for their wallets. Whether that is a feature or a dealbreaker depends entirely on your audience.

Wrapping Up

@heyputer/puter.js is an ambitious SDK that collapses the entire backend stack into a frontend import. Auth, storage, database, and multi-provider AI access with no configuration, no API keys, and no server to maintain. It is best suited for prototypes, side projects, internal tools, and applications where the "user-pays" model aligns with the business logic. For developers tired of provisioning infrastructure just to store a preference and call an LLM, Puter.js is a compelling shortcut that actually works.