@ashiteam/sveltekit-images
v2.0.7
Published
A SvelteKit image component that will render optimized images.
Downloads
16
Maintainers
Readme
@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&w=256&q=74"
srcset="/api/_image?url=%2Fimages%2Flogo.png&w=128&q=74 1x, /api/_image?url=%2Fimages%2Flogo.png&w=196&q=74 1.5x, /api/_image?url=%2Fimages%2Flogo.png&w=256&q=74 2x, /api/_image?url=%2Fimages%2Flogo.png&w=384&q=74 3x"
decoding="async"
loading="eager"
alt="Logo"
style="--height: 120;"
height="120"
width="120">
Table of contents
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, ...)