astro-lqip 1.5.0 → 1.7.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/).
@@ -61,14 +62,53 @@ Example:
 ---
 import { Image, Picture } from 'astro-lqip/components';
 
-import image from './path/to/image.png';
-import otherImage from './path/to/other-image.png';
+import image from '/src/assets/images/image.png';
+import otherImage from '/src/assets/images/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/assets/images/image.png" alt="Cover Image" width={220} height={220} />
+<Picture src="/src/assets/images/other-image.png" alt="Other Image" width={220} height={220} />
+```
+
+Example with relative path:
+
+```astro
+---
+import { Image, Picture } from 'astro-lqip/components';
+---
+
+<!-- assuming you are on the path `/src/pages/index.astro` -->
+<Image src="../assets/images/image.png" alt="Cover Image" width={220} height={220} />
+<Picture src="../assets/images/other-image.png" alt="Other Image" width={220} height={220} />
+```
+
+Example with alias:
+
+```astro
+---
+import { Image, Picture } from 'astro-lqip/components';
+---
+
+<Image src="@/assets/images/image.png" alt="Cover Image" width={220} height={220} />
+<Picture src="@/assets/images/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). If you want more examples of uses you can see the [Usage Tips](https://astro-lqip.web.app/usage-tips/) page.
+
 ## ⚙️ 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:
@@ -89,12 +129,12 @@ Example:
 ---
 import { Image, Picture } from 'astro-lqip/components';
 
-import image from './path/to/image.png';
-import otherImage from './path/to/other-image.png';
+import image from '/src/assets/images/image.png';
+import otherImage from '/src/assets/images/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]
@@ -104,6 +144,8 @@ import otherImage from './path/to/other-image.png';
 
 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.
 
+For some simple tips, visit the [Usage Tips](https://astro-lqip.web.app/usage-tips/) page.
+
 ## 🤝 Contributing
 If you wish to contribute to this project, you can do so by reading the [contribution guide](https://github.com/felixicaza/astro-lqip/blob/main/CONTRIBUTING.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-lqip",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Native extended Astro components for generating low quality image placeholders (LQIP).",
   "keywords": [
     "astro",
@@ -37,17 +37,17 @@
     "plaiceholder": "3.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.37.0",
-    "@typescript-eslint/parser": "8.46.1",
-    "astro": "5.14.5",
+    "@eslint/js": "9.39.1",
+    "@typescript-eslint/parser": "8.46.4",
+    "astro": "5.15.5",
     "bumpp": "10.3.1",
-    "eslint": "9.37.0",
-    "eslint-plugin-astro": "1.3.1",
+    "eslint": "9.39.1",
+    "eslint-plugin-astro": "1.5.0",
     "eslint-plugin-jsonc": "2.21.0",
     "eslint-plugin-jsx-a11y": "6.10.2",
-    "eslint-plugin-package-json": "0.56.4",
+    "eslint-plugin-package-json": "0.71.0",
     "eslint-plugin-yml": "1.19.0",
-    "globals": "16.4.0",
+    "globals": "16.5.0",
     "jiti": "2.6.1",
     "nano-staged": "0.8.0",
     "neostandard": "0.12.2",

package/src/components/Image.astro

@@ -16,17 +16,20 @@ 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,
-  isPrerendered
+  styleProps: (parentAttributes.style ?? {}) as Record<string, string | number | undefined>,
+  forbiddenVars: [],
+  isDevelopment
 })
 
+const componentProps = {
+  ...props,
+  src: resolvedSrc ?? props.src
+}
 const combinedParentAttributes = {
   ...parentAttributes,
   style: combinedStyle
@@ -35,7 +38,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,17 +13,20 @@ 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,
-  isPrerendered
+  styleProps: (pictureAttributes.style ?? {}) as Record<string, string | number | undefined>,
+  forbiddenVars: [],
+  isDevelopment
 })
 
