Skip to content

Commit 1b9e184

Browse files
bartlomiejuclaude
andcommitted
docs: add image optimization section to static files docs
Covers build-time optimization with vite-imagetools, CDN image services, and best practices for responsive images. Closes #671 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 0c74c35 commit 1b9e184

1 file changed

Lines changed: 55 additions & 0 deletions

File tree

docs/latest/concepts/static-files.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,58 @@ export default function Gallery() {
9797
);
9898
}
9999
```
100+
101+
## Image optimization
102+
103+
Fresh does not include a built-in image optimization pipeline, but since Fresh 2
104+
uses Vite, you can use Vite plugins or external services to optimize images.
105+
106+
### Build-time optimization with Vite
107+
108+
[vite-imagetools](https://github.com/JonasKruckenberg/imagetools) lets you
109+
import images with query parameters to resize, convert formats, and generate
110+
`srcset` at build time:
111+
112+
```ts
113+
deno add -D npm:vite-imagetools
114+
```
115+
116+
```ts vite.config.ts
117+
import { defineConfig } from "vite";
118+
import { fresh } from "@fresh/plugin-vite";
119+
import { imagetools } from "vite-imagetools";
120+
121+
export default defineConfig({
122+
plugins: [fresh(), imagetools()],
123+
});
124+
```
125+
126+
Then import optimized images directly:
127+
128+
```tsx
129+
import heroAvif from "../static/hero.jpg?format=avif&w=800";
130+
131+
export default function Page() {
132+
return <img src={heroAvif} alt="Hero" width={800} />;
133+
}
134+
```
135+
136+
### CDN image services
137+
138+
For dynamic optimization without a build step, use a CDN image service that
139+
transforms images on-the-fly:
140+
141+
- [Cloudflare Images](https://developers.cloudflare.com/images/)
142+
- [imgix](https://imgix.com/)
143+
- [Cloudinary](https://cloudinary.com/)
144+
145+
These services resize, compress, and convert images to modern formats (WebP,
146+
AVIF) based on URL parameters, with automatic caching at the edge.
147+
148+
### Best practices
149+
150+
- Use modern formats (WebP, AVIF) with `<picture>` fallbacks
151+
- Provide responsive images with `srcset` and `sizes` attributes
152+
- Set `width` and `height` on `<img>` tags to prevent layout shift
153+
- Use `loading="lazy"` for below-the-fold images
154+
- Use `asset()` / `assetSrcSet()` for cache-busted URLs

0 commit comments

Comments
 (0)