Quickstart

Twenty SDK Local Setup Example: Minimal App Against a Local Twenty Instance

A minimal twenty-sdk app (application, role, object definitions) wired up with vitest to run against a locally hosted Twenty CRM instance via TWENTY_API_URL and TWENTY_API_KEY.

This is a minimal twenty-sdk app we use to sanity-check a local Twenty development setup: an application definition, a default role, and one custom object (deal), plus a Vitest suite that fails loudly if your environment isn't wired up correctly. Clone it, point it at your local Twenty instance, and run the tests.

What's in this project#

File	Purpose
`src/application-config.ts`	`defineApplication()` call declaring the app, its `universalIdentifier`, and its default role
`src/roles/default-role.ts`	`defineRole()` call declaring the role referenced above
`src/objects/deal.object.ts`	`defineObject()` call declaring a `deal` object with `TEXT`, `CURRENCY`, and `DATE_TIME` fields
`src/utils/isDefined.ts`	Small type-guard used across the config and test files
`src/__tests__/setup-test.ts`	Vitest `setupFiles` hook that fails fast with a clear message if `TWENTY_API_URL` or `TWENTY_API_KEY` is missing
`src/__tests__/hello.integration-test.ts`	Verifies the app and role definitions load and that the environment points at a local instance

Prerequisites#

Node.js 18 or later and npm.
A running local Twenty instance. Follow the local setup guide to run Twenty from source, or the Docker Compose guide to self-host it. By default the API listens on http://localhost:2020 and the front end on http://localhost:3001.
A workspace inside that instance, and an API key generated from that workspace's Settings > Developers > API keys screen.

Setup#

Install dependencies:
```
npm install
```
Copy the environment template and fill it in:
```
cp .env.example .env
```
Set the two variables in .env:
```
TWENTY_API_URL=http://localhost:2020
TWENTY_API_KEY=<the JWT you generated in your workspace>
```
TWENTY_API_URL must match the origin your local Twenty API actually answers on. TWENTY_API_KEY is the raw JWT string from the API key screen, no quotes needed inside the value itself.
Load the environment variables into your shell (or let your editor/tooling read .env automatically), then run the tests:
```
npm test
```
Expected result: Vitest reports 3 passing tests. If TWENTY_API_URL or TWENTY_API_KEY is missing or empty, setupFiles throws before any test runs, with a message telling you which variable to set.

Extending this into a real app#

Once the definitions here load cleanly against your local instance, scaffold a full app and ship it with the Twenty CLI:

npx create-twenty-app my-app

This generates the same shape of project you see here (defineApplication, defineRole, defineObject, from twenty-sdk/define). When you're ready to install it into your workspace:

npx twenty app:publish --private

See the app development guide for adding views, agents, and logic functions on top of what's here.

Troubleshooting#

Tests fail immediately with "Missing required environment variable": your .env isn't loaded into the process running npm test, or the variable is set to an empty string. Confirm TWENTY_API_URL and TWENTY_API_KEY are exported in the shell you run npm test from.
npx twenty app:publish can't reach your workspace: confirm your local Twenty instance from the local setup guide is still running and that TWENTY_API_URL in .env matches its actual API origin.