Transloadit
Pricing
  • File Uploads
  • File Importing
  • Batch Processing
  • Video Encoding
  • Audio Encoding
  • Image Processing
  • Document Processing
  • Artificial Intelligence
  • File Filtering & Security
  • Media Cataloging
  • File Compression
  • Code Evaluation
  • File Exporting
  • Smart CDN
  • View all services
  • Explore integrations
  • Explore live demos
  • Uppy
  • TransloaditKit
  • Android SDK
  • Node.js SDK
  • Viewer for Next.js
  • Python SDK
  • Ruby SDK
  • Go SDK
  • Java SDK
  • PHP SDK
  • Zapier
  • MCP Server
  • Transloadit CLI
  • Terraform
  • Essentials
  • Best Practices
  • FAQ
  • Robots
  • API
  • Formats
  • Build your first app
  • About
  • Comparisons
  • Open Source
  • Testimonials
  • Jobs
  • Security
  • Posts
  • DevTimes
  • DevTips
  • Press
  • Research
  • Case Studies
  • Solutions
  • Guides
  • Glossary
  • Legal
  • Tools
  • Helping Coursera bring education to millions around the world
  • Transloadit Support
  • Open Source Support
  • Service level agreement
  • Book a demo with our engineers
EssentialsRobotsFAQAPIFormatsBest Practices
Getting started
  • Overview
  • My first App
  • Saving result files
Topics
  • Assembly Instructions
  • Assembly Variables
  • Dynamic Evaluation
  • Templates
  • Webhooks
  • Third-party Credentials
  • Builtin Templates
  • Resize Strategies
  • Assembly Execution Progress
  • Workspaces
  • AI Agents
  • Advanced use Parameter
  • The ignore_errors Parameter
Software Development Kits
  • Overview
  • Android SDK
  • Browsers
  • Convex
  • cURL
  • Go SDK
  • Java SDK
  • MCP Server
  • Multipart Form
  • Node.js SDK
  • Viewer for Next.js
  • PHP SDK
  • Python SDK
  • Ruby SDK
  • Terraform
  • TransloaditKit
  • Zapier Integration
Migration
  • Migration guides
  • Migrate from Cloudinary to Transloadit
  • Migrate from Uploadcare to Transloadit
  • Migrate from Mux to Transloadit
  • Migrate from Filestack to Transloadit

Viewer for Next.js

@transloadit/viewer renders responsive images whose bytes come directly from the Smart CDN, without passing through Next.js image optimization. Use originals in Transloadit Storage or keep your existing HTTP/S3 origin. You do not need to migrate your files to use the integration.

Viewer is an alpha. This guide uses @transloadit/viewer@0.1.0, Next.js 16.3.3+ with the App Router, React 19 and the Node.js runtime. Pin the Viewer version you test. Its Image component is not a drop-in loaderFile for stock next/image.

Start with public Storage images

Use this route for public website images managed alongside your code. For user-uploaded or private media, use the application integration instead. Storage is in private preview; ask us to enable it for your Workspace first.

In your existing Next.js project, install the published packages. These examples use npm; keep your project's package manager and lockfile if it already uses Yarn or pnpm.

npm install --save-exact @transloadit/viewer@0.1.0
npm install --save-dev --save-exact @transloadit/node@6.9.0

Put a non-sensitive JPEG at ./hero.jpg, then run:

npx @transloadit/node@6.9.0 auth login
npx @transloadit/node@6.9.0 storage store ./hero.jpg website/hero.jpg --public --hashed

Approve the intended Workspace in the browser. You can sign up there if you do not have an account. --public publishes the entire destination directory recursively, including existing files and future uploads. Use a dedicated directory containing only media intended to be public. Plain storage store does not publish a directory.

Wrap your existing next.config.ts configuration:

import type { NextConfig } from 'next'
import { withTransloaditImages } from '@transloadit/viewer/next/config'

const nextConfig: NextConfig = {}

export default withTransloaditImages(nextConfig)

In app/page.tsx (or src/app/page.tsx), use the exact path printed by the upload command. The hash below is an example, not a file that already exists in your Workspace:

import { Image } from '@transloadit/viewer/next'

export default function Page() {
  return (
    <Image
      storage
      src="website/hero.fce9d56a.jpg"
      alt="A canal house beside the water"
      width={960}
      preload
    />
  )
}

