Introduction

Amazon S3 does not have real folders in the filesystem sense. It stores objects by key, and folder views in the console are just key prefixes separated by /. In Node.js, creating a folder usually means creating a zero-byte object whose key ends with /, or simply uploading objects under that prefix.

Understand Keys, Prefixes, and Folder Illusion

If you upload an object with key reports/2026/march.csv, S3 treats the full string as the object key. The console shows nested folders because it groups keys by delimiter. This means you can often skip explicit folder creation and write objects directly using the full key path.

For teams new to S3, this model explains why deleting a folder in the console often just removes objects with a shared prefix.

Setup AWS SDK for JavaScript v3

Use the modular SDK package and authenticate with IAM role, profile, or environment variables.

npm install @aws-sdk/client-s3

1import { S3Client } from "@aws-sdk/client-s3";
2
3export const s3 = new S3Client({
4  region: process.env.AWS_REGION || "us-east-1",
5});

When running on EC2, ECS, or Lambda, prefer role-based credentials instead of hardcoded keys.

Create a Folder Marker Key

A folder marker is a zero-byte object ending in slash. It is optional, but can be useful when you want the prefix visible in tools before any real files exist.

1import { PutObjectCommand } from "@aws-sdk/client-s3";
2import { s3 } from "./s3-client.js";
3
4export async function createFolder(bucket, prefix) {
5  const normalizedPrefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
6
7  const command = new PutObjectCommand({
8    Bucket: bucket,
9    Key: normalizedPrefix,
10    Body: "",
11    ContentType: "application/x-directory",
12  });
13
14  await s3.send(command);
15  return normalizedPrefix;
16}
17
18// Example
19await createFolder("my-app-bucket", "uploads/images");

This produces a key such as uploads/images/ with zero content.

Create an Object Under a Prefix

In most production systems, you can skip folder markers and upload the real object directly.

1import { PutObjectCommand } from "@aws-sdk/client-s3";
2import { readFile } from "node:fs/promises";
3import { s3 } from "./s3-client.js";
4
5export async function uploadReport(bucket, localPath) {
6  const file = await readFile(localPath);
7
8  const command = new PutObjectCommand({
9    Bucket: bucket,
10    Key: "reports/2026/march-summary.json",
11    Body: file,
12    ContentType: "application/json",
13  });
14
15  await s3.send(command);
16}

After upload, the console automatically shows the reports and 2026 folder levels.

Verify Prefix Contents

Listing by prefix helps confirm creation and supports admin tooling.

1import { ListObjectsV2Command } from "@aws-sdk/client-s3";
2import { s3 } from "./s3-client.js";
3
4export async function listPrefix(bucket, prefix) {
5  const command = new ListObjectsV2Command({
6    Bucket: bucket,
7    Prefix: prefix.endsWith("/") ? prefix : `${prefix}/`,
8  });
9
10  const result = await s3.send(command);
11  return (result.Contents || []).map(obj => obj.Key);
12}

For large prefixes, handle pagination using ContinuationToken until IsTruncated is false.

Security and Design Guidance

Keep IAM policies scoped to required bucket paths. For example, an upload service may only need s3:PutObject under uploads/* and list access for one prefix. Avoid broad wildcard access for all buckets.

Choose key naming conventions early. Include stable partition fields such as tenant id, date, and file purpose. Predictable keys simplify lifecycle policies, analytics, and bulk cleanup.

Common Pitfalls

A common misunderstanding is expecting an API call named folder creation. In S3, folder behavior is key naming, not a separate resource type. Another issue is missing trailing slash when creating a marker object, which results in a regular object key instead of a visible folder-like node. Developers also forget content type metadata and later see incorrect behavior in downstream consumers. Finally, large list operations can become slow or expensive if prefixes are too broad, so design key partitions to keep list scopes narrow.

Summary

• S3 folders are key prefixes, not actual directories.
• Create folder markers with zero-byte keys ending in / only when needed.
• Most workflows can upload objects directly under a prefix.
• Use ListObjectsV2 with prefix filters to validate organization.
• Apply least-privilege IAM and consistent key naming from day one.