Project Structure

Overview

A new app generated by twenty app init looks like this:

my-twenty-app/
  package.json
  yarn.lock                                 # Created by app init; used by yarn install
  src/
    application-config.ts                   # Required — your app's entry point
    default-role.ts                         # Permissions for logic functions
    constants/
      universal-identifiers.ts              # Auto-generated UUIDs and metadata
    front-components/
      main-page.tsx                         # Welcome page component
    logic-functions/
      health-check.ts                       # Reports whether the app can run
    navigation-menu-items/
      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
    page-layouts/
      main-page.page-layout.ts              # Standalone page hosting the component
    __tests__/
      application-config.test.ts            # Unit test
      global-setup.ts                       # Integration test setup (sync + uninstall)
      run-twenty.ts                         # CLI subprocess helper for tests
      schema.integration-test.ts            # Integration test against a live server
  .github/workflows/
    ci.yml                                  # Lint, typecheck, unit + integration tests
    cd.yml                                  # Deploy + install on push to main
    publish.yml                             # Publish to npm on version tags (with provenance)
  public/
    logo.svg                                # Static assets
  locales/
    en.json                                 # Source catalog; add <locale>.json files next to it
  vitest.config.ts                          # Integration test runner config
  vitest.unit.config.ts                     # Unit test runner config
  tsconfig.json, tsconfig.spec.json
  .nvmrc, .yarnrc.yml, .oxlintrc.json
  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md

Key files

File / Folder	Purpose
`src/application-config.ts`	Required. The main configuration file for your app.
`src/default-role.ts`	Default role controlling what your logic functions can access.
`src/constants/universal-identifiers.ts`	Auto-generated UUIDs and metadata (display name, description).
`src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/`	A starter welcome page: a front component rendered by a standalone page layout, reachable from the sidebar.
`src/logic-functions/health-check.ts`	A starter health check reporting `ok`. Fill it in to surface configuration problems only your app can detect.
`src/__tests__/`	A unit test plus an integration test (with its global setup) that syncs the app against a real server.
`public/`	Static assets (images, fonts) served with your app.
`locales/`	Translation catalogs. `en.json` is the source catalog `twenty app translations extract` fills in; the set of files here is what a sync publishes, so an empty folder declares no translations. `locales/compiled/` is written by `twenty app pull` for entries whose source strings are not in the tree yet, is published by a sync too, and is not meant to be edited by hand.
`AGENTS.md` / `CLAUDE.md`	Guidance for AI coding agents working on the app.
`CHANGELOG.md` / `SETUP.md`	Changelog of notable changes and setup instructions for local development.

File organization is up to you. The folders above are conventions — the CLI detects entities via AST analysis on export default defineEntity(...) calls regardless of where the file lives.

Dependencies

twenty app init puts twenty-sdk, twenty-client-sdk, and twenty-ui under devDependencies, pinned to the SDK version selected by that CLI release. Keep the generated versions for a new app and keep all three packages in sync when upgrading. The CLI can receive patch releases independently, so its version need not match these packages. The generated engines.twenty sets the minimum server version to that SDK’s major and minor release. The generated GitHub Actions workflows pin the CLI separately.

twenty-sdk provides app definitions, runtime helpers, and renderer integration. Use the separately installed twenty package for CLI commands and build/scaffolding tooling.
twenty-client-sdk is imported by your app code (CoreApiClient, MetadataApiClient, RestApiClient), but Twenty provides it at runtime — logic functions get it from a generated SDK layer, and front components resolve it from server-served modules. Your installed copy is only used for typechecking and the deploy-time build, so it never needs to ship in the deployed bundle.

Keeping either package under dependencies pulls it into the installed app’s runtime bundle, where it is dead weight. twenty app build emits a warning when either is still listed under dependencies. Add your app’s own runtime dependencies (libraries your logic functions actually import at runtime) under dependencies as usual. Keep the tree lean: dependencies are installed into a runtime layer capped at 250MB unpacked, and a sync or install fails with a dependencies size error beyond that — UI libraries and dev tooling belong in devDependencies.

Developers

Apps

API

Self-Host

Contribute

UI Library

Overview

Key files

Dependencies

​Overview

​Key files

​Dependencies

Overview

Key files

Dependencies