Choose Your Integration Path

Eazip.js works as a standalone browser library with no account or backend. When a URL-based job needs managed execution, the same packages and job model can also connect to Eazip. Start on the simplest path and move only when the workload requires it.

One question decides most of it: does the browser already have the file URLs? A gallery that renders images already holds usable URLs. An "export my account" button usually doesn't — the list exists only on your server.

The four paths

The browser already has the URLs

Pass them straight to the SDK. No account, key, or backend is needed:

import { createZip } from '@eazip/core';

const result = await createZip({
  files: imageUrls,
  zipName: 'photos.zip',
});

result.download();

When the archive outgrows the tab — multi-gigabyte totals, thousands of URLs, or a job that must survive a reload — keep the same call and add a strategy:

const result = await createZip({
  strategy: 'cloud',
  publicKey: 'pk_ez_...',
  files: imageUrls,
  zipName: 'photos.zip',
});

Get a public key and scope it to your origins and source hosts.

The browser doesn't have the URLs

The list exists on your server. You have two options, and the difference is how much travels over the network.

Option 1 — return a signed URL list. Your endpoint authorizes the user, signs each object, and returns { url, filename } entries for the browser to zip. This is the only option that works without an Eazip account, since Local runs entirely in the browser, and it is what the platform guides implement first. The cost is structural: a 1,000-file export ships 1,000 signed URLs before the job starts.

Option 2 — create the session on your backend. With Cloud, your endpoint builds the source list server-side and returns only a small session handle:

const job = startZip({
  strategy: 'cloud',
  zipName: 'export.zip',
  createSession: async ({ signal, zipName, mode }) => {
    const response = await fetch('/api/exports/123/eazip-session', {
      method: 'POST',
      credentials: 'include',
      signal,
      body: JSON.stringify({ zipName, mode }),
    });
    if (!response.ok) throw new Error('Failed to create Eazip session');
    return response.json(); // { sessionId, clientSecret }
  },
});

The URL list never crosses the network, the browser never sees source URLs or keys, and the SDK still owns progress, resume, and the download UI. See Backend-created sessions for the server side.

No browser in the loop

Scheduled exports, pipelines, and "email the user a link" flows call the HTTP API directly with a secret zk_ key: create a job, receive a webhook when it finishes, and deliver the output URL however you like. No frontend SDK is involved.

How to decide

1. URLs already in the browser → Local, and add strategy: 'cloud' only when the job outgrows the tab.
2. URLs only on your server, zipping in the browser → signed URL list endpoint plus Local.
3. URLs only on your server, running the job in Cloud → backend session; don't build a URL-list endpoint just to download.
4. No user waiting in a browser → HTTP API.

Cloud is not a paid-only escalation: its free tier covers typical use, so pick between these paths on architecture, not price.

Each platform guide shows paths 1–2 in full and links back here when your situation calls for 3 or 4.