SSR
Recently, Astro has added experimental support for server-side rendering (SSR). To use Astro ImageTools in SSR, you need to have at least
v0.6.0 of the
astro-imagetools package installed.
How to use Astro ImageTools in SSR Mode
Install the required dependencies
The
v0.6.0 release adds experimental support for server-side rendering (SSR). At this moment, only Node.js is supported. You need to have the
@astrojs/node adapter and the latest version of
astro-imagetools installed on your Astro project.
pnpm i @astrojs/node @astrojs/imagetools@^0.6.0
You need to have the latest version of
astro-imagetools installed on the server too.
pnpm i @astrojs/imagetools@^0.6.0
To learn more about how to do set up the Node adapter and the Node server with Astro, please check out the
@astrojs/node readme.
Use the exported
middleware
Like any other component, the components and APIs provided by Astro ImageTools will be executed on the server. Due to how the Astro build process works, it’s not possible to emit assets during the build process.
When handling the incoming requests on the server, you need to use the
middleware exported by the
astro-imagetools package. The
middleware returns an instance of a
Buffer.
Code Example:
import http from "http"; import { middleware } from "astro-imagetools/ssr"; import { handler as ssrHandler } from "./dist/server/entry.mjs"; http .createServer(function (req, res) { ssrHandler(req, res, async (err) => { if (err) { res.writeHead(500); res.end(err.toString()); } else { const buffer = await middleware(req, res); if (buffer) { res.writeHead(200); res.end(buffer); } else { // Serve your other static assets or return 404 res.writeHead(404); res.end(); } } }); }) .listen(8080);
Notes
The components and APIs provided by Astro ImageTools will be executed on the server. So, the path that you have provided via the
src property won’t exist on the server. This limitation applies for local images only.
To use local images with SSR, you have to generate assets for them first and then you have to pass the path to the assets to the
src property.
Below is an example of how to do this.
--- import src from "../images/image.jpg?raw"; import { Picture } from "astro-imagetools/components"; --- <Picture {src}
The
rawquery parameter has been used to tell the internal Vite plugin to emit the asset from the source image unchanged.