@ashiteam/sveltekit-images

A SvelteKit image component that will render optimized images.

Images can be anywhere from the internet or from a local folder. An image set will be built and cached at build time, and these images will be the ones used.

Will convert

<Image
  src="/images/logo.png"
  alt="Logo"
  width={120}
  height={120}
  eager={true}
/>

To

<img
  src="/api/_image?url=%2Fimages%2Flogo.png&amp;w=256&amp;q=74"
  srcset="/api/_image?url=%2Fimages%2Flogo.png&amp;w=128&amp;q=74 1x, /api/_image?url=%2Fimages%2Flogo.png&amp;w=196&amp;q=74 1.5x, /api/_image?url=%2Fimages%2Flogo.png&amp;w=256&amp;q=74 2x, /api/_image?url=%2Fimages%2Flogo.png&amp;w=384&amp;q=74 3x"
  decoding="async"
  loading="eager"
  alt="Logo"
  style="--height: 120;"
  height="120"
  width="120">

Table of contents

1. Installing
2. Usage
3. Local Images
4. Props
5. Configuration

Installing

npm i -D @ashiteam/sveltekit-images

Usage

In routes/api/_image, create a +server.ts endpoint

import type { RequestHandler } from '@sveltejs/kit';
import { requestHandler } from '@ashiteam/sveltekit-images/api';

export const GET: RequestHandler = requestHandler();

NOTE - Initialization configuration can be passed in to the requestHandler.

Then import the image component and use it.

<!-- +page.svelte -->
<script lang="ts">
	import Image from '@ashiteam/sveltekit-images';
</script>

<Image src="image-url" width={500} height={400} alt="This is my image" class="any css classes" />

Local images

Reference local images just the same as external images. Just make sure not to include a trailing slash.

If you are using Sveltekit's prerender, you will need to set a leadingUrl in the configuration passed in to requestHandler

Props

The following are the props you can pass to Image

Name	Type	Description	Default Value	Mandetory
src	string	URL or Path to your image		Yes
width	number or undefined	Width of your image (to reduce CLS)		No
height	number or undefined	Height of your image (to reduce CLS)		No
alt	string or undefined	Alt for screen readers and missing image		No
sync	boolean or async	Changes image decoding	async	No
eager	boolean or lazy	Changes native browser loading attribute	lazy	No
important	boolean	Sets sync and eager to true	false	No
quality	number (1-100)	Quality of images generated	74	No

Configuration

Server configrations can be specified through the /api/_image/server.ts endpoint. e.g.

export const GET: RequestHandler = requestHandler({
	leadingUrl: process.env.NODE_ENV === 'production' ? 'https://your-url' : 'http://localhost:5173',
	avif: false,
	remoteDomains: ['ashiteam.com', 'unsplash.com'],
	allowedDomains: ['your-domain'],
	ttl: 1000 * 60 * 60 * 24 * 7,
	storePath: './public/image_cache'
});

The configuration has the following properties that can be set.

leadingUrl

string

The URL prefixed to requests of local images. You need to define this if using local images Defaults to ./public/image_cache

The following is a method to prefix based on node environment :

  leadingUrl: process.env.NODE_ENV === 'production'
			? 'YOUR-PRODUCTION-URL'
			: 'YOUR-LOCAL-URL',

avif

boolean

Enable AVIF image format. Defaults to false

Warning: The .avif format is not recommended due to its high CPU usage

remoteDomains

string[] | undefined

List of domains that the API will be allowed to optimize. Defaults to unset

From example above, remoteDomains: ['ashiteam.com', 'unsplash.com'], means that API will only be allowed to optimize images that served from ashiteam.com and unsplash.com.

If not set, the API will optimize ALL IMAGES from EVERYWHERE

allowedDomains

string[] | undefined

List of domains that are allowed to use the API, this will be checked via header Referer

Only affects when NODE_ENV=production. If not set, anyone will be allowed to request images from this API.

ttl

number

Time until images will become invalidated, defaults to 7 days

Value is in milliseconds

storePath

string

Directory path to cache optimized images. Defaults to ./public/image_cache. Ensure that the webserver has write access to this path as it will need to cache (save) images here.

imageApi

string

URL to the API that will optimize the image. This URL will be called from the server to optimize the image, when an optimized image is not found in the cache. The optimized image will then be saved in the cache and used from the cache in the future.

Defaults to https://ashiimage.ashiteam.com/api/OptimizedImage, which is my server that will properly optimize the image.

You can use any API endpoint (or build your own), as long as it is a GET request endpoint accepting the following parameters and will return the binary of the optimized image.

url full URL to the image to be optimized.

width The width of the optimized image.

height The height of the optimized image.

quality The quality of the optimized image. A value between 1 and 100.

ext The extension of the optimized image. (e.g. jpg, webp, png, ...)