activepieces/AGENTS.md

Activepieces — Coding Rules

File Structure

• Exported types and constants must be placed at the end of the file, after all logic (functions, hooks, components, classes, etc.). This keeps the logic front and centre when reading a file, and groups the public contract at a predictable location.

  // ✅ Correct
  function doSomething() { ... }
  
  export const MY_CONST = 'value';
  export type MyType = { ... };
  // ✅ Correct
  const businessService = () => { ... }
  
  export const MY_CONST = 'value';
  export type MyType = { ... };
  
  // ❌ Wrong — types/consts mixed in before logic
  export const MY_CONST = 'value';
  export type MyType = { ... };
  function doSomething() { ... }
  

Coding Conventions

• No any type — Use proper type definitions or unknown with type guards
• Zod error messages must be i18n keys — Every .min(), .refine(), .superRefine(), etc. that surfaces a user-facing message must pass a string that exists as a key in packages/web/public/locales/en/translation.json. For common messages (e.g. required fields) use the formErrors constant from @activepieces/shared. Add a new translation key if none fits; never use raw English sentences that are not in the translation file.
• @activepieces/shared version bump — Any change to packages/shared must be accompanied by a version bump in packages/shared/package.json: bump the patch version for non-breaking additions or fixes, bump the minor version for new exports or behaviour changes.
• No type casting — Do not use as SomeType to force types. If you encounter an unnecessary cast, remove it.
• No deprecated APIs — Before using any library method or export, check its JSDoc. If it carries a @deprecated tag, use the recommended replacement instead. Examples: prefer z.enum over z.nativeEnum.
• Go-style error handling — Use tryCatch / tryCatchSync from @activepieces/shared
• Helper functions — Define non-exported helpers outside of const declarations
• File order: Imports → Exported functions/constants → Helper functions → Types
• Comments — Only comment to explain why something is done, never what the code is doing. Code should be self-explanatory; comments that restate the code add noise and rot.

Git Push

• Always prefix git push with CLAUDE_PUSH=yes to auto-approve the pre-push lint/test gate, e.g. CLAUDE_PUSH=yes git push -u origin HEAD.

Pull Requests

• When creating a PR with gh pr create, always apply exactly one of these labels based on the nature of the change:
  • feature — new functionality
  • bug — bug fix
  • skip-changelog — changes that should not appear in the changelog (docs, CI tweaks, internal refactors, etc.)
• If the PR includes any contributions to pieces (integrations under packages/pieces), also add the pieces label (in addition to the primary label above).

Database Migrations

• Before creating or modifying a database migration, always read the Database Migrations Playbook first. Follow its instructions for generating and structuring migrations.

Verification

• Always run npm run lint-dev as part of any verification step before considering a task complete.

Useful Links

• Database Migrations Playbook
• TypeORM Migrations Docs