+const componentProps = {
+  ...props,
+  src: resolvedSrc ?? props.src
+}
 const combinedPictureAttributes = {
   ...pictureAttributes,
   style: combinedStyle
@@ -31,7 +34,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,8 +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/generateLqip.ts

@@ -6,6 +6,13 @@ import { PREFIX } from '../constants'
 
 import { getPlaiceholder } from 'plaiceholder'
 
+function normalizeFsPath(path: string) {
+  if (process.platform === 'win32' && /^\/[A-Za-z]:\//.test(path)) {
+    return path.slice(1)
+  }
+  return path
+}
+
 export async function generateLqip(
   imagePath: string,
   lqipType: LqipType,
@@ -13,7 +20,15 @@ export async function generateLqip(
   isDevelopment: boolean | undefined
 ) {
   try {
-    const buffer = await readFile(imagePath)
+    const normalizedPath = normalizeFsPath(imagePath)
+
+    const buffer = await readFile(normalizedPath)
+
+    if (!buffer) {
+      console.warn(`${PREFIX} image not found for:`, imagePath)
+      return undefined
+    }
+
     const plaiceholderResult = await getPlaiceholder(buffer, { size: lqipSize })
     let lqipValue: string | GetSVGReturn | undefined
 

package/src/utils/getLqip.ts

@@ -1,16 +1,22 @@
 import { join } from 'node:path'
-import { mkdir, writeFile, unlink } from 'node:fs/promises'
-import { existsSync } from 'node:fs'
+import { mkdir, writeFile, unlink, readdir } from 'node:fs/promises'
+import { existsSync, statSync } from 'node:fs'
 
 import type { LqipType } from '../types'
 
 import { generateLqip } from './generateLqip'
 
+import { PREFIX } from '../constants'
+
 function isRemoteUrl(url: string) {
   return /^https?:\/\//.test(url)
 }
 
 const CACHE_DIR = join(process.cwd(), 'node_modules', '.cache', 'astro-lqip')
+const EXTENSIONS = ['jpg', 'jpeg', 'png', 'webp', 'avif']
+const SEARCH_ROOT = ['src']
+
+const searchCache = new Map<string, string | null>()
 
 async function ensureCacheDir() {
   if (!existsSync(CACHE_DIR)) {
@@ -18,12 +24,80 @@ async function ensureCacheDir() {
   }
 }
 
+function extractOriginalFileName(filename: string) {
+  const file = filename.split('/').pop() || ''
+
+  const match = file.match(/^(.+?)\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9]+$/)
+  if (match) return match[1]
+
+  const parts = file.split('.')
+  if (parts.length >= 3) return parts.slice(0, parts.length - 2).join('.')
+
+  return parts[0]
+}
+
+async function recursiveFind(basename: string): Promise<string | undefined> {
+  if (!basename) return
+
+  if (searchCache.has(basename)) {
+    const cached = searchCache.get(basename)
+    return cached || undefined
+  }
+
+  const ignoreDirs = new Set(['node_modules', 'dist', '.astro'])
+
+  async function walk(dir: string): Promise<string | undefined> {
+    let entries: string[]
+
+    try {
+      entries = await readdir(dir)
+    } catch {
+      return
+    }
+
+    for (const entry of entries) {
+      const full = join(dir, entry)
+      let st: ReturnType<typeof statSync>
+
+      try {
+        st = statSync(full)
+      } catch {
+        continue
+      }
+
+      if (st.isDirectory()) {
+        if (ignoreDirs.has(entry)) continue
+        const found = await walk(full)
+        if (found) return found
+      } else {
+        // match by basename and extension
+        if (EXTENSIONS.some((ext) => entry === `${basename}.${ext}`)) {
+          return full
+        }
+      }
+    }
+  }
+
+  for (const rootRel of SEARCH_ROOT) {
+    const rootAbs = join(process.cwd(), rootRel)
+
+    if (existsSync(rootAbs)) {
+      const found = await walk(rootAbs)
+      if (found) {
+        searchCache.set(basename, found)
+        return found
+      }
+    }
+  }
+
+  searchCache.set(basename, null)
+}
+
 export async function getLqip(
   imagePath: { src: string },
   lqipType: LqipType,
   lqipSize: number,
-  isDevelopment: boolean | undefined,
-  isPrerendered: boolean | undefined
+  isDevelopment: boolean | undefined
 ) {
   if (!imagePath?.src) return undefined
 
@@ -39,8 +113,7 @@ export async function getLqip(
     await writeFile(tempPath, buffer)
 
     try {
-      const lqip = await generateLqip(tempPath, lqipType, lqipSize, isDevelopment)
-      return lqip
+      return await generateLqip(tempPath, lqipType, lqipSize, isDevelopment)
     } finally {
       await unlink(tempPath)
     }
@@ -51,14 +124,35 @@ export async function getLqip(
     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) {
+    const src = imagePath.src
+
+    const clean = src.replace(/^\//, '')
+
+    const candidatePaths = [
+      join(process.cwd(), 'dist', 'client', clean),
+      join(process.cwd(), 'dist', clean),
+      join(process.cwd(), 'dist', '_astro', clean.replace(/^_astro\//, ''))
+    ]
 
-  if (!isDevelopment && imagePath.src.startsWith('/_astro/')) {
-    const buildPath = join(process.cwd(), 'dist', imagePath.src)
-    return await generateLqip(buildPath, lqipType, lqipSize, isDevelopment)
+    for (const path of candidatePaths) {
+      if (existsSync(path)) {
+        return await generateLqip(path, lqipType, lqipSize, isDevelopment)
+      }
+    }
+
+    // if not found, try to recursively find the original source
+    if (src.startsWith('/_astro/')) {
+      const originalBase = extractOriginalFileName(src)
+      const originalSource = await recursiveFind(originalBase)
+
+      if (originalSource) {
+        console.log(`${PREFIX} fallback recursive source found:`, originalSource)
+        return await generateLqip(originalSource, lqipType, lqipSize, isDevelopment)
+      } else {
+        console.warn(`${PREFIX} original source not found recursively for basename:`, originalBase)
+      }
+    }
   }
 
   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,23 +13,17 @@ export async function useLqipImage({
   lqipSize = 4,
   styleProps = {},
   forbiddenVars = ['--lqip-background', '--z-index', '--opacity'],
-  isDevelopment,
-  isPrerendered
+  isDevelopment
 }: 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, lqip, lqipSize, isDevelopment, isPrerendered)
+  if (resolvedSrc) {
+    const lqipInput = typeof resolvedSrc === 'string' ? { src: resolvedSrc } : resolvedSrc
+    lqipImage = await getLqip(lqipInput, lqip, lqipSize, isDevelopment)
   }
 
   let svgHTML = ''
@@ -52,5 +46,5 @@ export async function useLqipImage({
     ...lqipStyle
   }
 
-  return { lqipImage, svgHTML, lqipStyle, combinedStyle }
+  return { lqipImage, svgHTML, lqipStyle, combinedStyle, resolvedSrc }
 }