PixKit SDK Documentation — @nickdjangir/pixkit-sdk

Introduction#

Pixkit-sdk is the official JavaScript/TypeScript SDK for PixKit — a lightweight, type-safe library for image uploads, dynamic transformations, AI-powered processing, and CDN-optimized delivery.

⚡

Direct Uploads

Files go straight to S3 via pre-signed URLs — zero server bottlenecks.

🔄

On-the-fly Transforms

Resize, format conversion, quality tuning, and AI processing via URL params.

🔐

Secure Deletion

Server-side file removal with secret-key authentication.

🦾

Type-Safe

Full TypeScript definitions with IntelliSense support out of the box.

🧩

Framework Agnostic

Works with React, Next.js, Node.js, Express, NestJS, and any modern JS runtime.

🤖

AI-Powered

Background removal and upscaling via AI transformation parameters.

Installation#

Install @nickdjangir/pixkit-sdk using your preferred package manager:

Bash

npm install @nickdjangir/pixkit-sdk

CDN (Browser)#

You can also load the SDK directly via a <script> tag:

HTML

<script src="https://unpkg.com/@nickdjangir/pixkit-sdk/dist/index.global.js"></script>
<script>
  const pixkit = new PixKitSDK.PixKit({
    publicKey: 'YOUR_PUBLIC_KEY',
    secretKey: 'YOUR_SECRET_KEY',
    projectId: 'YOUR_PROJECT_ID',
  });
</script>

Danger

Never expose your secretKey in client-side code. Use CDN loading only for prototyping or when calling url() (which does not require a secret key).

Getting Started#

Here's a complete example showing initialization, URL generation, upload, and deletion:

TypeScript

113 { PixKit } 14 4;
2
315 pixkit = 16 PixKit({
4  publicKey: 5,
5  secretKey: 6,
6  projectId: 7,
7});
8
90
1017 url = pixkit.url({
11  path: 8,
12  transformations: { width: 500, format: 9, quality: 80 },
13});
14
151
1618 { data } = 19 pixkit.upload({
17  file: fileBlob,
18  fileName: 10,
19  fileType: 11,
20  folder: 12,
21});
22
23console.log(data.imagePath); 2
24
253
2620 pixkit.delete(data.imagePath);

Authentication#

PixKit uses a dual-key authentication model. Both keys are required during SDK initialization.

Key	Required For	Client-Side Safe	Description
`publicKey`	Uploads & Deletion	Yes	Identifies your project. Safe to expose in frontend apps.
`secretKey`	Uploads & Deletion	No	Authorizes pre-signing and delete operations. Must remain server-side.

Public Key#

Required for upload and delete operations
Safe to include in frontend applications
Used to identify your PixKit project
Format: pk-live-xxxxxxxxxxxxxxxx

Secret Key#

Required for upload pre-signing and delete operations
Must only be used on trusted servers
Never expose in client-side applications or commit to version control
Format: sk-live-xxxxxxxxxxxxxxxx

Warning

Since secretKey is required for upload pre-signing, pixkit.upload() should only be called from a secure server environment (e.g., Next.js API routes, Express endpoints, or serverless functions).

Getting API Keys#

To use the PixKit SDK, you need a Public Key and Secret Key. Follow these steps:

Visit https://pixkit.nickdev.space/ and sign in or create an account.

Navigate to API Keys

From the dashboard sidebar, navigate to the API Keys section.

Create a new API Key

Click "Create API Key" to generate a new key pair for your project.

Copy your keys

Copy the generated Public Key and Secret Key. Store the Secret Key securely — it will only be shown once.

Initialize the SDK

Use both keys when creating a new PixKit instance.

Tip

Store your keys as environment variables and never commit them directly into your codebase. Use .env.local for local development.

.env.local

# .env.local
PIXKIT_PUBLIC_KEY=pk-live-xxxxxxxxxxxxxxxx
PIXKIT_SECRET_KEY=sk-live-xxxxxxxxxxxxxxxx
PIXKIT_PROJECT_ID=your-project-id

SDK Initialization#

Create an SDK instance with your PixKit project credentials:

TypeScript

2 { PixKit } 3 1;

4 pixkit = 5 PixKit({
  publicKey: process.env.PIXKIT_PUBLIC_KEY!,
  secretKey: process.env.PIXKIT_SECRET_KEY!,
  projectId: process.env.PIXKIT_PROJECT_ID!,
  urlEndpoint: 'https:0
});

PixKitOptions#

