Astro integration

Install

npm install @picsoar/astro

Configure

// astro.config.mjs
import { defineConfig } from 'astro/config';
import picsoar from '@picsoar/astro';

export default defineConfig({
  integrations: [picsoar()],
});

# .env
PUBLIC_PICSOAR_CDN_ORIGIN=https://cdn.picsoar.com
PUBLIC_PICSOAR_PROJECT_KEY=prj_your_project_key
PUBLIC_PICSOAR_DEFAULT_PRESET=content

Both variables are genuinely public — they appear in every image URL anyway. The integration throws at build time if it finds a signing secret behind a PUBLIC_ prefix, because that prefix means "inline this into the browser bundle".

Use

---
import OptimizedImage from '@picsoar/astro/OptimizedImage.astro';
---

<OptimizedImage
  src="products/shoe.jpg"
  alt="A grey running shoe photographed from the side"
  preset="card"
  width={640}
  height={480}
  sizes="(min-width: 60rem) 640px, 100vw"
  version="8f2c1a"
/>

What it renders

A plain <img> with a srcset built from the preset's own width family,loading="lazy" and decoding="async" unless you mark itpriority, and explicit dimensions so the browser reserves space and the page does not shift.

There is no hydration and no client-side JavaScript. The component runs at build time or during SSR and emits static markup.

Why widths come from the preset

A component that accepted arbitrary widths would let one page create dozens of derivatives of the same image — each one a transformation you pay for and a cache entry that displaces something else. The card preset has a DPR ceiling of 2, so it emits exactly two widths: 640 and 1280.

If you need a different size, define a preset for it once rather than a width per usage.

Development warnings

In astro dev the component warns about:

• a missing alt attribute;
• a preset name that is not a known built-in;
• missing width/height, which causes layout shift;
• a source path that cannot be canonicalized — caught here rather than as a 400 in production.

They are warnings, not errors: a missing alt should be impossible to ignore while you work, but it should not take down a production build that was already passing. The accessibility checks in CI are what gate a release.

Next steps

Create a projectRead the docs