feat: plugin template (#10150)

Updates the plugin template and adds it to the monorepo

Includes:
* Integration testing setup 
* Adding custom client / server components via a plugin
* The same building setup that we use for our plugins in the monorepo
* `create-payload-app` dynamically configures the project based on the
name:`dev/tsconfig.json`, `src/index.ts`, `dev/payload.config.ts`
For example, from project name: `payload-plugin-cool`
`src/index.ts`:
```ts
export type PayloadPluginCoolConfig = {
  /**
   * List of collections to add a custom field
   */
  collections?: Partial<Record<CollectionSlug, true>>
  disabled?: boolean
}

export const payloadPluginCool =
  (pluginOptions: PayloadPluginCoolConfig) =>
/// ...
```
`dev/tsconfig.json`:
```json
{
  "extends": "../tsconfig.json",
  "exclude": [],
  "include": [
    "**/*.ts",
    "**/*.tsx",
    "../src/**/*.ts",
    "../src/**/*.tsx",
    "next.config.mjs",
    ".next/types/**/*.ts"
  ],
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@payload-config": [
        "./payload.config.ts"
      ],
      "payload-plugin-cool": [
        "../src/index.ts"
      ],
      "payload-plugin-cool/client": [
        "../src/exports/client.ts"
      ],
      "payload-plugin-cool/rsc": [
        "../src/exports/rsc.ts"
      ]
    },
    "noEmit": true
  }
}

```

`./dev/payload.config.ts`
```
import { payloadPluginCool } from 'payload-plugin-cool'
///
 plugins: [
    payloadPluginCool({
      collections: {
        posts: true,
      },
    }),
  ],
```

Example of published plugin
https://www.npmjs.com/package/payload-plugin-cool

Author: r1tsuu

.github/workflows/main.yml

@@ -414,6 +414,8 @@ jobs:
           - template: with-vercel-postgres
             database: postgres
 
+          - template: plugin
+
           # Re-enable once PG conncection is figured out
           # - template: with-vercel-website
           #   database: postgres
@@ -467,6 +469,7 @@ jobs:
         uses: supercharge/mongodb-github-action@1.11.0
         with:
           mongodb-version: 6.0
+        if: matrix.database == 'mongodb'
 
       - name: Build Template
         run: |

docs/plugins/build-your-own.mdx

@@ -9,9 +9,8 @@ keywords: plugins, template, config, configuration, extensions, custom, document
 Building your own [Payload Plugin](./overview) is easy, and if you're already familiar with Payload then you'll have everything you need to get started. You can either start from scratch or use the [Plugin Template](#plugin-template) to get up and running quickly.
 
 <Banner type="success">
-  To use the template, run `npx create-payload-app@latest -t plugin -n my-new-plugin` directly in
-  your terminal or [clone the template directly from
-  GitHub](https://github.com/payloadcms/payload-plugin-template).
+  To use the template, run `npx create-payload-app@latest --template plugin` directly in
+  your terminal.
 </Banner>
 
 Our plugin template includes everything you need to build a full life-cycle plugin:

packages/create-payload-app/src/lib/configure-plugin-project.ts

@@ -0,0 +1,46 @@
+import fse from 'fs-extra'
+import path from 'path'
+
+import { toCamelCase, toPascalCase } from '../utils/casing.js'
+
+/**
+ * Configures a plugin project by updating all package name placeholders to projectName
+ */
+export const configurePluginProject = ({
+  projectDirPath,
+  projectName,
+}: {
+  projectDirPath: string
+  projectName: string
+}) => {
+  const devPayloadConfigPath = path.resolve(projectDirPath, './dev/payload.config.ts')
+  const devTsConfigPath = path.resolve(projectDirPath, './dev/tsconfig.json')
+  const indexTsPath = path.resolve(projectDirPath, './src/index.ts')
+
+  const devPayloadConfig = fse.readFileSync(devPayloadConfigPath, 'utf8')
+  const devTsConfig = fse.readFileSync(devTsConfigPath, 'utf8')
+  const indexTs = fse.readFileSync(indexTsPath, 'utf-8')
+
+  const updatedTsConfig = devTsConfig.replaceAll('plugin-package-name-placeholder', projectName)
+  let updatedIndexTs = indexTs.replaceAll('plugin-package-name-placeholder', projectName)
+
+  const pluginExportVariableName = toCamelCase(projectName)
+
+  updatedIndexTs = updatedIndexTs.replace(
+    'export const myPlugin',
+    `export const ${pluginExportVariableName}`,
+  )
+
+  updatedIndexTs = updatedIndexTs.replaceAll('MyPluginConfig', `${toPascalCase(projectName)}Config`)
+
+  let updatedPayloadConfig = devPayloadConfig.replace(
+    'plugin-package-name-placeholder',
+    projectName,
+  )
+
+  updatedPayloadConfig = updatedPayloadConfig.replaceAll('myPlugin', pluginExportVariableName)
+
+  fse.writeFileSync(devPayloadConfigPath, updatedPayloadConfig)
+  fse.writeFileSync(devTsConfigPath, updatedTsConfig)
+  fse.writeFileSync(indexTsPath, updatedIndexTs)
+}

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

@@ -44,10 +44,11 @@ describe('createProject', () => {
         name: 'plugin',
         type: 'plugin',
         description: 'Template for creating a Payload plugin',
-        url: 'https://github.com/payloadcms/payload-plugin-template',
+        url: 'https://github.com/payloadcms/payload/templates/plugin',
       }
+
       await createProject({
-        cliArgs: args,
+        cliArgs: { ...args, '--local-template': 'plugin' } as CliArgs,
         packageManager,
         projectDir,
         projectName,

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

@@ -10,6 +10,7 @@ import type { CliArgs, DbDetails, PackageManager, ProjectTemplate } from '../typ
 import { tryInitRepoAndCommit } from '../utils/git.js'
 import { debug, error, info, warning } from '../utils/log.js'
 import { configurePayloadConfig } from './configure-payload-config.js'
+import { configurePluginProject } from './configure-plugin-project.js'
 import { downloadTemplate } from './download-template.js'
 
 const filename = fileURLToPath(import.meta.url)
@@ -93,11 +94,17 @@ export async function createProject(args: {
   spinner.start('Checking latest Payload version...')
 
   await updatePackageJSON({ projectDir, projectName })
-  spinner.message('Configuring Payload...')
-  await configurePayloadConfig({
-    dbType: dbDetails?.type,
-    projectDirOrConfigPath: { projectDir },
-  })
+
+  if (template.type === 'plugin') {
+    spinner.message('Configuring Plugin...')
+    configurePluginProject({ projectDirPath: projectDir, projectName })
+  } else {
+    spinner.message('Configuring Payload...')
+    await configurePayloadConfig({
+      dbType: dbDetails?.type,
+      projectDirOrConfigPath: { projectDir },
+    })
+  }
 
   // Remove yarn.lock file. This is only desired in Payload Cloud.
   const lockPath = path.resolve(projectDir, 'pnpm-lock.yaml')

packages/create-payload-app/src/lib/templates.ts

@@ -27,12 +27,11 @@ export function getValidTemplates(): ProjectTemplate[] {
       description: 'Website Template',
       url: `https://github.com/payloadcms/payload/templates/website#main`,
     },
-
-    // {
-    //   name: 'plugin',
-    //   type: 'plugin',
-    //   description: 'Template for creating a Payload plugin',
-    //   url: 'https://github.com/payloadcms/plugin-template#beta',
-    // },
+    {
+      name: 'plugin',
+      type: 'plugin',
+      description: 'Template for creating a Payload plugin',
+      url: 'https://github.com/payloadcms/payload/templates/plugin#main',
+    },
   ]
 }

packages/create-payload-app/src/utils/casing.ts

@@ -0,0 +1,14 @@
+export const toCamelCase = (str: string) => {
+  const s = str
+    .match(/[A-Z]{2,}(?=[A-Z][a-z]+\d*|\b)|[A-Z]?[a-z]+\d*|[A-Z]|\d+/g)
+    ?.map((x) => x.slice(0, 1).toUpperCase() + x.slice(1).toLowerCase())
+    .join('')
+  return (s && s.slice(0, 1).toLowerCase() + s.slice(1)) ?? ''
+}
+
+export function toPascalCase(input: string): string {
+  return input
+    .replace(/[_-]+/g, ' ') // Replace underscores or hyphens with spaces
+    .replace(/(?:^|\s+)(\w)/g, (_, c) => c.toUpperCase()) // Capitalize first letter of each word
+    .replace(/\s+/g, '') // Remove all spaces
+}

templates/plugin/.gitignore

@@ -0,0 +1,43 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+.yarn/install-state.gz
+
+/.idea/*
+!/.idea/runConfigurations
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+/dist
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+
+.env
+
+/dev/media

templates/plugin/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "semi": false
+}

templates/plugin/.swcrc

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/swcrc",
+  "sourceMaps": true,
+  "jsc": {
+    "target": "esnext",
+    "parser": {
+      "syntax": "typescript",
+      "tsx": true,
+      "dts": true
+    },
+    "transform": {
+      "react": {
+        "runtime": "automatic",
+        "pragmaFrag": "React.Fragment",
+        "throwIfNamespace": true,
+        "development": false,
+        "useBuiltins": true
+      }
+    }
+  },
+  "module": {
+    "type": "es6"
+  }
+}