Skip to content

The open alternative to Salesforce, designed for AI.

Seed CHANGELOG.md and SETUP.md in create-twenty-app scaffold (#22769)

martmull0786f9e7932e
diff --git a/packages/create-twenty-app/src/constants/template/CHANGELOG.md b/packages/create-twenty-app/src/constants/template/CHANGELOG.md
new file mode 100644
index 00000000000..d88f1af1025
--- /dev/null
+++ b/packages/create-twenty-app/src/constants/template/CHANGELOG.md
@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this application are documented in this file.
+
+## 0.1.0
+
+- Initial application scaffolded with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app)
diff --git a/packages/create-twenty-app/src/constants/template/README.md b/packages/create-twenty-app/src/constants/template/README.md
index 5164f08185d..7d815cdd4a9 100644
--- a/packages/create-twenty-app/src/constants/template/README.md
+++ b/packages/create-twenty-app/src/constants/template/README.md
@@ -1,24 +1,24 @@
-This is a [Twenty](https://twenty.com) application bootstrapped with [`create-twenty-app`](https://www.npmjs.com/package/create-twenty-app).
+# My Twenty App
-## Getting Started
+Describe your app in one or two sentences.
-This app was scaffolded with a local Twenty server running at [http://localhost:2020](http://localhost:2020).
+## Features
-Login with the default development credentials: `[email protected]` / `[email protected]`.
+List the top things your app does, for example:
-Run `yarn twenty help` to list all available commands.
+- Feature one
+- Feature two
+- Feature three
-## Useful Commands
+## Getting started
-- `yarn twenty dev` - Start the development server and sync your app
-- `yarn twenty docker:status` - Check the local Twenty server status
-- `yarn twenty docker:start` - Start the local Twenty server
-- `yarn lint` - Lint the project with oxlint
-- `yarn typecheck` - Type-check the project
-- `yarn test:unit` - Run unit tests
-- `yarn test` - Run integration tests
+Setup instructions live in [SETUP.md](SETUP.md).
-## Learn More
+## Changelog
+
+Notable changes are documented in [CHANGELOG.md](CHANGELOG.md).
+
+## Learn more
- [Twenty Apps documentation](https://docs.twenty.com/developers/extend/apps/getting-started/quick-start)
- [twenty-sdk CLI reference](https://www.npmjs.com/package/twenty-sdk)
diff --git a/packages/create-twenty-app/src/constants/template/SETUP.md b/packages/create-twenty-app/src/constants/template/SETUP.md
new file mode 100644
index 00000000000..b226d914479
--- /dev/null
+++ b/packages/create-twenty-app/src/constants/template/SETUP.md
@@ -0,0 +1,44 @@
+# Setup
+
+Follow these steps to get your app running locally.
+
+## Prerequisites
+
+- Node.js (version specified in `.nvmrc`)
+- Yarn 4
+- Docker (to run the local Twenty server)
+
+## Steps
+
+1. Install dependencies:
+
+ ```bash
+ yarn install
+ ```
+
+2. Start the local Twenty server:
+
+ ```bash
+ yarn twenty docker:start
+ ```
+
+ Check the server status at any time with `yarn twenty docker:status`.
+
+3. Start the development server and sync your app:
+
+ ```bash
+ yarn twenty dev
+ ```
+
+4. Open [http://localhost:2020](http://localhost:2020) and log in with the default development credentials: `[email protected]` / `[email protected]`.
+
+## Verifying your setup
+
+- `yarn lint` - Lint the project with oxlint
+- `yarn typecheck` - Type-check the project
+- `yarn test:unit` - Run unit tests
+- `yarn test` - Run integration tests
+
+## Troubleshooting
+
+See the [troubleshooting guide](https://docs.twenty.com/developers/extend/apps/getting-started/troubleshooting) or ask on [Discord](https://discord.gg/cx5n4Jzs57).
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 3f15a092546..9917f2cfc8b 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
@@ -212,6 +212,23 @@ describe('copyBaseApplicationProject', () => {
expect(content).toContain("APP_DESCRIPTION = ''");
});
+ it.each(['CHANGELOG.md', 'SETUP.md'])(
+ 'should seed %s in the base template',
+ async (seedFileName) => {
+ const templateDirectory = join(
+ __dirname,
+ '..',
+ '..',
+ 'constants',
+ 'template',
+ );
+
+ expect(await fs.pathExists(join(templateDirectory, seedFileName))).toBe(
+ true,
+ );
+ },
+ );
+
it('should generate unique UUIDs across different scaffolds', async () => {
const firstAppDir = join(testAppDirectory, 'app1');
await fs.ensureDir(join(firstAppDir, 'src', 'constants'));
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 671be042a76..233317b49c3 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
@@ -33,7 +33,7 @@ my-twenty-app/
vitest.unit.config.ts # Unit test runner config
tsconfig.json, tsconfig.spec.json
.nvmrc, .yarnrc.yml, .oxlintrc.json
- README.md, AGENTS.md, CLAUDE.md
+ README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
```
## Key files
@@ -47,6 +47,7 @@ my-twenty-app/
| `src/__tests__/` | A unit test plus an integration test (with its global setup) that syncs the app against a real server. |
| `public/` | Static assets (images, fonts) served with your app. |
| `AGENTS.md` / `CLAUDE.md` | Guidance for AI coding agents working on the app. |
+| `CHANGELOG.md` / `SETUP.md` | Changelog of notable changes and setup instructions for local development. |
<Note>
**File organization is up to you.** The folders above are conventions — the SDK detects entities via AST analysis on `export default defineEntity(...)` calls regardless of where the file lives.