feat: caching of generated images

.changeset/quick-roses-fail.md

@@ -0,0 +1,5 @@
+---
+'vite-imagetools': minor
+---
+
+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 the 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.
+A value of `undefined` will disable this mechanism, which is the default.
+
+```
+// 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
+undefined
+```
+
+#### 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,7 @@
 - [include](vite_src_types.VitePluginOptions.md#include)
 - [removeMetadata](vite_src_types.VitePluginOptions.md#removemetadata)
 - [resolveConfigs](vite_src_types.VitePluginOptions.md#resolveconfigs)
+- [cache](vite_src_types.VitePluginOptions.md#cache)
 
 ## Properties
 
@@ -177,3 +178,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 'node:fs'
+import { rm, utimes, readdir } from 'node: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,63 @@ describe('vite-imagetools', () => {
  expect(window.__IMAGE__).toHaveProperty('hasAlpha')
  })
  })
+
+ describe('cache.retention', () => {
+ test('is used to clear cache with retention of 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, retention: 86400 } })
+ ]
+ })
+ 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)
+ expect(image_200).toBeTypeOf('string')
+
+ const date = new Date(Date.now() - 86400000)
+ await utimes(`${dir}/${image_300}`, date, date)
+ await utimes(`${dir}/${image_200}`, date, date)
+ await build(config(200))
+ expect(existsSync(`${dir}/${image_300}`)).toBe(false)
+ expect(existsSync(`${dir}/${image_200}`)).toBe(true)
+ })
+ })
+
+ 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 () => {
@@ -539,6 +604,28 @@ describe('vite-imagetools', () => {
  )
  })
 
+ 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__'),