refactor(astro-sdk): tighten config resolution, types, helpers; drop PUBLIC_ env

Centralize ImageKit config resolution, harden the image service, and
simplify the OG helper. Also remove PUBLIC_IMAGEKIT_URL_ENDPOINT since
every SDK caller runs server-side.

Resolution & integration:
- getImageKitConfig is the single resolver: prop > integration config
  (virtual:@imagekit/astro/config) > IMAGEKIT_URL_ENDPOINT
- Video.astro delegates to getImageKitConfig instead of resolving inline
- Integration only carries forward known service config keys
  (urlEndpoint, transformationPosition); foreign keys from a previous
  service no longer leak through
- Warn when urlEndpoint cannot be parsed as a URL
- Mark virtual:@imagekit/astro/config external in tsup

Image service:
- Throw a clear error when no urlEndpoint can be resolved (was: silent '')
- Add IKImageTransform type, remove all `as any` casts
- Align quality presets with Astro sharp defaults (low/mid/high/max
  = 25/50/75/100, was 30/80/90/95)

Helpers & types:
- Drop `format` option from getOgImageTags; emit a single image URL for
  og:image and twitter:image (ImageKit auto-format negotiates
  WebP/AVIF/JPEG via the Accept header)
- VideoProps extends Astro's HTMLAttributes<'video'> for full HTML
  video attribute autocomplete (replaces [key: string]: unknown)

test-app:
- Add /og page exercising getOgImageTags (default, minimal, custom
  dimensions + transformation)
- Link /og from index page

Author: manu4543

imagekit-astro/src/components/Video.astro

@@ -1,9 +1,5 @@
 ---
 import { buildSrc } from '@imagekit/javascript';
-import {
-  urlEndpoint as integrationUrlEndpoint,
-  transformationPosition as integrationTransformationPosition,
-} from 'virtual:@imagekit/astro/config';
 import { getImageKitConfig } from '../lib/imagekit';
 import type { VideoProps } from '../types/index';
 
