Pixxo Node.js SDK

Drop-in replacement for the ImageKit Node.js SDK. Swap import ImageKit from 'imagekit' with import Pixxo from 'pixxo' — zero refactor required.

Installation

npm install pixxo

Quick Start

import Pixxo from "pixxo";
import fs from "fs";

const pixxo = new Pixxo({
  email: "[email protected]",
  password: "your-password",
});

const result = await pixxo.upload({
  file: fs.readFileSync("receipt.pdf"),
  fileName: "receipt.pdf",
  folder: "/receipts",
});

console.log(result.url);    // https://px.pixxo.io/…
console.log(result.fileId); // MongoDB ObjectId
console.log(result.name);   // receipt.pdf

You can also pass raw base64 or a data URI:

const result = await pixxo.upload({
  file: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  fileName: "photo.png",
  folder: "/products/images",
});

Constructor Options

| Option | Type | Required | Default | Description | |---|---|---|---|---| | email | string | ✅ | — | Pixxo account email | | password | string | ✅ | — | Pixxo account password | | baseUrl | string | — | https://api.pixxo.io | API base URL | | cdnDomain | string | — | px.pixxo.io | CDN domain for returned URLs | | maxRetries | number | — | 2 | Retry attempts for S3 upload failures | | publicKey | string | — | — | Ignored (ImageKit compat) | | privateKey | string | — | — | Ignored (ImageKit compat) | | urlEndpoint | string | — | — | Ignored (ImageKit compat) |

upload(options)

Options

| Option | Type | Required | Description | |---|---|---|---| | file | Buffer \| string | ✅ | Buffer, base64 string, or file path | | fileName | string | ✅ | File name with extension | | folder | string | — | Destination folder (e.g. "/receipts") | | useUniqueFileName | boolean | — | Append unique suffix (default: true) |

Response

{
  url: string;      // CDN URL
  fileId: string;   // Pixxo asset ID
  name: string;     // Stored file name
  fileType: string;  // MIME type
  size: number;     // Size in bytes
  folderId: string | null;
  s3Key: string;
}

Migration from ImageKit

- import ImageKit from "imagekit";
+ import Pixxo from "pixxo";

- const imagekit = new ImageKit({
-   publicKey: "...",
-   privateKey: "...",
-   urlEndpoint: "...",
- });
+ const imagekit = new Pixxo({
+   email: "[email protected]",
+   password: "your-password",
+ });

// Everything else stays the same!
const result = await imagekit.upload({
  file: buffer,
  fileName: "photo.jpg",
  folder: "/products",
});
console.log(result.url);

Features

• Token caching — authenticates once, reuses token until expiry
• Automatic retry — exponential back-off for S3 upload failures
• Recursive folder creation — deeply nested paths just work
• Multiple file input types — Buffer, base64, file path
• ImageKit-compatible response — url, fileId, name
• Zero dependencies — uses native fetch (Node 18+)

License

MIT