Run npm run dev and open the page. Commit the generated transloadit.images.json and transloadit-images.d.ts with your app; do not commit CLI credentials. The plugin bundles the catalog, so public delivery needs neither application signing secrets nor a runtime metadata lookup. For optional scaffolding in an existing app, see the maintained image init instructions⁠.

Responsive sizes and loading

width={960} caps the responsive display width; the browser selects from the generated candidates. Use preload for the important above-the-fold image, not every image in a gallery. Other images load lazily by default. Set sizes when your layout needs a more precise sizing hint.

For a blurred placeholder, add --placeholder blur to the upload command and placeholder="blur" to Image. Extraction is optional server-side work and adds metadata usage equal to 20% of the file's bytes when successful. Do not repeat an already-completed upload just to add a placeholder. See the responsive image reference⁠ for layouts, crops and placeholder behavior.

Keep an existing HTTP or S3 origin

This route needs no Storage upload or catalog. Install Viewer as above, then create a compatible, restricted Template⁠ using the maintained HTTP or S3 example. Pin the allowed origin or bucket/prefix, require signatures and disable step overrides. Do not let browser input choose arbitrary import URLs or transformations.

Configure a separate application Auth Key for that Workspace with smart_cdn:sign, and set TRANSLOADIT_SMART_CDN_KEY and TRANSLOADIT_SMART_CDN_SECRET in your server-only environment. Do not deploy the CLI login key: logging out revokes it. Keep S3 credentials in the Template's restricted credentials, never in JSX or browser code.

Render in a Server Component, supplying the real original dimensions from trusted metadata:

import { Image } from '@transloadit/viewer/next'

export default function Page() {
  return (
    <Image
      workspace="my-shop"
      template="products"
      src="chairs/oak.jpg"
      alt="An oak chair"
      width={1200}
      height={800}
    />
  )
}

Replace the Workspace, Template, relative path and dimensions with your own values. This mode does not require withTransloaditImages unless you want its configuration defaults. Signed direct delivery is request-time work; authorize access in the calling Server Component for private files, or use the reference's per-request authorization route.

User-uploaded and private media

A committed catalog suits website assets, not a live user gallery. For Uppy uploads, private images and video, use the React receipt and authorized delivery recipe⁠. Store canonical receipts with their owner and check current per-asset access before serving media. The Convex integration and wedding demo⁠ show application-owned membership alongside the reusable upload and delivery components.

Other frameworks

Viewer has a framework-neutral image model and server handlers, with separate React and Next.js adapters. The Next.js config plugin above is only for Next.js apps. For plain JavaScript or another framework, start with the framework-neutral recipe⁠; it does not require React or Next.js. Your application still owns its UI, routing and access rules.

Verify your integration

  • In browser developer tools, verify that image requests reach your Workspace's Smart CDN and do not go through /_next/image. Resize the viewport and check the requested image size.
  • Compare a cold request with a repeated request. The first transformation can take longer; inspect actual response headers rather than assuming every request is cached.
  • Confirm useful alt text, layout stability and placeholder behavior on a narrow viewport.
  • For private delivery, test an unauthorized user as well as an authorized one. Signed URLs remain usable until expiry; they cannot recall bytes already downloaded.

If an image fails, use Viewer's development diagnostics and the troubleshooting guide⁠. If the catalog is lost, recover receipts⁠ instead of uploading again. Compare pricing using your own transformation, cache and delivery workload; bypassing Next's optimizer alone does not establish a cost saving.

Previous page ← Node.js SDKNext page PHP SDK →
Contact support
TransloaditChecking status…

Product

  • Services
  • Pricing
  • Demos
  • Tools
  • Security
  • Support

Company

  • About/Press
  • Blog/Jobs
  • Comparisons/Compliance matrix
  • Research
  • Open source
  • Solutions
  • Pioneers of the web

Docs

  • Getting started
  • Transcoding
  • FAQ
  • API
  • Guides/DevTips
  • Supported formats

More

  • Platform status⁠
  • Community forum⁠
  • Uppy
  • tus⁠

© 2009–2026 Transloadit-II GmbH

Transloadit®, tus®, and Uppy® are registered trademarks of Transloadit-II GmbH in the United States.

PrivacyTermsImprintTrademarksDMCA Policy
EnglishDeutschEspañolFrançaisPortuguês (Brasil)日本語