Registry / storage / keystone-storage-adapter-s3

keystone-storage-adapter-s3

library2.0.0jsnpmunverified

S3-based storage adapter for KeystoneJS (v2.0.0). Designed to replace the existing S3File field using the new storage API. Provides persistent file storage on Amazon S3 with configurable bucket, region, path, custom public URLs, and upload parameters. Supports per-file schema fields for bucket, path, etag, and URL. Release cadence is low/maintenance; this package is stable but tied to the older KeystoneJS stack (not Keystone Next). Alternatives include multer-s3 or direct S3 SDK, but this integrates directly with Keystone's file field system.

storage

npm install keystone-storage-adapter-s3

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KEYSTONE-STORAGE-A

keystone-storage-adapter-s3

storagejavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ const keystoneStorageAdapterS3 = require('keystone-storage-adapter-s3');

✗ import keystoneStorageAdapterS3 from 'keystone-storage-adapter-s3';

Package is CJS-only, no ESM export. Must use require().

adapter

✓ adapter: require('keystone-storage-adapter-s3')

✗ adapter: 'keystone-storage-adapter-s3'

Pass the required module directly, not a string path.

Schema fields

✓ schema: { bucket: true, etag: true, path: true, url: true }

✗ schema: { bucket: false, etag: false }

Omitting schema fields is valid but they will not be stored. Set to true to enable.

Configure S3 storage adapter with environment variables, custom public URL, and schema fields; then attach to a Keystone File field.

// Install: npm install keystone-storage-adapter-s3 const keystone = require('keystone'); const Types = keystone.Field.Types; const storage = new keystone.Storage({ adapter: require('keystone-storage-adapter-s3'), s3: { key: process.env.S3_KEY || '', secret: process.env.S3_SECRET || '', bucket: process.env.S3_BUCKET || 'mybucket', region: process.env.S3_REGION || 'us-east-1', path: '/uploads', publicUrl: (file) => `https://cdn.example.com${file.path}/${file.filename}`, uploadParams: { ACL: 'public-read' }, }, schema: { bucket: true, etag: true, path: true, url: true, }, }); // Define a List with a File field using this storage const FileList = new keystone.List('File'); FileList.add({ name: { type: String }, file: { type: Types.File, storage: storage }, }); FileList.register();

Debug

Known issues

gotchaAWS credentials (key, secret) must be explicitly provided or set via environment variables S3_KEY and S3_SECRET. Missing credentials cause upload failures.

fix

Set S3_KEY and S3_SECRET environment variables or pass options with key and secret.

affects: >=1.0.0

gotchaThe bucket must already exist; the adapter does not create buckets. Uploads to a non-existent bucket will fail.

fix

Create the S3 bucket via AWS console or SDK before using the adapter.

affects: >=1.0.0

deprecatedThis adapter is for the legacy KeystoneJS (v4/v5) and is not compatible with Keystone Next (v6+).

fix

For Keystone Next, use the prisma-based storage or custom S3 integration.

affects: >=2.0.0

gotchaPath option must be absolute (e.g., '/images/profilepics'). Relative paths will be treated as absolute from root.

fix

Always start path with '/'

affects: >=1.0.0

gotchaThe publicUrl option only supports a string domain or a function that returns the full URL. The file.path and file.filename may be undefined if not stored in schema.

fix

If using publicUrl function, ensure schema.path and schema.url are enabled to have file.path available.

affects: >=1.0.0

Errors

Common errors & fixes

Error: ENOENT: no such file or directory, open '...'

Missing or incorrect path configuration; adapter tries to write to local filesystem instead of S3.

fix

Ensure adapter is properly configured with s3 options and not fallback to local file adapter.

AccessDenied: Access Denied

AWS credentials lack permission to upload to the specified S3 bucket.

fix

Check IAM policy and ensure key/secret have s3:PutObject permission on the bucket.

NoSuchBucket: The specified bucket does not exist

Bucket name is incorrect or bucket not created.

fix

Verify bucket name and create it if necessary.

TypeError: keystone.Storage is not a constructor

Using Keystone Next (v6+) where Storage API does not exist.

fix

Use the legacy KeystoneJS v4/v5 or switch to Keystone Next's native storage approach.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

keystonerequiredPeer dependency: requires KeystoneJS's storage API and Types.File field.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/keystonejs/keystone-storage-adapter-s3 ↗

packagekeystone-storage-adapter-s3 ↗

homepagehttps://github.com/keystonejs/keystone-storage-adapter-s3 ↗