add-custom-code.md

id	custom-code-overview
title	Understanding Custom Code in Amplication
sidebar_label	Understanding Custom Code
slug	/custom-code-overview
pagination_next	getting-started/add-custom-code

Understanding Custom Code in Amplication

Amplication allows seamless integration of custom code with generated code, empowering you to add custom business logic while continuing to use Amplication for updating your data model, permissions, roles, and more.

How It Works

Amplication uses a specific folder structure and smart merging using Smart Git Sync to manage custom and generated code:

1. All code in your Amplication project can be customized.
2. Amplication generates a folder structure that separates base files from non-base files intended for custom code.
3. Updates to your Amplication configuration regenerate base files while preserving your custom code.

Folder Structure

Each entity has a dedicated folder under the src folder:

└── src
    ├── customer
    ├── user
    ├── project
    └── task

Within each entity folder, files are split into two groups:

1. Base files: Located in the 'base' folder, these are automatically generated by Amplication with every build. While these can be modified, changes to these files may be lost in subsequent builds.

2. Non-base files: These inherit from the base files and are intended for your custom code. They reside directly in the entity folder and your custom code is preserved across builds.

src
└── Customer
    ├── Base
    │    ├── customer.controller.base.ts
    │    ├── customer.service.base.ts
    │    └── ...
    ├── customer.controller.ts
    ├── customer.service.ts
    └── ...

Smart Git Sync

Amplication uses Smart Git Sync to merge changes, preserving your custom code while updating generated parts. This feature:

1. Regenerates base files with each build.
2. Preserves non-base files containing your custom code.
3. Makes necessary updates to non-base files (e.g., removing references to deleted plugins) while maintaining your custom code.

Best Practices for Custom Code

1. Add custom code to non-base files (e.g., user.service.ts instead of user.service.base.ts).
2. Use types and interfaces generated by Amplication to ensure type safety.
3. Leverage existing services and utilities provided by Amplication.
4. Document your custom code thoroughly.
5. Create a new branch for significant custom code changes.
6. Regularly pull and merge the latest Amplication-generated code into your working branch.

Handling Conflicts

While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur:

1. Amplication will provide clear indications of the conflicting areas.
2. You may need to manually resolve these conflicts, merging your custom code with the updated generated code.
3. After resolving conflicts, thoroughly test your application to ensure everything works as expected.

Considerations

• While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance.
• Major changes to your data model or entity structure may require manual updates to your custom code.
• Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations.

Next Steps

Now that you understand how custom code works in Amplication, you're ready to start adding your own business logic and customizations. For a step-by-step guide, check out our How To Add Custom Code To Your Service guide.

Happy coding!