#JavaScript SDK

The Pixault JavaScript SDK provides image URL construction, uploads, and management for Node.js and browser environments. Available as @pixault/sdk on npm.

Source on GitHub

#Installation

npm install @pixault/sdk
# or
yarn add @pixault/sdk
                              

#Configuration

import { Pixault } from '@pixault/sdk';
const px = new Pixault({
  clientId: 'px_cl_your_client_id',
  clientSecret: 'pk_your_secret_key',
  baseUrl: 'https://img.pixault.io',  // optional, this is the default
  project: 'myapp',
});
                              

Browser usage: Never expose your client secret in client-side code. Use the URL builder (which doesn't require secrets) in the browser, and make API calls from your server.

#URL Builder

Generate transform URLs without making network requests:

const url = px.url('img_01JKXYZ')
  .width(800)
  .height(600)
  .fit('cover')
  .quality(85)
  .format('webp')
  .build();
// → "https://img.pixault.io/myapp/img_01JKXYZ/w_800,h_600,fit_cover,q_85.webp"
                              

#Methods

#Browser-Only URL Builder

For client-side usage without credentials:

import { PixaultUrl } from '@pixault/sdk';
const builder = new PixaultUrl({
  baseUrl: 'https://img.pixault.io',
  project: 'myapp',
});
const url = builder.image('img_01JKXYZ')
  .width(400).format('webp').build();
                              

#Upload

// Node.js (with fs)
import fs from 'fs';
const image = await px.upload(fs.createReadStream('photo.jpg'), {
  filename: 'photo.jpg',
  alt: 'Team photo from retreat',
  tags: ['team', 'retreat'],
});
console.log(image.id);  // "img_01JKXYZ123"
console.log(image.url);  // "https://img.pixault.io/myapp/img_01JKXYZ123/original.jpg"
// Browser (with File object)
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
const image = await px.upload(file, {
  alt: 'User avatar',
  tags: ['avatar'],
});
                              

#Image Management

// List images
const { images, cursor, hasMore } = await px.listImages({
  limit: 20,
  tag: 'nature',
});
// Get metadata
const metadata = await px.getImage('img_01JKXYZ');
// Update metadata
await px.updateImage('img_01JKXYZ', {
  alt: 'Updated description',
  tags: ['updated', 'tags'],
});
// Delete
await px.deleteImage('img_01JKXYZ');
                              

#List & Search Images

// List all images
const result = await pixault.listImages('my-project');
// Search by text
const matches = await pixault.listImages('my-project', { search: 'hero' });
// Filter by category
const tattoos = await pixault.listImages('my-project', { category: 'tattoo-flash' });
// Filter by keyword
const portraits = await pixault.listImages('my-project', { keyword: 'portrait' });
// Paginate
const page2 = await pixault.listImages('my-project', {}, 50, result.nextCursor);
                              

#Watermarks

Manage watermark images at the project level. Watermarks are typically PNGs with transparency, applied to images at delivery time via the URL builder or named transforms.

// List watermarks for a project
const watermarks = await pixault.listWatermarks('my-project');
for (const wm of watermarks) {
  console.log(wm.id, wm.sizeBytes);
}
// Upload (or replace) a watermark — browser
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
const wm = await pixault.uploadWatermark('my-project', 'logo', file);
// Upload from a Buffer — Node.js
import { readFile } from 'node:fs/promises';
const buffer = await readFile('logo.png');
await pixault.uploadWatermark('my-project', 'logo', buffer);
// Delete a watermark
await pixault.deleteWatermark('my-project', 'logo');
                              

#Apply a watermark to a URL

const url = pixault.image('my-project', 'img_01JKXYZ')
  .width(1200)
  .watermark('logo', 'br', 40)
  .format('jpg')
  .build();
// → "...img_01JKXYZ/w_1200,wm_logo,wm_pos_br,wm_opacity_40.jpg"
                              

#Position values

Watermark IDs must match ^[a-z0-9][a-z0-9\-_]{0,63}$ (lowercase letters, digits, hyphens, or underscores; max 64 characters). Watermark images must be under 5 MB.

#Folder Management

// List folders
const folders = await client.listFolders();
// Create a folder
await client.createFolder('portfolio/landscapes');
// Delete a folder
await client.deleteFolder('portfolio/landscapes');
// List images in a specific folder
const result = await client.listImages({ folder: 'portfolio/landscapes' });
                              

#Named Transforms

// Create
await px.createTransform('thumbnail', {
  parameters: { w: 200, h: 200, fit: 'cover', q: 80 },
  locked: ['w', 'h', 'fit'],
});
// List
const transforms = await px.listTransforms();
// Use in URL builder
const url = px.url('img_01JKXYZ').transform('thumbnail').format('webp').build();
                              

#TypeScript Support

The SDK is written in TypeScript and exports full type definitions:

import type { PixaultConfig, ImageMetadata, UploadOptions } from '@pixault/sdk';
const config: PixaultConfig = {
  clientId: 'px_cl_abc123',
  clientSecret: 'pk_secret456',
  project: 'myapp',
};
                              

#Error Handling

try {
  await px.upload(file, { alt: 'Photo' });
} catch (err) {
  if (err.status === 413) {
    console.error('Storage quota exceeded');
  } else if (err.status === 429) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  }
}
                              

#React Integration

See the React Integration Guide for component examples and hooks.