@nocloud/cfx-nui

NoCloud SDK for CFX NUI (FiveM/RedM) - browser environment only

Overview

NoCloud CFX NUI SDK provides a TypeScript client library for interacting with NoCloud services from CFX NUI (browser) contexts. This package enables NUI applications to check service availability, obtain presigned upload URLs, and upload files directly to NoCloud's serverless storage.

Features

• ☁️ Cloud Storage - Upload files directly from NUI to NoCloud's serverless storage
• 🔒 Signed URLs - Secure uploads with pre-signed URLs
• ⚡ Zero Dependencies - Lightweight, self-contained library
• 🛠️ TypeScript First - Full type safety for NUI applications
• 🎯 Simple API - Clean, promise-based interface

Installation

This package is designed to be used in CFX NUI projects.

bun add @nocloud/cfx-nui

Usage

Importing

import { NoCloud } from "@nocloud/cfx-nui";

Check Service Availability

const isAvailable = await NoCloud.isAvailable();
if (isAvailable) {
  console.log("NoCloud service is available");
}

Upload a File

async function uploadFile(file: File) {
  try {
    // Check if NoCloud is available
    if (await NoCloud.isAvailable()) {
      // Upload with optional metadata
      const mediaUrl = await NoCloud.upload(file, {
        customMeta: "value",
        userId: "12345"
      });

      console.log("File uploaded to:", mediaUrl);
    } else {
      console.error("NoCloud service is not available");
    }
  } catch (error) {
    console.error("Upload failed:", error);
  }
}

Get Presigned URL

const { url, mediaUrl } = await NoCloud.getPresignedUrl(
  "image/png", // Content type
  1024000, // File size in bytes
  {
    // Optional metadata
    category: "screenshots",
    userId: "12345"
  }
);

// url: The presigned URL for uploading
// mediaUrl: The final URL where the file will be accessible

Advanced Upload with Blob

// Upload any Blob (e.g., canvas data)
const blob = await fetch(canvasDataUrl).then((r) => r.blob());
const mediaUrl = await NoCloud.upload(blob, {
  type: "canvas-export",
  timestamp: Date.now()
});

API Reference

NoCloud.isAvailable()

Checks if the NoCloud service is available by pinging the service endpoint.

Returns: Promise<boolean>

Example:

const available = await NoCloud.isAvailable();

NoCloud.getPresignedUrl(contentType, size, metadata?)

Obtains a presigned URL for uploading a file.

Parameters:

• contentType (string): The MIME type of the file (e.g., 'image/png')
• size (number): The file size in bytes
• metadata (Record<string, any>, optional): Additional metadata for the file

Returns: Promise<{ mediaUrl: string; url: string }>

• url: The presigned URL to upload the file
• mediaUrl: The final URL where the uploaded file will be accessible

Example:

const { url, mediaUrl } = await NoCloud.getPresignedUrl("image/jpeg", 50000);

NoCloud.upload(file, metadata?)

Uploads a file to NoCloud storage.

Parameters:

• file (Blob | File): The file or blob to upload
• metadata (Record<string, any>, optional): Additional metadata for the file

Returns: Promise<string> - The media URL of the uploaded file

Example:

const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
const url = await NoCloud.upload(file, { category: "user-uploads" });

Error Handling

All methods throw errors when operations fail. Always wrap calls in try-catch blocks:

try {
  const mediaUrl = await NoCloud.upload(file);
  console.log("Success:", mediaUrl);
} catch (error) {
  console.error("Upload failed:", error);
}

License

MIT © NoCloud