# Custom code best practices
Source: https://speakeasy.com/docs/sdks/customize/code/custom-code/custom-code-best-practices

import { Callout } from "@/mdx/components";



This guide covers best practices for using custom code effectively, avoiding common pitfalls, and working smoothly in team environments.

## When to use custom code

### Good use cases

Custom code works best for:

- **Adding utility methods** to models or SDK classes
- **Extending initialization** with custom authentication or middleware
- **Modifying configuration files** like package.json or pyproject.toml
- **Adding business logic** specific to the domain
- **Performance optimizations** that require deep changes
- **Integration code** for internal systems

### When to consider alternatives

Consider other approaches when:

- **OpenAPI can solve it**: Many customizations can be handled via OpenAPI extensions
- **Hooks suffice**: [SDK hooks](/docs/sdks/customize/code/sdk-hooks) might provide enough flexibility if you want to simply alter or act on the request or response. They are also useful for custom authentication setups

## Avoiding conflicts

### Structure changes to minimize conflicts

**Delegate logic to separate files**

Keep changes in generated files minimal to reduce merge conflicts.

```typescript
// ❌ Avoid: Writing complex logic directly in generated files
export class PaymentSDK {
  async createPayment(data: PaymentRequest): Promise<Payment> {
    // Generated code...

    // 50 lines of custom validation logic mixed in...
    if (!data.amount || data.amount < 0) {
      // ...complex validation...
    }

    // More generated code...
  }
}

// ✅ Better: Import and call external logic
import { validatePayment } from "./custom/validator"; // Only 1 line added

export class PaymentSDK {
  async createPayment(data: PaymentRequest): Promise<Payment> {
    validatePayment(data); // Only 1 line added
    // Generated code continues unchanged...
  }
}
```

**Add methods, do not modify existing ones**
```typescript
// ❌ Avoid: Modifying generated methods
class User {
  // This method is generated
  getName(): string {
    // Changed the implementation
    return this.firstName + " " + this.lastName;
  }
}

// ✅ Better: Add new methods
class User {
  // Generated method untouched
  getName(): string {
    return this.name;
  }

  // Custom method addition
  getFullName(): string {
    return this.firstName + " " + this.lastName;
  }
}
```

## Team workflows

### Communicating changes

**Document customizations**
Create a `CUSTOMIZATIONS.md` file in the SDK:

```markdown filename="CUSTOMIZATIONS.md"