chore: builds custom server example (#2920)

examples/custom-server/.env.example

@@ -0,0 +1,6 @@
+MONGODB_URI=mongodb://localhost/payload-example-custom-server
+PAYLOAD_SECRET=PAYLOAD_CUSTOM_SERVER_EXAMPLE_SECRET_KEY
+PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000
+NEXT_PUBLIC_SERVER_URL=http://localhost:3000
+PAYLOAD_SEED=true
+PAYLOAD_DROP_DATABASE=true

examples/custom-server/.eslintrc.js

@@ -0,0 +1,5 @@
+module.exports = {
+  root: true,
+  extends: ['@payloadcms'],
+  ignorePatterns: ['**/payload-types.ts'],
+}

examples/custom-server/.gitignore

@@ -0,0 +1,7 @@
+build
+dist
+node_modules
+package-lock.json
+.env
+.next
+.vercel

examples/custom-server/.prettierignore

@@ -0,0 +1 @@
+**/payload-types.ts

examples/custom-server/.prettierrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+  printWidth: 100,
+  parser: "typescript",
+  semi: false,
+  singleQuote: true,
+  trailingComma: "all",
+  arrowParens: "avoid",
+};

examples/custom-server/README.md

@@ -0,0 +1,118 @@
+# Payload Custom Server Example
+
+This example demonstrates how to serve your front-end alongside [Payload](https://github.com/payloadcms/payload) in a single Express server. This pattern will cut down on hosting costs and can simplify your deployment process.
+
+## Quick Start
+
+To spin up this example locally, follow these steps:
+
+1. First clone the repo
+1. Then `cd YOUR_PROJECT_REPO && cp .env.example .env`
+1. Next `yarn && yarn dev`
+1. Now `open http://localhost:3000/admin` to access the admin panel
+1. Login with email `dev@payloadcms.com` and password `test`
+
+That's it! Changes made in `./src` will be reflected in your app. See the [Development](#development) section for more details.
+
+## How it works
+
+When you use Payload, you plug it into _**your**_ Express server. That's a fundamental difference between Payload and other application frameworks. It means that when you use Payload, you're technically _adding_ Payload to _your_ app, and not building a "Payload app".
+
+One of the strengths of this pattern is that it lets you do powerful things like integrate your Payload instance directly with your front-end. This will allow you to host Payload alongside a fully dynamic, CMS-integrated website or app on a single, combined server—while still getting all of the benefits of a headless CMS.
+
+### Express
+
+In every Payload app is a `server.ts` file in which you instantiate your own Express server and attach Payload to it. This is where you can can add any custom Express middleware or routes you need to serve your front-end. To combine Payload with your framework on the same server, we need to do three main things:
+
+1. Modify your `server.ts` file to build and serve your front-end using the APIs provided by your framework
+2. Modify your `package.json` scripts include your framework's build commands
+3. Use a separate `tsconfig.server.json` file to build the server, because your front-end may require incompatible TypeScript settings
+
+This example demonstrates how to do this with [Next.js](https://nextjs.org), although the same principles apply to any front-end framework like [Vue](https://vuejs.org), [Nuxt](https://nuxt.com), or [SvelteKit](https://kit.svelte.dev). If your framework does not yet have instructions listed here, please consider contributing them to this example for others to use. To quickly eject Next.js from this example, see the [Eject](#eject) section.
+
+#### Next.js
+
+For Next.js apps, your `server.ts` file looks something like this:
+
+```ts
+import next from 'next'
+import nextBuild from 'next/dist/build'
+
+// Instantiate Express and Payload
+// ...
+
+// If building, start the server to build the Next.js app then exit
+if (process.env.NEXT_BUILD) {
+  app.listen(3000, async () => {
+    await nextBuild(path.join(__dirname, '../'))
+    process.exit()
+  })
+
+  return
+}
+
+// Attach Next.js routes and start the server
+const nextApp = next({
+  dev: process.env.NODE_ENV !== 'production',
+})
+
+const nextHandler = nextApp.getRequestHandler()
+
+app.get('*', (req, res) => nextHandler(req, res))
+
+nextApp.prepare().then(() => {
+  app.listen(3000)
+})
+```
+
+Check out the [server.ts](./src/server.ts) in this repository for a complete working example. You can also see the [Next.js docs](https://nextjs.org/docs/advanced-features/custom-server) for more details.
+
+Then your `package.json` might look something like this:
+
+```json
+// ...
+"scripts": {
+  // ...
+  "build:payload": "payload build",
+  "build:server": "tsc --project tsconfig.server.json",
+  "build:next": "next build",
+  "build": "yarn build:payload && yarn build:server && yarn build:next",
+}
+```
+
+Check out the [package.json](./src/package.json) in this repository for a complete working example. You can also see the [Next.js docs](https://nextjs.org/docs/api-reference/cli#build) for more details.
+
+## Eject
+
+To eject Next.js from this template and replace it with another front-end framework, follow these steps:
+
+1. Remove the `next`, `react`, and `react-dom` dependencies from your `package.json` file
+1. Remove the `next.config.js` and `next-env.d.ts` files from your project root
+1. Remove the `./src/app` directory and all of its contents
+
+Now you can install and setup any other framework you'd like. Follow the [Express](#express) instructions above to make the necessary changes to build and serve your front-end.
+
+## Development
+
+To spin up this example locally, follow the [Quick Start](#quick-start).
+
+### Seed
+
+On boot, a seed script is included to scaffold a basic database for you to use as an example. This is done by setting the `PAYLOAD_DROP_DATABASE` and `PAYLOAD_SEED` environment variables which are included in the `.env.example` by default. You can remove these from your `.env` to prevent this behavior. You can also freshly seed your project at any time by running `yarn seed`. This seed creates an admin user with email `dev@payloadcms.com`, password `test`, and a `home` page.
+
+> NOTICE: seeding the database is destructive because it drops your current database to populate a fresh one from the seed template. Only run this command if you are starting a new project or can afford to lose your current data.
+
+## Production
+
+To run Payload in production, you need to build and serve the Admin panel. To do so, follow these steps:
+
+1. First, invoke the `payload build` script by running `yarn build` or `npm run build` in your project root. This creates a `./build` directory with a production-ready admin bundle.
+1. Then, run `yarn serve` or `npm run serve` to run Node in production and serve Payload from the `./build` directory.
+
+### Deployment
+
+The easiest way to deploy your project is to use [Payload Cloud](https://payloadcms.com/new/import), a one-click hosting solution to deploy production-ready instances of your Payload apps directly from your GitHub repo. You can also choose to self-host your app, check out the [Deployment](https://payloadcms.com/docs/production/deployment) docs for more details.
+
+## Questions
+
+If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/payload) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions).

examples/custom-server/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/basic-features/typescript for more information.

examples/custom-server/next.config.js

@@ -0,0 +1,13 @@
+require('dotenv').config()
+
+module.exports = {
+  publicRuntimeConfig: {
+    SERVER_URL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
+  },
+  images: {
+    domains: [
+      'localhost',
+      // Your domain(s) here
+    ],
+  },
+}

examples/custom-server/nodemon.json

@@ -0,0 +1,4 @@
+{
+  "ext": "ts,tsx",
+  "exec": "ts-node src/server.ts"
+}

examples/custom-server/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "payload-example-custom-server",
+  "description": "Payload custom server example.",
+  "version": "1.0.0",
+  "main": "dist/server.js",
+  "license": "MIT",
+  "scripts": {
+    "dev": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts nodemon",
+    "seed": "rm -rf media && cross-env PAYLOAD_SEED=true PAYLOAD_DROP_DATABASE=true PAYLOAD_CONFIG_PATH=src/payload.config.ts ts-node src/server.ts",
+    "build:payload": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload build",
+    "build:server": "tsc --project tsconfig.server.json",
+    "build:next": "cross-env PAYLOAD_CONFIG_PATH=dist/payload.config.js NEXT_BUILD=true node dist/server.js",
+    "build": "cross-env NODE_ENV=production yarn build:payload && yarn build:server && yarn copyfiles && yarn build:next",
+    "serve": "cross-env PAYLOAD_CONFIG_PATH=dist/payload.config.js NODE_ENV=production node dist/server.js",
+    "copyfiles": "copyfiles -u 1 \"src/**/*.{html,css,scss,ttf,woff,woff2,eot,svg,jpg,png}\" dist/",
+    "generate:types": "cross-env PAYLOAD_CONFIG_PATH=src/payload.config.ts payload generate:types",
+    "generate:graphQLSchema": "PAYLOAD_CONFIG_PATH=src/payload.config.ts payload generate:graphQLSchema",
+    "lint": "eslint src",
+    "lint:fix": "eslint --fix --ext .ts,.tsx src"
+  },
+  "dependencies": {
+    "dotenv": "^8.2.0",
+    "escape-html": "^1.0.3",
+    "express": "^4.17.1",
+    "next": "^13.4.7",
+    "payload": "^1.8.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@payloadcms/eslint-config": "^0.0.1",
+    "@types/escape-html": "^1.0.2",
+    "@types/express": "^4.17.9",
+    "@types/node": "18.11.3",
+    "@types/react": "18.0.21",
+    "@typescript-eslint/eslint-plugin": "^5.51.0",
+    "@typescript-eslint/parser": "^5.51.0",
+    "copyfiles": "^2.4.1",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.19.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-filenames": "^1.3.2",
+    "eslint-plugin-import": "2.25.4",
+    "eslint-plugin-prettier": "^4.0.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "nodemon": "^2.0.22",
+    "prettier": "^2.7.1",
+    "ts-node": "^9.1.1",
+    "typescript": "^4.8.4"
+  }
+}

examples/custom-server/public/favicon.svg

@@ -0,0 +1,15 @@
+<svg width="260" height="260" viewBox="0 0 260 260" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    path {
+      fill: #0F0F0F;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      path {
+        fill: white;
+      }
+    }
+  </style>
+	<path d="M120.59 8.5824L231.788 75.6142V202.829L148.039 251.418V124.203L36.7866 57.2249L120.59 8.5824Z" />
+	<path d="M112.123 244.353V145.073L28.2114 193.769L112.123 244.353Z" />
+</svg>

examples/custom-server/src/app/_components/Gutter/index.module.scss

@@ -0,0 +1,7 @@
+.gutterLeft {
+  padding-left: var(--gutter-h);
+}
+
+.gutterRight {
+  padding-right: var(--gutter-h);
+}

examples/custom-server/src/app/_components/Gutter/index.tsx

@@ -0,0 +1,33 @@
+import React, { forwardRef, Ref } from 'react'
+
+import classes from './index.module.scss'
+
+type Props = {
+  left?: boolean
+  right?: boolean
+  className?: string
+  children: React.ReactNode
+  ref?: Ref<HTMLDivElement>
+}
+
+export const Gutter: React.FC<Props> = forwardRef<HTMLDivElement, Props>((props, ref) => {
+  const { left = true, right = true, className, children } = props
+
+  return (
+    <div
+      ref={ref}
+      className={[
+        left && classes.gutterLeft,
+        right && classes.gutterRight,
+        className,
+        classes.gutter,
+      ]
+        .filter(Boolean)
+        .join(' ')}
+    >
+      {children}
+    </div>
+  )
+})
+
+Gutter.displayName = 'Gutter'

examples/custom-server/src/app/_components/RichText/Serialize/index.tsx

@@ -0,0 +1,180 @@
+import React, { Fragment } from 'react'
+import escapeHTML from 'escape-html'
+import Link from 'next/link'
+
+type Node = {
+  type: string
+  value?: {
+    url: string
+    alt: string
+  }
+  children?: Node[]
+  url?: string
+  [key: string]: unknown
+  newTab?: boolean
+}
+
+export type CustomRenderers = {
+  [key: string]: (args: { node: Node; Serialize: SerializeFunction; index: number }) => JSX.Element // eslint-disable-line
+}
+
+type SerializeFunction = React.FC<{
+  content?: Node[]
+  customRenderers?: CustomRenderers
+}>
+
+const isText = (value: any): boolean =>
+  typeof value === 'object' && value !== null && typeof value.text === 'string'
+
+export const Serialize: SerializeFunction = ({ content, customRenderers }) => {
+  return (
+    <Fragment>
+      {content?.map((node, i) => {
+        if (isText(node)) {
+          // @ts-expect-error
+          let text = <span dangerouslySetInnerHTML={{ __html: escapeHTML(node.text) }} />
+
+          if (node.bold) {
+            text = <strong key={i}>{text}</strong>
+          }
+
+          if (node.code) {
+            text = <code key={i}>{text}</code>
+          }
+
+          if (node.italic) {
+            text = <em key={i}>{text}</em>
+          }
+
+          if (node.underline) {
+            text = (
+              <span style={{ textDecoration: 'underline' }} key={i}>
+                {text}
+              </span>
+            )
+          }
+
+          if (node.strikethrough) {
+            text = (
+              <span style={{ textDecoration: 'line-through' }} key={i}>
+                {text}
+              </span>
+            )
+          }
+
+          return <Fragment key={i}>{text}</Fragment>
+        }
+
+        if (!node) {
+          return null
+        }
+
+        if (
+          customRenderers &&
+          customRenderers[node.type] &&
+          typeof customRenderers[node.type] === 'function'
+        ) {
+          return customRenderers[node.type]({ node, Serialize, index: i })
+        }
+
+        switch (node.type) {
+          case 'br':
+            return <br key={i} />
+
+          case 'h1':
+            return (
+              <h1 key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </h1>
+            )
+
+          case 'h2':
+            return (
+              <h2 key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </h2>
+            )
+
+          case 'h3':
+            return (
+              <h3 key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </h3>
+            )
+
+          case 'h4':
+            return (
+              <h4 key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </h4>
+            )
+
+          case 'h5':
+            return (
+              <h5 key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </h5>
+            )
+
+          case 'h6':
+            return (
+              <h6 key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </h6>
+            )
+
+          case 'quote':
+            return (
+              <blockquote key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </blockquote>
+            )
+
+          case 'ul':
+            return (
+              <ul key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </ul>
+            )
+
+          case 'ol':
+            return (
+              <ol key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </ol>
+            )
+
+          case 'li':
+            return (
+              <li key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </li>
+            )
+
+          case 'link':
+            return (
+              <Link
+                href={escapeHTML(node.url)}
+                key={i}
+                {...(node.newTab
+                  ? {
+                      target: '_blank',
+                      rel: 'noopener noreferrer',
+                    }
+                  : {})}
+              >
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </Link>
+            )
+
+          default:
+            return (
+              <p key={i}>
+                <Serialize content={node.children} customRenderers={customRenderers} />
+              </p>
+            )
+        }
+      })}
+    </Fragment>
+  )
+}

examples/custom-server/src/app/_components/RichText/index.module.scss

@@ -0,0 +1,20 @@
+.richText {
+  text-align: center; // hack but whatever
+  max-width: 1000px;
+
+  a {
+    text-decoration: underline;
+  }
+
+  :first-child {
+    margin-top: 0;
+  }
+
+  :last-child {
+    margin-bottom: 0;
+  }
+
+  span {
+    white-space: pre-wrap;
+  }
+}

examples/custom-server/src/app/_components/RichText/index.tsx

@@ -0,0 +1,23 @@
+'use client'
+
+import React from 'react'
+
+import { CustomRenderers, Serialize as SerializeContent } from './Serialize'
+
+import classes from './index.module.scss'
+
+export const RichText: React.FC<{
+  className?: string
+  content: any
+  customRenderers?: CustomRenderers
+}> = ({ className, content, customRenderers }) => {
+  if (!content) {
+    return null
+  }
+
+  return (
+    <div className={[classes.richText, className].filter(Boolean).join(' ')}>
+      <SerializeContent content={content} customRenderers={customRenderers} />
+    </div>
+  )
+}

examples/custom-server/src/app/globals.scss

@@ -0,0 +1,106 @@
+$breakpoint: 1000px;
+
+:root {
+  --max-width: 1100px;
+  --border-radius: 12px;
+  --foreground-rgb: 0, 0, 0;
+  --background-rgb: 255, 255, 255;
+  --block-spacing: 2rem;
+  --gutter-h: 4rem;
+
+  @media (max-width: $breakpoint) {
+    --block-spacing: 1rem;
+    --gutter-h: 2rem;
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --foreground-rgb: 255, 255, 255;
+    --background-rgb: 7, 7, 7;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html {
+  font-size: 20px;
+  line-height: 1.5;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+
+  @media (max-width: $breakpoint) {
+    font-size: 16px;
+  }
+}
+
+html,
+body {
+  max-width: 100vw;
+  overflow-x: hidden;
+}
+
+body {
+  margin: 0;
+  color: rgb(var(--foreground-rgb));
+  background: rgb(var(--background-rgb));
+}
+
+img {
+  height: auto;
+  max-width: 100%;
+  display: block;
+}
+
+h1 {
+  font-size: 4.5rem;
+  line-height: 1.2;
+  margin: 0 0 2.5rem 0;
+
+  @media (max-width: $breakpoint) {
+    font-size: 3rem;
+    margin: 0 0 1.5rem 0;
+  }
+}
+
+h2 {
+  font-size: 3.5rem;
+  line-height: 1.2;
+  margin: 0 0 2.5rem 0;
+}
+
+h3 {
+  font-size: 2.5rem;
+  line-height: 1.2;
+  margin: 0 0 2rem 0;
+}
+
+h4 {
+  font-size: 1.5rem;
+  line-height: 1.2;
+  margin: 0 0 1rem 0;
+}
+
+h5 {
+  font-size: 1.25rem;
+  line-height: 1.2;
+  margin: 0 0 1rem 0;
+}
+
+h6 {
+  font-size: 1rem;
+  line-height: 1.2;
+  margin: 0 0 1rem 0;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  html {
+    color-scheme: dark;
+  }
+}

examples/custom-server/src/app/layout.module.scss

@@ -0,0 +1,16 @@
+.body {
+  padding: 6rem 0;
+  min-height: 100vh;
+}
+
+.logo {
+  width: 200px;
+}
+
+.header {
+  margin-bottom: 4rem;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}

examples/custom-server/src/app/layout.tsx

@@ -0,0 +1,35 @@
+import React from 'react'
+
+import './globals.scss'
+
+import classes from './layout.module.scss'
+
+export const metadata = {
+  title: 'Payload Custom Server',
+  description: 'Serve Payload alongside any front-end framework.',
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body className={classes.body}>
+        <header className={classes.header}>
+          <a href="https://payloadcms.com" target="_blank" rel="noopener noreferrer">
+            <picture>
+              <source
+                media="(prefers-color-scheme: dark)"
+                srcSet="https://raw.githubusercontent.com/payloadcms/payload/master/src/admin/assets/images/payload-logo-light.svg"
+              />
+              <img
+                className={classes.logo}
+                alt="payload cms logo"
+                src="https://raw.githubusercontent.com/payloadcms/payload/master/src/admin/assets/images/payload-logo-dark.svg"
+              />
+            </picture>
+          </a>
+        </header>
+        {children}
+      </body>
+    </html>
+  )
+}

examples/custom-server/src/app/page.module.scss

@@ -0,0 +1,17 @@
+.main {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  align-items: center;
+  margin: 0 auto;
+
+  @media (max-width: 768px) {
+    padding: 2rem 0;
+  }
+}
+
+.body {
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+}

examples/custom-server/src/app/page.tsx

@@ -0,0 +1,32 @@
+import React, { Fragment } from 'react'
+import { notFound } from 'next/navigation'
+
+import { Page } from './../payload-types'
+import { Gutter } from './_components/Gutter'
+import { RichText } from './_components/RichText'
+
+import classes from './page.module.scss'
+
+export default async function Home() {
+  const home: Page = await fetch(
+    `${process.env.NEXT_PUBLIC_SERVER_URL}/api/pages?where[slug][equals]=home`,
+  )
+    .then(res => res.json())
+    .then(res => res?.docs?.[0])
+
+  if (!home) {
+    return notFound()
+  }
+
+  return (
+    <Fragment>
+      <main className={classes.main}>
+        <Gutter>
+          <div className={classes.body}>
+            <RichText content={home.richText} />
+          </div>
+        </Gutter>
+      </main>
+    </Fragment>
+  )
+}

examples/custom-server/src/collections/Pages.ts

@@ -0,0 +1,39 @@
+import type { CollectionConfig } from 'payload/types'
+
+import formatSlug from '../utilities/formatSlug'
+
+export const Pages: CollectionConfig = {
+  slug: 'pages',
+  admin: {
+    useAsTitle: 'title',
+  },
+  access: {
+    read: () => true,
+  },
+  fields: [
+    {
+      name: 'title',
+      label: 'Title',
+      type: 'text',
+      required: true,
+    },
+    {
+      name: 'richText',
+      type: 'richText',
+      label: 'Content',
+    },
+    {
+      name: 'slug',
+      label: 'Slug',
+      type: 'text',
+      admin: {
+        position: 'sidebar',
+      },
+      hooks: {
+        beforeValidate: [formatSlug('title')],
+      },
+    },
+  ],
+}
+
+export default Pages

examples/custom-server/src/payload-types.ts

@@ -0,0 +1,38 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * This file was automatically generated by Payload.
+ * DO NOT MODIFY IT BY HAND. Instead, modify your source Payload config,
+ * and re-run `payload generate:types` to regenerate this file.
+ */
+
+export interface Config {
+  collections: {
+    pages: Page;
+    users: User;
+  };
+  globals: {};
+}
+export interface Page {
+  id: string;
+  title: string;
+  richText?: {
+    [k: string]: unknown;
+  }[];
+  slug?: string;
+  updatedAt: string;
+  createdAt: string;
+}
+export interface User {
+  id: string;
+  updatedAt: string;
+  createdAt: string;
+  email: string;
+  resetPasswordToken?: string;
+  resetPasswordExpiration?: string;
+  salt?: string;
+  hash?: string;
+  loginAttempts?: number;
+  lockUntil?: string;
+  password?: string;
+}

examples/custom-server/src/payload.config.ts

@@ -0,0 +1,18 @@
+import dotenv from 'dotenv'
+import path from 'path'
+
+dotenv.config({
+  path: path.resolve(__dirname, '../.env'),
+})
+
+import { buildConfig } from 'payload/config'
+
+import { Pages } from './collections/Pages'
+
+export default buildConfig({
+  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL || '',
+  collections: [Pages],
+  typescript: {
+    outputFile: path.resolve(__dirname, 'payload-types.ts'),
+  },
+})

examples/custom-server/src/seed/index.ts

@@ -0,0 +1,93 @@
+import type { Payload } from 'payload'
+
+export const seed = async (payload: Payload): Promise<void> => {
+  // create admin
+  await payload.create({
+    collection: 'users',
+    data: {
+      email: 'dev@payloadcms.com',
+      password: 'test',
+    },
+  })
+
+  // create home page
+  await Promise.all([
+    await payload.create({
+      collection: 'pages',
+      data: {
+        title: 'Home',
+        richText: [
+          {
+            children: [
+              {
+                text: 'Payload Custom Server Example',
+              },
+            ],
+            type: 'h1',
+          },
+          {
+            children: [
+              {
+                text: 'This is an example of how to host ',
+              },
+              {
+                type: 'link',
+                linkType: 'custom',
+                url: 'https://payloadcms.com',
+                children: [
+                  {
+                    text: 'Payload',
+                  },
+                ],
+                newTab: true,
+              },
+              {
+                text: ' alongside your front-end by sharing a single Express server. You are currently browsing a ',
+              },
+              {
+                type: 'link',
+                linkType: 'custom',
+                url: 'https://nextjs.org',
+                children: [
+                  {
+                    text: 'Next.js',
+                  },
+                ],
+                newTab: true,
+              },
+              {
+                text: ' app, but you can easily swap in any framework you like—check out the ',
+              },
+              {
+                type: 'link',
+                linkType: 'custom',
+                url: 'http://github.com/payloadcms/payload/tree/master/examples/custom-server',
+                children: [
+                  {
+                    text: 'README.md',
+                  },
+                ],
+              },
+              {
+                text: ' for instructions on how to do this. ',
+              },
+              {
+                type: 'link',
+                linkType: 'custom',
+                url: 'http://localhost:3000/admin',
+                children: [
+                  {
+                    text: 'Click here',
+                  },
+                ],
+              },
+              {
+                text: ' to navigate to the admin panel and login.',
+              },
+            ],
+          },
+        ],
+      },
+    }),
+  ])
+}

examples/custom-server/src/server.ts

@@ -0,0 +1,61 @@
+import dotenv from 'dotenv'
+import next from 'next'
+import nextBuild from 'next/dist/build'
+import path from 'path'
+
+dotenv.config({
+  path: path.resolve(__dirname, '../.env'),
+})
+
+import express from 'express'
+import payload from 'payload'
+
+import { seed } from './seed'
+
+const app = express()
+const PORT = process.env.PORT || 3000
+
+const start = async (): Promise<void> => {
+  await payload.init({
+    secret: process.env.PAYLOAD_SECRET || '',
+    mongoURL: process.env.MONGODB_URI || '',
+    express: app,
+    onInit: () => {
+      payload.logger.info(`Payload Admin URL: ${payload.getAdminURL()}`)
+    },
+  })
+
+  if (process.env.PAYLOAD_SEED === 'true') {
+    payload.logger.info('---- SEEDING DATABASE ----')
+    await seed(payload)
+  }
+
+  if (process.env.NEXT_BUILD) {
+    app.listen(PORT, async () => {
+      payload.logger.info(`Next.js is now building...`)
+      // @ts-expect-error
+      await nextBuild(path.join(__dirname, '../'))
+      process.exit()
+    })
+
+    return
+  }
+
+  const nextApp = next({
+    dev: process.env.NODE_ENV !== 'production',
+  })
+
+  const nextHandler = nextApp.getRequestHandler()
+
+  app.get('*', (req, res) => nextHandler(req, res))
+
+  nextApp.prepare().then(() => {
+    payload.logger.info('Next.js started')
+
+    app.listen(PORT, async () => {
+      payload.logger.info(`Server listening on ${PORT}...`)
+    })
+  })
+}
+
+start()

examples/custom-server/src/utilities/formatSlug.ts

@@ -0,0 +1,24 @@
+import type { FieldHook } from 'payload/types'
+
+const format = (val: string): string =>
+  val
+    .replace(/ /g, '-')
+    .replace(/[^\w-/]+/g, '')
+    .toLowerCase()
+
+const formatSlug =
+  (fallback: string): FieldHook =>
+  ({ value, originalDoc, data }) => {
+    if (typeof value === 'string') {
+      return format(value)
+    }
+    const fallbackData = data?.[fallback] || originalDoc?.[fallback]
+
+    if (fallbackData && typeof fallbackData === 'string') {
+      return format(fallbackData)
+    }
+
+    return value
+  }
+
+export default formatSlug

examples/custom-server/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "target": "es5",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "incremental": true,
+    "jsx": "preserve",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "server.ts",
+    "payload.config.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    "next.config.js",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ],
+  "ts-node": {
+    "transpileOnly": true,
+    "swc": true
+  }
+}

examples/custom-server/tsconfig.server.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "outDir": "dist",
+    "noEmit": false,
+    "jsx": "react",
+  },
+  "include": [
+    "src/server.ts",
+    "src/payload.config.ts",
+  ]
+}