Property	Type	Required	Description
`publicKey`	`string`	Yes	Public API key for upload and delete operations.
`secretKey`	`string`	Yes	Secret API key for upload and delete operations.
`projectId`	`string`	Yes	Your unique PixKit project identifier.
`urlEndpoint`	`string`	No	Custom API endpoint. Defaults to `https://api.pixkit.nickdstudio.online/v1`.

Note

The constructor throws a PixKitConfigError if publicKey, secretKey, or projectId are missing.

Upload Examples#

PixKit uploads files directly to AWS S3 via pre-signed URLs. No data passes through PixKit servers, ensuring minimal latency and bandwidth costs.

TypeScript

3 result = 4 pixkit.upload({
  file,
  fileName: 1,
  fileType: 2,
});

console.log(result.data.imagePath);
0

Tip

Always store data.imagePath in your database — it's required for generating URLs and deleting files later.

Available Methods#

The PixKit SDK exposes three core methods:

url()

Synchronous

Generate a transformed image URL. No network request is made.

Returns: string

upload()

Async

Upload a file to your project via pre-signed S3 URL.

Returns: Promise<UploadResponse>

delete()

Async

Permanently delete a previously uploaded file.

Returns: Promise<DefaultResponse>

pixkit.url(options)#

Generates a fully qualified image URL with optional transformations. This is a synchronous operation — no network request is made.

TypeScript

3 url = pixkit.url({
  path: 1,
  transformations: {
    width: 500,
    height: 500,
    format: 2,
    quality: 80,
  },
});
0

Transformation Options#

Property	Type	Description
`width`	`number`	Output width in pixels.
`height`	`number`	Output height in pixels.
`format`	`'webp' \| 'jpeg' \| 'png' \| 'avif'`	Target image format.
`quality`	`number (1–100)`	Output quality percentage.
`ai.removeBackground`	`boolean`	Remove image background using AI.
`ai.upscale`	`boolean`	Upscale image resolution using AI.

AI Background Removal:

TypeScript

1 url = pixkit.url({
  path: 0,
  transformations: { ai: { removeBackground: 2 } },
});

React Usage:

TSX

<;img
  src={pixkit.url({
    path: imagePath,
    transformations: { width: 1200, format: 0, quality: 85 },
  })}
  alt=1
/>;

pixkit.upload(options)#

Uploads a file to your PixKit project. The file is sent directly to AWS S3 using a pre-signed URL — no data passes through PixKit servers.

Property	Type	Required	Description
`file`	`File`	Yes	The file or blob to upload.
`fileName`	`string`	Yes	Original file name (e.g., `avatar.png`).
`fileType`	`string`	Yes	MIME type (e.g., `'image/png'`).
`folder`	`string`	No	Target folder within the project bucket.

Returns:

TypeScript

{
  success: 2,
  message: 0,
  data: { imagePath: 1 }
}

pixkit.delete(imagePath)#

Permanently deletes a previously uploaded file. Requires a valid secretKey.

Parameter	Type	Required	Description
`imagePath`	`string`	Yes	Relative image path returned by upload.

TypeScript

0
1 (user.avatar) {
  2 pixkit.delete(user.avatar);
}

3 { data } = 4 pixkit.upload({
  file,
  fileName: file.name,
  fileType: file.5,
});

6 db.user.update({
  where: { id: userId },
  data: { avatar: data.imagePath },
});

Danger

Deletion is irreversible. Your database is not updated automatically — remove references to deleted files separately.

Type Definitions#

The SDK is written in TypeScript and ships with complete type definitions. You can import both the class and its types:

TypeScript

2 { PixKit } 3 0;
4 5 { PixKitOptions } 6 1;

PixKitOptions#

TypeScript

0 PixKitOptions {
  publicKey: 1;
  secretKey: 2;
  projectId: 3;
  urlEndpoint?: 4;
}

UrlOptions#

TypeScript

0 UrlOptions {
  path: 1;
  transformations?: PixKitTransformations;
}

PixKitTransformations#

TypeScript

4 PixKitTransformations {
  width?: 5;
  height?: 6;
  format?: 0 | 1 | 2 | 3;
  quality?: 7;
  ai?: {
    removeBackground?: 8;
    upscale?: 9;
  };
}

UploadOptions#

TypeScript

0 UploadOptions {
  file: 1;
  fileName: 2;
  fileType: 3;
  folder?: 4;
}

UploadResponse#

TypeScript

0 UploadResponse {
  success: 1;
  message: 2;
  data: {
    imagePath: 3;
  };
}

