feat: add dynamic variables support with custom metadata fields and bulk generation

Author: ahnv

examples/react-example/src/index.tsx

@@ -1,10 +1,13 @@
 import {
+  type CustomMetadataFieldDefinition,
+  type DynamicVariableDefinition,
   ImageKitEditor,
   type ImageKitEditorProps,
   type ImageKitEditorRef,
   type TemplateStorageProvider,
   TRANSFORMATION_STATE_VERSION,
   type Transformation,
+  type VariableAssetResolver,
 } from "@imagekit/editor"
 import React, { useCallback, useEffect } from "react"
 import ReactDOM from "react-dom"
@@ -18,6 +21,8 @@ type StoredTemplateRecord = {
   isPinned: boolean
   name: string
   transformations: Omit<Transformation, "id">[]
+  variables?: DynamicVariableDefinition[]
+  urlTemplate?: string
   createdBy: { userId: string; name: string; email: string }
   updatedBy: { userId: string; name: string; email: string }
   createdAt: number
@@ -70,6 +75,8 @@ function createLocalTemplateStorage(): TemplateStorageProvider {
         isPinned: input.isPinned ?? existing?.isPinned ?? false,
         name: input.name,
         transformations: input.transformations,
+        variables: input.variables ?? existing?.variables,
+        urlTemplate: input.urlTemplate,
         createdBy: input.createdBy ??
           existing?.createdBy ?? {
             userId: session.userId,
@@ -112,6 +119,65 @@ function createLocalTemplateStorage(): TemplateStorageProvider {
   }
 }
 
+const SAMPLE_CUSTOM_METADATA_FIELDS: CustomMetadataFieldDefinition[] = [
+  {
+    id: "1",
+    name: "brand",
+    label: "Brand",
+    schema: { type: "Text", maxLength: 100 },
+  },
+  {
+    id: "2",
+    name: "category",
+    label: "Category",
+    schema: {
+      type: "SingleSelect",
+      selectOptions: ["shirts", "pants", "shoes", "accessories"],
+    },
+  },
+  {
+    id: "3",
+    name: "price",
+    label: "Price",
+    schema: { type: "Number", minValue: 0 },
+  },
+  {
+    id: "4",
+    name: "isActive",
+    label: "Active",
+    schema: { type: "Boolean" },
+  },
+  {
+    id: "5",
+    name: "publishDate",
+    label: "Publish Date",
+    schema: { type: "Date" },
+  },
+  {
+    id: "6",
+    name: "colors",
+    label: "Colors",
+    schema: {
+      type: "MultiSelect",
+      selectOptions: ["red", "blue", "green", "black", "white"],
+    },
+  },
+]
+
+const sampleVariableAssetResolver: VariableAssetResolver = async (request) => {
+  console.log(
+    "[variableAssetResolver] variable:",
+    request.variable.name,
+    "query:",
+    request.query,
+  )
+  await new Promise((resolve) => setTimeout(resolve, 500))
+  const mockPath = request.query.path
+    ? `${request.query.path.replace(/\/$/, "")}/sample.jpg`
+    : "/sample.jpg"
+  return { value: mockPath }
+}
+
 function App() {
   const [open, setOpen] = React.useState(true)
   const [editorProps, setEditorProps] =
@@ -254,6 +320,14 @@ function App() {
         return Promise.resolve(request.url)
       },
       templateStorage: createLocalTemplateStorage(),
+      customMetadataFields: SAMPLE_CUSTOM_METADATA_FIELDS,
+      variableAssetResolver: sampleVariableAssetResolver,
+      onBulkGenerate: (template) => {
+        console.log("Bulk generate requested for template:", template)
+        alert(
+          `Bulk Generate with CSV for "${template.name}" (id: ${template.id})`,
+        )
+      },
     })
   }, [handleAddImage])
 

packages/imagekit-editor-dev/src/ImageKitEditor.tsx

