astro-lqip 1.5.0 → 1.6.0

package/README.md

@@ -13,6 +13,7 @@ Native extended Astro components for generating low quality image placeholders (
 - 🖼️ Supports both `<Image>` and `<Picture>` components.
 - 🎨 Multiple LQIP techniques: base64, solid color, CSS via gradients and SVG.
 - 🚀 Easy to use, just replace the native Astro components with the ones from [astro-lqip](https://astro-lqip.web.app/).
+- ⚡️ Support images as static imports or using string paths.
 - 🔧 Fully compatible with [Astro's image optimization features](https://docs.astro.build/en/guides/images/).
 - 🌍 Supports both local and remote images.
 - ⚙️ Supports SSR mode with [Node Adapter](https://docs.astro.build/en/guides/integrations-guide/node/).
@@ -66,9 +67,47 @@ import otherImage from './path/to/other-image.png';
 ---
 
 <Image src={image} alt="Cover Image" width={220} height={220} />
-<Picture src={otherImage} alt="Other cover Image" width={220} height={220} />
+<Picture src={otherImage} alt="Other Image" width={220} height={220} />
 ```
 
+> [!TIP]
+> Since version `1.6.0`, you can also put the image path as string directly in the `src` prop. Support absolute paths in `src`, relative paths and alias.
+
+Example with absolute path:
+
+```astro
+---
+import { Image, Picture } from 'astro-lqip/components';
+---
+
+<Image src="/src/path/to/image.png" alt="Cover Image" width={220} height={220} />
+<Picture src="/src/path/to/other-image.png" alt="Other Image" width={220} height={220} />
+```
+
+Example with relative path:
+
+```astro
+---
+import { Image, Picture } from 'astro-lqip/components';
+---
+
+<Image src="../path/to/image.png" alt="Cover Image" width={220} height={220} />
+<Picture src="../path/to/other-image.png" alt="Other Image" width={220} height={220} />
+```
+
+Example with alias:
+
+```astro
+---
+import { Image, Picture } from 'astro-lqip/components';
+---
+
+<Image src="@/assets/image.png" alt="Cover Image" width={220} height={220} />
+<Picture src="@/assets/other-image.png" alt="Other Image" width={220} height={220} />
+```
+
+Learn how to configure path aliasing in the [Astro documentation](https://docs.astro.build/en/guides/typescript/#import-aliases).
+
 ## ⚙️ Props
 
 Both `<Image>` and `<Picture>` components support all the props of the [native Astro components](https://docs.astro.build/en/reference/modules/astro-assets/), but adds a couple of props for LQIP management:
@@ -94,7 +133,7 @@ import otherImage from './path/to/other-image.png';
 ---
 
 <Image src={image} alt="Cover Image" width={220} height={220} lqip="svg" lqipSize={10} />
-<Picture src={otherImage} alt="Other cover Image" width={220} height={220} lqip="css" lqipSize={7} />
+<Picture src={otherImage} alt="Other Image" width={220} height={220} lqip="css" lqipSize={7} />
 ```
 
 > [!TIP]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-lqip",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Native extended Astro components for generating low quality image placeholders (LQIP).",
   "keywords": [
     "astro",

package/src/components/Image.astro

@@ -18,15 +18,20 @@ const { class: className, lqip = 'base64', lqipSize = 4, parentAttributes = {},
 const isDevelopment = import.meta.env.MODE === 'development'
 const isPrerendered = Astro.isPrerendered
 
-const { combinedStyle } = await useLqipImage({
+const { combinedStyle, resolvedSrc } = await useLqipImage({
   src: props.src,
   lqip,
   lqipSize,
-  styleProps: parentAttributes.style ?? {},
+  styleProps: (parentAttributes.style ?? {}) as Record<string, string | number | undefined>,
+  forbiddenVars: [],
   isDevelopment,
   isPrerendered
 })
 
+const componentProps = {
+  ...props,
+  src: resolvedSrc ?? props.src
+}
 const combinedParentAttributes = {
   ...parentAttributes,
   style: combinedStyle
@@ -35,7 +40,7 @@ const combinedParentAttributes = {
 
 <div class={className} data-astro-lqip {...combinedParentAttributes}>
   <ImageComponent
-    {...props}
+    {...componentProps as LocalImageProps | RemoteImageProps}
     class={className}
     onload="parentElement.style.setProperty('--z-index', 1), parentElement.style.setProperty('--opacity', 0)"
   />

package/src/components/Picture.astro

@@ -15,15 +15,20 @@ const { class: className, lqip = 'base64', lqipSize = 4, pictureAttributes = {},
 const isDevelopment = import.meta.env.MODE === 'development'
 const isPrerendered = Astro.isPrerendered
 
-const { combinedStyle } = await useLqipImage({
+const { combinedStyle, resolvedSrc } = await useLqipImage({
   src: props.src,
   lqip,
   lqipSize,
-  styleProps: pictureAttributes.style ?? {},
+  styleProps: (pictureAttributes.style ?? {}) as Record<string, string | number | undefined>,
+  forbiddenVars: [],
   isDevelopment,
   isPrerendered
 })
 
+const componentProps = {
+  ...props,
+  src: resolvedSrc ?? props.src
+}
 const combinedPictureAttributes = {
   ...pictureAttributes,
   style: combinedStyle
@@ -31,7 +36,7 @@ const combinedPictureAttributes = {
 ---
 
 <PictureComponent
-  {...props}
+  {...(componentProps as AstroPictureProps)}
   class={className}
   pictureAttributes={{ 'data-astro-lqip': '', ...combinedPictureAttributes }}
   onload="parentElement.style.setProperty('--z-index', 1), parentElement.style.setProperty('--opacity', 0)"

package/src/types/components-options.type.ts

@@ -4,7 +4,7 @@ export type ComponentsOptions = {
   src: string | object
   lqip: LqipType
   lqipSize: number
-  styleProps: Record<string, any>
+  styleProps: Record<string, string | number | undefined>
   forbiddenVars: string[]
   isDevelopment: boolean | undefined
   isPrerendered: boolean | undefined

package/src/types/image-path.type.ts

@@ -1 +1,4 @@
 export type ImagePath = string | { src: string } | Promise<{ default: { src: string } }>
+export type ResolvedImage = { src: string, width?: number, height?: number, [k: string]: unknown }
+export type ImportModule = Record<string, unknown> & { default?: unknown }
+export type GlobMap = Record<string, () => Promise<ImportModule>>

package/src/utils/resolveImagePath.ts

@@ -1,10 +1,128 @@
-import type { ImagePath } from '../types'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { GlobMap, ImagePath, ImportModule, ResolvedImage } from '../types'
+
+import { PREFIX } from '../constants'
+
+const PUBLIC_DIR = join(process.cwd(), 'public')
+
+const globFilesInSrc: GlobMap = ({ ...import.meta.glob('/src/**/*.{png,jpg,jpeg,svg}') } as unknown) as GlobMap
+
+function warnFiles(filePath: string | undefined) {
+  if (!filePath) return
+
+  const lowerPath = filePath.toLowerCase()
+
+  if (lowerPath.includes(`${join('/', 'public')}`) || lowerPath.includes('/public/') || filePath.startsWith(PUBLIC_DIR)) {
+    console.warn(
+      `${PREFIX} Warning: image resolved from /public. Images should not be placed in /public — move them to /src so Astro can process them correctly.`
+    )
+  }
+
+  if (lowerPath.endsWith('.webp') || lowerPath.endsWith('.avif')) {
+    const extension = lowerPath.endsWith('.webp') ? 'webp' : 'avif'
+    console.warn(
+      `${PREFIX} Warning: image is in ${extension} format. These formats are usually already optimized; using this component to re-process them may degrade quality.`
+    )
+  }
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null
+}
+
+function isPromise(v: unknown): v is Promise<unknown> {
+  if (!isObject(v)) return false
+  const promise = v as { then?: unknown }
+  return typeof promise.then === 'function'
+}
+
+function hasSrc(v: unknown): v is ResolvedImage {
+  return isObject(v) && typeof (v as Record<string, unknown>)['src'] === 'string'
+}
+
+function isRemoteUrl(v: string) {
+  return /^https?:\/\//.test(v)
+}
+
+function findGlobMatch(keys: string[], path: string) {
+  const candidates = [path.replace(/^\//, ''), `/${path.replace(/^\//, '')}`]
+  const match = keys.find((k) => candidates.includes(k) || k.endsWith(path) || k.endsWith(path.replace(/^\//, '')))
+  if (match) return match
+
+  const fileName = path.split('/').pop()
+  if (!fileName) return null
+
+  return keys.find((k) => k.endsWith(`/${fileName}`) || k.endsWith(fileName)) ?? null
+}
 
 export async function resolveImagePath(path: ImagePath) {
-  // If it's a string, we can't resolve it here. ex: Remote images URLs
-  if (typeof path === 'string') return null
-  // Handle dynamic imports
-  if ('then' in path && typeof path.then === 'function') return (await path).default
-  if ('src' in path) return path
+  if (path == null) return null
+
+  // validate dynamic import (Promise-like)
+  if (isPromise(path)) {
+    const mod = (await (path as Promise<ImportModule>)) as ImportModule
+    const resolved = (mod.default ?? mod) as unknown
+    if (hasSrc(resolved)) {
+      warnFiles(resolved.src)
+      return resolved
+    }
+    if (typeof resolved === 'string') {
+      warnFiles(resolved)
+      return resolved
+    }
+    return null
+  }
+
+  // validate already-resolved object (import result or { src: ... })
+  if (isObject(path)) {
+    const obj = path as Record<string, unknown>
+    const objSrc = typeof obj['src'] === 'string' ? (obj['src'] as string) : undefined
+    warnFiles(objSrc)
+    return hasSrc(obj) ? (obj as ResolvedImage) : null
+  }
+
+  // validate string path
+  if (typeof path === 'string') {
+    if (isRemoteUrl(path)) return path
+
+    const keys = Object.keys(globFilesInSrc)
+    const matchKey = findGlobMatch(keys, path)
+
+    if (matchKey) {
+      try {
+        const mod = await globFilesInSrc[matchKey]()
+        const resolved = (mod.default ?? mod) as unknown
+
+        if (hasSrc(resolved)) {
+          warnFiles((resolved as ResolvedImage).src)
+          return resolved as ResolvedImage
+        }
+
+        if (typeof resolved === 'string') {
+          warnFiles(resolved)
+          return resolved
+        }
+      } catch (err) {
+        console.log(`${PREFIX} resolveImagePath: failed to import glob match "${matchKey}" — falling back to filesystem.`, err)
+      }
+    }
+
+    // If module doesn't expose a usable value, fall through to filesystem check
+    try {
+      const absCandidate = path.startsWith('/') ? join(process.cwd(), path) : join(process.cwd(), path)
+
+      if (existsSync(absCandidate)) {
+        warnFiles(absCandidate)
+        return { src: `/@fs${absCandidate}` }
+      }
+    } catch (err) {
+      console.debug(`${PREFIX} resolveImagePath: filesystem check failed for "${path}".`, err)
+    }
+
+    return null
+  }
+
   return null
 }

package/src/utils/useLqipImage.ts

@@ -1,4 +1,4 @@
-import type { ComponentsOptions, SVGNode } from '../types'
+import type { ComponentsOptions, ImagePath, SVGNode } from '../types'
 
 import { PREFIX } from '../constants'
 
@@ -16,19 +16,14 @@ export async function useLqipImage({
   isDevelopment,
   isPrerendered
 }: ComponentsOptions) {
-  let getImagePath: string | { src: string } | null
-
-  if (typeof src === 'string') {
-    getImagePath = src
-  } else if (typeof src === 'object' && src !== null) {
-    getImagePath = await resolveImagePath(src as unknown as string)
-  } else {
-    getImagePath = null
-  }
+  // resolve any kind of src (string, alias, import result, dynamic import)
+  const resolved = await resolveImagePath(src as unknown as ImagePath)
+  // resolved may be an object (module-like), { src: '...' } or null
+  const resolvedSrc = resolved ?? null
 
   let lqipImage
-  if (getImagePath) {
-    const lqipInput = typeof getImagePath === 'string' ? { src: getImagePath } : getImagePath
+  if (resolvedSrc) {
+    const lqipInput = typeof resolvedSrc === 'string' ? { src: resolvedSrc } : resolvedSrc
     lqipImage = await getLqip(lqipInput, lqip, lqipSize, isDevelopment, isPrerendered)
   }
 
@@ -52,5 +47,5 @@ export async function useLqipImage({
     ...lqipStyle
   }
 
-  return { lqipImage, svgHTML, lqipStyle, combinedStyle }
+  return { lqipImage, svgHTML, lqipStyle, combinedStyle, resolvedSrc }
 }