astro-lqip 1.4.1 → 1.6.0

package/README.md

@@ -9,6 +9,15 @@
 
 Native extended Astro components for generating low quality image placeholders (LQIP).
 
+## ✨ Features
+- 🖼️ 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/).
+
 ## ⬇️ Installation
 
 NPM:
@@ -58,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:
@@ -73,7 +120,7 @@ Both `<Image>` and `<Picture>` components support all the props of the [native A
 - `lqipSize`: The size of the LQIP image, which can be any number from `4` to `64`. (default is 4)
 
 > [!WARNING]
-> A major size in the `lqipSize` prop can significantly impact the performance of your application.
+> A high value for `lqipSize` can significantly increase the total size of your website.
 
 Example:
 
@@ -86,21 +133,12 @@ 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]
 > For the `<Image>` component, a `parentAttributes` prop similar to `pictureAttributes` has been added.
 
-## 📝 ToDo
-
-- [x] Add support for Image component.
-- [x] Add support for more lqip techniques.
-- [x] Test for remote images.
-- [x] Optimize current CSS usage.
-- [x] Improve docs page.
-- [ ] Test support for SSR mode.
-
 ## 💡 Knowledge
 
 Since this integration is built on top of Astro native `<Image>` and `<Picture>` components, you can refer to the [Astro documentation](https://docs.astro.build/en/guides/images/) for more information on how to use it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-lqip",
-  "version": "1.4.1",
+  "version": "1.6.0",
   "description": "Native extended Astro components for generating low quality image placeholders (LQIP).",
   "keywords": [
     "astro",
@@ -37,18 +37,18 @@
     "plaiceholder": "3.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.36.0",
-    "@typescript-eslint/parser": "8.44.1",
-    "astro": "5.13.11",
-    "bumpp": "10.2.3",
-    "eslint": "9.36.0",
+    "@eslint/js": "9.37.0",
+    "@typescript-eslint/parser": "8.46.1",
+    "astro": "5.14.5",
+    "bumpp": "10.3.1",
+    "eslint": "9.37.0",
     "eslint-plugin-astro": "1.3.1",
-    "eslint-plugin-jsonc": "2.20.1",
+    "eslint-plugin-jsonc": "2.21.0",
     "eslint-plugin-jsx-a11y": "6.10.2",
-    "eslint-plugin-package-json": "0.56.3",
-    "eslint-plugin-yml": "1.18.0",
+    "eslint-plugin-package-json": "0.56.4",
+    "eslint-plugin-yml": "1.19.0",
     "globals": "16.4.0",
-    "jiti": "2.6.0",
+    "jiti": "2.6.1",
     "nano-staged": "0.8.0",
     "neostandard": "0.12.2",
     "simple-git-hooks": "2.13.1"

package/src/components/Image.astro

@@ -16,15 +16,22 @@ type Props = (LocalImageProps | RemoteImageProps) & LqipProps & {
 const { class: className, lqip = 'base64', lqipSize = 4, parentAttributes = {}, ...props } = Astro.props as Props
 
 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 ?? {},
-  isDevelopment
+  styleProps: (parentAttributes.style ?? {}) as Record<string, string | number | undefined>,
+  forbiddenVars: [],
+  isDevelopment,
+  isPrerendered
 })
 
+const componentProps = {
+  ...props,
+  src: resolvedSrc ?? props.src
+}
 const combinedParentAttributes = {
   ...parentAttributes,
   style: combinedStyle
@@ -33,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

@@ -13,15 +13,22 @@ type Props = AstroPictureProps & LqipProps
 const { class: className, lqip = 'base64', lqipSize = 4, pictureAttributes = {}, ...props } = Astro.props as Props
 
 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 ?? {},
-  isDevelopment
+  styleProps: (pictureAttributes.style ?? {}) as Record<string, string | number | undefined>,
+  forbiddenVars: [],
+  isDevelopment,
+  isPrerendered
 })
 