@@ -4,17 +4,21 @@ import merge from "lodash/merge"
 import React, {
   forwardRef,
   useCallback,
+  useEffect,
   useImperativeHandle,
   useMemo,
+  useRef,
 } from "react"
 import { EditorLayout, EditorWrapper } from "./components/editor"
 import type { HeaderProps } from "./components/header"
 import type { GetTemplatePermissions } from "./context/TemplatePermissionsContext"
 import { TemplatePermissionsContextProvider } from "./context/TemplatePermissionsContext"
 import { TemplateStorageContextProvider } from "./context/TemplateStorageContext"
 import {
+  type DynamicVariableDefinition,
   isTemplateAccessDeniedError,
   type TemplateStorageProvider,
+  type VariableAssetResolver,
 } from "./storage"
 import {
   type FocusObjects,
@@ -25,6 +29,7 @@ import {
   useEditorStore,
 } from "./store"
 import { themeOverrides } from "./theme"
+import { buildUrlTemplate } from "./utils/buildUrlTemplate"
 
 export interface ImageKitEditorRef {
   /**
@@ -46,29 +51,45 @@ export interface ImageKitEditorRef {
   setCurrentImage: (imageSrc: string) => void
 
   /**
-   * Gets the current editor template (transformation stack)
-   * @returns Array of transformation objects representing the template
+   * Gets the current editor template including transformations and variables.
+   * @returns Object with transformations and variables
    * @example
    * ```tsx
-   * const template = editorRef.current?.getTemplate()
+   * const { transformations, variables } = editorRef.current?.getTemplate()
    * // Save to localStorage or backend
-   * localStorage.setItem('editorTemplate', JSON.stringify(
-   *   template.map(({ id, ...rest }) => rest)
-   * ))
+   * localStorage.setItem('editorTemplate', JSON.stringify({ transformations, variables }))
    * ```
    */
-  getTemplate: () => Transformation[]
+  getTemplate: () => {
+    transformations: Transformation[]
+    variables: DynamicVariableDefinition[]
+    /**
+     * URL transformation string with `{{variableName}}` placeholders.
+     * Empty string when no transformations are active.
+     */
+    urlTemplate: string
+  }
 
   /**
-   * Loads a template (transformation stack) into the editor
-   * @param template - Array of transformation objects without the 'id' field
+   * Loads a template (transformations + variables) into the editor.
+   * Accepts either a full payload or a legacy transformations-only array.
    * @example
    * ```tsx
-   * const saved = JSON.parse(localStorage.getItem('editorTemplate'))
-   * editorRef.current?.loadTemplate(saved)
+   * // Full payload (recommended)
+   * editorRef.current?.loadTemplate({ transformations, variables })
+   *
+   * // Legacy: transformations-only array
+   * editorRef.current?.loadTemplate(savedTransformations)
    * ```
    */
-  loadTemplate: (template: Omit<Transformation, "id">[]) => void
+  loadTemplate: (
+    template:
+      | Omit<Transformation, "id">[]
+      | {
+          transformations: Omit<Transformation, "id">[]
+          variables?: DynamicVariableDefinition[]
+        },
+  ) => void
 
   /**
    * Explicitly saves the current template to the configured storage provider.
@@ -91,11 +112,34 @@ interface EditorProps<Metadata extends RequiredMetadata = RequiredMetadata> {
    * Omit or pass `null` to disable template sync UI.
    */
   templateStorage?: TemplateStorageProvider | null
+  variableAssetResolver?: VariableAssetResolver
+  /**
+   * Custom metadata field definitions from the host app (matches the shape of
+   * the ImageKit Get Custom Metadata Fields API response). When provided, the
+   * Variables modal renders typed form fields for each definition instead of
+   * falling back to free-form key-value pairs.
+   */
+  customMetadataFields?: import("./variables/types").CustomMetadataFieldDefinition[]
   /**
    * Host-controlled, per-template permissions for template management UI.
    * If omitted, the editor defaults to allowing all actions.
    */
   getTemplatePermissions?: GetTemplatePermissions
+  /**
+   * Called whenever dynamic variables change (add, update, remove).
+   * Use this to persist variables to your backend or localStorage.
+   */
+  onVariablesChange?: (variables: DynamicVariableDefinition[]) => void
+  /**
+   * Called when the user clicks "Bulk Generate" on a template row.
+   * The host app handles CSV upload and batch URL generation.
+   */
+  onBulkGenerate?: (template: { id: string; name: string }) => void
+  /**
+   * When provided, the editor fetches this template from `templateStorage`
+   * on mount and loads its transformations and variables.
+   */
+  templateId?: string
 }
 
 function ImageKitEditorImpl<M extends RequiredMetadata>(
@@ -108,16 +152,18 @@ function ImageKitEditorImpl<M extends RequiredMetadata>(
     signer,
     focusObjects,
     templateStorage,
+    variableAssetResolver,
+    customMetadataFields,
     getTemplatePermissions,
   } = props
   const {
     addImage,
     addImages,
     setCurrentImage,
-    transformations,
     initialize,
     destroy,
     loadTemplate,
+    loadTemplatePayload,
   } = useEditorStore()
 
   const resolvedProvider = useMemo<TemplateStorageProvider | null>(
@@ -140,6 +186,12 @@ function ImageKitEditorImpl<M extends RequiredMetadata>(
         transformations: state.transformations.map(
           ({ id: _id, ...rest }) => rest,
         ),
+        variables: state.dynamicVariables,
+        urlTemplate: buildUrlTemplate(
+          state.transformations,
+          state.visibleTransformations,
+          state.dynamicVariables,
+        ),
         ...(state.templateIsPrivate !== null
           ? { isPrivate: state.templateIsPrivate }
           : {}),
@@ -204,25 +256,120 @@ function ImageKitEditorImpl<M extends RequiredMetadata>(
       imageList: initialImages,
       signer,
       focusObjects,
+      variableAssetResolver,
+      customMetadataFields,
+      onBulkGenerate: props.onBulkGenerate,
+      onAddImage: props.onAddImage,
+    })
+    // Trigger onAddImage if initial image list is empty
+    if (!initialImages || initialImages.length === 0) {
+      props.onAddImage?.()
+    }
+  }, [
+    initialImages,
+    signer,
+    focusObjects,
+    variableAssetResolver,
+    customMetadataFields,
+    initialize,
+  ])
+
+  // Keep onBulkGenerate in sync with latest prop value
+  useEffect(() => {
+    useEditorStore.setState({ onBulkGenerate: props.onBulkGenerate })
+  }, [props.onBulkGenerate])
+
+  // Keep onAddImage in sync with latest prop value
+  useEffect(() => {
+    useEditorStore.setState({ onAddImage: props.onAddImage })
+  }, [props.onAddImage])
+
+  // Trigger onAddImage when image list becomes empty
+  useEffect(() => {
+    return useEditorStore.subscribe(
+      (state) => state.originalImageList.length,
+      (count, prevCount) => {
+        // Trigger when transitioning to empty (0 images) and not on initial mount (prevCount > 0)
+        if (count === 0 && prevCount > 0) {
+          useEditorStore.getState().onAddImage?.()
+        }
+      },
+    )
+  }, [])
+
+  // Load template by ID from storage on mount
+  const templateIdProp = props.templateId
+  const hasLoadedTemplateRef = useRef(false)
+  useEffect(() => {
+    if (!templateIdProp || !resolvedProvider || hasLoadedTemplateRef.current)
+      return
+    hasLoadedTemplateRef.current = true
+    resolvedProvider.getTemplate(templateIdProp).then((record) => {
+      if (!record) return
+      loadTemplatePayload({
+        transformations: record.transformations,
+        variables: record.variables,
+      })
+      useEditorStore.getState().hydrateTemplateMetadata({
+        templateId: record.id,
+        templateName: record.name,
+        templateIsPrivate: record.isPrivate,
+      })
     })
-  }, [initialImages, signer, focusObjects, initialize])
+  }, [templateIdProp, resolvedProvider, loadTemplatePayload])
+
+  // Fire onVariablesChange callback when dynamic variables change
+  const onVariablesChangeRef = useRef(props.onVariablesChange)
+  onVariablesChangeRef.current = props.onVariablesChange
+  useEffect(() => {
+    return useEditorStore.subscribe(
+      (state) => state.dynamicVariables,
+      (variables) => {
+        onVariablesChangeRef.current?.(variables)
+      },
+    )
+  }, [])
 
   useImperativeHandle(
     ref,
     () => ({
       loadImage: addImage,
       loadImages: addImages,
       setCurrentImage,
-      getTemplate: () => transformations,
-      loadTemplate,
+      getTemplate: () => {
+        const state = useEditorStore.getState()
+        return {
+          transformations: state.transformations,
+          variables: state.dynamicVariables,
+          urlTemplate: buildUrlTemplate(
+            state.transformations,
+            state.visibleTransformations,
+            state.dynamicVariables,
+          ),
+        }
+      },
+      loadTemplate: (
+        template:
+          | Omit<Transformation, "id">[]
+          | {
+              transformations: Omit<Transformation, "id">[]
+              variables?: DynamicVariableDefinition[]
+            },
+      ) => {
+        if (Array.isArray(template)) {
+          loadTemplate(template)
+        } else {
+          loadTemplatePayload(template)
+        }
+      },
       saveTemplate: saveTemplateImperative,
     }),
     [
       addImage,
       addImages,
       setCurrentImage,
-      transformations,
       loadTemplate,
+      loadTemplatePayload,
       saveTemplateImperative,
     ],
   )