Quickstart

This guide gives you the shortest path from an empty JavaScript project to a rendered DeGallery gallery. Choose the JavaScript client for API access and the React library for UI.

1. Install the packages

pnpm add @degallery/sdk @degallery/react

For a server-only integration, install @degallery/node instead of the React package.

2. Create a client

import { GalleryClient } from '@degallery/sdk';

const client = new GalleryClient({
  apiUrl: process.env.DEGALLERY_API_URL ?? 'https://api.degallery.mpotulo.com',
  apiKey: process.env.DEGALLERY_API_KEY,
});

Keep secret API keys on the server. Browser applications should use a public read token or receive a server-rendered public gallery.

3. Retrieve a gallery

const gallery = await client.getGallery('gallery_uuid');

4. Render it with React

import { Gallery } from '@degallery/react';

export function ProductGallery({ gallery }: { gallery: Gallery }) {
  return <Gallery gallery={gallery} layout="Masonry" />;
}

5. Add uploads on the server

const intent = await client.createUpload({
  filename: 'studio.jpg',
  contentType: 'image/jpeg',
  size: image.byteLength,
  visibility: 'public',
});

await fetch(intent.uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': intent.contentType ?? 'image/jpeg' },
  body: image,
});

await client.completeUpload(intent.intentId);

The upload URL is short-lived. Upload the exact bytes and content type returned by the client, then complete the intent before it expires.

Choose the right integration

Need	Use	Why
Read galleries or manage assets from a server	`@degallery/sdk`	Typed browser-compatible client for public or server-side requests.
Use the Node runtime and upload local files	`@degallery/node`	Server helpers for filesystem and stream-based workflows.
Render a gallery in React	`@degallery/react`	Components, provider context, hooks, and accessible lightbox behavior.

The normal production boundary is: the server uses the SDK to create or authorize a gallery, then the React layer receives a bounded gallery payload or a public read capability. Do not ship private API keys to the browser.

The request lifecycle

sequenceDiagram
  participant App as Your app
  participant SDK as DeGallery SDK
  participant API as DeGallery API
  participant Edge as Media edge
  participant React as React library

  App->>SDK: Create client with server credential
  SDK->>API: Read gallery or create upload intent
  API-->>SDK: Typed metadata or signed upload URL
  App->>API: Upload bytes to signed destination
  App->>SDK: Complete upload intent
  SDK->>API: Confirm asset
  API-->>App: Public gallery payload / capability
  React->>Edge: Request image URL
  Edge-->>React: Cached transformed image

Image delivery is intentionally separate from metadata reads: once the React component has the gallery data, image requests resolve through the media edge and do not need to call the metadata API for every image.

Before you ship

Store DEGALLERY_API_KEY in the server secret store, never in NEXT_PUBLIC_* or a client bundle.
Use stable gallery and asset IDs as React keys; do not key images by array index.
Keep upload completion idempotent so retries after a timeout do not create duplicate state.
Treat image URLs as cacheable delivery artifacts, not as permission to expose private metadata.