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. ItsImagecomponent is not a drop-inloaderFilefor stocknext/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.