애플리케이션 구성

• 식별 정보 — 범용 식별자, 표시 이름, 설명.
• 권한 — 로직 함수와 프런트 컴포넌트가 어떤 역할로 실행되는지.
• 변수 (선택 사항) — 코드에 환경 변수로 노출되는 키–값 쌍.
• 설치 전/설치 후/제거 훅 (선택 사항) — Logic Functions를 참조하세요.

import { defineApplication } from 'twenty-sdk/define';

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'My Twenty App',
  description: 'My first Twenty app',
  applicationVariables: {
    DEFAULT_RECIPIENT_NAME: {
      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
      description: 'Default recipient name for postcards',
      value: 'Jane Doe',
      isSecret: false,
    },
  },
});

• universalIdentifier 필드는 여러분이 소유하는 변하지 않는 고유 ID입니다. 한 번만 생성하고 이후 동기화 동안에도 변하지 않도록 유지하세요.
• applicationVariables는 함수와 프런트 컴포넌트의 환경 변수가 됩니다. 로직 함수(서버 사이드)에서는 process.env.VARIABLE_NAME으로 사용할 수 있습니다. 프런트 컴포넌트에서는 twenty-sdk/front-component의 getApplicationVariable('VARIABLE_NAME')을 사용하세요. isSecret: true로 표시된 변수는 로직 함수에만 주입됩니다. 프런트 컴포넌트는 비밀이 아닌 변수만 받습니다.
• 기본 역할은 defineApplicationRole()로 표시된 역할 파일에서 자동으로 감지되므로, defineApplication()에서 이를 참조할 필요가 없습니다.
• 설치 전, 설치 후, 제거 함수는 매니페스트 빌드 중 자동으로 감지됩니다 — defineApplication()에서 별도로 참조할 필요가 없습니다.
• 하위 호환성을 위해 defaultRoleUniversalIdentifier를 명시적으로 전달하는 방식도 계속 지원되지만, 이제는 defineApplicationRole() 사용을 권장하며 이전 방식은 더 이상 권장되지 않습니다.
• serverVariables는 인스턴스 범위의 구성 및 비밀(예: API 키)입니다. applicationVariables와 달리, 매니페스트에는 값을 선언하지 않으며, 워크스페이스 운영자가 앱 설정에서 값을 채워 넣으면 설정된 이후에만 로직 함수에 주입됩니다.
• 앱의 Settings 탭에서 기본 변수 구성 섹션 대신 사용자 지정 구성 UI를 렌더링하려면, 별도의 파일에서 defineSettingsFrontComponent()를 사용하여 프론트 컴포넌트를 선언하세요. 앱당 하나만 허용됩니다. 시스템에서 관리하는 섹션(auto-upgrade, App URL, connections)은 항상 표시된 상태로 유지됩니다.

​

변수 유형

import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    MAX_POSTCARDS: {
      universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
      description: 'Maximum postcards per batch',
      type: FieldType.NUMBER,
      value: 10,
    },
    DEFAULT_REGION: {
      universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
      description: 'Default shipping region',
      type: FieldType.SELECT,
      options: [
        { label: 'Europe', value: 'eu' },
        { label: 'United States', value: 'us' },
      ],
      value: 'eu',
    },
  },
});

const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }

​

기본 함수 역할

• TWENTY_APP_ACCESS_TOKEN로 주입되는 런타임 토큰은 이 역할에서 파생됩니다.
• 타입드 API 클라이언트는 해당 역할에 부여된 권한으로 제한됩니다.
• 최소 권한 원칙을 따르세요: 함수에 필요한 권한만 선언하세요.

​

마켓플레이스 메타데이터