<h3 align="center">Puter.js</h3>

<p align="center">
    <a href="https://developer.puter.com" target="_blank">Learn More</a>
    ·
    <a href="https://docs.puter.com" target="_blank">Docs</a>
    ·
    <a href="https://developer.puter.com/tutorials">Tutorials</a>
    ·
    <a href="https://github.com/Puter-Apps/">Examples</a>
    ·
    <a href="https://twitter.com/HeyPuter">X</a>
</p>


<br>

Puter.js gives you auth, cloud storage, database, AI, and more through a single JavaScript library. It is the go-to backend for AI-generated apps.

There is nothing to configure, no API keys, no infrastructure to set up, whether you write the code yourself or have your AI tool do it. Tools like Claude Code, Codex, OpenCode, Lovable, and Replit can generate complete, production-ready apps in a single shot with fewer AI tokens.

<br>

## Installation


### NPM:
```sh
npm install @heyputer/puter.js
```

### CDN:

Include Puter.js directly in your HTML via CDN in the `<head>` section:

```html
<script src="https://js.puter.com/v2/"></script>
```
<br>

## Usage

### Browser

#### ES Modules

```js
import {puter} from '@heyputer/puter.js';
// or
import puter from '@heyputer/puter.js';
// or 
import '@heyputer/puter.js'; // puter will be available globally
```

#### CommonJS

```js
const {puter} = require('@heyputer/puter.js');
// or
const puter = require('@heyputer/puter.js');
// or
require('@heyputer/puter.js'); // puter will be available globally
```

#### Node.js (with Auth Token)

```js
const {init} = require("@heyputer/puter.js/src/init.cjs"); // NODE JS ONLY
// or
import {init} from "@heyputer/puter.js/src/init.cjs";

const puter = init(process.env.puterAuthToken); // uses your auth token
const puter2 = init(process.env.puterAuthToken2); // use some other auth token
```

#### Node.js (with Auth Token + Web Login)

```js
const {init, getAuthToken} = require("@heyputer/puter.js/src/init.cjs");
// or
import {init, getAuthToken} from "@heyputer/puter.js/src/init.cjs";

const authToken = await getAuthToken(); // performs browser based auth and retrieves token (requires browser)
const puter = init(authToken); // uses your auth token
```

<br>

## Usage Example

After importing, you can use the global `puter` object:

```js
// Print a message
puter.print('Hello from Puter.js!');

// Chat with GPT-5 nano
puter.ai.chat('What color was Napoleon\'s white horse?').then(response => {
  puter.print(response);
});
```

<br>

## Starter Templates

You can also use one of the following templates:

- Client-side projects: [Angular](https://github.com/HeyPuter/angular), [React](https://github.com/HeyPuter/react), [Next.js](https://github.com/HeyPuter/next.js), [Vue.js](https://github.com/HeyPuter/vue.js), [Vanilla.js](https://github.com/HeyPuter/vanilla.js)
- Node.js + Express: [Node.js + Express template](https://github.com/HeyPuter/node.js-express.js)

<br>

## Setting Custom Origins
By default puter.js uses the official Puter API and GUI origins. You can customize these origins by setting global variables before importing the SDK like so:

```js
// For API origin
globalThis.PUTER_API_ORIGIN = 'https://custom-api.puter.com';
// For GUI origin
globalThis.PUTER_ORIGIN = 'https://custom-gui.puter.com';

import {puter} from '@heyputer/puter.js'; // or however you import it for your env
```
<br>

---

## Documentation & Community

- [Developer Site](https://developer.puter.com)
- [API Docs](https://docs.puter.com)
- [Live Demo](https://docs.puter.com/playground/)
- [Puter.com](https://puter.com)
- [Discord](https://discord.com/invite/PQcx7Teh8u)
- [Reddit](https://reddit.com/r/puter)
- [X (Twitter)](https://twitter.com/HeyPuter)

## License

Apache-2.0
