feat: caching of generated images

.changeset/quick-roses-fail.md

@@ -0,0 +1,5 @@
+---
+'vite-imagetools': patch
+---
+
+feat: caching of generated images

docs/README.md

@@ -17,3 +17,4 @@ unclear!
 
 - [Extend Imagetools](guide/extending.md)
 - [Sharp's documentation](https://sharp.pixelplumbing.com)
+- [Caching](guide/caching.md)

docs/guide/caching.md

@@ -0,0 +1,46 @@
+# Caching
+
+To speed up a build pipeline with many images, the generated images can be cached on disk. 
+If the source image changes, the cached images will be regenerated.
+
+## How to configure caching
+
+Caching is enabled by default and uses './node_modules/.cache/imagetools' as cache directory. 
+You can disable caching or change the directory with options.
+
+```
+// vite.config.js, etc
+...
+    plugins: [
+      react(),
+      imagetools({
+        cache: {
+          enabled: true,
+          dir: './node_modules/.cache/imagetools'
+        }
+      })
+    ]
+...
+```
+
+## Cache retention to remove unused images
+
+When an image is no longer there or the transformation parameters change, the previously
+cached images will be removed after a configurable retention period.
+The default retention is 1 day (86400 seconds). A value of 0 will disable this mechanism.
+
+```
+// vite.config.js, etc
+...
+    plugins: [
+      react(),
+      imagetools({
+        cache: {
+          enabled: true,
+          dir: './node_modules/.cache/imagetools',
+          retention: 172800
+        }
+      })
+    ]
+...
+```

docs/interfaces/vite_src_types.CacheOptions.md

@@ -0,0 +1,63 @@
+[imagetools](../README.md) / [Modules](../modules.md) / [vite/src/types](../modules/vite_src_types.md) / CacheOptions
+
+# Interface: CacheOptions
+
+[vite/src/types](../modules/vite_src_types.md).CacheOptions
+
+## Table of contents
+
+### Properties
+
+- [enabled](vite_src_types.CacheOptions.md#enabled)
+- [dir](vite_src_types.CacheOptions.md#dir)
+- [retention](vite_src_types.CacheOptions.md#retention)
+
+## Properties
+
+### enabled
+
+• **enabled**: `boolean`
+
+Wether caching of transformed images is enabled.
+
+**`Default`**
+
+```ts
+true
+```
+
+#### Defined in
+
+[packages/vite/src/types.ts:104](https://github.com/JonasKruckenberg/imagetools/blob/4ebc88f/packages/vite/src/types.ts#L104)
+
+### dir
+
+• **dir**: `string`
+
+Where to store generated images on disk as cache.
+
+**`Default`**
+
+```ts
+'./node_modules/.cache/imagetools'
+```
+
+#### Defined in
+
+[packages/vite/src/types.ts:109](https://github.com/JonasKruckenberg/imagetools/blob/4ebc88f/packages/vite/src/types.ts#L109)
+
+### retention
+
+• **retention**: `number`
+
+After what time an unused image will be removed from the cache.
+
+**`Default`**
+
+```ts
+86400
+```
+
+#### Defined in
+
+[packages/vite/src/types.ts:114](https://github.com/JonasKruckenberg/imagetools/blob/4ebc88f/packages/vite/src/types.ts#L114)

docs/interfaces/vite_src_types.VitePluginOptions.md

@@ -15,6 +15,8 @@
 - [include](vite_src_types.VitePluginOptions.md#include)
 - [removeMetadata](vite_src_types.VitePluginOptions.md#removemetadata)
 - [resolveConfigs](vite_src_types.VitePluginOptions.md#resolveconfigs)
+- [cacheRetention](vite_src_types.VitePluginOptions.md#cacheretention)
+- [cacheDir](vite_src_types.VitePluginOptions.md#cachedir)
 
 ## Properties
 
@@ -177,3 +179,19 @@ undefined
 #### Defined in
 
 [packages/vite/src/types.ts:79](https://github.com/JonasKruckenberg/imagetools/blob/4ebc88f/packages/vite/src/types.ts#L79)
+
+### cache
+
+• **cache**: [`CacheOptions`](./vite_src_types.CacheOptions.md)
+
+Options to enable caching of generated images.
+
+**`Default`**
+
+```ts
+undefined
+```
+
+#### Defined in
+
+[packages/vite/src/types.ts:97](https://github.com/JonasKruckenberg/imagetools/blob/4ebc88f/packages/vite/src/types.ts#L97)

docs/modules/vite_src_types.md

@@ -7,6 +7,7 @@
 ### Interfaces
 
 - [VitePluginOptions](../interfaces/vite_src_types.VitePluginOptions.md)
+- [CacheOptions](../interfaces/vite_src_types.CacheOptions.md)
 
 ### Type Aliases
 

packages/vite/src/__tests__/main.test.ts

@@ -1,4 +1,4 @@
-import { build, createLogger } from 'vite'
+import { InlineConfig, build, createLogger } from 'vite'
 import { imagetools } from '../index'
 import { join } from 'path'
 import { getFiles, testEntry } from './util'
@@ -8,6 +8,8 @@ import { JSDOM } from 'jsdom'
 import sharp from 'sharp'
 import { afterEach, describe, test, expect, it, vi } from 'vitest'
 import { createBasePath } from '../utils'
+import { existsSync } from 'fs'
+import { rm, utimes, readdir } from 'fs/promises'
 
 expect.extend({ toMatchImageSnapshot })
 
@@ -235,7 +237,8 @@ describe('vite-imagetools', () => {
                     return (image) => image
                   }
                 ]
-              }
+              },
+              cache: { enabled: false }
             })
           ]
         })
@@ -263,7 +266,8 @@ describe('vite-imagetools', () => {
                     return (image) => image
                   }
                 ]
-              }
+              },
+              cache: { enabled: false }
             })
           ]
         })
