From 0786f9e7932e96b15a4794a3bdf0df00b7003aa3 Mon Sep 17 00:00:00 2001 From: martmull Date: Fri, 10 Jul 2026 10:02:43 +0200 Subject: [PATCH] Seed CHANGELOG.md and SETUP.md in create-twenty-app scaffold (#22769) Projects scaffolded with `create-twenty-app` now include two additional seed files: - `CHANGELOG.md` with an initial `0.1.0` entry matching the template's package version - `SETUP.md` with step-by-step local setup instructions (prerequisites, install, local server, dev sync, verification commands) Both files live in `src/constants/template/`, so they flow through the existing `fs.copy` scaffolding and the vite `copy-assets` build step with no code changes. Verified `dist/constants/template/` contains both files after `nx build create-twenty-app`. The scaffolded `README.md` was also simplified into a marketable front page for the app being built: a pitch placeholder, a features section, and links to `SETUP.md` for setup instructions and `CHANGELOG.md` for history, instead of duplicating dev commands. Also: - Adds a regression test asserting the template directory contains both seed files - Updates `project-structure.mdx` docs to list the new files in the scaffold directory tree --------- Co-authored-by: Martin --- .../src/constants/template/CHANGELOG.md | 7 +++ .../src/constants/template/README.md | 28 ++++++------ .../src/constants/template/SETUP.md | 44 +++++++++++++++++++ .../src/utils/__tests__/app-template.spec.ts | 17 +++++++ .../getting-started/project-structure.mdx | 3 +- 5 files changed, 84 insertions(+), 15 deletions(-) create mode 100644 packages/create-twenty-app/src/constants/template/CHANGELOG.md create mode 100644 packages/create-twenty-app/src/constants/template/SETUP.md 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 0000000000..d88f1af102 --- /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 5164f08185..7d815cdd4a 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: `tim@apple.dev` / `tim@apple.dev`. +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 0000000000..b226d91447 --- /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: `tim@apple.dev` / `tim@apple.dev`. + +## 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 3f15a09254..9917f2cfc8 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 671be042a7..233317b49c 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. | **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.