Skip to main content

Add custom code to your services

Although your application built with Amplication is fully functional and you can start using it as it was shipped, you probably want to add your core business logic and other functionality to your server.

The Vision​

Our vision is that you will be able to add custom code to the server while keeping the ability to work on Amplication to update your data model, change permissions, add roles, and more.

To do so, Amplication will merge changes via Git, based on pre-defined policies that will allow you to add and update services, controllers, resolvers, and more without losing the link to Amplication. You will have the freedom and power of code while saving time on repetitive tasks with Amplication.

info

This document describes the method to customize the server code only.

Customizing the client application (Admin UI) code is not supported. You can use the generated client application as a boilerplate and keep developing it, but Amplication will not be able to merge your code changes with the newly generated code.

In case you decide to customize the client application, it is recommended to first clone the entire Admin folder to a separate folder or a separate repository and work on the cloned code instead of the original folder.

How it works​

Your server application is created with a folder structure that allows easy and maintainable customization and development, with a clear separation between customizable code and non-customizable code.

The 'entity' folder​

Each entity has a dedicated folder under the 'src' folder. For example:

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

The entity folder contains all the modules and files required to work with a specific entity, i.e. GraphQL resolver, REST API controller, service, and DTOs.

The files are split into two groups:

  • Base files - the base files are the ones that are automatically generated by Amplication with every change. These files should not be altered or customized as they will be overwritten and the changes will not be preserved. All the base files exist in a separate folder named "base".

  • Customizable files - the customizable files inherit from the base files and they can be customized and will never be overwritten by Amplication. All the customizable files reside directly in the entity folder and can be freely customized and altered.

src
└── Customer
    ├── Base
    │    ├── CreateCustomerArgs.ts
    │    ├── CustomerFindManyArgs.ts
    │    ├── CustomerFindUniqueArgs.ts
    │    ├── customer.controller.base.spec.ts
    │    ├── customer.controller.base.ts
    │    ├── customer.resolver.base.ts
    │    ├── customer.service.base.ts
    │    ├── customer.ts
    │    ├── CustomerCreateInput.ts
    │    ├── CustomerUpdateInput.ts
    │    ├── CustomerWhereInput.ts
    │    ├── CustomerWhereUniqueInput.ts
    │    ├── DeleteCustomerArgs.ts
    │    └── updateCustomerArgs.ts
    ├── customer.controller.spec.ts
    ├── customer.controller.ts
    ├── customer.module.ts
    ├── customer.resolver.ts
    └── customer.service.ts

The 'base' folder​

The base folder contains all the base files that are automatically generated by Amplication with every change. These files should not be altered or customized as they will be overwritten and the changes will not be preserved.

  • entity.ts - the entity model class with all the model's properties
  • entity.service.base.ts - the base service that wraps the Prisma client with all the CRUD operations on the entity.
  • entity.controller.base.ts - the base REST API controller that provides all the CRUD operations on the entity.
  • entity.resolver.base.ts - the base GraphQL resolver that provides all the queries and mutations on the entity.
  • DTOs - Args and Input classes that are used for transferring data to and from the controller and resolver.

Examples​

Following are some examples of how to add custom code in different layers of the application.

The purpose of these examples is to get familiar with the layers' structure and the responsibility of each of the components in the server.