opensource/dify
2
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-03-11 11:40:02 +08:00
Code Issues Packages Projects Releases Wiki Activity
477bf6e075
dify/web/docs/overlay-migration.md
yyh 7f67e1a2fc
feat(web): overlay migration guardrails + Base UI primitives (#32824) 
Signed-off-by: yyh <yuanyouhuilyz@gmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
2026-03-03 16:56:13 +08:00

1.9 KiB
Raw Blame History

Overlay Migration Guide

This document tracks the migration away from legacy portal-to-follow-elem APIs.

Scope

  • Deprecated API: @/app/components/base/portal-to-follow-elem
  • Replacement primitives:
    • @/app/components/base/ui/tooltip
    • @/app/components/base/ui/dropdown-menu
    • @/app/components/base/ui/popover
    • @/app/components/base/ui/dialog
    • @/app/components/base/ui/select
  • Tracking issue: https://github.com/langgenius/dify/issues/32767

ESLint policy

  • no-restricted-imports blocks new usage of portal-to-follow-elem.
  • The rule is enabled for normal source files and test files are excluded.
  • Legacy app/components/base/* callers are temporarily allowlisted in ESLint config.
  • New files must not be added to the allowlist without migration owner approval.

Migration phases

  1. Business/UI features outside app/components/base/**
    • Migrate old calls to semantic primitives.
    • Keep eslint-suppressions.json stable or shrinking.
  2. Legacy base components in allowlist
    • Migrate allowlisted base callers gradually.
    • Remove migrated files from allowlist immediately.
  3. Cleanup
    • Remove remaining suppressions for no-restricted-imports.
    • Remove legacy portal-to-follow-elem implementation.

Suppression maintenance

  • After each migration batch, run:
pnpm eslint --prune-suppressions --pass-on-unpruned-suppressions <changed-files>
  • Never increase suppressions to bypass new code.
  • Prefer direct migration over adding suppression entries.

React Refresh policy for base UI primitives

  • We keep primitive aliases (for example DropdownMenu = Menu.Root) in the same module.
  • For app/components/base/ui/**/*.tsx, react-refresh/only-export-components is currently set to off in ESLint to avoid false positives and IDE noise during migration.
  • Do not use file-level eslint-disable comments for this policy; keep control in the scoped ESLint override.