Rewrite of Image and Files (breaking)

[rohan-deshpande]

Warning: This new feature includes breaking changes that may affect you

This pull request replaces image and files configuration options in Keystone's configuration, and replaces them with a new storage configuration object.

• ➕ Amazon S3 (and other compatible providers) are now supported when uploading images and files
• ➕ New Guide coming - see Add Images and Files Guide to Keystone Docs #7563 will be merged soon but check it out if you are keen
• 🚨 Images and files are now - DELETED BY DEFAULT from the underlying storage provider when replaced or deleted from the database

  • Note: A preserve flag has been added to the new storage configurations to default back to the previous behaviour

• ⚠️ If you were previously using refs in your application, you need to migrate your database

How to upgrade

Previously, your images and files were managed in your root Keystone configuration, under the fields .images and .files respectively.
The underlying storage mechanism was denominated through an upload field on each respectively, and you had no easy way to modify this behaviour for different fields.

It probably looked something like this

export default config({
  image: { upload: 'local' },
  lists: {
    Image: { fields: { image: image() } },
    /* ... */
  },
  /* ... */
});

As of this pull request, there is now a unified .storage configuration object that can contain multiple different storage providers, which you can optionally share or differentiate between for different fields as desired.
A canonical example for storing some images on the local filesystem might look something like the following:

export default config({
  storage: {
    my_avatars: {
      kind: 'local',
      type: 'image',
      generateUrl: path => `http://localhost:3000/avatars${path}`,
      serverRoute: { path: '/avatars' },
      storagePath: 'public/avatars',
    },
  },
  lists: {
    User: {
		fields: {
			avatar: image({ storage: 'my_avatars' })
		}
	 },
    // ...
  },
  // ...
});

A canonical example for storing some images on an S3 compatible storage provider might look something like the following:

export default config({
  storage: {
    my_avatars: {
      kind: 's3',
      type: 'image',
      bucketName: process.env.S3_BUCKET_NAME,
      region: process.env.S3_REGION,
      accessKeyId: process.env.S3_ACCESS_KEY_ID,
      secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
    },
  },
  lists: {
    User: {
		fields: {
			avatar: image({ storage: 'my_avatars' })
		}
	 },
	// ...
  },
  // ...
});

Goodbye refs

The previous implementation of refs were useful for moving images between different lists using the admin interface, allowing a user to refer to same image or file without copying that duplicating that image or file at the storage layer.
Unfortunately, this creates a precarious and imperformant situation when you want or need to delete these images or file; you then need to undertake a form of ref-counting across your different lists in a custom hook to ensure you won't 404 the the underlying image or file.

This complexity didn't really pay off for the benefits it provided, when compared with typical Keystone relationships; and in fact the inability to use GraphQL to introspect these references was inhibitive.
The end result is images or files are left to orphan and/or duplicate themselves until some external reason results in the manual database and storage layer interventions.

With refs removed, the new recommendation for sharing images between lists and fields is an approach you may already be familiar with: Keystone Relationships.
A canonical examle for sharing an image between multiple lists might look something like the following:

export default config({
  storage: {
    my_images: {
      // ...
    },
  },
  lists: {
    Image: { fields: { image: image({ storage: 'my_images' }) } },
    User: { fields: { avatar: relationship({ ref: 'Image' }) } },
    Post: { fields: { photos: relationship({ ref: 'Image', many: true }) } },
    // ...
  },
  // ...
});

Using Keystone relationships allows you to mirror the previous functionality while supporting the needs and features required when scaling up.

What if I can't?

If you can't migrate your schema to use Keystone relationships, but you still want to update your Keystone instance to the new storage configuration, you can use preserve: true to ensure that files - that are replaced or deleted from the database - are not deleted from the underlying storage layer.
However, similar to the previous behaviour prior to this pull request, this will result in images and files becoming orphans within the relevant filesystems as they are removed from the database.

Other changes

Local images no longer need a baseUrl

If you were previously using baseUrl for your upload: 'local', the configuration approach has changed to serverRoute.path.

For example

{
-   baseUrl: '/images'
+   serverRoute: {
+       path: '/images'
+   }
}

[boyboy1995]

Hi, is this file config written in the right way to using s3 storage for file field? For some reasons all properties not being recognized in the storage object.

[Andrey-Bazhanov]

looks like this is not released yet... documentation is updated but @keystonejs/core - not