DefaultResponse#

TypeScript

0 DefaultResponse<;T = 2>; {
  success: 3;
  message: 4;
  data?: T | 1;
}

Error Handling#

All SDK errors extend the base PixKitError class and include a machine-readable code and optional cause property.

Error Class	Code	When Thrown
`PixKitConfigError`	`CONFIG_ERROR`	Missing or invalid SDK options during initialization.
`PixKitAuthError`	`AUTH_ERROR`	Invalid public/secret key (HTTP 401/403).
`PixKitNetworkError`	`NETWORK_ERROR`	Network failure reaching API or storage provider.
`PixKitUploadError`	`UPLOAD_ERROR`	Upload pre-signing or S3 upload failed.
`PixKitDeleteError`	`DELETE_ERROR`	Delete request rejected by the backend.

TypeScript

15 { PixKit } 6 1;
2
37 {
4  8 result = 9 pixkit.upload({
5    file,
6    fileName: 2,
7    fileType: 3,
8  });
9  console.log(result.data.imagePath);
10} 10 (error) {
11  11 (error 12 13) {
12    0
13    console.error(4, error.message);
14  }
15}

Note

All PixKit error classes extend PixKitError, which extends the native Error class. Use instanceof checks for granular error handling or catch any Error for general cases.

Best Practices#

🔐 Security#

Never expose secretKey in client-side code. Use server-side API routes (Next.js, Express, NestJS) for upload and delete operations.
Store keys in environment variables (.env.local, .env). Never commit them to version control.
publicKey is safe for client-side use (e.g., generating image URLs).

⚡ Performance#

Use format: 'webp' or format: 'avif' transformations for smaller file sizes and faster loading.
Always specify width and/or height to avoid serving oversized images.
Leverage quality between 75–85 for the best balance of quality and file size.
Generated image URLs are CDN-cacheable — use them directly in <img> tags.

💾 Data Persistence#

Always store data.imagePath in your database after upload — it's required for URL generation and deletion.
When deleting a file, also remove the reference from your database.
Use pixkit.url() to generate display URLs on-the-fly from stored paths.

API Reference#

Complete reference for all SDK exports.

Export	Kind	Description
`PixKit`	Class	Main SDK entry point. Instantiate with PixKitOptions.
`PixKitOptions`	Interface	SDK constructor configuration type.

app/api/upload/route.ts

10
26 { PixKit } 7 1;
38 { NextRequest, NextResponse } 9 2;
4
510 pixkit = 11 PixKit({
6  publicKey: process.env.PIXKIT_PUBLIC_KEY!,
7  secretKey: process.env.PIXKIT_SECRET_KEY!,
8  projectId: process.env.PIXKIT_PROJECT_ID!,
9});
10
1112 13 14 POST(request: NextRequest) {
12  15 formData = 16 request.formData();
13  17 file = formData.get(3) 18 26;
14
15  19 {
16    20 result = 21 pixkit.upload({
17      file,
18      fileName: file.name,
19      fileType: file.22,
20      folder: 4,
21    });
22    23 NextResponse.json(result);
23  } 24 (error) {
24    25 NextResponse.json(
25      { error: 5 },
26      { status: 500 }
27    );
28  }
29}

FAQ#

What file types are supported?

PixKit supports any file type that can be represented as a File, Blob, or Buffer. Image transformations (resize, format, AI) work with JPEG, PNG, WebP, and AVIF.

Is there a file size limit?

File size limits depend on your PixKit plan and AWS S3 configuration. Pre-signed URLs support large file uploads directly to storage.

Can I use the SDK in the browser?

Yes, but with caveats. The url() method is safe for client-side use. However, upload() and delete() require the secretKey, which should never be exposed in the browser. Use server-side API routes for these operations.

How do image transformations work?

Transformations are applied on-demand via URL parameters when the image is requested. The original file remains unchanged in storage. This means you can generate multiple variants from a single upload.

Do I need to set up AWS S3 myself?

No. PixKit handles all storage infrastructure. You just need your API keys to start uploading.

Are uploaded images publicly accessible?

Yes, image URLs generated by pixkit.url() are publicly accessible and CDN-cacheable. Access control is managed at the upload/delete level via API keys.

What happens if I delete an image?

Deletion is permanent and irreversible. The file is removed from storage. Make sure to also remove any references to the imagePath from your database.

Can I use a custom domain for image URLs?

Yes. Pass a custom urlEndpoint when initializing the SDK to use your own domain or CDN endpoint for image delivery.