Next.js 向け Viewer
@transloadit/viewer は、Next.js の画像最適化を経由せず、Smart CDN から直接取得した画像データでレスポンシブ画像を表示します。Transloadit Storage のオリジナル画像を使うことも、既存の HTTP/S3 オリジンをそのまま使うこともできます。この連携のためにファイルを移行する必要はありません。
Viewer はアルファ版です。このガイドでは
@transloadit/viewer@0.1.0、App Router を使用する Next.js 16.3.3 以降、React 19、Node.js ランタイムを使用します。テストした Viewer のバージョンを固定してください。Imageコンポーネントは、標準のnext/imageにそのまま使えるloaderFileではありません。
Storage の公開画像で始める
この方法は、コードと一緒に管理する Web サイトの公開画像に適しています。ユーザーがアップロードしたメディアや非公開メディアには、アプリケーション連携を使用してください。Storage はプライベートプレビュー中です。まずお問い合わせから、Workspace での有効化をご依頼ください。
既存の Next.js プロジェクトに、公開されているパッケージをインストールします。以下の例では npm を使用しますが、すでに Yarn や pnpm を使っているプロジェクトでは、既存のパッケージマネージャーとロックファイルをそのまま使用してください。
npm install --save-exact @transloadit/viewer@0.1.0
npm install --save-dev --save-exact @transloadit/node@6.9.0
機密情報を含まない JPEG を ./hero.jpg に配置し、次を実行します。
npx @transloadit/node@6.9.0 auth login
npx @transloadit/node@6.9.0 storage store ./hero.jpg website/hero.jpg --public --hashed
ブラウザーで対象の Workspace を承認します。アカウントがない場合は、その画面で登録できます。--public は、既存のファイルと今後のアップロードを含め、保存先ディレクトリ全体を再帰的に公開します。公開するメディアだけを格納した専用ディレクトリを使用してください。storage store だけではディレクトリは公開されません。
既存の next.config.ts 設定をラップします。
import type { NextConfig } from 'next'
import { withTransloaditImages } from '@transloadit/viewer/next/config'
const nextConfig: NextConfig = {}
export default withTransloaditImages(nextConfig)
app/page.tsx(または src/app/page.tsx)では、アップロードコマンドが出力したパスを正確に使用してください。以下のハッシュは例であり、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
/>
)
}
npm run dev を実行してページを開きます。生成された transloadit.images.json と transloadit-images.d.ts をアプリと一緒にコミットしてください。CLI の認証情報はコミットしないでください。プラグインがカタログをバンドルするため、公開配信にはアプリケーションの署名用シークレットも、実行時のメタデータ取得も必要ありません。既存アプリで任意のひな形生成を行う場合は、メンテナンスされている
image init の手順を参照してください。
レスポンシブなサイズ指定と読み込み
width={960} はレスポンシブ表示の幅の上限を設定します。ブラウザーは生成された候補から画像を選択します。preload は、最初の画面内に表示される重要な画像に使用し、ギャラリーのすべての画像には使用しないでください。他の画像はデフォルトで遅延読み込みされます。レイアウトに合わせてより正確なサイズのヒントが必要な場合は、sizes を設定してください。
ぼかしたプレースホルダーを表示するには、アップロードコマンドに
--placeholder blur を追加し、Image に
placeholder="blur" を追加します。抽出は任意のサーバー側処理で、成功した場合はファイルのバイト数の 20% に相当するメタデータ使用量が加算されます。プレースホルダーの追加だけを目的に、完了済みのアップロードを繰り返さないでください。レイアウト、切り抜き、プレースホルダーの動作については、レスポンシブ画像リファレンスを参照してください。
既存の HTTP または S3 オリジンの利用
この方法では、Storage へのアップロードもカタログも必要ありません。上記の手順で Viewer をインストールしたら、メンテナンスされている HTTP または S3 の例を使い、互換性のある制限付き Templateを作成してください。許可するオリジンまたはバケットとプレフィックスを固定し、署名を必須にして、ステップの上書きを無効にしてください。ブラウザーからの入力で任意のインポート URL や変換処理を選択できるようにしないでください。
その Workspace に対して、smart_cdn:sign を指定したアプリケーション専用の Auth Key を別途設定し、サーバー専用の環境で
TRANSLOADIT_SMART_CDN_KEY と TRANSLOADIT_SMART_CDN_SECRET を設定します。CLI のログインキーはデプロイしないでください。ログアウトすると失効します。S3 の認証情報は Template の制限付き認証情報に保存し、JSX やブラウザーのコードには決して含めないでください。
信頼できるメタデータから取得したオリジナル画像の実際の寸法を渡し、Server Component で表示します。
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}
/>
)
}
Workspace、Template、相対パス、寸法を実際の値に置き換えてください。このモードでは、デフォルト設定を利用する場合を除き、withTransloaditImages は必要ありません。署名付きの直接配信はリクエスト時に処理されます。非公開ファイルの場合は、呼び出し元の Server Component でアクセスを認可するか、リファレンスにあるリクエストごとの認可ルートを使用してください。
ユーザーのアップロードと非公開メディア
コミットされたカタログは Web サイトのアセットには適していますが、随時更新されるユーザーギャラリーには適していません。Uppy によるアップロード、非公開画像、動画には、React のレシートと認可付き配信のレシピを使用してください。正規のレシートをその所有者と関連付けて保存し、メディアを配信する前に、アセットごとの現在のアクセス権を確認してください。Convex 連携とウェディングのデモでは、再利用可能なアップロード・配信コンポーネントとともに、アプリケーション側でメンバーシップを管理する方法を示しています。
その他のフレームワーク
Viewer は、フレームワークに依存しない画像モデルとサーバーハンドラーに加え、React 用と Next.js 用の個別のアダプターを備えています。上記の Next.js 設定プラグインは、Next.js アプリ専用です。プレーンな JavaScript や他のフレームワークでは、フレームワークに依存しないレシピから始めてください。React も Next.js も必要ありません。UI、ルーティング、アクセスルールは、引き続きアプリケーション側で管理します。
連携の検証
- ブラウザーの開発者ツールで、画像リクエストが Workspace の Smart CDN に届き、
/_next/imageを経由していないことを確認してください。ビューポートのサイズを変更し、リクエストされる画像サイズを確認します。 - キャッシュのない状態でのリクエストと、繰り返したリクエストを比較してください。初回の変換は時間がかかる場合があります。すべてのリクエストがキャッシュされると想定せず、実際のレスポンスヘッダーを確認してください。
- 幅の狭いビューポートで、代替テキストの有用性、レイアウトの安定性、プレースホルダーの動作を確認してください。
- 非公開配信では、認可されたユーザーだけでなく、認可されていないユーザーでもテストしてください。署名付き URL は有効期限まで使用でき、ダウンロード済みのデータは回収できません。
画像の表示に失敗した場合は、Viewer の開発用診断機能とトラブルシューティングガイドを利用してください。カタログを失った場合は、再アップロードするのではなく、レシートを復元してください。実際の変換、キャッシュ、配信のワークロードに基づいて料金を比較してください。Next のオプティマイザーを経由しないというだけでは、コスト削減になるとは限りません。