TuzzleTuzzle Docs

Overview

Official @tuzzle/* client libraries for building URLs, uploading, and managing assets.

Tuzzle ships a set of official, open-source client libraries under the @tuzzle/* scope on npm. They are built around two layers:

  1. URL & transform builder (@tuzzle/url) — a pure, dependency-free function for composing CDN delivery URLs and signing them server-side. This is the piece you touch on almost every request.
  2. Management client (@tuzzle/client) — a typed API client for uploading and managing assets, generated from the API's OpenAPI spec.

Everything else composes those two: the chooser widget and the framework packages for React, Vue, Next.js, and Nuxt.

All SDKs are framework-thin wrappers over the same REST API and CDN. If there is no package for your stack, you can always call the REST API directly.

Packages

@tuzzle/urlBuilding & signing CDN URLs. Zero dependencies, runs anywhere.@tuzzle/clientUploading files and managing spaces, files, folders, and more.@tuzzle/chooserDropping a media-library / upload widget into any page (no framework).@tuzzle/reactReact components & hooks.@tuzzle/vueVue 3 components & composables.@tuzzle/nextnext/image loader + server-side signing for Next.js.@tuzzle/nuxtA Nuxt 4 module with auto-imports and server-side signing.

Install

Install only what you need. The framework packages pull in their dependencies automatically.

# URL builder (the daily driver)
npm install @tuzzle/url

# Management / upload client
npm install @tuzzle/client

# Framework bindings
npm install @tuzzle/react   # or @tuzzle/vue, @tuzzle/next, @tuzzle/nuxt

Quick example

Build a delivery URL with @tuzzle/url:

import { createTuzzle } from '@tuzzle/url'

const tuzzle = createTuzzle({
  cdnUrl: 'https://cdn.tzzl.io',
  space: 'a1b2c3',
})

// Plain URL with transforms
tuzzle.url('image-01HQ...', { width: 400, format: 'webp', quality: 80 })
// https://cdn.tzzl.io/a1b2c3/image-01HQ...?w=400&f=webp&q=80

// Or chain with the fluent builder
tuzzle.image('image-01HQ...').width(400).format('webp').quality(80).toURL()

Upload a file with @tuzzle/client:

import { createTuzzleClient } from '@tuzzle/client'

const client = createTuzzleClient({
  baseUrl: 'https://api.tzzl.io',
  apiKey: 'sk_a1b2c3d4...',
})

const result = await client.upload(file, { space: 'a1b2c3' })

No SDK for your language?

The API is a standard REST API that accepts JSON and multipart form data, so any HTTP client works:

# Python
import requests

requests.post(
    'https://api.tzzl.io/api/v1/upload',
    headers={'Authorization': f'Bearer {api_key}'},
    files={'file': open('photo.jpg', 'rb')},
    data={'space': 'a1b2c3'},
)

// PHP
$response = Http::withToken($apiKey)
    ->attach('file', file_get_contents('photo.jpg'), 'photo.jpg')
    ->post('https://api.tzzl.io/api/v1/upload', ['space' => 'a1b2c3']);

// Go
req, _ := http.NewRequest("POST", "https://api.tzzl.io/api/v1/upload", body)
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", writer.FormDataContentType())
resp, _ := http.DefaultClient.Do(req)

CDN URLs are plain string concatenation: https://cdn.tzzl.io/<space>/<file>?w=400&f=webp&q=80. See the API Reference for the full specification.

PreviousErrorsNext@tuzzle/url