Implementation:Langgenius Dify UseReferenceSettings

Knowledge Sources	Dify
Domains	Plugin_System, Marketplace, Frontend
Last Updated	2026-02-12 00:00 GMT

Overview

Description

The UseReferenceSettings module in web/service/use-plugins.ts provides three React Query hooks and one imperative function that manage workspace-level plugin settings:

• useReferenceSettings -- A query hook that fetches the current ReferenceSetting from the plugin preferences endpoint.
• useMutationReferenceSettings -- A mutation hook that saves updated preferences to the server with an optional success callback.
• useRemoveAutoUpgrade -- A mutation hook that excludes a specific plugin from automatic upgrades.
• updatePermission -- An imperative async function (from web/service/plugins.ts) that updates workspace plugin permissions.

Together, these hooks and functions provide the complete settings management surface for the Dify plugin subsystem.

Usage

These hooks are consumed by the workspace administration UI components where administrators configure plugin behavior, manage auto-upgrade policies, and set installation permissions.

Code Reference

Source Location

web/service/use-plugins.ts (Lines 446--484) and web/service/plugins.ts (Lines 100--102)

Signature

// Fetch current reference settings
export const useReferenceSettings = () => {
  return useQuery({
    queryKey: [NAME_SPACE, 'referenceSettings'],
    queryFn: () => get<ReferenceSetting>('/workspaces/current/plugin/preferences/fetch'),
  })
}

// Invalidate settings cache
export const useInvalidateReferenceSettings = () => {
  const queryClient = useQueryClient()
  return () => {
    queryClient.invalidateQueries({ queryKey: [NAME_SPACE, 'referenceSettings'] })
  }
}

// Mutate reference settings
export const useMutationReferenceSettings = ({
  onSuccess,
}: {
  onSuccess?: () => void
}) => {
  return useMutation({
    mutationFn: (payload: ReferenceSetting) => {
      return post('/workspaces/current/plugin/preferences/change', { body: payload })
    },
    onSuccess,
  })
}

// Exclude a plugin from auto-upgrade
export const useRemoveAutoUpgrade = () => {
  return useMutation({
    mutationFn: (payload: { plugin_id: string }) => {
      return post('/workspaces/current/plugin/preferences/autoupgrade/exclude', { body: payload })
    },
  })
}

// Update workspace plugin permissions (imperative)
export const updatePermission = async (permissions: Permissions) => {
  return post('/workspaces/current/plugin/permission/change', { body: permissions })
}

Import

import {
  useReferenceSettings,
  useInvalidateReferenceSettings,
  useMutationReferenceSettings,
  useRemoveAutoUpgrade,
} from '@/service/use-plugins'

import { updatePermission } from '@/service/plugins'

I/O Contract

useReferenceSettings

Direction	Field	Type	Description
Input	(none)	--	No parameters; uses workspace context
Output	data	ReferenceSetting	The current plugin reference settings object

useMutationReferenceSettings

Direction	Field	Type	Description
Input	payload	ReferenceSetting	The updated settings to persist
Output	(server response)	varies	Confirmation of settings update

useRemoveAutoUpgrade

Direction	Field	Type	Description
Input	plugin_id	string	The unique identifier of the plugin to exclude from auto-upgrade
Output	(server response)	varies	Confirmation of exclusion

updatePermission

Direction	Field	Type	Description
Input	permissions	Permissions	The permission configuration object controlling installation sources and roles
Output	(server response)	varies	Confirmation of permission change

Usage Examples

Fetching and displaying current settings

import { useReferenceSettings } from '@/service/use-plugins'

function PluginSettingsPanel() {
  const { data: settings, isLoading } = useReferenceSettings()

  if (isLoading) return <Spinner />
  return <SettingsForm initialValues={settings} />
}

Updating plugin preferences

import { useMutationReferenceSettings, useInvalidateReferenceSettings } from '@/service/use-plugins'

function useUpdateSettings() {
  const invalidate = useInvalidateReferenceSettings()
  const { mutateAsync } = useMutationReferenceSettings({
    onSuccess: () => invalidate(),
  })

  return async (newSettings: ReferenceSetting) => {
    await mutateAsync(newSettings)
  }
}

Excluding a plugin from auto-upgrade

import { useRemoveAutoUpgrade } from '@/service/use-plugins'

const { mutateAsync: excludeFromAutoUpgrade } = useRemoveAutoUpgrade()
await excludeFromAutoUpgrade({ plugin_id: 'org/my-plugin' })

Updating workspace permissions

import { updatePermission } from '@/service/plugins'

await updatePermission({
  can_install_from_marketplace: true,
  can_install_from_github: true,
  can_install_from_local: false,
})

Related Pages

• Principle:Langgenius_Dify_Plugin_Settings