App structure

src/
├── app/
│   ├── extensions/
│   │   └── send-invoice/
│   │       ├── extension.tsx        # default-exports defineExtension(...)
│   │       └── invoice-dialog.tsx   # helper used by this extension
│   ├── settings/
│   │   ├── schema.ts                # default-exports Settings.defineWorkspaceSchema(...)
│   │   └── page.tsx                 # default-exports Settings.defineWorkspacePage(...)
│   ├── events/
│   │   └── connection-added.event.ts
│   ├── webhooks/
│   │   └── prospect-updated.webhook.ts
│   └── blocks/                      # workflow blocks
│       └── my-step/
└── get-invoice-data.server.ts       # server functions can live anywhere in src/

​

Extensions

import {Extensions} from "attio/client"

export default Extensions.defineExtension({
  type: "record-action",
  id: "show-weather-forecast",
  label: "Show weather forecast",
  icon: "Sun",
  objects: ["people", "companies"],
  onTrigger: async ({recordId, object}) => {
    // Run code here
  },
})

​

Discovery rules

• Extension folders can be nested at any depth under src/app/extensions/, but each folder contains at most one definition file, extension.tsx or extension.ts.
• Extensions are identified by the id property in the defineExtension call, not by the folder name. Ids must be unique across the app.
• id and type must be written as string literals, and the defineExtension(...) call must be the file’s default export directly. Wrapping defineExtension in another function call, or assigning id and type to variables, is not permitted.
• Ids are lowercase kebab-case: they start with a letter, contain only lowercase letters, digits, and single hyphens, and are at most 64 characters.
• Sibling files in an extension folder are ignored by discovery; import them from extension.tsx like any other module.

​

Settings

​

Events and webhooks

​

Server functions and workflow blocks

​

Using a legacy app.ts

• Once src/app/ exists, app.ts is optional.
• If the same extension id is registered in both places, the folder-based definition wins.
• Settings are the exception: defining settings both in src/app/settings/ and via the legacy API (app.settings.ts or app.ts settings.workspace) is a build error. Migrate settings in one step.