refactor(images): separate client and server image utilities for improved organization and functionality

Author: onmax

.eslintcache

@@ -6,7 +6,7 @@
  * Much simpler than the previous implementation.
  */
 import type { PrismicImageProps } from '@prismicio/vue'
-import { generateSrcSet, transformImageField } from '../../utils/prismic-images'
+import { generateSrcSet, transformImageField } from '../../utils/prismic-images-client'
 
 const props = defineProps<PrismicImageProps & {
   width?: number | string

app/components/ProxiedPrismicImage.vue

@@ -8,7 +8,7 @@ import process from 'node:process'
 import { defineNuxtModule } from '@nuxt/kit'
 import consola from 'consola'
 import environment from '../lib/env'
-import { downloadMissingImages, fetchPrismicImages } from '../utils/prismic-images'
+import { downloadMissingImages, fetchPrismicImages } from '../utils/prismic-images-server'
 
 const prismicAccessToken = process.env.PRISMIC_ACCESS_TOKEN!
 

modules/prismic-images.ts

@@ -1,5 +1,5 @@
 import type { ImageField } from '@prismicio/client'
-import { transformImageUrl } from '../../utils/prismic-images'
+import { transformImageUrl } from '../../utils/prismic-images-client'
 
 export function transformImageFieldToLocal(baseUrl: string, field: ImageField): ImageField {
   if (!field.url)

shared/utils/image-proxy.ts

@@ -0,0 +1,87 @@
+/**
+ * Client-safe Prismic image utilities
+ * These functions can be used in Vue components and other client-side code
+ */
+
+const IMAGE_FOLDER = 'assets/images/prismic'
+
+// Transform Prismic URL to local URL (client-safe)
+export function transformImageUrl(baseUrl: string, url: string): string {
+  if (!url?.includes('prismic'))
+    return url
+
+  const fileName = normalizeFileName(url.split('/').pop() || 'image')
+  return `${baseUrl.replace(/\/$/, '')}/${IMAGE_FOLDER}/${fileName}`
+}
+
+// Transform image field with responsive variants (client-safe)
+export function transformImageField(baseUrl: string, field: any): any {
+  const transformed = { ...field }
+
+  if (field.url) {
+    transformed.url = transformImageUrl(baseUrl, field.url)
+  }
+
+  // Handle responsive variants
+  const responsiveViews = ['Lg', 'Md', 'Sm', 'Xs'] as const
+  for (const view of responsiveViews) {
+    const variant = (field as any)[view]
+    if (variant?.url) {
+      (transformed as any)[view] = {
+        ...variant,
+        url: transformImageUrl(baseUrl, variant.url),
+      }
+    }
+  }
+
+  return transformed
+}
+
+// Generate srcSet from transformed field (client-safe)
+export function generateSrcSet(field: any, widths?: number[] | string): { src: string, srcSet: string } {
+  const defaultWidths = [640, 768, 1024, 1280, 1536]
+  const _targetWidths = widths || defaultWidths
+
+  const src = field.url || ''
+  const srcSetEntries: string[] = []
+
+  // Add main image
+  if (src && field.dimensions?.width) {
+    srcSetEntries.push(`${src} ${field.dimensions.width}w`)
+  }
+
+  // Add responsive variants
+  const responsiveViews = ['Xs', 'Sm', 'Md', 'Lg'] as const
+  for (const view of responsiveViews) {
+    const variant = (field as any)[view]
+    if (variant?.url && variant.dimensions?.width) {
+      srcSetEntries.push(`${variant.url} ${variant.dimensions.width}w`)
+    }
+  }
+
+  return {
+    src,
+    srcSet: srcSetEntries.join(', '),
+  }
+}
+
+// Client-safe filename normalization
+function normalizeFileName(fileName: string): string {
+  // Extract just the base filename and extension, removing Prismic URL parameters
+  // Example: "image.png_auto_compress_format_rect_0_0_100_100" -> "image.png"
+  const extensionMatch = fileName.match(/\.(jpg|jpeg|png|gif|webp|svg|avif)/i)
+  if (extensionMatch) {
+    const extensionIndex = fileName.indexOf(extensionMatch[0])
+    const baseFileName = fileName.substring(0, extensionIndex + extensionMatch[0].length)
+    fileName = baseFileName
+  }
+
+  return fileName
+    .replace(/%([0-9A-F]{2})/gi, (_, hex) => {
+      const char = String.fromCharCode(Number.parseInt(hex, 16))
+      return /[\w.-]/.test(char) ? char : '_'
+    })
+    .replace(/[^\w.-]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '') || 'image'
+}

utils/prismic-images-client.ts

@@ -1,3 +1,7 @@
+/**
+ * Server-only Prismic image utilities
+ * These functions use Node.js APIs and can only run on the server
+ */
 import type { BlogPageDocument, ExchangeDocument, NavigationDocument, PageDocument } from '~~/prismicio-types'
 import { filter } from '@prismicio/client'
 import consola from 'consola'
@@ -16,67 +20,7 @@ export interface ImageInfo {
 
 const IMAGE_FOLDER = 'assets/images/prismic'
 
-// Transform Prismic URL to local URL
-export function transformImageUrl(baseUrl: string, url: string): string {
-  if (!url?.includes('prismic'))
-    return url
-
-  const fileName = normalizeFileName(url.split('/').pop() || 'image')
-  return `${baseUrl.replace(/\/$/, '')}/${IMAGE_FOLDER}/${fileName}`
-}
-
-// Transform image field with responsive variants
-export function transformImageField(baseUrl: string, field: any): any {
-  const transformed = { ...field }
-
-  if (field.url) {
-    transformed.url = transformImageUrl(baseUrl, field.url)
-  }
-
-  // Handle responsive variants
-  const responsiveViews = ['Lg', 'Md', 'Sm', 'Xs'] as const
-  for (const view of responsiveViews) {
-    const variant = (field as any)[view]
-    if (variant?.url) {
-      (transformed as any)[view] = {
-        ...variant,
-        url: transformImageUrl(baseUrl, variant.url),
-      }
-    }
-  }
-
-  return transformed
-}
-
-// Generate srcSet from transformed field
-export function generateSrcSet(field: any, widths?: number[] | string): { src: string, srcSet: string } {
-  const defaultWidths = [640, 768, 1024, 1280, 1536]
-  const _targetWidths = widths || defaultWidths
-
-  const src = field.url || ''
-  const srcSetEntries: string[] = []
-
-  // Add main image
-  if (src && field.dimensions?.width) {
-    srcSetEntries.push(`${src} ${field.dimensions.width}w`)
-  }
-
-  // Add responsive variants
-  const responsiveViews = ['Xs', 'Sm', 'Md', 'Lg'] as const
-  for (const view of responsiveViews) {
-    const variant = (field as any)[view]
-    if (variant?.url && variant.dimensions?.width) {
-      srcSetEntries.push(`${variant.url} ${variant.dimensions.width}w`)
-    }
-  }
-
-  return {
-    src,
-    srcSet: srcSetEntries.join(', '),
-  }
-}
-
-// Extract all images from Prismic document
+// Extract all images from Prismic document (server-only)
 export function extractImagesFromDocument(baseUrl: string, document: any): ImageInfo[] {
   const images: ImageInfo[] = []
 
@@ -152,7 +96,7 @@ function normalizeFileName(fileName: string): string {
     .replace(/^_+|_+$/g, '') || 'image'
 }
 
-// Fetch all Prismic data and extract images
+// Fetch all Prismic data and extract images (server-only)
 export async function fetchPrismicImages(prismicAccessToken: string, showDrafts = false): Promise<ImageInfo[]> {
   consola.info('🌐 Fetching Prismic data...')
 
@@ -183,7 +127,7 @@ export async function fetchPrismicImages(prismicAccessToken: string, showDrafts
   return uniqueImages
 }
 
-// Download missing images
+// Download missing images (server-only)
 export async function downloadMissingImages(images: ImageInfo[]): Promise<void> {
   if (import.meta.client)
     return
@@ -271,7 +215,7 @@ async function findMissingImages(images: ImageInfo[]): Promise<ImageInfo[]> {
   }
 }
 
-// Prismic API helpers
+// Prismic API helpers (server-only)
 async function fetchDocuments<T>(
   documentType: string,
   prismicAccessToken: string,
@@ -306,7 +250,7 @@ async function fetchDocument<T>(
     return response.results[0] || null
   }
   catch (error) {
-    console.warn(`⚠️ Failed to fetch ${documentType}:`, error)
+    consola.warn(`⚠️ Failed to fetch ${documentType}:`, error)
     return null
   }
 }