Improving support for third-party hosted image services (#3957)

* WIP: always use the built-in sharp service for local images in `dev`

* adding type definitions for the integration's use of globalThis

* simplifying the globalThis type checking

* chore: adding changeset

* removing temp hosted service used for testing

.changeset/purple-vans-bake.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/image': patch
+---
+
+Improves the `astro dev` experience when using a third-party hosted image service

packages/integrations/image/README.md

@@ -73,6 +73,8 @@ The included `sharp` transformer supports resizing images and encoding them to d
 
 The intergration can be configured to run with a different image service, either a hosted image service or a full image transformer that runs locally in your build or SSR deployment.
 
+> During development, local images may not have been published yet and would not be available to hosted image services. Local images will always use the built-in `sharp` service when using `astro dev`.
+
 There are currently no other configuration options for the `@astrojs/image` integration. Please [open an issue](https://github.com/withastro/astro/issues/new/choose) if you have a compelling use case to share.
 
 <details>

packages/integrations/image/src/endpoints/dev.ts

@@ -1,10 +1,10 @@
 import type { APIRoute } from 'astro';
 import { lookup } from 'mrmime';
-// @ts-ignore
-import loader from 'virtual:image-loader';
 import { loadImage } from '../utils.js';
 
 export const get: APIRoute = async ({ request }) => {
+ const loader = globalThis.astroImage.ssrLoader;
+
  try {
  const url = new URL(request.url);
  const transform = loader.parseTransform(url.searchParams);

packages/integrations/image/src/get-image.ts

@@ -8,7 +8,7 @@ import {
  OutputFormat,
  TransformOptions,
 } from './types.js';
-import { parseAspectRatio } from './utils.js';
+import { isRemoteImage, parseAspectRatio } from './utils.js';
 
 export interface GetImageTransform extends Omit<TransformOptions, 'src'> {
  src: string | ImageMetadata | Promise<{ default: ImageMetadata }>;
@@ -105,23 +105,32 @@ export async function getImage(
  loader: ImageService,
  transform: GetImageTransform
 ): Promise<ImageAttributes> {
- (globalThis as any).loader = loader;
+ globalThis.astroImage.loader = loader;
 
  const resolved = await resolveTransform(transform);
+
  const attributes = await loader.getImageAttributes(resolved);
 
+ const isDev = globalThis.astroImage.command === 'dev';
+ const isLocalImage = !isRemoteImage(resolved.src);
+
+ const _loader = isDev && isLocalImage ? globalThis.astroImage.ssrLoader : loader;
+
+ if (!_loader) {
+ throw new Error('@astrojs/image: loader not found!');
+ }
+
  // For SSR services, build URLs for the injected route
- if (isSSRService(loader)) {
- const { searchParams } = loader.serializeTransform(resolved);
+ if (isSSRService(_loader)) {
+ const { searchParams } = _loader.serializeTransform(resolved);
 
  // cache all images rendered to HTML
- if (globalThis && (globalThis as any).addStaticImage) {
- (globalThis as any)?.addStaticImage(resolved);
+ if (globalThis?.astroImage) {
+ globalThis.astroImage.addStaticImage(resolved);
  }
 
- const src =
- globalThis && (globalThis as any).filenameFormat
- ? (globalThis as any).filenameFormat(resolved, searchParams)
+ const src = globalThis?.astroImage
+ ? globalThis.astroImage.filenameFormat(resolved, searchParams)
  : `${ROUTE_PATTERN}?${searchParams.toString()}`;
 
  return {

packages/integrations/image/src/index.ts

@@ -3,6 +3,7 @@ import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { OUTPUT_DIR, PKG_NAME, ROUTE_PATTERN } from './constants.js';
+import sharp from './loaders/sharp.js';
 import { IntegrationOptions, TransformOptions } from './types.js';
 import {
  ensureDir,
@@ -51,15 +52,15 @@ const createIntegration = (options: IntegrationOptions = {}): AstroIntegration =
 
  // Used to cache all images rendered to HTML
  // Added to globalThis to share the same map in Node and Vite
- (globalThis as any).addStaticImage = (transform: TransformOptions) => {
+ function addStaticImage(transform: TransformOptions) {
  staticImages.set(propsToFilename(transform), transform);
  };
 
  // TODO: Add support for custom, user-provided filename format functions
- (globalThis as any).filenameFormat = (
+ function filenameFormat(
  transform: TransformOptions,
  searchParams: URLSearchParams
- ) => {
+ ) {
  if (mode === 'ssg') {
  return isRemoteImage(transform.src)
  ? path.join(OUTPUT_DIR, path.basename(propsToFilename(transform)))
@@ -73,6 +74,16 @@ const createIntegration = (options: IntegrationOptions = {}): AstroIntegration =
  }
  };
 
+ // Initialize the integration's globalThis namespace
+ // This is needed to share scope between Node and Vite
+ globalThis.astroImage = {
+ loader: undefined, // initialized in first getImage() call
+ ssrLoader: sharp,
+ command,
+ addStaticImage,
+ filenameFormat,
+ }
+
  if (mode === 'ssr') {
  injectRoute({
  pattern: ROUTE_PATTERN,
@@ -83,7 +94,12 @@ const createIntegration = (options: IntegrationOptions = {}): AstroIntegration =
  },
  'astro:build:done': async ({ dir }) => {
  for await (const [filename, transform] of staticImages) {
- const loader = (globalThis as any).loader;
+ const loader = globalThis.astroImage.loader;
+
+ if (!loader || !('transform' in loader)) {
+ // this should never be hit, how was a staticImage added without an SSR service?
+ return;
+ }
 
  let inputBuffer: Buffer | undefined = undefined;
  let outputFile: string;

packages/integrations/image/src/types.ts

@@ -2,6 +2,18 @@
 export type { Image, Picture } from '../components/index.js';
 export * from './index.js';
 
+interface ImageIntegration {
+ loader?: ImageService;
+ ssrLoader: SSRImageService;
+ command: 'dev' | 'build';
+ addStaticImage: (transform: TransformOptions) => void;
+ filenameFormat: (transform: TransformOptions, searchParams: URLSearchParams) => string;
+}
+
+declare global {
+ var astroImage: ImageIntegration;
+}
+
 export type InputFormat =
  | 'heic'
  | 'heif'