Platforms and integrations

# Normalize Supabase Storage documents to PDF

Import a controlled Supabase Storage document batch, normalize supported office files to PDF, and export them to a separate prefix.

Published September 1, 2026

## Key takeaways

* Limit the import prefix to supported office formats; a mixed bucket is not a conversion contract.
* Paginate recursive imports and checkpoint each completed page instead of assuming one Assembly covers the library.
* Write PDFs to a separate prefix so subsequent import runs do not consume their own results.

Supabase Storage can hold product documents without being the system that converts them. A batch workflow is useful when an application has accumulated office files that need a consistent PDF representation for review, download, or downstream indexing. The safe design treats conversion as a versioned derivative job rather than rewriting the original object.

## In this guide

1. [Create a convertible document inbox](#supabase-document-processing-workflow-section-1)
2. [Paginate and checkpoint recursive imports](#supabase-document-processing-workflow-section-2)
3. [Build the Supabase PDF Template](#supabase-document-processing-workflow-section-3)
4. [Verify the PDF and application record](#supabase-document-processing-workflow-section-4)
5. [Design retries and retention per object](#supabase-document-processing-workflow-section-5)
6. [Observe the batch independently of user traffic](#supabase-document-processing-workflow-section-6)

## What matters most

* Use separate read and write Template Credentials or narrowly scoped S3 access keys where practical.
* Record source path, source version, Assembly ID, output path, and workflow version in the application database.
* Treat the stored object’s bucket permissions as the access control, and record the destination path rather than a result URL as the document’s identity.

## Create a convertible document inbox

Do not point recursive import at a mixed production bucket. Create an inbox prefix whose contract is limited to the office and text formats selected for PDF conversion. Images, archives, and unrelated application objects are outside this workflow’s scope, so route or exclude them explicitly. PDF is not a supported input for /document/convert, so route existing PDFs around this Step.

Write the contract into the upload or application path that populates the inbox. Validate filename, detected type, size, tenant ownership, and document state before scheduling processing. A storage object’s extension is useful routing data but not authoritative content validation.

## Paginate and checkpoint recursive imports

/supabase/import can recurse through a directory and paginate with page\_number and files\_per\_page. Treat each page as a bounded execution. Store the page request and the source objects observed in the application so a crash or retry can resume without assuming the bucket stayed unchanged.

Keep the normalized output prefix outside the imported inbox. Otherwise a later recursive run can encounter its own PDFs, which this conversion branch is not designed to accept. A separate bucket is even clearer when retention or permissions differ.

### Inbox

Contains only source formats eligible for the current conversion policy.

### Normalized output

Contains versioned PDFs and is excluded from every inbox traversal.

### Database record

Maps each source version to its Assembly, output object, and workflow state.

## Build the Supabase PDF Template

The Template imports the bounded inbox prefix, converts each emitted office document to PDF, and stores each result beneath a normalized path containing Assembly uniqueness. /supabase/store requires a file path rather than a directory, so the path must end in a concrete filename expression.

The sample references separate read and write credential names. Supabase exposes an S3-compatible Storage connection; keep its endpoint and access keys in Template Credentials. Store the output bucket and path as the durable identity. Set sign\_urls\_for only when the application needs an expiring signed\_ssl\_url; when it is omitted, no URL signing is done.

Convert a bounded Supabase office-document page to versioned PDFs

```
{
  "allow_steps_override": false,
  "steps": {
    "office_inbox": {
      "robot": "/supabase/import",
      "credentials": "supabase-document-read",
      "path": "documents/office-inbox/",
      "recursive": true,
      "page_number": 1,
      "files_per_page": 100
    },
    "normalized_pdf": {
      "use": "office_inbox",
      "robot": "/document/convert",
      "format": "pdf"
    },
    "supabase_output": {
      "use": "normalized_pdf",
      "robot": "/supabase/store",
      "credentials": "supabase-document-write",
      "path": "documents/normalized-pdf-v1/${assembly.id}/${unique_prefix}/${file.url_name}",
      "result": true
    }
  }
}
```

## Verify the PDF and application record

Test DOCX, ODT, PPTX, XLSX, HTML, and Markdown fixtures only if the product promises those inputs. Review page count, fonts, tables, formulas, links, headers, and non-Latin text. Unsupported or fidelity-sensitive files should enter a visible review state rather than being silently marked normalized.

After export, update the application database idempotently with the source path and version, workflow version, Assembly ID, output bucket and path, and terminal state. Supabase Storage does not update the database row that represents the document; the application must reconcile that relationship.

## Design retries and retention per object

One bad document should not require replaying a complete directory page. Track success and failure per source identity, then retry only the source objects the application has not recorded as complete. The sample path is unique per run, so processing the same source again writes a new object; de-duplication comes from the application’s source-to-result record, checked before another Assembly is created.

Keep originals until the application’s retention policy permits deletion and the normalized PDFs have passed review. Record separately whether the PDF is a viewing rendition or the reviewed record copy, instead of allowing the output prefix to decide that business role.

## Observe the batch independently of user traffic

Run large normalization batches through a queue or scheduled worker rather than an interactive request. Monitor page checkpoints, object-level failures, Assembly duration, output bytes, and Supabase export errors. Surface an operator-visible list of unresolved source objects instead of burying provider responses in logs.

Throttle work so recursive imports, document conversion, and writes do not overwhelm application databases or storage access. Use a small representative rollout first, then increase concurrency only after completion, retry, and webhook behavior are measured under realistic files.

## Technical details worth knowing

* /supabase/import accepts one path, an array of paths, or a directory path. Recursive imports use page\_number and files\_per\_page.
* /document/convert supports office and text formats including DOCX, ODT, PPTX, XLSX, HTML, and Markdown, with PDF available as an output.
* PDF is not a supported input for /document/convert. Route existing PDFs around conversion and convert only supported source formats.
* /supabase/store requires a file path rather than a directory path and can include Assembly Variables in that path.
* /supabase/store defaults the Content-Type header to the processed file’s detected MIME type. Set sign\_urls\_for to return an expiring signed\_ssl\_url; when it is omitted, no URL signing is done.
* Supabase import and store use its S3-compatible Storage connection. Template Credentials keep the endpoint and access keys out of the saved Instructions.

## A practical approach

1. 1\
   Define the convertible inbox, output prefix, pagination size, and application record transition.
2. 2\
   Create scoped Supabase credentials and save the import–convert–store Template.
3. 3\
   Convert representative DOCX, PPTX, and ODT files and review layout and metadata.
4. 4\
   Run bounded pages with checkpoints, idempotent records, and a retry path for failed objects.

A four-stage media workflow

## When Transloadit is useful

Use this workflow for batch normalization of a document library already held in Supabase Storage. Use /supabase/import for a bounded file or paginated prefix, /document/convert for supported office-to-PDF conversion, and /supabase/store for the resulting object. Keep the inbox limited to convertible formats, separate input and output prefixes, and reconcile each exported path with its Supabase database record.

## Architecture boundary

Supabase Storage owns the source and output objects, while the application owns tenant access, database records, document status, retention, and publication. Transloadit processes only the objects selected by the saved workflow and does not update application rows automatically.

## Frequently asked questions

### Can the inbox contain existing PDFs?

No. PDF is not a supported input for /document/convert. Keep PDFs outside this office-file inbox or route them around the conversion Step.

### Can one Assembly convert an entire bucket?

Recursive imports can cover directories, but bounded pages with durable checkpoints are safer for large or changing libraries.

### Why use a separate output prefix?

It prevents recursive imports from reading generated PDFs as new source documents and makes retention, rollback, and permissions easier to reason about.

### Which result URL should the application store?

Store the destination bucket and path as the durable identity, not a result URL. Set sign\_urls\_for when the application needs an expiring signed\_ssl\_url; when it is omitted, /supabase/store does not sign a URL.

### Does Transloadit update our Supabase database row?

No. The application must reconcile the Assembly result with its own tenant, document, and version records.

## Build the workflow

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

### Relevant Robots

* [/supabase/import](/docs/robots/supabase-import.md)
* [/document/convert](/docs/robots/document-convert.md)
* [/supabase/store](/docs/robots/supabase-store.md)
* [Import from Supabase Storage](/docs/robots/supabase-import.md)
* [Convert office documents to PDF](/docs/robots/document-convert.md)
* [Export to Supabase Storage](/docs/robots/supabase-store.md)
* [Protect Supabase credentials](/docs/topics/template-credentials.md)
* [Build non-overlapping output paths](/docs/topics/assembly-variables.md)
* [Read the API documentation](/docs.md)
* [Explore working demos](/demos.md)
* [Create a free workspace](/c/signup/)

Platforms and integrations

## 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.
* [A complete guide to digital-asset workflows](/guides/digital-asset-workflows.md)\
  Design a digital-asset workflow from intake and processing through review, publication, retention, and deletion.
* [How to extract text from documents and images at scale](/guides/extract-text-from-documents-and-images.md)\
  Recognise text across PDFs, scans, and photographs, and keep the result attached to the file it came from.
* [Convert uploaded documents to PDF and store them in Box](/guides/upload-convert-documents-pdf-box.md)\
  Turn uploaded office documents into consistent PDFs and place them in a controlled Box folder without exposing storage credentials.
* [Four pillars of digital transformation in retail](/guides/retail-digital-transformation-pillars.md)\
  Connect customer experience, operations, data, and platform modernization through a practical retail media layer.
* [Magento media optimization for technical SEO](/guides/magento-media-seo.md)\
  Improve Magento media performance and image search hygiene as part of a broader technical SEO program.