Uploads and frontend integration

# Integrate Transloadit in five minutes

Install the Node SDK, resize one image, and inspect a real Assembly result in about five minutes.

Published August 26, 2026

## Key takeaways

* Keep the Auth Secret on a trusted server and pass it through environment variables.
* Create one Assembly with an upload Step and an image-resize Step that fits the image within 400 × 400 pixels.
* Print both the result URL and Assembly ID so the first run is easy to inspect.

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.

## In this guide

1. [Start with one trusted server process](#transloadit-five-minute-integration-section-1)
2. [Install the SDK and prepare the command](#transloadit-five-minute-integration-section-2)
3. [Run the first Assembly](#transloadit-five-minute-integration-section-3)
4. [Inspect the result instead of stopping at success](#transloadit-five-minute-integration-section-4)
5. [Turn the proof into a production integration](#transloadit-five-minute-integration-section-5)
6. [Expose safe status, protect diagnostics, and keep a smoke test](#transloadit-five-minute-integration-section-6)

## What matters most

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

## Start with one trusted server process

Create a free Workspace, open the Credentials page, and generate an Auth Key and Auth Secret. You need both values for this server-side quickstart. Do not paste either value into the source file, and never send the secret to a browser. The Node SDK uses the pair to authenticate requests without transmitting the Auth Secret as a request credential.

Choose a small JPEG, PNG, WebP, or AVIF image already on disk. A modest input keeps the first run fast and makes the output easy to recognize. The script accepts the file path as its only command-line argument, so the same code can be retried with another fixture without editing it.

### Auth Key

Identifies the credential used for the Assembly and may be referenced safely by trusted integration code.

### Auth Secret

Stays in the server environment and is used by the SDK to authenticate the request.

### One local file

Keeps this run focused on the API path rather than browser upload state or remote imports.

## Install the SDK and prepare the command

Create an empty ES module project and add the current Node SDK with npm. In the next section, save the TypeScript listing as `quickstart.ts`, then run it with the command shown after the listing. This quickstart runs the TypeScript file directly with Node’s native type stripping, so it needs no `tsx` or `ts-node`. Native type stripping is enabled by default from Node 22.18 and 23.6, so use Node 22.18+, 23.6+, or 24. The SDK and the image are the only runtime inputs.

Pass credentials to the process with environment variables. Shell history, process inspection, CI logs, and local machine policy all affect whether inline environment assignments are appropriate, so use your normal secret manager for production. The command shown here is intentionally local and short-lived.

Scaffold the project and install the Node SDK

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

### One dependency

`@transloadit/node` handles authentication, file upload, status polling, and typed responses.

### Node 24

Runs the TypeScript file directly while preserving a copy-pasteable typed example.

### No secret file required

The quickstart reads the two credentials from the process environment.

## Run the first Assembly

Save the TypeScript listing below as `quickstart.ts`. The `:original` Step accepts the upload. The `resized` Step names `:original` in `use`, so it starts after the upload produces a file. Its `resize_strategy` is `fit`, which preserves aspect ratio and keeps both dimensions within 400 pixels instead of cropping the image to a square.

With `waitForCompletion` enabled, `createAssembly` returns once the Assembly reaches a terminal state. That blocking behavior makes the first result obvious, but it is a teaching convenience rather than a default architecture for slow videos, large batches, or a request handler with a short timeout.

Upload and resize one image

```
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)
})
```

Run the quickstart

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

### :original

The reserved upload Step that makes incoming files available to later Robots.

### resized

A name chosen by the integration; it also becomes the key used to read these result files.

### fit

Bounds the output without stretching or removing image content.

## Inspect the result instead of stopping at success

Open the printed HTTPS result URL and confirm that the dimensions and visible content match the request. Then open the Assembly in the Transloadit Console using its ID. Assembly Status shows uploads, Step results, timestamps, metadata, and any error, which makes it the first place to compare what the application requested with what the platform executed.

Keep the Assembly ID next to your own job or asset identifier. A URL alone is not enough for troubleshooting because it does not explain which input, parameters, or Step produced it. In production, persist the specific result fields your application needs rather than storing or returning a raw third-party response wholesale.

### Visual check

Confirms the workflow produced the intended rendition rather than only a successful status code.

### Assembly Status

Provides the processing trace and metadata for debugging and reconciliation.

### Application record

Connects the external Assembly ID to the user, input, and business action that initiated it.

## Turn the proof into a production integration

Temporary Assembly files are retained for about 24 hours and are intended for a limited number of short-term retrievals, not for serving directly to end users. Add an export Robot such as `/s3/store`, `/azure/store`, or the destination your application owns before a result becomes durable. Store cloud keys as Template Credentials, not as literal values in application code or Assembly Instructions.

Next, save the Steps as a Template, set `allow_steps_override` to false when callers must not change the graph, and send only its `template_id` plus validated fields. Browser uploads need signed, expiring parameters generated by a backend. Background work should return an application job ID immediately, consume a verified webhook, accept duplicate deliveries safely, and reconcile against Assembly Status when a notification is missed.

### Permanent export

Moves results out of the default temporary retention window and into owned storage.

### Saved Template

Keeps the processing graph controlled while integrations submit a compact Template ID.

### Verified completion

A signed webhook and periodic reconciliation make long-running jobs recoverable.

## Expose safe status, protect diagnostics, and keep a smoke test

A production interface should show a concise application-owned state such as queued, processing, ready, or failed. Operators still need a protected path from that record to the Assembly ID and sanitized diagnostics. Do not return raw provider errors, stack traces, storage responses, or credential-bearing URLs to end users merely because the quickstart prints a result to a terminal.

Keep a tiny known-good image and the expected output constraints as a smoke test. Run it after credential rotation or a controlled workflow change, but do not make a paid external Assembly part of every unit-test run. Unit tests should validate local policy and mapping, while an explicit integration check proves the live credential, upload, Robot, and result path together.

### Safe client state

Expose an actionable status without leaking a third-party response or internal exception.

### Protected trace

Let authorized operators reach the Assembly ID and the diagnostics needed to investigate.

### Known-good fixture

Separates live integration failures from unusual customer media when the path is tested.

## 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 debugging reference even when an application stores its own higher-level job identifier.

## A practical approach

1. 1\
   Create an Auth Key and choose a small local image.
2. 2\
   Install the Node SDK and run the TypeScript quickstart with credentials in the environment.
3. 3\
   Open the printed result URL and inspect the Assembly in the Console.
4. 4\
   Move the workflow into a saved Template and add permanent storage before production use.

A four-stage media workflow

## 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.

## Frequently asked questions

### Can I put the Auth Secret in browser JavaScript for this quickstart?

No. The example is server-side. A browser should request signed, short-lived Assembly parameters from a backend that keeps the Auth Secret private.

### Why does the script wait for completion?

`waitForCompletion` makes a first run easy to verify by returning the finished result. Production request handlers should normally start background work and use a verified webhook or controlled status polling.

### Where is the resized image stored?

It is a temporary Assembly result retained for 24 hours by default. Add a storage Robot to keep it permanently in a destination you control.

### Why use `fit` instead of `fillcrop`?

`fit` preserves the complete image and constrains it to the requested box. `fillcrop` fills exact dimensions by cropping, which requires an intentional composition decision.

### What should I save after the Assembly finishes?

Save the Assembly ID, your own job or asset ID, the selected result metadata and durable storage location, and a sanitized terminal status. Do not expose the entire raw response to clients by default.

## Build the workflow

Move from the concept to a tested Assembly with Robot documentation and working demos.

### Relevant Robots

* [/upload/handle](/docs/robots/upload-handle.md)
* [/image/resize](/docs/robots/image-resize.md)
* [Create an Auth Key](/c/credentials/)
* [Read the Node SDK documentation](/docs/sdks/node-sdk.md)
* [Store results permanently](/docs/getting-started/saving-conversion-results.md)
* [Read the API documentation](/docs.md)
* [Explore working demos](/demos.md)
* [Create a free workspace](/c/signup/)

Uploads and frontend integration

## Continue with related guides

* [Customizable media processing workflows with Transloadit](/guides/customizable-media-processing-workflows.md)\
  Design a reusable Template with validation, variables, parallel derivatives, secure storage, and observable completion.
* [File Upload API guide: architecture, security, and provider selection](/guides/file-upload-api-guide.md)\
  Choose and implement a File Upload API by comparing architecture, resumability, direct-to-cloud transfer, security, storage boundaries, and providers.
* [React file uploads with Uppy: resumability, previews, validation, and processing](/guides/react-file-uploads-with-uppy.md)\
  Build a React file uploader with Uppy that handles previews, validation, accessible progress, cancellation, resumable transfer, and a Transloadit processing handoff.
* [File uploads, image optimization, and your own S3 bucket](/guides/file-uploads-image-optimization-s3.md)\
  Combine resumable browser uploads, image optimization, customer-owned Amazon S3 storage, and on-demand delivery without operating separate media services.
* [HTML video in production: 10 practical checks](/guides/html-video-production-checklist.md)\
  Ten production checks for HTML video, from source selection and captions to poster images and preprocessing.
* [Three best practices for CSS banner images](/guides/css-banner-image-best-practices.md)\
  Three durable practices for sharp, responsive CSS banner images without unreadable text or accidental crops.