Your first Transloadit integration with Node.js

The shortest useful Transloadit integration is a server-side script that uploads one image and produces one derivative. It proves that credentials, file transfer, processing, and result handling work before a browser, storage destination, database, or webhook adds more moving parts.

What matters most

• Treat the returned file as temporary until an export Step stores it permanently.

mkdir transloadit-quickstart
cd transloadit-quickstart
npm init -y
npm pkg set type=module
npm install @transloadit/node

import { Transloadit } from '@transloadit/node'

async function main(): Promise<void> {
  const authKey = process.env.TRANSLOADIT_KEY
  const authSecret = process.env.TRANSLOADIT_SECRET
  const inputPath = process.argv[2]

  if (authKey == null || authSecret == null || inputPath == null) {
    throw new Error(
      'Set TRANSLOADIT_KEY and TRANSLOADIT_SECRET, then pass an image path.',
    )
  }

  const transloadit = new Transloadit({ authKey, authSecret })
  const assembly = await transloadit.createAssembly({
    files: { image: inputPath },
    params: {
      steps: {
        ':original': {
          robot: '/upload/handle',
        },
        resized: {
          use: ':original',
          robot: '/image/resize',
          result: true,
          width: 400,
          height: 400,
          resize_strategy: 'fit',
        },
      },
    },
    waitForCompletion: true,
  })

  const result = assembly.results?.resized?.[0]
  if (result == null) {
    throw new Error(`Assembly ${assembly.assembly_id} produced no resized result.`)
  }

  console.log(`Result: ${result.ssl_url}`)
  console.log(`Assembly: ${assembly.assembly_id}`)
}

main().catch((error: unknown) => {
  if (!(error instanceof Error)) {
    throw new Error(`Was thrown a non-error: ${error}`)
  }

  console.error(error.message)
  process.exit(1)
})

env \
  TRANSLOADIT_KEY="YOUR_TRANSLOADIT_KEY" \
  TRANSLOADIT_SECRET="YOUR_TRANSLOADIT_SECRET" \
  node quickstart.ts ./your-image.jpg

Technical details worth knowing

• An Assembly is one execution of Assembly Instructions. Each processing Step invokes one Robot and declares its upstream input with use; the reserved :original upload Step is the source and takes no use.
• The Node SDK generates request authentication from the Auth Key and Auth Secret. The secret belongs only in a trusted server process, never in browser JavaScript or a mobile application.
• Setting waitForCompletion to true makes the SDK poll until the Assembly reaches a terminal state, which is convenient for a small first run but unsuitable for long request handlers.
• The result flag marks a Step’s files for inclusion in the top-level Assembly results object. It does not make the files permanent.
• Temporary Assembly files are available for about 24 hours and a limited number of retrievals by default. Do not serve their URLs directly to end users; add an export Robot for user-facing files.
• The Assembly ID is a useful private debugging reference, but anyone holding it or the status URL can read Assembly Status without further authentication. Keep both out of public logs and client responses; use your own application job identifier for those surfaces.

A practical approach

When Transloadit is useful

Use the Node SDK to create an Assembly containing /upload/handle and /image/resize. The SDK signs the request with server-side credentials, uploads the local file, waits for completion, and returns the result URL and Assembly ID.

Architecture boundary

This quickstart runs on a trusted server and waits for one small image to finish. A browser integration must receive signed, short-lived parameters from a backend, while production background work should use a verified webhook instead of holding an HTTP request open.