Skip to content

The open alternative to Salesforce, designed for AI.

Document that app development is only supported on Unix systems (#28817)

Paul Rastoin729f6236126e
diff --git a/packages/twenty-cli/README.md b/packages/twenty-cli/README.md
index 66f88a83d9c..7ff41223a36 100644
--- a/packages/twenty-cli/README.md
+++ b/packages/twenty-cli/README.md
@@ -5,7 +5,8 @@ inspect metadata and records, send API requests, and develop applications.
## Install
-The CLI needs Node.js 24.5 or later.
+The CLI needs Node.js 24.5 or later. Building apps is officially supported on
+Unix systems (macOS and Linux) only; on Windows, work inside WSL 2.
```bash
npm install -g twenty
@@ -85,5 +86,3 @@ for supported SDK exports and compiler configuration.
Run `twenty commands` for the command inventory or `twenty <command> --help` for
its arguments and options.
-
-Generated next-step commands use PowerShell on Windows and POSIX shell syntax on macOS/Linux.
diff --git a/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts b/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts
index 535b0d169a8..4373728a39a 100644
--- a/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts
+++ b/packages/twenty-cli/src/commands/app/__tests__/app-init.spec.ts
@@ -245,6 +245,27 @@ describe('app init', () => {
expect((await readPackageJson(appDirectory)).name).toBe('@acme/billing');
});
+ it('warns on Windows that building apps needs WSL 2', async () => {
+ const platform = process.platform;
+
+ Object.defineProperty(process, 'platform', { value: 'win32' });
+
+ try {
+ const result = await runJson(['my-app']);
+
+ expect(result.exitCode, result.stdout).toBe(0);
+ expect(result.envelope.warnings).toEqual([
+ {
+ code: 'PLATFORM_UNSUPPORTED',
+ message:
+ 'Building apps is only supported on macOS and Linux. On Windows, work inside WSL 2.',
+ },
+ ]);
+ } finally {
+ Object.defineProperty(process, 'platform', { value: platform });
+ }
+ });
+
it('writes quotes and replacement patterns in the display name and description literally', async () => {
const result = await run([
'my-app',
diff --git a/packages/twenty-cli/src/commands/app/init/run-app-init-command.ts b/packages/twenty-cli/src/commands/app/init/run-app-init-command.ts
index 2cb9444ded6..faffa8fcc3d 100644
--- a/packages/twenty-cli/src/commands/app/init/run-app-init-command.ts
+++ b/packages/twenty-cli/src/commands/app/init/run-app-init-command.ts
@@ -73,6 +73,14 @@ export const runAppInitCommand: CommandRun = async ({
});
const packageNames = [...APP_TEMPLATE_FIRST_PARTY_PACKAGES];
+ if (process.platform === 'win32') {
+ output.warn({
+ code: 'PLATFORM_UNSUPPORTED',
+ message:
+ 'Building apps is only supported on macOS and Linux. On Windows, work inside WSL 2.',
+ });
+ }
+
return {
data: {
app: {
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx
index 9dd4e77a221..40a201d7a96 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx
@@ -6,6 +6,10 @@ description: Create your first Twenty app with the standalone CLI.
Use Node.js 24.5+ and Yarn 4. Install the CLI globally; your app keeps its own SDK dependencies.
+<Note>
+Building Twenty apps is officially supported on Unix systems (macOS and Linux) only. On Windows, work inside WSL 2.
+</Note>
+
## Create the project
```bash