Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: caching of generated images #661

Merged
merged 1 commit into from
Mar 28, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
feat: caching of generated images
pzerelles committed Mar 28, 2024
commit b0b152f521338558c039f0cc2306bdaedaf27c00
5 changes: 5 additions & 0 deletions .changeset/quick-roses-fail.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'vite-imagetools': minor
---

feat: caching of generated images
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -17,3 +17,4 @@ unclear!

- [Extend Imagetools](guide/extending.md)
- [Sharp's documentation](https://sharp.pixelplumbing.com)
- [Caching](guide/caching.md)
46 changes: 46 additions & 0 deletions docs/guide/caching.md
Original file line number Diff line number Diff line change
@@ -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
}
})
]
...
```
63 changes: 63 additions & 0 deletions docs/interfaces/vite_src_types.CacheOptions.md
Original file line number Diff line number Diff line change
@@ -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)
17 changes: 17 additions & 0 deletions docs/interfaces/vite_src_types.VitePluginOptions.md
Original file line number Diff line number Diff line change
@@ -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)
1 change: 1 addition & 0 deletions docs/modules/vite_src_types.md
Original file line number Diff line number Diff line change
@@ -7,6 +7,7 @@
### Interfaces

- [VitePluginOptions](../interfaces/vite_src_types.VitePluginOptions.md)
- [CacheOptions](../interfaces/vite_src_types.CacheOptions.md)

### Type Aliases

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
97 changes: 92 additions & 5 deletions packages/vite/src/__tests__/main.test.ts
Original file line number Diff line number Diff line change
@@ -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__'),
78 changes: 64 additions & 14 deletions packages/vite/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import { basename, extname } from 'node:path'
import { join } from 'node:path/posix'
import { statSync, mkdirSync, createReadStream } from 'node:fs'
import { writeFile, readFile, opendir, stat, rm } from 'node:fs/promises'
import type { Plugin, ResolvedConfig } from 'vite'
import {
applyTransforms,
@@ -13,7 +15,8 @@
resolveConfigs,
type Logger,
type OutputFormat,
type ProcessedImageMetadata
type ProcessedImageMetadata,
type ImageMetadata
} from 'imagetools-core'
import { createFilter, dataToEsm } from '@rollup/pluginutils'
import sharp, { type Metadata, type Sharp } from 'sharp'
@@ -41,6 +44,13 @@
export function imagetools(userOptions: Partial<VitePluginOptions> = {}): Plugin {
const pluginOptions: VitePluginOptions = { ...defaultOptions, ...userOptions }

const cacheOptions = {
enabled: pluginOptions.cache?.enabled ?? true,
dir: pluginOptions.cache?.dir ?? './node_modules/.cache/imagetools',
retention: pluginOptions.cache?.retention
}
mkdirSync(`${cacheOptions.dir}`, { recursive: true })

const filter = createFilter(pluginOptions.include, pluginOptions.exclude)

const transformFactories = pluginOptions.extendTransforms ? pluginOptions.extendTransforms(builtins) : builtins
@@ -52,7 +62,7 @@
let viteConfig: ResolvedConfig
let basePath: string

const generatedImages = new Map<string, Sharp>()
const generatedImages = new Map<string, { image?: Sharp; metadata: ImageMetadata }>()

return {
name: 'imagetools',
@@ -123,23 +133,39 @@
error: (msg) => this.error(msg)
}

const imageBuffer = await img.clone().toBuffer()

for (const config of imageConfigs) {
const { transforms } = generateTransforms(config, transformFactories, srcURL.searchParams, logger)
const { image, metadata } = await applyTransforms(transforms, img.clone(), pluginOptions.removeMetadata)
const id = await generateImageID(srcURL, config, imageBuffer)
let image: Sharp | undefined
let metadata: ImageMetadata

let imageId: string
if (viteConfig.command === 'serve') {
imageId = await generateImageID(srcURL, config, img)
generatedImages.set(imageId, image)
if (cacheOptions.enabled && (statSync(`${cacheOptions.dir}/${id}`, { throwIfNoEntry: false })?.size ?? 0) > 0) {
metadata = (await sharp(`${cacheOptions.dir}/${id}`).metadata()) as ImageMetadata
} else {
const { transforms } = generateTransforms(config, transformFactories, srcURL.searchParams, logger)
const res = await applyTransforms(transforms, img, pluginOptions.removeMetadata)
metadata = res.metadata
if (cacheOptions.enabled) {
await writeFile(`${cacheOptions.dir}/${id}`, await res.image.toBuffer())
} else {
image = res.image
}
}

generatedImages.set(id, { image, metadata })

if (directives.has('inline')) {
metadata.src = `data:image/${metadata.format};base64,${(await image.toBuffer()).toString('base64')}`
metadata.src = `data:image/${metadata.format};base64,${(image
? await image.toBuffer()

Check warning on line 160 in packages/vite/src/index.ts

Codecov / codecov/patch

packages/vite/src/index.ts#L160

Added line #L160 was not covered by tests
: await readFile(`${cacheOptions.dir}/${id}`)
).toString('base64')}`
} else if (viteConfig.command === 'serve') {
metadata.src = join(viteConfig?.server?.origin ?? '', basePath) + imageId
metadata.src = join(viteConfig?.server?.origin ?? '', basePath) + id

Check warning on line 164 in packages/vite/src/index.ts

Codecov / codecov/patch

packages/vite/src/index.ts#L164

Added line #L164 was not covered by tests
} else {
const fileHandle = this.emitFile({
name: basename(pathname, extname(pathname)) + `.${metadata.format}`,
source: await image.toBuffer(),
source: image ? await image.toBuffer() : await readFile(`${cacheOptions.dir}/${id}`),
type: 'asset'
})

@@ -173,22 +199,46 @@
if (req.url?.startsWith(basePath)) {
const [, id] = req.url.split(basePath)

const image = generatedImages.get(id)
const { image, metadata } = generatedImages.get(id) ?? {}

Check warning on line 202 in packages/vite/src/index.ts

Codecov / codecov/patch

packages/vite/src/index.ts#L202

Added line #L202 was not covered by tests

if (!image)
if (!metadata)

Check warning on line 204 in packages/vite/src/index.ts

Codecov / codecov/patch

packages/vite/src/index.ts#L204

Added line #L204 was not covered by tests
throw new Error(`vite-imagetools cannot find image with id "${id}" this is likely an internal error`)

if (!image) {
res.setHeader('Content-Type', `image/${metadata.format}`)
return createReadStream(`${cacheOptions.dir}/${id}`).pipe(res)
}

Check warning on line 211 in packages/vite/src/index.ts

Codecov / codecov/patch

packages/vite/src/index.ts#L207-L211

Added lines #L207 - L211 were not covered by tests
if (pluginOptions.removeMetadata === false) {
image.withMetadata()
}

res.setHeader('Content-Type', `image/${getMetadata(image, 'format')}`)
res.setHeader('Cache-Control', 'max-age=360000')
return image.clone().pipe(res)
}

next()
})
},

Check warning on line 222 in packages/vite/src/index.ts

Codecov / codecov/patch

packages/vite/src/index.ts#L222

Added line #L222 was not covered by tests

async buildEnd(error) {
if (!error && cacheOptions.enabled && cacheOptions.retention !== undefined && viteConfig.command !== 'serve') {
const dir = await opendir(cacheOptions.dir)

for await (const dirent of dir) {
if (dirent.isFile()) {
if (generatedImages.has(dirent.name)) continue

const imagePath = `${cacheOptions.dir}/${dirent.name}`
const stats = await stat(imagePath)

if (Date.now() - stats.mtimeMs > cacheOptions.retention * 1000) {
console.debug(`deleting stale cached image ${dirent.name}`)
await rm(imagePath)
}
}
}
}
}
}
}
22 changes: 22 additions & 0 deletions packages/vite/src/types.ts
Original file line number Diff line number Diff line change
@@ -90,4 +90,26 @@ export interface VitePluginOptions {
* @default undefined
*/
namedExports?: boolean

/**
* Whether to cache transformed images and options for caching.
*/
cache?: CacheOptions
}

export interface CacheOptions {
/**
* Should the image cache be enabled. Default is true
*/
enabled?: boolean

/**
* Where should the cached images be stored. Default is './node_modules/.cache/imagetools'
*/
dir?: string

/**
* For how many seconds to keep transformed images cached. Default is undefined, which keeps the images forever.
*/
retention?: number
}
6 changes: 2 additions & 4 deletions packages/vite/src/utils.ts
Original file line number Diff line number Diff line change
@@ -2,17 +2,15 @@
import path from 'node:path'
import { statSync } from 'node:fs'
import type { ImageConfig } from 'imagetools-core'
import type { Sharp } from 'sharp'

export const createBasePath = (base?: string) => {
return (base?.replace(/\/$/, '') || '') + '/@imagetools/'
}

export async function generateImageID(url: URL, config: ImageConfig, originalImage: Sharp) {
export async function generateImageID(url: URL, config: ImageConfig, imageBuffer: Buffer) {
if (url.host) {
const baseURL = new URL(url.origin + url.pathname)
const buffer = await originalImage.toBuffer()
return hash([baseURL.href, JSON.stringify(config), buffer])
return hash([baseURL.href, JSON.stringify(config), imageBuffer])

Check warning on line 13 in packages/vite/src/utils.ts

Codecov / codecov/patch

packages/vite/src/utils.ts#L13

Added line #L13 was not covered by tests
}

// baseURL isn't a valid URL, but just a string used for an identifier