feat(cpa): create project from example using --example CLI arg (#10172

)

Adds the ability to create a project using an existing in the Payload
repo example through `create-payload-app`:

For example:
`pnpx create-payload-app --example custom-server` - creates a project
from the
[custom-server](https://github.com/payloadcms/payload/tree/main/examples/custom-server)
example.

This is much easier and faster then downloading the whole repo and
copying the example to another folder.
Note that we don't configure the payload config with the storage / DB
adapter there because examples can be very specific.

README.md

@@ -96,7 +96,11 @@ If you want to add contributions to this repository, please follow the instructi
 
 The [Examples Directory](./examples) is a great resource for learning how to setup Payload in a variety of different ways, but you can also find great examples in our blog and throughout our social media.
 
-If you'd like to run the examples, you can either copy them to a folder outside this repo or run them directly by (1) navigating to the example's subfolder (`cd examples/your-example-folder`) and (2) using the `--ignore-workspace` flag to bypass workspace restrictions (e.g., `pnpm --ignore-workspace install` or `pnpm --ignore-workspace dev`).
+If you'd like to run the examples, you can use `create-payload-app` to create a project from one:
+
+```sh
+npx create-payload-app --example example_name
+```
 
 You can see more examples at:
 

docs/examples/overview.mdx

@@ -19,4 +19,10 @@ Payload provides a vast array of examples to help you get started with your proj
 - [Tests](https://github.com/payloadcms/payload/tree/main/examples/testing)
 - [White-label Admin UI](https://github.com/payloadcms/payload/tree/main/examples/whitelabel)
 
+If you'd like to run the examples, you can use `create-payload-app` to create a project from one:
+
+```sh
+npx create-payload-app --example example_name
+```
+
 We are adding new examples every day, so if your particular use case is not demonstrated in any existing example, please feel free to start a new [Discussion](https://github.com/payloadcms/payload/discussions) or open a new [PR](https://github.com/payloadcms/payload/pulls) to add it yourself.

examples/auth/README.md

@@ -6,20 +6,17 @@ This [Payload Auth Example](https://github.com/payloadcms/payload/tree/main/exam
 
 To spin up this example locally, follow the steps below:
 
-1. Clone this repo
-1. Navigate into the project directory and install dependencies using your preferred package manager:
+1. Run the following command to create a project from the example:
 
-- `pnpm i --ignore-workspace`\*, `yarn`, or `npm install`
+- `npx create-payload-app --example auth`
 
-> \*NOTE: The --ignore-workspace flag is needed if you are running this example within the Payload monorepo to avoid workspace conflicts.
-
-1. Start the server:
+2. Start the server:
    - Depending on your package manager, run `pnpm dev`, `yarn dev` or `npm run dev`
    - When prompted, type `y` then `enter` to seed the database with sample data
-1. Access the application:
+3. Access the application:
    - Open your browser and navigate to `http://localhost:3000` to access the homepage.
    - Open `http://localhost:3000/admin` to access the admin panel.
-1. Login:
+4. Login:
 
 - Use the following credentials to log into the admin panel:
   > `Email: [email protected]` > `Password: demo`

examples/custom-components/README.md

@@ -6,20 +6,17 @@ This example demonstrates how to use Custom Components in the [Payload](https://
 
 To spin up this example locally, follow the steps below:
 
-1. Clone this repo
-1. Navigate into the project directory and install dependencies using your preferred package manager:
+1. Run the following command to create a project from the example:
 
-- `pnpm i --ignore-workspace`\*, `yarn`, or `npm install`
+- `npx create-payload-app --example custom-components`
 
-> \*NOTE: The --ignore-workspace flag is needed if you are running this example within the Payload monorepo to avoid workspace conflicts.
-
-1. Start the server:
+2. Start the server:
    - Depending on your package manager, run `pnpm dev`, `yarn dev` or `npm run dev`
    - When prompted, type `y` then `enter` to seed the database with sample data
-1. Access the application:
+3. Access the application:
    - Open your browser and navigate to `http://localhost:3000` to access the homepage.
    - Open `http://localhost:3000/admin` to access the admin panel.
-1. Login:
+4. Login:
 
 - Use the following credentials to log into the admin panel:
   > `Email: [email protected]` > `Password: demo`

examples/custom-server/README.md

@@ -1,5 +1,9 @@
 # Payload 3 with Custom Server
 
+Run the following command to create a project from the example:
+
+- `npx create-payload-app --example custom-server`
+
 Uses a [Next.js Custom Server](https://nextjs.org/docs/pages/building-your-application/configuring/custom-server) with express.
 
 Made from official [examples/custom-server](https://github.com/vercel/next.js/tree/canary/examples/custom-server) from Next.js repository.

examples/draft-preview/README.md

@@ -6,15 +6,14 @@ The [Payload Draft Preview Example](https://github.com/payloadcms/payload/tree/m
 
 To spin up this example locally, follow these steps:
 
-1. Clone this repo
-2. `cd` into this directory and run `pnpm i --ignore-workspace`\*, `yarn`, or `npm install`
+1. Run the following command to create a project from the example:
 
-   > \*If you are running using pnpm within the Payload Monorepo, the `--ignore-workspace` flag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root.
+- `npx create-payload-app --example draft-preview`
 
-3. `cp .env.example .env` to copy the example environment variables
-4. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
-5. `open http://localhost:3000/admin` to access the admin panel
-6. Login with email `[email protected]` and password `demo`
+2. `cp .env.example .env` to copy the example environment variables
+3. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
+4. `open http://localhost:3000/admin` to access the admin panel
+5. Login with email `[email protected]` and password `demo`
 
 That's it! Changes made in `./src` will be reflected in your app. See the [Development](#development) section for more details.
 

examples/email/README.md

@@ -6,7 +6,10 @@ This example demonstrates how to integrate email functionality into Payload.
 
 To spin up this example locally, follow these steps:
 
-1. Clone this repo
+1. Run the following command to create a project from the example:
+
+- `npx create-payload-app --example email`
+
 2. `cp .env.example .env` to copy the example environment variables
 3. `pnpm install && pnpm dev` to install dependencies and start the dev server
 4. open `http://localhost:3000/admin` to access the admin panel

examples/form-builder/README.md

@@ -6,17 +6,16 @@ The [Payload Form Builder Example](https://github.com/payloadcms/payload/tree/ma
 
 ## Quick Start
 
-1. Clone this repo
-2. `cd` into this directory and run `pnpm i --ignore-workspace`\*, `yarn`, or `npm install`
+1. Run the following command to create a project from the example:
 
-   > \*If you are running using pnpm within the Payload Monorepo, the `--ignore-workspace` flag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root.
+- `npx create-payload-app --example form-builder`
 
-3. `cp .env.example .env` to copy the example environment variables
+2. `cp .env.example .env` to copy the example environment variables
 
-4. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
+3. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
    - Press `y` when prompted to seed the database
-5. `open http://localhost:3000` to access the home page
-6. `open http://localhost:3000/admin` to access the admin panel
+4. `open http://localhost:3000` to access the home page
+5. `open http://localhost:3000/admin` to access the admin panel
    - Login with email `[email protected]` and password `demo`
 
 That's it! Changes made in `./src` will be

examples/live-preview/README.md

@@ -6,17 +6,16 @@ The [Payload Live Preview Example](https://github.com/payloadcms/payload/tree/ma
 
 ## Quick Start
 
-1. Clone this repo
-2. `cd` into this directory and run `pnpm i --ignore-workspace`\*, `yarn`, or `npm install`
+1. Run the following command to create a project from the example:
 
-   > \*If you are running using pnpm within the Payload Monorepo, the `--ignore-workspace` flag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root.
+- `npx create-payload-app --example live-preview`
 
-3. `cp .env.example .env` to copy the example environment variables
+2. `cp .env.example .env` to copy the example environment variables
 
-4. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
+3. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
    - Press `y` when prompted to seed the database
-5. `open http://localhost:3000` to access the home page
-6. `open http://localhost:3000/admin` to access the admin panel
+4. `open http://localhost:3000` to access the home page
+5. `open http://localhost:3000/admin` to access the admin panel
    - Login with email `[email protected]` and password `demo`
 
 That's it! Changes made in `./src` will be reflected in your app. See the [Development](#development) section for more details.

examples/localization/README.md

@@ -8,10 +8,14 @@ To facilitate the localization process, this example uses the next-intl library.
 
 ## Setup
 
-1. `cp .env.example .env` (copy the .env.example file to .env)
-2. `pnpm install` (`pnpm i --ignore-workspaces` if you are running from the monorepo)
-3. `pnpm run dev`
-4. Seed your database in the admin panel (see below)
+1. Run the following command to create a project from the example:
+
+- `npx create-payload-app --example localization`
+
+2. `cp .env.example .env` (copy the .env.example file to .env)
+3. `pnpm install`
+4. `pnpm run dev`
+5. Seed your database in the admin panel (see below)
 
 ## Seed
 

examples/multi-tenant/README.md

@@ -6,15 +6,14 @@ This example demonstrates how to achieve a multi-tenancy in [Payload](https://gi
 
 To spin up this example locally, follow these steps:
 
-1. Clone this repo
-1. `cd` into this directory and run `pnpm i --ignore-workspace`\*, `yarn`, or `npm install`
+1. Run the following command to create a project from the example:
 
-   > \*If you are running using pnpm within the Payload Monorepo, the `--ignore-workspace` flag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root.
+- `npx create-payload-app --example multi-tenant`
 
-1. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
+2. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
    - Press `y` when prompted to seed the database
-1. `open http://localhost:3000` to access the home page
-1. `open http://localhost:3000/admin` to access the admin panel
+3. `open http://localhost:3000` to access the home page
+4. `open http://localhost:3000/admin` to access the admin panel
    - Login with email `[email protected]` and password `demo`
 
 ## How it works

examples/tailwind-shadcn-ui/README.md

@@ -8,18 +8,17 @@ Checkout our [tutorial](https://payloadcms.com/blog/how-to-setup-tailwindcss-and
 
 To spin up this example locally, follow these steps:
 
-1. Clone this repo
-1. `cd` into this directory and run `pnpm i --ignore-workspace`\*, or `npm install`
+1. Run the following command to create a project from the example:
 
-   > \*If you are running using pnpm within the Payload Monorepo, the `--ignore-workspace` flag is needed so that pnpm generates a lockfile in this example's directory despite the fact that one exists in root.
+- `npx create-payload-app --example tailwind-shadcn-ui`
 
-1. `cp .env.example .env` to copy the example environment variables
+2. `cp .env.example .env` to copy the example environment variables
 
    > Adjust `PAYLOAD_PUBLIC_SITE_URL` in the `.env` if your front-end is running on a separate domain or port.
 
-1. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
+3. `pnpm dev`, `yarn dev` or `npm run dev` to start the server
    - Press `y` when prompted to seed the database
-1. `open http://localhost:3000` to access the home page
-1. `open http://localhost:3000/admin` to access the admin panel
+4. `open http://localhost:3000` to access the home page
+5. `open http://localhost:3000/admin` to access the admin panel
 
 That's it! Changes made in `./src` will be reflected in your app. See the [Development](#development) section for more details.

examples/testing/README.md

@@ -2,6 +2,12 @@
 
 This example demonstrates how to get started with testing Payload using [Jest](https://jestjs.io/). You can clone this down and use it as a starting point for your own Payload projects, or you can follow the steps below to add testing to your existing Payload project.
 
+## Spin up locally:
+
+Run the following command to create a project from the example:
+
+- `npx create-payload-app --example testing`
+
 ## Add testing to your existing Payload project
 
 1. Initial setup:

examples/whitelabel/README.md

@@ -6,7 +6,10 @@ This example demonstrates how to re-brand or white-label the [Payload Admin Pane
 
 To spin up this example locally, follow these steps:
 
-1. Clone this repo
+1. Run the following command to create a project from the example:
+
+- `npx create-payload-app --example whitelabel`
+
 2. `cp .env.example .env` to copy the example environment variables
 3. `pnpm install && pnpm dev` to install dependencies and start the dev server
 4. `open http://localhost:3000/admin` to access the admin panel

packages/create-payload-app/src/lib/create-project.spec.ts

@@ -5,7 +5,7 @@ import globby from 'globby'
 import * as os from 'node:os'
 import path from 'path'
 
-import type { CliArgs, DbType, ProjectTemplate } from '../types.js'
+import type { CliArgs, DbType, ProjectExample, ProjectTemplate } from '../types.js'
 
 import { createProject } from './create-project.js'
 import { dbReplacements } from './replacements.js'
@@ -62,6 +62,32 @@ describe('createProject', () => {
       expect(packageJson.name).toStrictEqual(projectName)
     })
 
+    it('creates example', async () => {
+      const projectName = 'custom-server-example'
+      const example: ProjectExample = {
+        name: 'custom-server',
+        url: 'https://github.com/payloadcms/payload/examples/custom-server#main',
+      }
+
+      await createProject({
+        cliArgs: {
+          ...args,
+          '--local-template': undefined,
+          '--local-example': 'custom-server',
+        } as CliArgs,
+        packageManager,
+        projectDir,
+        projectName,
+        example,
+      })
+
+      const packageJsonPath = path.resolve(projectDir, 'package.json')
+      const packageJson = fse.readJsonSync(packageJsonPath)
+
+      // Check package name and description
+      expect(packageJson.name).toStrictEqual(projectName)
+    })
+
     describe('creates project from template', () => {
       const templates = getValidTemplates()