|
| 1 | +--- |
| 2 | +title: Custom code best practices |
| 3 | +description: "Best practices and tips for using custom code effectively in team environments." |
| 4 | +--- |
| 5 | + |
| 6 | +import { Callout } from "@/mdx/components"; |
| 7 | + |
| 8 | +# Custom code best practices |
| 9 | + |
| 10 | +This guide covers best practices for using custom code effectively, avoiding common pitfalls, and working smoothly in team environments. |
| 11 | + |
| 12 | +## When to use custom code |
| 13 | + |
| 14 | +### Good use cases |
| 15 | + |
| 16 | +Custom code works best for: |
| 17 | + |
| 18 | +- **Adding utility methods** to models or SDK classes |
| 19 | +- **Extending initialization** with custom authentication or middleware |
| 20 | +- **Modifying configuration files** like package.json or pyproject.toml |
| 21 | +- **Adding business logic** specific to the domain |
| 22 | +- **Performance optimizations** that require deep changes |
| 23 | +- **Integration code** for internal systems |
| 24 | + |
| 25 | +### When to consider alternatives |
| 26 | + |
| 27 | +Consider other approaches when: |
| 28 | + |
| 29 | +- **OpenAPI can solve it**: Many customizations can be handled via OpenAPI extensions |
| 30 | +- **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 |
| 31 | + |
| 32 | +## Avoiding conflicts |
| 33 | + |
| 34 | +### Structure changes to minimize conflicts |
| 35 | + |
| 36 | +**Delegate logic to separate files** |
| 37 | + |
| 38 | +Keep changes in generated files minimal to reduce merge conflicts. |
| 39 | + |
| 40 | +```typescript |
| 41 | +// ❌ Avoid: Writing complex logic directly in generated files |
| 42 | +export class PaymentSDK { |
| 43 | + async createPayment(data: PaymentRequest): Promise<Payment> { |
| 44 | + // Generated code... |
| 45 | + |
| 46 | + // 50 lines of custom validation logic mixed in... |
| 47 | + if (!data.amount || data.amount < 0) { |
| 48 | + // ...complex validation... |
| 49 | + } |
| 50 | + |
| 51 | + // More generated code... |
| 52 | + } |
| 53 | +} |
| 54 | + |
| 55 | +// ✅ Better: Import and call external logic |
| 56 | +import { validatePayment } from "./custom/validator"; // Only 1 line added |
| 57 | + |
| 58 | +export class PaymentSDK { |
| 59 | + async createPayment(data: PaymentRequest): Promise<Payment> { |
| 60 | + validatePayment(data); // Only 1 line added |
| 61 | + // Generated code continues unchanged... |
| 62 | + } |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +**Add methods, do not modify existing ones** |
| 67 | +```typescript |
| 68 | +// ❌ Avoid: Modifying generated methods |
| 69 | +class User { |
| 70 | + // This method is generated |
| 71 | + getName(): string { |
| 72 | + // Changed the implementation |
| 73 | + return this.firstName + " " + this.lastName; |
| 74 | + } |
| 75 | +} |
| 76 | + |
| 77 | +// ✅ Better: Add new methods |
| 78 | +class User { |
| 79 | + // Generated method untouched |
| 80 | + getName(): string { |
| 81 | + return this.name; |
| 82 | + } |
| 83 | + |
| 84 | + // Custom method addition |
| 85 | + getFullName(): string { |
| 86 | + return this.firstName + " " + this.lastName; |
| 87 | + } |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +## Team workflows |
| 92 | + |
| 93 | +### Communicating changes |
| 94 | + |
| 95 | +**Document customizations** |
| 96 | +Create a `CUSTOMIZATIONS.md` file in the SDK: |
| 97 | + |
| 98 | +```markdown filename="CUSTOMIZATIONS.md" |
| 99 | +# SDK Customizations |
| 100 | + |
| 101 | +This SDK has custom code enabled. The following customizations have been added: |
| 102 | + |
| 103 | +## Utility Methods |
| 104 | +- `Payment.toInvoiceItem()` - Converts payments to invoice format |
| 105 | +- `User.getFullName()` - Returns formatted full name |
| 106 | + |
| 107 | +## Custom Dependencies |
| 108 | +- `aws-sdk` - For S3 upload functionality |
| 109 | +- `redis` - For caching API responses |
| 110 | + |
| 111 | +## Modified Files |
| 112 | +- `src/models/payment.ts` - Added utility methods |
| 113 | +- `package.json` - Added custom dependencies and scripts |
| 114 | +``` |
| 115 | + |
| 116 | +**Use clear commit messages** |
| 117 | +```bash |
| 118 | +# When adding customizations |
| 119 | +git commit -m "feat(sdk): add payment utility methods for invoice conversion" |
| 120 | + |
| 121 | +# When resolving conflicts |
| 122 | +git commit -m "fix(sdk): resolve generation conflicts in payment model" |
| 123 | +``` |
| 124 | + |
| 125 | +## Troubleshooting tips |
| 126 | + |
| 127 | +### Common patterns to avoid |
| 128 | + |
| 129 | +**Do not remove generated headers** |
| 130 | +```typescript |
| 131 | +// ❌ Do not remove these |
| 132 | +// Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT. |
| 133 | +// @generated-id: a1b2c3d4e5f6 |
| 134 | + |
| 135 | +// ✅ Keep them for move detection to work |
| 136 | +``` |
| 137 | + |
| 138 | +**Do not copy files with IDs** |
| 139 | +```bash |
| 140 | +# ❌ Copying creates duplicate IDs |
| 141 | +cp src/models/user.ts src/models/user-v2.ts |
| 142 | + |
| 143 | +# ✅ Either move or create new file |
| 144 | +mv src/models/user.ts src/models/user-v2.ts |
| 145 | +# or create fresh without the @generated-id header |
| 146 | +``` |
| 147 | + |
| 148 | +### Recovery procedures |
| 149 | + |
| 150 | +**Reset a single file** |
| 151 | +```bash |
| 152 | +# Remove custom changes from one file |
| 153 | +git checkout HEAD -- src/models/payment.ts |
| 154 | + |
| 155 | +# Re-run generation using the same pristine snapshot (no new snapshot is created) |
| 156 | +speakeasy run --skip-versioning |
| 157 | +``` |
| 158 | + |
| 159 | +**Reset everything** |
| 160 | +```bash |
| 161 | +# Disable custom code |
| 162 | +# Edit .speakeasy/gen.yaml: enabled: false |
| 163 | + |
| 164 | +# Remove all generated files |
| 165 | +find . -name "*.gen.*" -delete # Adjust pattern for the SDK |
| 166 | + |
| 167 | +# Regenerate fresh |
| 168 | +speakeasy run |
| 169 | +``` |
| 170 | + |
| 171 | +**Fix "duplicate ID" warnings** |
| 172 | +1. Find files with duplicate IDs |
| 173 | +2. Remove `@generated-id` line from copied files |
| 174 | +3. Let next generation assign new IDs |
| 175 | + |
| 176 | +## Summary checklist |
| 177 | + |
| 178 | +<Callout title="Quick reference" type="info"> |
| 179 | +✓ Enable custom code before reorganizing files. Move detection is file-specific, not folder-specific |
| 180 | +✓ Document customizations for team members |
| 181 | +✓ Do not remove @generated-id headers |
| 182 | +✓ Commit custom edits independently of generator changes for clarity |
| 183 | +</Callout> |
0 commit comments