RFC: Allow specifying a custom image optimizer image cache folder using an environment variable

[zmarty]

Summary

Image Optimizer stores cached images under {distDir}/cache/images. This RFC proposes making this path configurable such that the cached images can be stored in a different location that can be even outside of the folder of the project.

Background

Depending on how you look at it, Azure is either in position 1 or 2 of the biggest cloud providers in the world. Azure App Service, one of its most popular hosted services, allows developers to easily deploy code written in multiple programming languages across multiple operating systems and have it scale automatically with load.

The two main types of app deployment in Azure App Service are package deployment and Zip deployment:

• Package deployment takes a user's code and overwrites these files into the wwwroot folder and keeps the folder writable. This type of deployment is strongly discouraged by Azure because if there are files already that exist in wwwroot then the code may have some locks on these files so when new code comes in the overwrite might fail. A potentially even bigger problem with this type of deployment is that it takes a very long time for Node.js projects, which can easily contain hundreds of thousands of files. On our next.js-based code base which is quite small deployment takes 20+ minutes, and our website is unresponsive for most of that time.
• Zip deployment mounts a zip file into the wwwroot folder, but makes the folder read-only. This approach is the recommended way to deploy code and its advantage is that deploying with this method only takes a couple of minutes, and the environment is guaranteed to only contain the files in the zip. The disadvantage, and the reason for this RFC, is that baseDir is read-only.

Therefore, because zip deployments are read only, the Image Optimizer inside next.js fails to write to the image cache, which in turn means we cannot use the awesome features of next/image.

I would like to also mention that I do not think this feature is Azure-specific. I can think of several scenarios across other cloud providers where storing the image cache separately can come in handy, for example storing image cache on a separate faster volume, or other instances where it's not wise to write into the same folder as your project.

Implementation

There are folders on the Azure App Service machines that we can write into, even if we use a zip deployment. For example /home/. So we would like to direct the Image Optimizer to optionally use a writable folder by specifying a custom path using an environment variable such as NEXT_IMAGE_CACHE_PATH.

I noticed that in next-server.ts you send in server.distDir to imageOptimizer. I wonder if we could also send in an optional imageCacheDir. If imageCacheDir is defined, the code will use that path for the image cache. If it's not defined, then it will instead use the default join(distDir, 'cache', 'images')

I took a stab at the proposed implementation here: #26103. I have validated that imageOptimizer code does work with a folder that is located out of distDir.

Breaking changes?

None. This is an optional environment variable. If it is not specified, ImageOptimizer will store the cached images in {distDir}/cache/images like before.

Downsides

I don't see any. This change is so small that me writing this RFC took longer than implementing it. It's literally a couple of lines of code. I understand where the next.js team is coming from with requesting RFCs to make sure a feature is popular enough before adding the future maintenance burden for it, but in this particular case in my opinion the change is so minimal that it almost has no cost. I did classify this as a feature request as opposed to bug, but one could maybe argue either way.

Describe alternatives you've considered

We could in theory use a symbolic link for the image cache to a writable folder but it's more complicated than it sounds because that symbolic link would need to be part of the deployed zip package, which complicates the build time if our developers are on a Windows machine and the deployment is on Linux, or vice versa.

[zmarty]

Proposed implementation: #26103

[valstu]

This is exactly what we would need as well 👍

[styfle]

Could you configure the distDir instead?

[kroussea]

Going back to this issue since it kind of blocks us from having fast releases on Azure because we cannot run the application from a Zip package.

I was wondering how we could configure distDir option when in the docs it says that

distDir should not leave your project directory. For example, ../build is an invalid directory.

Unless i'm mistaken, when we run the application from a Zip, the next/cache folder is still inside the Zip package (since the zip contains the entire app) and is read only.

Have an idea? Maybe now that Next 13 is out there is a better way of handling this?

[kroussea]

We have an application hosted on Azure and we're using WEBSITE_RUN_FROM_PACKAGE which enables running the application from a ZIP package for faster deployments (2mins instead of 15mins).
Nextjs cannot write in the wwwroot folder when this is enabled, so it cannot create the cached images in .next/cache/images.

Having a way to specify the custom location of cache images would be highly beneficial for this scenario.
FYI, this is the actual issue we are facing: #34310

[mbyrne00]

Same kind of thing for Google App Engine Standard and using /tmp dir. Probably the same with many serverless/PaaS cloud solutions.

[viraptor]

This is also important for systems like NixOS, GUIX (I assume), and various embedded environments with readonly system images.
In those types of environments, the default dist / .next is not writable at all.

Ideally, $XDG_CACHE_HOME could also be taken into account if set.