Allow custom file path/folder for S3 uploads

[melihciray]

Initial checklist

• I understand this is a feature request and questions should be posted in the Community Forum
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

Currently, @tus/s3-store uploads all files directly to the root of the configured S3 bucket. There’s no built-in way to define a custom subdirectory or path prefix, which makes organizing uploads (by tenant, environment, or project) difficult.

I opened a PR (#804) to address this by adding support for a configurable path prefix. With this change, developers can specify a folder like uploads/test/ so files are stored under:

s3://your-bucket/uploads/test/<file-id>

instead of:

s3://your-bucket/<file-id>

This enhancement keeps full backward compatibility and has been tested with AWS S3 and MinIO.
Thank you for reviewing 🙏

Solution

The S3 store should allow specifying a custom path or folder (e.g. uploads/test/) where uploaded files will be saved, instead of always storing them at the root of the bucket.

Developers should be able to configure this behavior through a simple option like keyPrefix , and the server should automatically prepend that prefix to the uploaded file key.

Alternatives

Currently, the only alternative is to manually override or modify the uploaded object key inside a custom S3Store subclass, or handle file movement after upload via an external S3 operation (e.g. using AWS SDK to move the file to a folder).

However, these workarounds are not ideal — they add extra complexity and require maintaining a custom implementation instead of using the official package directly.

[Murderlon]

Have you tried this? https://github.com/tus/tus-node-server/tree/main/packages/server#example-store-files-in-custom-nested-directories

This would get confusing as there would be two ways (namingFunction, keyPrefix) to achieve the same thing.

[melihciray]

I see now , both namingFunction and keyPrefix can basically achieve the same thing, especially for S3.
I initially missed that when I was looking through the examples, so thanks for pointing it out.
Since namingFunction already lets me organize uploads into custom folder-like paths, I think that’s enough for my use case.

[Murderlon]

I'll admin it's not the best DX, ideally you can use namingFunction without having to do the whole generateUrl and getFileIdFromRequest, but that requires a major version.