Skip to content

The open alternative to Salesforce, designed for AI.

Improve Standard and Custom app marketplace pages (#28387)

martmull3ba92411d72b
diff --git a/packages/twenty-front/src/modules/applications/utils/getCustomApplicationDescription.ts b/packages/twenty-front/src/modules/applications/utils/getCustomApplicationDescription.ts
index fc04656e530..5cd8aac0ea0 100644
--- a/packages/twenty-front/src/modules/applications/utils/getCustomApplicationDescription.ts
+++ b/packages/twenty-front/src/modules/applications/utils/getCustomApplicationDescription.ts
@@ -1,26 +1,4 @@
import { t } from '@lingui/core/macro';
-export const getCustomApplicationDescription =
- (): string => t`Host your workspace's customizations and overrides.
-
-#### What it includes
-Every extension you create on top of the standard app is grouped under Custom. It keeps your schema changes, interface changes, and workspace-specific logic in one place.
-
-- Custom objects and fields for your own data model
-- Views, navigation items, and record layouts that shape how your team works
-- Logic functions, front components, and agents that automate or extend the workspace
-
-#### Why it exists
-Use this app for workspace-specific customization that should stay local to this workspace.
-
-If you are shaping one workspace for one business, keep it here. If you are building a reusable business app with its own data model, UI, and automation that should be versioned, shared, or installed across workspaces, create a dedicated app instead.
-
-#### Build your own app
-
-Scaffold a new app in one command:
-
-\`\`\`bash
-npx create-twenty-app@latest my-twenty-app
-\`\`\`
-
-See the [Getting Started guide](https://twenty.com/developers/extend/apps/getting-started) for the full walkthrough, and [Building Apps](https://twenty.com/developers/extend/apps/building) for the \`defineApplication\` / \`defineEntity\` APIs.`;
+export const getCustomApplicationDescription = (): string =>
+ t`Host your workspace's customizations and overrides.`;
diff --git a/packages/twenty-front/src/modules/applications/utils/getCustomApplicationReadme.ts b/packages/twenty-front/src/modules/applications/utils/getCustomApplicationReadme.ts
new file mode 100644
index 00000000000..2b35e1a6485
--- /dev/null
+++ b/packages/twenty-front/src/modules/applications/utils/getCustomApplicationReadme.ts
@@ -0,0 +1,20 @@
+import { t } from '@lingui/core/macro';
+
+export const getCustomApplicationReadme =
+ (): string => t`Everything you build directly in this workspace lives here. Every object, field, view or automation you add on top of the Standard app is grouped under Custom, so your schema changes, interface changes and workspace-specific logic stay in one place.
+
+## ✨ What you get
+
+- **Custom objects and fields**: your own data model, next to the standard objects
+- **Views, navigation items and record layouts**: the screens that shape how your team works
+- **Logic functions, front components and agents**: automation and extensions specific to this workspace
+
+## πŸ“Œ Good to know
+
+- Created with your workspace and unique to it
+- Cannot be uninstalled: it holds your workspace's customizations
+- Customizations you make from the Twenty interface are saved here automatically
+
+## πŸ’³ Billing
+
+**Free**: no credits, no metering.`;
diff --git a/packages/twenty-front/src/modules/applications/utils/getStandardApplicationDescription.ts b/packages/twenty-front/src/modules/applications/utils/getStandardApplicationDescription.ts
index 1c540a0ae43..8837bed4fe8 100644
--- a/packages/twenty-front/src/modules/applications/utils/getStandardApplicationDescription.ts
+++ b/packages/twenty-front/src/modules/applications/utils/getStandardApplicationDescription.ts
@@ -1,33 +1,4 @@
import { t } from '@lingui/core/macro';
-export const getStandardApplicationDescription =
- (): string => t`The base data model every Twenty workspace runs on.
-
-#### What "foundation" means
-
-Every Twenty workspace starts with this set of objects. They define the shape of your CRM, including relationships, activity, and reporting. Everything else, including marketplace apps, AI agents, and custom objects, plugs into them.
-
-#### Included objects
-- **People & Companies**: contact and account records
-- **Opportunities**: your sales pipeline
-- **Notes & Tasks**: activity and follow-ups
-- **Workflows & Dashboards**: automation and reporting
-
-Remove this app and the rest of Twenty has nothing to hang off.
-
-#### Build your own app
-
-Extend Twenty with your own objects, fields, logic functions, or AI skills. Scaffold a new app in one command:
-
-\`\`\`bash
-npx create-twenty-app@latest my-twenty-app
-\`\`\`
-
-Then inside the folder:
-
-\`\`\`bash
-cd my-twenty-app
-yarn twenty dev
-\`\`\`
-
-See the [Getting Started guide](https://twenty.com/developers/extend/apps/getting-started) for the full walkthrough, and [Building Apps](https://twenty.com/developers/extend/apps/building) for the \`defineApplication\` / \`defineEntity\` APIs.`;
+export const getStandardApplicationDescription = (): string =>
+ t`The base data model every Twenty workspace runs on.`;
diff --git a/packages/twenty-front/src/modules/applications/utils/getStandardApplicationReadme.ts b/packages/twenty-front/src/modules/applications/utils/getStandardApplicationReadme.ts
new file mode 100644
index 00000000000..97ec2213128
--- /dev/null
+++ b/packages/twenty-front/src/modules/applications/utils/getStandardApplicationReadme.ts
@@ -0,0 +1,22 @@
+import { t } from '@lingui/core/macro';
+
+export const getStandardApplicationReadme =
+ (): string => t`Every Twenty workspace starts with this app. It defines the shape of your CRM: the core objects, how they relate to each other, and the views and record pages your team works in. Marketplace apps, AI agents and your own customizations all build on top of it.
+
+## ✨ What you get
+
+- **People & Companies**: your contacts and the accounts they belong to
+- **Opportunities**: your sales pipeline, stage by stage
+- **Notes & Tasks**: activity and follow-ups attached to any record
+- **Emails & Calendar events**: synced from your connected accounts and linked to the right records
+- **Workflows & Dashboards**: automation and reporting on top of your data
+
+## πŸ“Œ Good to know
+
+- Installed on every workspace and maintained by Twenty
+- Cannot be uninstalled: the rest of the workspace is built on it
+- Your own objects, fields and layouts live in the **Custom** app
+
+## πŸ’³ Billing
+
+**Free**: no credits, no metering.`;
diff --git a/packages/twenty-front/src/pages/settings/applications/SettingsAvailableApplicationDetails.tsx b/packages/twenty-front/src/pages/settings/applications/SettingsAvailableApplicationDetails.tsx
index 8b9f8c0a672..3ff9e7629d3 100644
--- a/packages/twenty-front/src/pages/settings/applications/SettingsAvailableApplicationDetails.tsx
+++ b/packages/twenty-front/src/pages/settings/applications/SettingsAvailableApplicationDetails.tsx
@@ -1,5 +1,12 @@
import { AppChip } from '@/applications/components/AppChip';
import { CurrentApplicationContext } from '@/applications/contexts/CurrentApplicationContext';
+import { getCustomApplicationDescription } from '@/applications/utils/getCustomApplicationDescription';
+import { getCustomApplicationReadme } from '@/applications/utils/getCustomApplicationReadme';
+import { getStandardApplicationDescription } from '@/applications/utils/getStandardApplicationDescription';
+import { getStandardApplicationReadme } from '@/applications/utils/getStandardApplicationReadme';
+import { isTwentyStandardApplication } from '@/applications/utils/isTwentyStandardApplication';
+import { isWorkspaceCustomApplication } from '@/applications/utils/isWorkspaceCustomApplication';
+import { currentWorkspaceState } from '@/auth/states/currentWorkspaceState';
import { SettingsApplicationInstallPermissionValidationModal } from '@/marketplace/components/SettingsApplicationInstallPermissionValidationModal';
import { useCopyMarketplaceAppLink } from '@/marketplace/hooks/useCopyMarketplaceAppLink';
import { useInstallMarketplaceAppWithPermissionValidation } from '@/marketplace/hooks/useInstallMarketplaceAppWithPermissionValidation';
@@ -9,6 +16,7 @@ import { SettingsPageContainer } from '@/settings/components/SettingsPageContain
import { SettingsSectionSkeletonLoader } from '@/settings/components/SettingsSectionSkeletonLoader';
import { SettingsPageLayout } from '@/settings/components/layout/SettingsPageLayout';
import { useHasPermissionFlag } from '@/settings/roles/hooks/useHasPermissionFlag';
+import { useAtomStateValue } from '@/ui/utilities/state/jotai/hooks/useAtomStateValue';
import { useQuery } from '@apollo/client/react';
import { t } from '@lingui/core/macro';
import { useCallback } from 'react';
@@ -27,6 +35,8 @@ import { useNavigateSettings } from '~/hooks/useNavigateSettings';
import { SettingsApplicationDetailAbout } from '~/pages/settings/applications/components/SettingsApplicationDetailAbout';
import { SettingsApplicationLoadErrorBanner } from '@/settings/applications/components/SettingsApplicationLoadErrorBanner';
import { SettingsApplicationNotFound } from '~/pages/settings/applications/components/SettingsApplicationNotFound';
+import { CUSTOM_APPLICATION_ILLUSTRATIONS } from '~/pages/settings/applications/constants/CustomApplicationIllustrations';
+import { STANDARD_APPLICATION_ILLUSTRATIONS } from '~/pages/settings/applications/constants/StandardApplicationIllustrations';
import { getApplicationLookupStatus } from '~/pages/settings/applications/utils/getApplicationLookupStatus';
import { isUuidFormat } from '~/pages/settings/applications/utils/isUuidFormat';
@@ -102,8 +112,41 @@ export const SettingsAvailableApplicationDetails = () => {
? `https://www.npmjs.com/package/${detail.sourcePackage}`
: undefined;
+ const currentWorkspace = useAtomStateValue(currentWorkspaceState);
+
+ // Read from the workspace state so built-in apps are known before the application query resolves
+ const installedApplication = currentWorkspace?.installedApplications.find(
+ (workspaceApplication) =>
+ workspaceApplication.universalIdentifier === availableApplicationId,
+ );
+
+ const getBuiltInApplicationContent = () => {
+ if (isTwentyStandardApplication(installedApplication)) {
+ return {
+ description: getStandardApplicationDescription(),
+ readme: getStandardApplicationReadme(),
+ illustrations: STANDARD_APPLICATION_ILLUSTRATIONS,
+ };
+ }
+
+ if (isWorkspaceCustomApplication(installedApplication, currentWorkspace)) {
+ return {
+ description: getCustomApplicationDescription(),
+ readme: getCustomApplicationReadme(),
+ illustrations: CUSTOM_APPLICATION_ILLUSTRATIONS,
+ };
+ }
+
+ return undefined;
+ };
+
+ const builtInApplicationContent = getBuiltInApplicationContent();
+
const isUnlisted = isDefined(detail) && !detail.isListed;
- const isNotVetted = isDefined(detail) && !detail.isVetted;
+ const isNotVetted =
+ isDefined(detail) &&
+ !detail.isVetted &&
+ !isDefined(builtInApplicationContent);
const defaultRole = getMarketplaceAppDefaultRoleManifest(detail);
@@ -141,11 +184,21 @@ export const SettingsAvailableApplicationDetails = () => {
applicationId={application?.id}
logoUrl={detail.logoUrl}
displayName={displayName}
- description={detail.description ?? undefined}
- aboutDescription={detail.aboutDescription ?? undefined}
+ description={
+ builtInApplicationContent?.description ??
+ detail.description ??
+ undefined
+ }
+ aboutDescription={
+ builtInApplicationContent?.readme ??
+ detail.aboutDescription ??
+ undefined
+ }
pricingDescription={detail.pricingDescription ?? undefined}
billsCredits={detail.billsCredits}
- screenshots={detail.galleryImages}
+ screenshots={
+ builtInApplicationContent?.illustrations ?? detail.galleryImages
+ }
author={detail.author ?? undefined}
version={currentVersion ?? latestAvailableVersion ?? undefined}
installCount={detail.installCount}
diff --git a/packages/twenty-front/src/pages/settings/applications/__tests__/SettingsAvailableApplicationDetails.test.tsx b/packages/twenty-front/src/pages/settings/applications/__tests__/SettingsAvailableApplicationDetails.test.tsx
new file mode 100644
index 00000000000..22964ef8343
--- /dev/null
+++ b/packages/twenty-front/src/pages/settings/applications/__tests__/SettingsAvailableApplicationDetails.test.tsx
@@ -0,0 +1,204 @@
+import { useQuery } from '@apollo/client/react';
+import { i18n } from '@lingui/core';
+import { I18nProvider } from '@lingui/react';
+import { render, screen } from '@testing-library/react';
+import { type ReactNode } from 'react';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+import { TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER } from 'twenty-shared/application';
+
+import {
+ ApplicationRegistrationSourceType,
+ FindOneApplicationByUniversalIdentifierDocument,
+} from '~/generated-metadata/graphql';
+import { SettingsAvailableApplicationDetails } from '~/pages/settings/applications/SettingsAvailableApplicationDetails';
+
+const CUSTOM_APPLICATION_ID = '5d3c1a9e-7b2f-4c8d-9e1a-3f6b8c2d4e70';
+const THIRD_PARTY_APPLICATION_ID = '8f2e6d4c-1b3a-4c5d-8e7f-9a0b1c2d3e4f';
+
+jest.mock('@apollo/client/react', () => ({
+ ...jest.requireActual('@apollo/client/react'),
+ useQuery: jest.fn(),
+}));
+
+jest.mock('@/ui/utilities/state/jotai/hooks/useAtomStateValue', () => ({
+ useAtomStateValue: jest.fn(() => ({
+ workspaceCustomApplication: { id: CUSTOM_APPLICATION_ID },
+ installedApplications: [
+ {
+ id: 'standard-application-id',
+ universalIdentifier: TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER,
+ },
+ {
+ id: CUSTOM_APPLICATION_ID,
+ universalIdentifier: CUSTOM_APPLICATION_ID,
+ },
+ ],
+ })),
+}));
+
+jest.mock('@/settings/roles/hooks/useHasPermissionFlag', () => ({
+ useHasPermissionFlag: jest.fn(() => true),
+}));
+
+jest.mock(
+ '@/marketplace/hooks/useInstallMarketplaceAppWithPermissionValidation',
+ () => ({
+ useInstallMarketplaceAppWithPermissionValidation: jest.fn(() => ({
+ requestInstall: jest.fn(),
+ install: jest.fn(),
+ isInstalling: false,
+ installProgress: 0,
+ modalInstanceId: 'install-modal',
+ })),
+ }),
+);
+
+jest.mock('@/marketplace/hooks/useCopyMarketplaceAppLink', () => ({
+ useCopyMarketplaceAppLink: jest.fn(() => ({
+ copyMarketplaceAppLink: jest.fn(),
+ })),
+}));
+
+jest.mock(
+ '@/marketplace/components/SettingsApplicationInstallPermissionValidationModal',
+ () => ({
+ SettingsApplicationInstallPermissionValidationModal: () => null,
+ }),
+);
+
+jest.mock('~/hooks/useNavigateSettings', () => ({
+ useNavigateSettings: jest.fn(() => jest.fn()),
+}));
+
+jest.mock('@/ai/components/LazyMarkdownRenderer', () => ({
+ LazyMarkdownRenderer: ({ text }: { text: string }) => (
+ <div data-testid="markdown-renderer">{text}</div>
+ ),
+}));
+
+jest.mock('@/applications/components/AppChip', () => ({
+ AppChip: () => null,
+}));
+
+jest.mock('@/settings/components/SettingsPageContainer', () => ({
+ SettingsPageContainer: ({ children }: { children: ReactNode }) => (
+ <>{children}</>
+ ),
+}));
+
+jest.mock('@/settings/components/layout/SettingsPageLayout', () => ({
+ SettingsPageLayout: ({ children }: { children: ReactNode }) => (
+ <>{children}</>
+ ),
+}));
+
+const mockedUseQuery = useQuery as jest.MockedFunction<typeof useQuery>;
+
+// The installed application query never resolves, so the page has to rely on the workspace state
+const mockQueries = ({
+ universalIdentifier,
+ name,
+}: {
+ universalIdentifier: string;
+ name: string;
+}) => {
+ mockedUseQuery.mockImplementation(((document: unknown) => {
+ if (document === FindOneApplicationByUniversalIdentifierDocument) {
+ return { data: undefined, loading: true };
+ }
+
+ return {
+ data: {
+ findMarketplaceAppDetail: {
+ id: 'registration-id',
+ universalIdentifier,
+ name,
+ sourceType: ApplicationRegistrationSourceType.LOCAL,
+ isListed: false,
+ isVetted: false,
+ description: null,
+ aboutDescription: null,
+ galleryImages: [],
+ installCount: 1,
+ billsCredits: false,
+ },
+ },
+ error: undefined,
+ loading: false,
+ refetch: jest.fn(),
+ };
+ }) as never);
+};
+
+const renderPage = (availableApplicationId: string) =>
+ render(
+ <I18nProvider i18n={i18n}>
+ <MemoryRouter
+ initialEntries={[`/settings/applications/${availableApplicationId}`]}
+ >
+ <Routes>
+ <Route
+ path="/settings/applications/:availableApplicationId"
+ element={<SettingsAvailableApplicationDetails />}
+ />
+ </Routes>
+ </MemoryRouter>
+ </I18nProvider>,
+ );
+
+const NOT_VETTED_WARNING =
+ 'This application is not vetted by Twenty. Use at your own risk.';
+
+describe('SettingsAvailableApplicationDetails', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('shows the readme of the standard application without the not vetted warning', () => {
+ mockQueries({
+ universalIdentifier: TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER,
+ name: 'Standard',
+ });
+
+ renderPage(TWENTY_STANDARD_APPLICATION_UNIVERSAL_IDENTIFIER);
+
+ expect(screen.queryByText(NOT_VETTED_WARNING)).not.toBeInTheDocument();
+ expect(
+ screen.getByText('The base data model every Twenty workspace runs on.'),
+ ).toBeInTheDocument();
+ expect(screen.getByTestId('markdown-renderer')).toHaveTextContent(
+ 'Every Twenty workspace starts with this app.',
+ );
+ });
+
+ it('shows the readme of the workspace custom application without the not vetted warning', () => {
+ mockQueries({
+ universalIdentifier: CUSTOM_APPLICATION_ID,
+ name: 'Custom',
+ });
+
+ renderPage(CUSTOM_APPLICATION_ID);
+
+ expect(screen.queryByText(NOT_VETTED_WARNING)).not.toBeInTheDocument();
+ expect(
+ screen.getByText("Host your workspace's customizations and overrides."),
+ ).toBeInTheDocument();
+ expect(screen.getByTestId('markdown-renderer')).toHaveTextContent(
+ 'Everything you build directly in this workspace lives here.',
+ );
+ });
+
+ it('warns that a third-party application is not vetted', () => {
+ mockQueries({
+ universalIdentifier: THIRD_PARTY_APPLICATION_ID,
+ name: 'Third party',
+ });
+
+ renderPage(THIRD_PARTY_APPLICATION_ID);
+
+ expect(screen.getByText(NOT_VETTED_WARNING)).toBeInTheDocument();
+ expect(
+ screen.getByText('No description available for this application'),
+ ).toBeInTheDocument();
+ });
+});