S3 | EdgeStore

Learn how to use your own AWS S3 bucket or an S3-compatible service with EdgeStore.

You can also use the EdgeStore package with your own AWS S3 bucket. You might want to do that in case you have strict company policies that require you to have all the data in your own AWS account.

You can also use the S3 provider with other S3-compatible storage services like MinIO.

By using this provider, you will be able to use most of the basic features of EdgeStore. However, for some of the more advanced features like access control with protected files, you will have to create your own infrastructure and logic from scratch.

Installation

You need to install some peer dependencies to use this provider.

npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

Then configure the provider together with the router and pass the resulting configuredEdgeStore instance to the adapter.

import { createEdgeStore, initEdgeStore } from '@edgestore/server';
import {
  createEdgeStoreNextHandler,
  type CreateContextOptions,
} from '@edgestore/server/adapters/next/pages';
import { s3 } from '@edgestore/server/providers/s3';
import { z } from 'zod';

// ...

const configuredEdgeStore = createEdgeStore({
  router,
  provider: s3(),
});

export default createEdgeStoreNextHandler<Context>({
  edgestore: configuredEdgeStore,
  createContext,
});

Options

export type S3ProviderOptions = {
  /**
   * AWS SDK credentials (or credentials provider) to use for S3 requests.
   *
   * If unset, the AWS SDK will use its default credential provider chain
   * (environment variables, shared config files, instance/task roles, etc).
   */
  credentials?: S3ClientConfig['credentials'];
  /**
   * AWS region to use.
   * Can also be set via the `ES_AWS_REGION` environment variable.
   */
  region?: string;
  /**
   * Name of the S3 bucket to use.
   * Can also be set via the `ES_AWS_BUCKET_NAME` environment variable.
   */
  bucketName?: string;
  /**
   * Custom endpoint for S3-compatible storage providers (e.g., MinIO).
   * Can also be set via the `ES_AWS_ENDPOINT` environment variable.
   */
  endpoint?: string;
  /**
   * Force path style for S3-compatible storage providers.
   * Can also be set via the `ES_AWS_FORCE_PATH_STYLE` environment variable.
   * Defaults to false for AWS S3, but should be true for most S3-compatible providers.
   */
  forcePathStyle?: boolean;
  /**
   * Base URL to use for accessing files.
   * Only needed if you are using a custom domain or cloudfront.
   *
   * Can also be set via the `EDGE_STORE_BASE_URL` environment variable.
   */
  baseUrl?: string;
  /**
   * Secret to use for encrypting JWT tokens.
   * Can be generated with `openssl rand -base64 32`.
   *
   * Can also be set via the `EDGE_STORE_JWT_SECRET` environment variable.
   */
  jwtSecret?: string;
  /**
   * Customizes the object path beneath the logical EdgeStore bucket prefix.
   *
   * The logical bucket prefix is always preserved so router authorization for
   * one bucket cannot access objects from another.
   */
  path?: (args: {
    edgestoreBucketName: string;
    fileInfo: FileInfo;
    defaultPath: string;
  }) => Promise<string> | string;
};

Customizing S3 Object Paths

By default, the S3 provider uses the same path-generation logic as the hosted provider. The first object-key segment is always the logical EdgeStore router bucket. This lets multiple logical buckets safely share one physical S3 bucket:

documents/_public/acme/invoice.pdf
avatars/_public/user-123/profile.png

Use path to customize everything beneath that protected prefix. For example, this removes _public while keeping the remaining generated path:

src/server/edgestore.ts

const configuredEdgeStore = createEdgeStore({
  router,
  provider: s3({
    path: ({ defaultPath }) => {
      // `documents/_public/acme/invoice.pdf`
      // becomes `documents/acme/invoice.pdf`
      return defaultPath.replace(/^_public\//, '');
    },
  }),
});

const handler = createEdgeStoreNextHandler({
  edgestore: configuredEdgeStore,
  createContext,
});

The callback returns a path relative to the logical bucket and cannot escape that boundary. It also receives edgestoreBucketName and fileInfo when you need provider-specific naming logic.

If you remove _public, you might also want to disable the development proxy in createEdgeStoreProvider.

const { EdgeStoreProvider, useEdgeStore } =
  createEdgeStoreProvider<EdgeStoreRouter>({
    disableDevProxy: true,
  });

Using with Minio

You can use the S3 provider with MinIO or other S3-compatible storage providers by setting the endpoint and forcePathStyle options.

provider: s3({
  endpoint: 'http://localhost:9000', // can be set via the `ES_AWS_ENDPOINT` environment variable
  forcePathStyle: true, // can be set via the `ES_AWS_FORCE_PATH_STYLE` environment variable
}),

S3

Installation

Options

Customizing S3 Object Paths

Using with Minio

On this page