+const componentProps = {
+  ...props,
+  src: resolvedSrc ?? props.src
+}
 const combinedPictureAttributes = {
   ...pictureAttributes,
   style: combinedStyle
@@ -29,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

@@ -2,9 +2,10 @@ import type { LqipType } from './lqip.type'
 
 export type ComponentsOptions = {
   src: string | object
-  lqip?: LqipType
-  lqipSize?: number
-  styleProps?: Record<string, any>
-  forbiddenVars?: string[]
-  isDevelopment?: boolean
+  lqip: LqipType
+  lqipSize: number
+  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/generateLqip.ts

@@ -6,7 +6,12 @@ import { PREFIX } from '../constants'
 
 import { getPlaiceholder } from 'plaiceholder'
 
-export async function generateLqip(imagePath: string, isDevelopment: boolean, lqipType: LqipType, lqipSize: number) {
+export async function generateLqip(
+  imagePath: string,
+  lqipType: LqipType,
+  lqipSize: number,
+  isDevelopment: boolean | undefined
+) {
   try {
     const buffer = await readFile(imagePath)
     const plaiceholderResult = await getPlaiceholder(buffer, { size: lqipSize })

package/src/utils/getLqip.ts

@@ -18,7 +18,13 @@ async function ensureCacheDir() {
   }
 }
 
-export async function getLqip(imagePath: { src: string }, isDevelopment: boolean, lqipType: LqipType, lqipSize: number) {
+export async function getLqip(
+  imagePath: { src: string },
+  lqipType: LqipType,
+  lqipSize: number,
+  isDevelopment: boolean | undefined,
+  isPrerendered: boolean | undefined
+) {
   if (!imagePath?.src) return undefined
 
   if (isRemoteUrl(imagePath.src)) {
@@ -33,7 +39,7 @@ export async function getLqip(imagePath: { src: string }, isDevelopment: boolean
     await writeFile(tempPath, buffer)
 
     try {
-      const lqip = await generateLqip(tempPath, isDevelopment, lqipType, lqipSize)
+      const lqip = await generateLqip(tempPath, lqipType, lqipSize, isDevelopment)
       return lqip
     } finally {
       await unlink(tempPath)
@@ -42,12 +48,17 @@ export async function getLqip(imagePath: { src: string }, isDevelopment: boolean
 
   if (isDevelopment && imagePath.src.startsWith('/@fs/')) {
     const filePath = imagePath.src.replace(/^\/@fs/, '').split('?')[0]
-    return await generateLqip(filePath, isDevelopment, lqipType, lqipSize)
+    return await generateLqip(filePath, lqipType, lqipSize, isDevelopment)
+  }
+
+  if (!isPrerendered && !isDevelopment) {
+    const filePath = join(process.cwd(), 'dist', 'client', imagePath.src)
+    return await generateLqip(filePath, lqipType, lqipSize, isDevelopment)
   }
 
   if (!isDevelopment && imagePath.src.startsWith('/_astro/')) {
     const buildPath = join(process.cwd(), 'dist', imagePath.src)
-    return await generateLqip(buildPath, isDevelopment, lqipType, lqipSize)
+    return await generateLqip(buildPath, lqipType, lqipSize, isDevelopment)
   }
 
   return undefined

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'
 
@@ -13,22 +13,18 @@ export async function useLqipImage({
   lqipSize = 4,
   styleProps = {},
   forbiddenVars = ['--lqip-background', '--z-index', '--opacity'],
-  isDevelopment = false
+  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
-    lqipImage = await getLqip(lqipInput, isDevelopment, lqip, lqipSize)
+  if (resolvedSrc) {
+    const lqipInput = typeof resolvedSrc === 'string' ? { src: resolvedSrc } : resolvedSrc
+    lqipImage = await getLqip(lqipInput, lqip, lqipSize, isDevelopment, isPrerendered)
   }
 
   let svgHTML = ''
@@ -51,5 +47,5 @@ export async function useLqipImage({
     ...lqipStyle
   }
 
-  return { lqipImage, svgHTML, lqipStyle, combinedStyle }
+  return { lqipImage, svgHTML, lqipStyle, combinedStyle, resolvedSrc }
 }