Skip to content

The open alternative to Salesforce, designed for AI.

Align twenty-ui with SDK package versions (#25758)

Raphaël Bosi196d676bbc66
diff --git a/.github/workflows/ci-create-app-e2e-minimal.yaml b/.github/workflows/ci-create-app-e2e-minimal.yaml
index 4c7a343877c..9243e14e2e3 100644
--- a/.github/workflows/ci-create-app-e2e-minimal.yaml
+++ b/.github/workflows/ci-create-app-e2e-minimal.yaml
@@ -22,10 +22,12 @@ jobs:
packages/create-twenty-app/**
packages/twenty-sdk/**
packages/twenty-client-sdk/**
+ packages/twenty-ui/**
packages/twenty-shared/**
!packages/create-twenty-app/package.json
!packages/twenty-sdk/package.json
!packages/twenty-client-sdk/package.json
+ !packages/twenty-ui/package.json
!packages/twenty-shared/package.json
create-app-e2e-minimal:
needs: changed-files-check
@@ -50,7 +52,7 @@ jobs:
ports:
- 6379:6379
env:
- PUBLISHABLE_PACKAGES: twenty-client-sdk twenty-sdk create-twenty-app
+ PUBLISHABLE_PACKAGES: twenty-client-sdk twenty-ui twenty-sdk create-twenty-app
TWENTY_API_URL: http://localhost:3000
TWENTY_API_KEY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ1c2VySWQiOiIyMDIwMjAyMC1lNmI1LTQ2ODAtOGEzMi1iODIwOTczNzE1NmIiLCJ3b3Jrc3BhY2VJZCI6IjIwMjAyMDIwLTFjMjUtNGQwMi1iZjI1LTZhZWNjZjdlYTQxOSIsIndvcmtzcGFjZU1lbWJlcklkIjoiMjAyMDIwMjAtNDYzZi00MzViLTgyOGMtMTA3ZTAwN2EyNzExIiwidXNlcldvcmtzcGFjZUlkIjoiMjAyMDIwMjAtMWU3Yy00M2Q5LWE1ZGItNjg1YjUwNjlkODE2IiwidHlwZSI6IkFDQ0VTUyIsImF1dGhQcm92aWRlciI6InBhc3N3b3JkIiwiaWF0IjoxNzUxMjgxNzA0LCJleHAiOjIwNjY4NTc3MDR9.HMGqCsVlOAPVUBhKSGlD1X86VoHKt4LIUtET3CGIdik
steps:
@@ -117,15 +119,17 @@ jobs:
- name: Verify installed app versions
run: |
cd /tmp/e2e-test-workspace/test-app
- echo "--- Checking package.json references correct SDK version ---"
+ echo "--- Checking scaffolded app package versions ---"
node -e "
const pkg = require('./package.json');
- const sdkVersion = pkg.devDependencies['twenty-sdk'];
- if (!sdkVersion.startsWith('0.0.0-ci.')) {
- console.error('Expected twenty-sdk version to start with 0.0.0-ci., got:', sdkVersion);
- process.exit(1);
+ for (const name of ['twenty-client-sdk', 'twenty-sdk', 'twenty-ui']) {
+ const version = pkg.devDependencies[name];
+ if (version !== process.env.CI_VERSION) {
+ console.error('Expected', name, 'version', process.env.CI_VERSION, 'got:', version);
+ process.exit(1);
+ }
+ console.log(name, 'version in scaffolded app:', version);
}
- console.log('SDK version in scaffolded app:', sdkVersion);
"
- name: Verify SDK CLI is available
diff --git a/packages/create-twenty-app/src/constants/template/package.json b/packages/create-twenty-app/src/constants/template/package.json
index e56d6598ac9..86f75128754 100644
--- a/packages/create-twenty-app/src/constants/template/package.json
+++ b/packages/create-twenty-app/src/constants/template/package.json
@@ -28,7 +28,7 @@
"react-dom": "^19.0.0",
"twenty-client-sdk": "TO-BE-GENERATED",
"twenty-sdk": "TO-BE-GENERATED",
- "twenty-ui": "1.0.0-alpha.2",
+ "twenty-ui": "TO-BE-GENERATED",
"typescript": "^5.9.3",
"vite-tsconfig-paths": "^4.2.1",
"vitest": "^4.0.0"
diff --git a/packages/create-twenty-app/src/utils/__tests__/app-template.spec.ts b/packages/create-twenty-app/src/utils/__tests__/app-template.spec.ts
index a3cf95fafb1..13671eebd43 100644
--- a/packages/create-twenty-app/src/utils/__tests__/app-template.spec.ts
+++ b/packages/create-twenty-app/src/utils/__tests__/app-template.spec.ts
@@ -36,6 +36,7 @@ const TEMPLATE_PACKAGE_JSON = {
devDependencies: {
'twenty-client-sdk': '0.0.0',
'twenty-sdk': '0.0.0',
+ 'twenty-ui': '0.0.0',
},
};
@@ -136,7 +137,7 @@ describe('copyBaseApplicationProject', () => {
expect(uuidMatches![0]).not.toBe(uuidMatches![1]);
});
- it('should update package.json with app name and SDK versions', async () => {
+ it('should update package.json with app name and matching package versions', async () => {
await copyBaseApplicationProject({
appName: 'my-test-app',
appDisplayName: 'My Test App',
@@ -154,6 +155,9 @@ describe('copyBaseApplicationProject', () => {
expect(packageJson.devDependencies['twenty-client-sdk']).toBe(
createTwentyAppPackageJson.version,
);
+ expect(packageJson.devDependencies['twenty-ui']).toBe(
+ createTwentyAppPackageJson.version,
+ );
});
it('should create an empty public directory in the scaffolded project', async () => {
diff --git a/packages/create-twenty-app/src/utils/app-template.ts b/packages/create-twenty-app/src/utils/app-template.ts
index ca2801f97d4..ff09e3f4ffa 100644
--- a/packages/create-twenty-app/src/utils/app-template.ts
+++ b/packages/create-twenty-app/src/utils/app-template.ts
@@ -124,6 +124,7 @@ const updatePackageJson = async ({
createTwentyAppPackageJson.version;
packageJson.devDependencies['twenty-client-sdk'] =
createTwentyAppPackageJson.version;
+ packageJson.devDependencies['twenty-ui'] = createTwentyAppPackageJson.version;
await fs.writeFile(
join(appDirectory, 'package.json'),
diff --git a/packages/twenty-codex-plugin/references/concepts/how-apps-work.md b/packages/twenty-codex-plugin/references/concepts/how-apps-work.md
index 4646f120054..438a18091b7 100644
--- a/packages/twenty-codex-plugin/references/concepts/how-apps-work.md
+++ b/packages/twenty-codex-plugin/references/concepts/how-apps-work.md
@@ -21,7 +21,7 @@ A Twenty app depends on two SDK packages:
`twenty-sdk/front-component` provides runtime APIs available inside front components: `navigate`, `enqueueSnackbar`, `openSidePanelPage`, `useSelectedRecordIds`, `getApplicationVariable`, and others.
-Twenty UI components (`Button`, `Chip`, `Tag`, `Status`, `H2Title`, `ThemeProvider`, icons, `themeCssVariables`) live in the `twenty-ui` package. Install `[email protected]` from npm and import from its subpaths (`twenty-ui/input`, `twenty-ui/data-display`, `twenty-ui/icon`, `twenty-ui/typography`, `twenty-ui/theme-constants`, and others).
+Twenty UI components (`Button`, `Chip`, `Tag`, `Status`, `H2Title`, `ThemeProvider`, icons, `themeCssVariables`) live in the `twenty-ui` package. Install `twenty-ui` from npm at the same version as `twenty-sdk` and `twenty-client-sdk` and import from its subpaths (`twenty-ui/input`, `twenty-ui/data-display`, `twenty-ui/icon`, `twenty-ui/typography`, `twenty-ui/theme-constants`, and others).
`twenty-client-sdk/core` provides `CoreApiClient` for querying and mutating workspace records (companies, people, custom objects). `twenty-client-sdk/metadata` provides access to workspace metadata (object definitions, field definitions).
diff --git a/packages/twenty-codex-plugin/references/develop-app/front-components.md b/packages/twenty-codex-plugin/references/develop-app/front-components.md
index 10406383c37..1a84cd13e1c 100644
--- a/packages/twenty-codex-plugin/references/develop-app/front-components.md
+++ b/packages/twenty-codex-plugin/references/develop-app/front-components.md
@@ -33,7 +33,7 @@ Keep imports narrow:
- Use `twenty-sdk/front-component` for front component hooks and host APIs.
- Use `twenty-client-sdk/core` or `twenty-client-sdk/metadata` for data access.
-- Install `[email protected]` from npm and import Twenty UI components, icons, and theme tokens from its subpaths (`twenty-ui/input`, `twenty-ui/data-display`, `twenty-ui/icon`, `twenty-ui/typography`, `twenty-ui/theme-constants`, and others) before adding external UI libraries.
+- Install `twenty-ui` from npm at the same version as `twenty-sdk` and `twenty-client-sdk` and import Twenty UI components, icons, and theme tokens from its subpaths (`twenty-ui/input`, `twenty-ui/data-display`, `twenty-ui/icon`, `twenty-ui/typography`, `twenty-ui/theme-constants`, and others) before adding external UI libraries.
The front component renderer provides a Twenty `ThemeProvider` around the remote root. For isolated examples or local story-style verification, wrapping the component in `ThemeProvider` from `twenty-ui/theme-constants` is also acceptable.
diff --git a/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js b/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js
index d2cc95a8254..decda48d627 100644
--- a/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js
+++ b/packages/twenty-codex-plugin/scripts/__tests__/validate.spec.js
@@ -107,6 +107,25 @@ test('assertFrontComponentGuidance passes on current state', () => {
assert.deepStrictEqual(collectFailures(crossDocContracts.assertFrontComponentGuidance), []);
});
+test('assertFrontComponentGuidance catches independent UI version guidance', () => {
+ const frontComponentsPath = path.join(
+ PLUGIN_ROOT,
+ 'references/develop-app/front-components.md',
+ );
+
+ withFileMutation(
+ frontComponentsPath,
+ (contents) => contents.replace(
+ 'at the same version as `twenty-sdk` and `twenty-client-sdk`',
+ 'at an independent version',
+ ),
+ () => {
+ const failures = collectFailures(crossDocContracts.assertFrontComponentGuidance);
+ assert.ok(failures.some((failure) => failure.includes('same version as')));
+ },
+ );
+});
+
test('assertCliGuidanceSplit passes on current state', () => {
assert.deepStrictEqual(collectFailures(crossDocContracts.assertCliGuidanceSplit), []);
});
diff --git a/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js b/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js
index b10c3312956..b986a7ace7f 100644
--- a/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js
+++ b/packages/twenty-codex-plugin/scripts/validators/cross-doc-contracts.js
@@ -82,7 +82,7 @@ const assertFrontComponentGuidance = (fail) => {
'defineFrontComponent',
'Use `twenty-sdk/front-component`',
'Use `twenty-client-sdk/core` or `twenty-client-sdk/metadata`',
+ 'Install `twenty-ui` from npm at the same version as `twenty-sdk` and `twenty-client-sdk`',
'import Twenty UI components, icons, and theme tokens from its subpaths',
'ThemeProvider',
'showcase/twenty-ui-example.front-component.tsx',
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx
index 86b5bf16fd3..9abc10826c7 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx
@@ -59,20 +59,20 @@ my-twenty-app/
## Dependencies
-Both Twenty SDK packages belong under `devDependencies`, not `dependencies`:
+The Twenty SDK and UI packages belong under `devDependencies`:
```json filename="package.json"
{
"dependencies": {},
"devDependencies": {
- "twenty-client-sdk": "2.20.0",
- "twenty-sdk": "2.20.0",
- "twenty-ui": "1.0.0-alpha.2"
+ "twenty-client-sdk": "2.40.0",
+ "twenty-sdk": "2.40.0",
+ "twenty-ui": "2.40.0"
}
}
```
-The scaffolder pins `twenty-sdk` and `twenty-client-sdk` to its own version — keep the two in sync when upgrading.
+The scaffolder pins `twenty-sdk`, `twenty-client-sdk`, and `twenty-ui` to its own version. Keep all three in sync when upgrading.
- **`twenty-sdk`** ships the `twenty` CLI and the build/scaffolding tooling. It only runs at development and build time and is never imported by your published app's runtime.
- **`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.
diff --git a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx
index 315742c9a3d..0ae9e97697d 100644
--- a/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx
+++ b/packages/twenty-docs/developers/extend/apps/layout/front-components.mdx
@@ -690,14 +690,18 @@ Front components support multiple styling approaches. You can use:
## Using Twenty UI components
-Twenty ships its component library as the [`twenty-ui`](https://www.npmjs.com/package/twenty-ui/v/1.0.0-alpha.2) package. Front components can use it for buttons, tags, status pills, chips, avatars, icons, typography, and theme tokens that automatically match the workspace's light and dark theme.
+Twenty ships its component library as the [`twenty-ui`](https://www.npmjs.com/package/twenty-ui) package. Front components can use it for buttons, tags, status pills, chips, avatars, icons, typography, and theme tokens that automatically match the workspace's light and dark theme.
+
+<Warning>
+`twenty-ui` is still in alpha. Its version number follows the Twenty SDK release cycle. APIs and component behavior may change between releases.
+</Warning>
### Installation
-Add the package to your app, pinned to the version your Twenty instance ships:
+`twenty-ui` is published alongside the SDK packages with the same version. Add it to your app, pinned to the version of `twenty-sdk` and `twenty-client-sdk` you use:
```bash
+yarn add -D [email protected]
```
`twenty-ui` is bundled into your front component at build time, so it only needs to be a dependency of your app — there is nothing to configure at runtime.
diff --git a/packages/twenty-ui/README.md b/packages/twenty-ui/README.md
index 6ede1628fe1..7f260213ef7 100644
--- a/packages/twenty-ui/README.md
+++ b/packages/twenty-ui/README.md
@@ -6,6 +6,8 @@
Twenty's open-source React UI component library: components, icons, and design tokens built on a zero-runtime, CSS-variable styling layer.
+> **Alpha:** `twenty-ui` is still in alpha. Its version number follows the Twenty SDK release cycle. APIs and component behavior may change between releases.
+
# Installation
```bash
diff --git a/packages/twenty-ui/package.json b/packages/twenty-ui/package.json
index a58723e3b75..66574e3c777 100644
--- a/packages/twenty-ui/package.json
+++ b/packages/twenty-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "twenty-ui",
- "version": "1.0.0-alpha.2",
+ "version": "2.40.0",
"description": "Twenty's shared React UI component library.",
"license": "MIT",
"repository": {
diff --git a/packages/twenty-ui/project.json b/packages/twenty-ui/project.json
index 0a0053d3be9..09546d2b0c2 100644
--- a/packages/twenty-ui/project.json
+++ b/packages/twenty-ui/project.json
@@ -95,6 +95,7 @@
"executor": "nx:run-commands",
"options": { "command": "rimraf {projectRoot}/dist" }
},
+ "set-local-version": {},
"lint": {},
"fmt": { "options": { "files": "src" }, "configurations": { "fix": {} } },
"test": {