@@ -21,17 +17,15 @@ const {
 
 // Resolve ImageKit configuration.
 // Priority: prop > integration config (astro.config.mjs) > env vars.
-const config = getImageKitConfig({
-  urlEndpoint: urlEndpoint ?? (integrationUrlEndpoint || undefined),
-  transformationPosition:
-    transformationPosition ?? integrationTransformationPosition,
-});
+const config = getImageKitConfig({ urlEndpoint, transformationPosition });
 
-// Build the video URL
+// Build the video URL.
+// Note: width/height props are HTML attributes only; they are NOT applied as
+// ImageKit transformations. To resize the video, pass them via `transformation`.
 const videoSrc = buildSrc({
   src,
   urlEndpoint: config.urlEndpoint,
-  transformation: [...transformation],
+  transformation,
   queryParameters,
   transformationPosition: config.transformationPosition,
 });
@@ -48,3 +42,4 @@ if (className) {
   class={videoClassName}
   {...restProps}
 />
+

imagekit-astro/src/helpers/index.ts

@@ -11,7 +11,9 @@ export interface OgMetaTag {
 /**
  * Build OG/Twitter meta tags for a given image.
  *
- * Render these tags inside your page's <head>.
+ * Render these tags inside your page's <head>. ImageKit serves the optimal
+ * image format automatically based on the requesting client (no `format`
+ * option needed).
  */
 export function getOgImageTags(props: OgImageTagOptions): OgMetaTag[] {
   const {
@@ -28,7 +30,6 @@ export function getOgImageTags(props: OgImageTagOptions): OgMetaTag[] {
     transformation = [],
     queryParameters,
     transformationPosition,
-    format,
     width = OG_IMAGE_WIDTH,
     height = OG_IMAGE_HEIGHT,
   } = props;
@@ -47,33 +48,19 @@ export function getOgImageTags(props: OgImageTagOptions): OgMetaTag[] {
 
   const config = getImageKitConfig({ urlEndpoint, transformationPosition });
 
-  const ogImageUrl = buildSrc({
+  const imageUrl = buildSrc({
     src,
     urlEndpoint: config.urlEndpoint,
-    transformation: [
-      ...transformation,
-      { width, height },
-    ],
-    queryParameters,
-    transformationPosition: config.transformationPosition,
-  });
-
-  const twitterImageUrl = buildSrc({
-    src,
-    urlEndpoint: config.urlEndpoint,
-    transformation: [
-      ...transformation,
-      { width, height, format: format || 'webp' },
-    ],
+    transformation: [...transformation, { width, height }],
     queryParameters,
     transformationPosition: config.transformationPosition,
   });
 
   const tags: Array<OgMetaTag | undefined> = [
     resolvedOgTitle ? { property: 'og:title', content: resolvedOgTitle } : undefined,
     resolvedOgDescription ? { property: 'og:description', content: resolvedOgDescription } : undefined,
-    { property: 'og:image', content: ogImageUrl },
-    { property: 'og:image:secure_url', content: ogImageUrl },
+    { property: 'og:image', content: imageUrl },
+    { property: 'og:image:secure_url', content: imageUrl },
     { property: 'og:image:width', content: String(width) },
     { property: 'og:image:height', content: String(height) },
     alt ? { property: 'og:image:alt', content: alt } : undefined,
@@ -82,8 +69,9 @@ export function getOgImageTags(props: OgImageTagOptions): OgMetaTag[] {
       ? { property: 'twitter:description', content: resolvedTwitterDescription }
       : undefined,
     { property: 'twitter:card', content: twitterCard },
-    { property: 'twitter:image', content: twitterImageUrl },
+    { property: 'twitter:image', content: imageUrl },
   ];
 
   return tags.filter((tag): tag is OgMetaTag => Boolean(tag));
 }
+

imagekit-astro/src/integration.ts

@@ -38,8 +38,7 @@ export default { urlEndpoint, transformationPosition };
 export interface ImageKitIntegrationOptions {
   /**
   * The ImageKit URL endpoint.
-  * If omitted, PUBLIC_IMAGEKIT_URL_ENDPOINT is checked first,
-  * then IMAGEKIT_URL_ENDPOINT.
+  * If omitted, IMAGEKIT_URL_ENDPOINT is used.
    */
   urlEndpoint?: string;
 
@@ -197,7 +196,6 @@ export default function imagekit(
         const resolvedUrlEndpoint =
           options.urlEndpoint ??
           asString(existingServiceConfig.urlEndpoint) ??
-          import.meta.env?.PUBLIC_IMAGEKIT_URL_ENDPOINT ??
           import.meta.env?.IMAGEKIT_URL_ENDPOINT;
 
         const resolvedTransformationPosition =
@@ -211,6 +209,12 @@ export default function imagekit(
           ? parseEndpoint(resolvedUrlEndpoint)
           : undefined;
 
+        if (resolvedUrlEndpoint && !endpoint) {
+          logger.warn(
+            `Could not parse urlEndpoint "${resolvedUrlEndpoint}" as a URL. Make sure it includes the protocol (e.g. "https://ik.imagekit.io/your_id"). The endpoint host will not be added to image.domains/remotePatterns.`,
+          );
+        }
+
         const mergedDomains = uniqStrings([
           ...normalizeDomainList(imageConfigRecord.domains),
           ...normalizeDomainList(options.domains),
@@ -224,9 +228,10 @@ export default function imagekit(
           ...getDefaultRemotePatterns(endpoint),
         ]);
 
-        const nextServiceConfig: Record<string, unknown> = {
-          ...(typeof existingServiceConfig === 'object' ? existingServiceConfig : {}),
-        };
+        // Only carry forward keys we recognize. Any leftover keys from a
+        // previous image service config (e.g. sharp's `limitInputPixels`)
+        // would not make sense for this service.
+        const nextServiceConfig: Record<string, unknown> = {};
 
         if (resolvedUrlEndpoint) {
           nextServiceConfig.urlEndpoint = resolvedUrlEndpoint;
@@ -248,7 +253,7 @@ export default function imagekit(
 
         if (!resolvedUrlEndpoint) {
           logger.warn(
-            'No ImageKit urlEndpoint found. Set PUBLIC_IMAGEKIT_URL_ENDPOINT or IMAGEKIT_URL_ENDPOINT, or pass urlEndpoint to imagekit().',
+            'No ImageKit urlEndpoint found. Set IMAGEKIT_URL_ENDPOINT, or pass urlEndpoint to imagekit().',
           );
         }
 

imagekit-astro/src/lib/imagekit.ts

@@ -1,16 +1,21 @@
 
+import {
+  urlEndpoint as integrationUrlEndpoint,
+  transformationPosition as integrationTransformationPosition,
+} from 'virtual:@imagekit/astro/config';
 
 /**
  * ImageKit configuration options.
- * Can be passed as props to override environment variable defaults.
+ * Can be passed as props to override values resolved from the integration
+ * config (`astro.config.mjs`) or environment variables.
  */
 export interface ImageKitConfig {
-  /** 
-   * The URL endpoint for your ImageKit account. 
+  /**
+   * The URL endpoint for your ImageKit account.
    * Get it from https://imagekit.io/dashboard/url-endpoints
    */
   urlEndpoint: string;
-  
+
   /**
    * Position of the transformation string in the URL.
    * - `'query'` (default): appended as `?tr=...`
@@ -20,26 +25,31 @@ export interface ImageKitConfig {
 }
 
 /**
- * Resolves ImageKit configuration from props and/or environment variables.
- * 
- * Priority: prop overrides > environment variables
- * 
- * @throws {Error} If no urlEndpoint is available from either source.
+ * Resolves ImageKit configuration.
+ *
+ * Priority:
+ *   1. Per-call overrides (props)
+ *   2. Integration config from `astro.config.mjs` (via virtual module)
+ *   3. `IMAGEKIT_URL_ENDPOINT` env var
+ *
+ * @throws {Error} If no urlEndpoint is available from any source.
  */
 export function getImageKitConfig(overrides?: Partial<ImageKitConfig>): ImageKitConfig {
   const urlEndpoint =
-    overrides?.urlEndpoint ??
-    import.meta.env.PUBLIC_IMAGEKIT_URL_ENDPOINT ??
+    overrides?.urlEndpoint ||
+    integrationUrlEndpoint ||
     import.meta.env.IMAGEKIT_URL_ENDPOINT;
 
   if (!urlEndpoint) {
     throw new Error(
-      'An ImageKit URL endpoint is required. Set PUBLIC_IMAGEKIT_URL_ENDPOINT or IMAGEKIT_URL_ENDPOINT in your environment, or pass urlEndpoint as a prop.'
+      'An ImageKit URL endpoint is required. Pass urlEndpoint to the imagekit() integration in astro.config.mjs, set IMAGEKIT_URL_ENDPOINT, or pass urlEndpoint as a prop.'
     );
   }
 
   return {
     urlEndpoint,
-    transformationPosition: overrides?.transformationPosition ?? 'query',
+    transformationPosition:
+      overrides?.transformationPosition ?? integrationTransformationPosition ?? 'query',
   };
 }
+

imagekit-astro/src/services/imagekit-service.ts

@@ -13,6 +13,19 @@ type UnresolvedSrcSetValue = {
   attributes?: Record<string, any>;
 };
 
+/**
+ * Astro `ImageTransform` augmented with the ImageKit-specific props
+ * declared on `Astro.CustomImageProps` via the integration's `injectTypes`.
+ */
+type IKImageTransform = ImageTransform & {
+  urlEndpoint?: string;
+  transformation?: Transformation[];
+  queryParameters?: Record<string, string | number>;
+  transformationPosition?: 'path' | 'query';
+  densities?: Array<number | `${number}x`>;
+  widths?: number[];
+};
+
 export interface ImageKitServiceConfig {
   /**
    * The URL endpoint for your ImageKit account.
@@ -30,32 +43,45 @@ export interface ImageKitServiceConfig {
 
 /**
  * Astro quality presets mapped to ImageKit quality (0-100).
- * https://imagekit.io/docs/image-resize-and-crop#quality-q
+ *
+ * Aligned with Astro's sharp service defaults
+ * (https://docs.astro.build/en/reference/image-service-reference/).
  */
 const QUALITY_PRESETS: Record<string, number> = {
-  low: 30,
-  mid: 80,
-  high: 90,
-  max: 95,
+  low: 25,
+  mid: 50,
+  high: 75,
+  max: 100,
 };
 
 /**
  * Resolves the ImageKit config from the service config and per-image overrides.
+ *
+ * Priority: per-image prop > integration service config > env vars.
+ *
+ * @throws {Error} If no urlEndpoint can be resolved.
  */
 function resolveConfig(
-  options: ImageTransform,
+  options: IKImageTransform,
   imageConfig: AstroConfig['image'],
 ): { urlEndpoint: string; transformationPosition: 'path' | 'query' } {
-  const config = (imageConfig.service.config ?? {}) as ImageKitServiceConfig;
+  const config = (imageConfig.service.config ?? {}) as Partial<ImageKitServiceConfig>;
   const urlEndpoint =
-    (options as any).urlEndpoint ??
-    config.urlEndpoint ??
-    import.meta.env?.PUBLIC_IMAGEKIT_URL_ENDPOINT ??
-    import.meta.env?.IMAGEKIT_URL_ENDPOINT ??
-    '';
-  const transformationPosition =
-    (options as any).transformationPosition ?? config.transformationPosition ?? 'query';
-  return { urlEndpoint, transformationPosition };
+    options.urlEndpoint ||
+    config.urlEndpoint ||
+    import.meta.env?.IMAGEKIT_URL_ENDPOINT;
+
+  if (!urlEndpoint) {
+    throw new Error(
+      '[@imagekit/astro] An ImageKit URL endpoint is required. Pass urlEndpoint to the imagekit() integration in astro.config.mjs, set IMAGEKIT_URL_ENDPOINT, or pass urlEndpoint as a prop on <Image>.',
+    );
+  }
+
+  return {
+    urlEndpoint,
+    transformationPosition:
+      options.transformationPosition ?? config.transformationPosition ?? 'query',
+  };
 }
 
 /**
@@ -87,13 +113,12 @@ function resolveQuality(quality: ImageTransform['quality']): number | undefined
  * preserves aspect ratio and there's no crop/focus to apply on top of it.
  * Users who need cropping or focus should pass them via `transformation`.
  */
-function buildIKTransformations(options: ImageTransform): Transformation[] {
+function buildIKTransformations(options: IKImageTransform): Transformation[] {
   const result: Transformation[] = [];
 
   // 1. User-supplied transformations come first.
-  const userTransformation = (options as any).transformation as Transformation[] | undefined;
-  if (Array.isArray(userTransformation) && userTransformation.length > 0) {
-    result.push(...userTransformation);
+  if (Array.isArray(options.transformation) && options.transformation.length > 0) {
+    result.push(...options.transformation);
   }
 
   // 2. Final chain step: width / quality / at_max crop.
@@ -118,14 +143,15 @@ const service: ExternalImageService = {
   },
 
   getURL(options: ImageTransform, imageConfig: AstroConfig['image']) {
-    const { urlEndpoint, transformationPosition } = resolveConfig(options, imageConfig);
-    const src = typeof options.src === 'string' ? options.src : options.src.src;
+    const opts = options as IKImageTransform;
+    const { urlEndpoint, transformationPosition } = resolveConfig(opts, imageConfig);
+    const src = typeof opts.src === 'string' ? opts.src : opts.src.src;
 
     return buildSrc({
       src,
       urlEndpoint,
-      transformation: buildIKTransformations(options),
-      queryParameters: (options as any).queryParameters,
+      transformation: buildIKTransformations(opts),
+      queryParameters: opts.queryParameters,
       transformationPosition,
     });
   },
@@ -156,7 +182,14 @@ const service: ExternalImageService = {
       queryParameters,
       transformationPosition,
       ...nonIKAttributes
-    } = options as any;
+    } = options as IKImageTransform & {
+      format?: unknown;
+      fit?: unknown;
+      position?: unknown;
+      layout?: unknown;
+      background?: unknown;
+      inferSize?: unknown;
+    };
 
     return {
       ...nonIKAttributes,
@@ -173,10 +206,8 @@ const service: ExternalImageService = {
    * need handling here.
    */
   getSrcSet(options: ImageTransform): UnresolvedSrcSetValue[] {
-    const { width, height, densities, widths } = options as ImageTransform & {
-      densities?: Array<number | `${number}x`>;
-      widths?: number[];
-    };
+    const opts = options as IKImageTransform;
+    const { width, height, densities, widths } = opts;
 
     const targets: Array<{ w: number; descriptor: string }> = [];
 
@@ -193,7 +224,7 @@ const service: ExternalImageService = {
 
     return targets.map(({ w, descriptor }) => ({
       transform: {
-        ...options,
+        ...opts,
         width: Math.round(w),
         height: aspectRatio ? Math.round(w / aspectRatio) : height,
       },
@@ -204,3 +235,4 @@ const service: ExternalImageService = {
 };
 
 export default service;
+