Node SDK v4:TypeScript ファーストと包括的な Robot 対応
本日、Node.js SDK のバージョン 4 をリリースします。初回リリース以来、パッケージを最も大きく見直したバージョンです。全面的な TypeScript 対応、オートコンプリート付きの完全な Robot 定義、構造化されたエラー処理、最新のツールを利用できます。同時に、Node エコシステムとともに成長してきた API の 15 年の歩みも尊重しています。
v4 の新機能
Node SDK v4 は TypeScript で全面的に書き直され、主に次の点が改善されています。
TypeScript ファーストの設計
すべての Robot、パラメーター、レスポンスに完全な型が付きました。Assembly Instructionsを記述すると、IDE が入力中に適切な Robot、パラメーター、戻り値を候補として表示します。
import { Transloadit } from 'transloadit'
const transloadit = new Transloadit({
authKey: process.env.TRANSLOADIT_KEY,
authSecret: process.env.TRANSLOADIT_SECRET,
})
await transloadit.createAssembly({
params: {
steps: {
resize: {
use: ':original',
robot: '/image/resize', // ← autocompletes all available Robots
width: 320, // ← only shows valid parameters for this Robot
height: 240,
result: true,
},
},
},
waitForCompletion: true,
})
Assembly Instructionsは詳細な型定義に基づいて検証されます。設定や後方互換性の問題を、デプロイの途中ではなく、ローカル開発の早い段階で検出します。
モダンな JavaScript 環境
SDK は純粋な ESM となり、Node.js 20 以降を対象に、全体で名前付きエクスポートを使用します。
// Named exports replace the default export
import { Transloadit } from 'transloadit'
CommonJS プロジェクトでは、動的インポートを使用してください。
async function getClient() {
const { Transloadit } = await import('transloadit')
return new Transloadit({ authKey, authSecret })
}
エラー処理の改善
エラーにより詳しいコンテキストを含むスタックトレースが付くようになり、デバッグしやすくなりました。
Smart CDN URL ヘルパー
SDK から署名付き Smart CDN URL を直接生成できます。
const signedUrl = transloadit.getSignedSmartCDNUrl({
workspace: 'my-team',
template: 'hero-image',
input: 'photo.jpg',
urlParams: { format: 'webp' },
})
既存 API への型導入方針
15 年にわたって自然に進化してきた API に TypeScript を追加するにあたり、興味深い課題に直面しました。この API が誕生したのは Node.js の初期で、JavaScript の制約は今よりはるかに緩く、動的型付けが当たり前の時代でした。
既存の連携を壊してしまう理想化された型定義を作るのではなく、実用的な方針を選びました。
-
現状をモデル化する:理想的とはいえないパターンを許容する必要があっても、現在の API インターフェースを正確に反映した型を定義します。
-
すべてをテストする:各型定義をテストハーネスで検証し、実際の API の動作と一致することを確認します。
-
段階的に洗練する:正確な型を土台に、常に後方互換性を確保しながら、スキーマと API 自体の両方を徐々に改善できます。
-
互換性を維持する:API に特有の挙動がある場合は、即座に変更を強いるのではなく、その挙動を文書化します。
この方針では、最初から見た目の美しい型になるとは限りません。単一の型を期待する箇所にユニオン型があったり、論理的には必須のはずのフィールドが省略可能になっていたりすることがあります。これは意図的なものです。異なる時期に異なる規約のもとで各エンドポイントが成長してきた、15 年にわたる API の進化を反映しています。
こうした慎重な進め方により、既存コードの動作を維持し、新しいコードには適切な指針を提供し、将来の改善の余地も残します。開発者にとっては、理想論よりも実態に忠実であることが重要だと考えています。型は、独特な挙動も含めて API の実態を正直に表しています。
移行ガイド
v3 から v4 への移行には、いくつかの重要な変更が必要です。
アップグレードの簡易チェックリスト
transloadit@^4.0.0に更新し、Node.js 20 以降を使用していることを確認します- デフォルトインポートを名前付きインポートに置き換えます
- CommonJS の
require呼び出しを削除します(代わりに動的インポートを使用します) - TypeScript を有効にするか JSDoc の型注釈を追加して、エディターの支援を強化します
- カスタムエラークラスを使用している場合は、エラー処理を更新します
validateResponsesを有効にして統合テストを実行し、想定外のスキーマ差異を検出します。エラーが発生した場合は、ぜひお知らせください。修正します。
レスポンスの検証(任意)
開発中に API レスポンスのランタイム検証を有効にできます。
const transloadit = new Transloadit({
authKey,
authSecret,
validateResponses: true, // This runs API responses through Zod, so you can have more confidence in the types. This will become the default in 5.x, but for this release it still defaults to false
})
開発体験の改善
新しい SDK は、モダンなワークフローにシームレスに統合できます。
- VS Code などの IDE での完全な IntelliSense 対応
- すべてのメソッドとパラメーターに対する詳細な JSDoc コメント
- デバッグを容易にするソースマップ
- 厳密な null チェックとの互換性
はじめに
新しい SDK をインストールします。
npm install transloadit@^4.0.0
クライアントを作成して、開発を始めます。
import { Transloadit } from 'transloadit'
const transloadit = new Transloadit({
authKey: 'YOUR_AUTH_KEY',
authSecret: 'YOUR_AUTH_SECRET',
})
// TypeScript knows exactly what's available
const assembly = await transloadit.createAssembly({
params: {
steps: {
optimize: {
use: ':original',
robot: '/image/optimize',
},
},
},
})
今後の予定は?
今回の v4 リリースは、TypeScript への取り組みの始まりにすぎません。API とスキーマの改善を続けながら、さらに精密な型、型定義から生成されるより充実したドキュメント、改善されたエラーメッセージ、互換性を維持した段階的なスキーマの改善を提供していきます。
今すぐ試す
Node SDK v4 は、npm と GitHub で公開しています。詳しいアップグレード手順は移行ガイドをご覧ください。ご感想もお待ちしています。
準備はできましたか?無料アカウントを作成して、TypeScript を活用した新しい SDK をぜひお試しください。
2026 年 2 月 2 日更新: Node.js SDK 全体を導入せずにスキーマや型を利用したい場合に向け、@transloadit/zod/v3、@transloadit/zod/v4、@transloadit/types も提供するようになりました。また、名称を @transloadit/node に変更しましたが、後方互換性のため、transloadit もそのクローンとして引き続き提供します.