@@ -289,7 +293,8 @@ describe('vite-imagetools', () => {
                       return (image) => image
                     }
                   ]
-                }
+                },
+                cache: { enabled: false }
               })
             ]
           })
@@ -327,6 +332,8 @@ describe('vite-imagetools', () => {
       })
 
       test('false leaves private metadata', async () => {
+        const dir = './node_modules/.cache/imagetools_test_false_leaves_private_metadata'
+        await rm(dir, { recursive: true, force: true })
         const bundle = (await build({
           root: join(__dirname, '__fixtures__'),
           logLevel: 'warn',
@@ -337,7 +344,8 @@ describe('vite-imagetools', () => {
                             window.__IMAGE__ = Image
                         `),
             imagetools({
-              removeMetadata: false
+              removeMetadata: false,
+              cache: { dir }
             })
           ]
         })) as RollupOutput | RollupOutput[]
@@ -458,6 +466,59 @@ describe('vite-imagetools', () => {
         expect(window.__IMAGE__).toHaveProperty('hasAlpha')
       })
     })
+    describe('cache.retention', () => {
+      test('is used to clear cache with default 86400', async () => {
+        const dir = './node_modules/.cache/imagetools_test_cache_retention'
+        await rm(dir, { recursive: true, force: true })
+        const root = join(__dirname, '__fixtures__')
+        const config: (width: number) => InlineConfig = (width) => ({
+          root,
+          logLevel: 'warn',
+          build: { write: false },
+          plugins: [
+            testEntry(`
+                            import Image from "./pexels-allec-gomes-5195763.png?w=${width}"
+                            export default Image
+                        `),
+            imagetools({ cache: { dir } })
+          ]
+        })
+        await build(config(300))
+        const image_300 = (await readdir(dir))[0]
+        expect(image_300).toBeTypeOf('string')
+
+        await build(config(200))
+        const image_200 = (await readdir(dir)).find((name) => name !== image_300)?.[0]
+        expect(image_200).toBeTypeOf('string')
+
+        const date = new Date(Date.now() - 86400000)
+        await utimes(`${dir}/${image_300}`, date, date)
+        await build(config(200))
+        expect(existsSync(`${dir}/${image_300}`)).toBe(false)
+      })
+    })
+    describe('cache.dir', () => {
+      test('is used', async () => {
+        const dir = './node_modules/.cache/imagetools_test_cache_dir'
+        await rm(dir, { recursive: true, force: true })
+        const root = join(__dirname, '__fixtures__')
+        await build({
+          root,
+          logLevel: 'warn',
+          build: { write: false },
+          plugins: [
+            testEntry(`
+                            import Image from "./pexels-allec-gomes-5195763.png?w=300"
+                            export default Image
+                        `),
+            imagetools({ cache: { dir } })
+          ]
+        })
+
+        const image = (await readdir(dir))[0]
+        expect(image).toBeTypeOf('string')
+      })
+    })
   })
 
   test('relative import', async () => {
@@ -516,6 +577,28 @@ describe('vite-imagetools', () => {
     expect(files[0].source).toMatchImageSnapshot()
   })
 
+  test('import with space in identifier and cache', async () => {
+    const dir = './node_modules/.cache/imagetools_test_import_with_space'
+    await rm(dir, { recursive: true, force: true })
+    const config: InlineConfig = {
+      root: join(__dirname, '__fixtures__'),
+      logLevel: 'warn',
+      build: { write: false },
+      plugins: [
+        testEntry(`
+                    import Image from "./with space.png?w=300"
+                    export default Image
+                `),
+        imagetools({ cache: { dir } })
+      ]
+    }
+    await build(config)
+    const bundle = (await build(config)) as RollupOutput | RollupOutput[]
+
+    const files = getFiles(bundle, '**.png') as OutputAsset[]
+    expect(files[0].source).toMatchImageSnapshot()
+  })
+
   test('non existent file', async () => {
     const p = build({
       root: join(__dirname, '__fixtures__'),