From ced7c80a3432426638696b3e3ef2e094f7226275 Mon Sep 17 00:00:00 2001
From: enisn <info@enisnecipoglu.com>
Date: Sun, 22 Mar 2026 00:33:18 +0300
Subject: [PATCH] docs: add ABP Suite guidance for Mapperly migration

---
 .../migration-guides/AutoMapper-To-Mapperly.md       | 12 ++++++++++++
 docs/en/suite/generating-crud-page.md                | 11 +++++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md b/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md
index 7356a6930b..c293dd9a37 100644
--- a/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md
+++ b/docs/en/release-info/migration-guides/AutoMapper-To-Mapperly.md
@@ -174,6 +174,16 @@ public partial class IdentityUserToIdentityUserDtoMapper : MapperBase<IdentityUs
 }
 ```
 
+## ABP Suite Compatibility Note
+
+If you still use [ABP Suite](../../suite/index.md) to generate CRUD pages after migrating to Mapperly, keep the main Suite-managed mapper files reserved for Suite updates.
+
+- Keep the conventional files such as `*ApplicationMappers.cs`, `*BlazorMappers.cs` and `*WebMappers.cs` as the files that ABP Suite updates.
+- Move manual or AI-generated Mapperly classes into separate files.
+- Avoid creating extra manual files with the same conventional suffixes that ABP Suite scans, because Suite may pick the wrong file when generating or updating mappings.
+
+For example, names like `IdentityUserMapperlyMappings.cs`, `CustomObjectMappings.cs` or `ManualOrderMappings.cs` are safer for your hand-written mappers.
+
 ## AI Prompt for Migrating AutoMapper to Mapperly
 
 If you have AI tools like Cursor, you can use the following prompt to migrate your AutoMapper mappings to Mapperly automatically:
@@ -187,6 +197,8 @@ Please help me migrate AutoMapper Profile classes to Mapperly. I have AutoMapper
 
 1. **Convert AutoMapper Profile to Mapperly Mappers**: Transform each `CreateMap` into a separate Mapperly mapper class
 2. **Rename the file**: Change from `XXXAutoMapperProfile.cs` to `XXXMappers.cs`
+
+   > If you still use **ABP Suite**, keep Suite-managed mapper files separate from your manual/AI-generated mapper files. See the **ABP Suite Compatibility Note** section above.
 3. **Use proper Mapperly attributes**: 
    - `[Mapper(RequiredMappingStrategy = RequiredMappingStrategy.Target)]` for each mapper class
    - `[MapExtraProperties]` for classes that need extra properties mapping
diff --git a/docs/en/suite/generating-crud-page.md b/docs/en/suite/generating-crud-page.md
index cc9df3ee32..43e88e4b5a 100644
--- a/docs/en/suite/generating-crud-page.md
+++ b/docs/en/suite/generating-crud-page.md
@@ -300,6 +300,17 @@ There are some adjustments you may need to make before generating CRUD pages for
   - Project key is in kebab case. E.g. `book-store`.
   - Project is defined as `defaultProject`.
 
+### What to Check If CRUD Generation Fails After Migrating to Mapperly
+
+If you migrated an existing solution from AutoMapper to Mapperly and ABP Suite starts appending mappings to the wrong file or generating duplicate/inconsistent mapper classes, check your mapper file layout.
+
+- Keep the main Suite-managed files, such as `*ApplicationMappers.cs`, `*BlazorMappers.cs` and `*WebMappers.cs`, reserved for ABP Suite updates.
+- Move manual or AI-generated Mapperly classes to separate files.
+- Avoid naming those manual files with the same conventional suffixes that ABP Suite scans, otherwise Suite may choose the wrong file while generating CRUD pages.
+- If you temporarily excluded a Suite-managed mapper file from the build, add it back after reorganizing your mappings.
+
+After reorganizing the files, clean the solution, rebuild it, and try generating the entity again.
+
 ## Generating CRUD Pages via Command Line
 
 You can generate CRUD pages via [ABP CLI](../cli), without opening ABP Suite's user interface.