From 6f82cefdc57d2941b82f191f5e0acf89a1ba4975 Mon Sep 17 00:00:00 2001 From: Jacob Fletcher Date: Wed, 3 May 2023 11:14:11 -0400 Subject: [PATCH] chore: adds cloud messaging to example READMEs (#2612) --- examples/auth/cms/README.md | 51 +++++++++++++----- examples/auth/nextjs/README.md | 10 ++-- examples/form-builder/cms/.env.example | 4 +- examples/form-builder/cms/README.md | 56 +++++++++++++------ examples/form-builder/nextjs/README.md | 4 +- examples/preview/cms/.env.example | 4 +- examples/preview/cms/README.md | 35 +++++++++--- examples/preview/cms/src/seed/home.ts | 2 +- examples/preview/nextjs/README.md | 10 ++-- examples/redirects/cms/.env.example | 4 +- examples/redirects/cms/README.md | 29 ++++++++-- examples/redirects/cms/src/seed/home.ts | 2 +- examples/redirects/nextjs/README.md | 8 +-- examples/virtual-fields/.env.example | 4 +- examples/virtual-fields/README.md | 56 ++++++++++++------- examples/whitelabel/.env.example | 5 +- examples/whitelabel/README.md | 72 +++++++++++-------------- 17 files changed, 228 insertions(+), 128 deletions(-) diff --git a/examples/auth/cms/README.md b/examples/auth/cms/README.md index 534625840a..776c943ae9 100644 --- a/examples/auth/cms/README.md +++ b/examples/auth/cms/README.md @@ -1,21 +1,24 @@ -# Auth Example for Payload CMS +# Payload Auth Example -This example demonstrates how to implement [Authentication](https://payloadcms.com/docs/authentication/overview) in Payload CMS. +This example demonstrates how to implement [Payload Authentication](https://payloadcms.com/docs/authentication/overview). -There is a fully working Next.js app tailored specifically for this example which can be found [here](../nextjs). Follow the instructions there to get started. If you are setting up authentication for another front-end, please consider contributing to this repo with your own example! +There is a fully working Next.js app made explicitly for this example which can be found [here](../nextjs). Follow the instructions there to get started. If you are setting up authentication for another front-end, please consider contributing to this repo with your own example! -## Getting Started +## Quick Start -1. Clone this repo -2. `cd` into this directory and run `yarn` or `npm install` -3. `cp .env.example .env` to copy the example environment variables -4. `yarn dev` or `npm run dev` to start the server and seed the database -5. `open http://localhost:8000/admin` to access the admin panel -6. Login with email `dev@payloadcms.com` and password `test` +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:8000/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 -An auth-enabled `users` collection is create which opens all [auth-related operations](https://payloadcms.com/docs/authentication/operations) needed to create a fully custom workflow on your front-end using the REST or GraphQL APIs, including: +The `users` collection exposes all [auth-related operations](https://payloadcms.com/docs/authentication/operations) needed to create a fully custom workflow on your front-end using the REST or GraphQL APIs, including: - `Me` - `Login` @@ -28,7 +31,7 @@ An auth-enabled `users` collection is create which opens all [auth-related opera The [`cors`](https://payloadcms.com/docs/production/preventing-abuse#cross-origin-resource-sharing-cors), [`csrf`](https://payloadcms.com/docs/production/preventing-abuse#cross-site-request-forgery-csrf), and [`cookies`](https://payloadcms.com/docs/authentication/config#options) settings are also configured to ensure that the admin panel and front-end can communicate with each other securely. -### Role-based Access Control +### Access Control Basic role-based access control is setup to determine what users can and cannot do based on their roles, which are: @@ -37,6 +40,28 @@ Basic role-based access control is setup to determine what users can and cannot A `beforeChange` field hook called `protectRoles` is placed on this to automatically populate `roles` with the `user` role when a new user is created. It also protects roles from being changed by non-admins. +## Development + +To spin up this example locally, follow the [Quick Start](#quick-start). + ### Seed -On boot, a seed script is included to create a user with the role `admin`. +On boot, a seed script is included to create a user with email `dev@payloadcms.com`, password `test`, the role `admin`. + +> 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 deploy your app manually, check out the [deployment documentation](https://payloadcms.com/docs/production/deployment) for full details. + +## Questions + +If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/r6sCXqVk3v) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions). + diff --git a/examples/auth/nextjs/README.md b/examples/auth/nextjs/README.md index 01c3d0ac2a..e887eb6513 100644 --- a/examples/auth/nextjs/README.md +++ b/examples/auth/nextjs/README.md @@ -4,9 +4,9 @@ This is a [Next.js](https://nextjs.org/) app made explicitly for Payload's [Auth ## Getting Started -### Payload CMS +### Payload -First you'll need a running CMS. If you have not done so already, open up the `cms` folder alongside this example and follow the setup instructions. Take note of your server URL, you'll need this in the next step. +First you'll need a running Payload app. If you have not done so already, open up the `cms` folder alongside this example and follow the setup instructions. Take note of your server URL, you'll need this in the next step. ### Next.js App @@ -22,14 +22,14 @@ Once running you will find a couple seeded pages on your local environment with To learn more about PayloadCMS and Next.js, take a look at the following resources: -- [Payload CMS Documentation](https://payloadcms.com/docs) - learn about Payload CMS features and API. +- [Payload Documentation](https://payloadcms.com/docs) - learn about Payload features and API. - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. -You can check out [the Payload CMS GitHub repository](https://github.com/payloadcms/payload/) as well as [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! +You can check out [the Payload GitHub repository](https://github.com/payloadcms/payload/) as well as [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! ## Deploy on Vercel The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. -Check out our [Payload CMS deployment documentaton](https://payloadcms.com/docs/production/deployment) or the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. +Check out our [Payload deployment documentation](https://payloadcms.com/docs/production/deployment) or the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. diff --git a/examples/form-builder/cms/.env.example b/examples/form-builder/cms/.env.example index f1eee737c6..a1766fe3b9 100644 --- a/examples/form-builder/cms/.env.example +++ b/examples/form-builder/cms/.env.example @@ -1,4 +1,4 @@ +MONGODB_URI=mongodb://localhost/payload-example-form-builder +PAYLOAD_SECRET=ENTER-STRING-HERE PAYLOAD_PUBLIC_SITE_URL=http://localhost:3000 PAYLOAD_PUBLIC_SERVER_URL=http://localhost:8000 -MONGODB_URI=mongodb://localhost/form-builder-example -PAYLOAD_SECRET=ENTER-STRING-HERE diff --git a/examples/form-builder/cms/README.md b/examples/form-builder/cms/README.md index 96445c9673..8da97f3b4b 100644 --- a/examples/form-builder/cms/README.md +++ b/examples/form-builder/cms/README.md @@ -1,26 +1,48 @@ -# Form Builder Example CMS +# Payload Form Builder Example -This is an example repo for a CMS built with [Payload](https://payloadcms.com). This repo showcases how to utilize Payload's [Form Builder Plugin](https://github.com/payloadcms/plugin-form-builder). +This example demonstrates how to implement the official [Form Builder Plugin](https://github.com/payloadcms/plugin-form-builder) into Payload. -## Getting Started +There is a fully working Next.js app made explicitly for this example which can be found [here](../nextjs). Follow the instructions there to get started. If you are setting up the form builder plugin for another front-end, please consider contributing to this repo with your own example + +## Quick Start + +To spin up this example locally, follow these steps: 1. Clone this repo -2. `cd` into the directory and run `yarn` or `npm install` -3. Copy (`cp`) the `.env.example` file to an `.env` file -4. Run `yarn dev` or `npm run dev` to start the development server -5. Visit `http://localhost:8000/admin` to access the admin panel -6. Login with the following credentials: - - Email: `dev@payloadcms.com` - - Password: `test` +2. `cd` into this directory and run `yarn` or `npm install` +3. `cp .env.example .env` to copy the example environment variables +4. `yarn dev` or `npm run dev` to start the server and seed the database +5. `open http://localhost:8000/admin` to access the admin panel +6. Login with email `dev@payloadcms.com` and password `test` -## Frontend Development +That's it! Changes made in `./src` will be reflected in your app. See the [Development](#development) section for more details. -There is a fully working Next.js app tailored specifically for this example which can be found [here](../nextjs). Follow the instructions there to get started. You can use this repo as a backend for the frontend and see for yourself how it all works together. +## How it works -## Usage +The [Form Builder Plugin](https://github.com/payloadcms/plugin-form-builder) automatically adds the `forms` and `formSubmissions` collections to your config which your front-end can use to query forms and submit form data. You can embed forms into layout building blocks by referring a `forms` document in a relationship field. -Once booted up, a `Basic Form` will be immediately available to view on the home page along with a few other forms on their corresponding pages. +See the official [Form Builder Plugin](https://github.com/payloadcms/plugin-form-builder) for full details. + +## Development + +To spin up this example locally, follow the [Quick Start](#quick-start). + +### Seed + +On boot, a seed script is included to create a user, a home page, and some basic forms. + +## 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 deploy your app manually, check out the [deployment documentation](https://payloadcms.com/docs/production/deployment) for full details. + +## Questions + +If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/r6sCXqVk3v) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions). -- These forms are seeded into the `forms` collection. -- A few pages have also been seeded in on start up and utilize a layout building block called `Form Block` that is wired up to use the different forms from the `forms` collection. -- This is done by adding a `relationship` field in the form-block config and setting its `relationTo` field to the `forms` collection. diff --git a/examples/form-builder/nextjs/README.md b/examples/form-builder/nextjs/README.md index 385474b7de..6be0922c2e 100644 --- a/examples/form-builder/nextjs/README.md +++ b/examples/form-builder/nextjs/README.md @@ -6,9 +6,9 @@ This example repo was made explicitly to demonstrate the power and convenience o ## Getting Started -### Payload CMS +### Payload -First you'll need a running CMS. If you have not done so already, open up the `cms` folder and follow the setup instructions. Take note of your server URL, you'll need this in the next step. +First you'll need a running Payload app. If you have not done so already, open up the `cms` folder and follow the setup instructions. Take note of your server URL, you'll need this in the next step. ### Next.js App diff --git a/examples/preview/cms/.env.example b/examples/preview/cms/.env.example index bfc1b3f4b4..e0515a9e4e 100644 --- a/examples/preview/cms/.env.example +++ b/examples/preview/cms/.env.example @@ -1,6 +1,6 @@ +MONGODB_URI=mongodb://localhost/payload-example-preview +PAYLOAD_SECRET=ENTER-STRING-HERE PAYLOAD_PUBLIC_SITE_URL=http://localhost:3000 PAYLOAD_PUBLIC_SERVER_URL=http://localhost:8000 -MONGODB_URI=mongodb://localhost/payload-example-preview -PAYLOAD_SECRET=PAYLOAD_PREVIEW_EXAMPLE_SECRET_KEY COOKIE_DOMAIN=localhost REVALIDATION_KEY=EXAMPLE_REVALIDATION_KEY diff --git a/examples/preview/cms/README.md b/examples/preview/cms/README.md index e227003560..4123d1d7bd 100644 --- a/examples/preview/cms/README.md +++ b/examples/preview/cms/README.md @@ -1,10 +1,10 @@ -# Preview Example for Payload CMS +# Payload Preview Example -This example demonstrates how to implement preview into Payload CMS using [Versions](https://payloadcms.com/docs/versions/overview) and [Drafts](https://payloadcms.com/docs/versions/drafts). +This example demonstrates how to implement preview into Payload using [Versions](https://payloadcms.com/docs/versions/overview) and [Drafts](https://payloadcms.com/docs/versions/drafts). -There is a fully working Next.js app tailored specifically for this example which can be found [here](../nextjs). Follow the instructions there to get started. If you are setting up preview for another front-end, please consider contributing to this repo with your own example! +There is a fully working Next.js app made explicitly for this example which can be found [here](../nextjs). Follow the instructions there to get started. If you are setting up preview for another front-end, please consider contributing to this repo with your own example! -## Getting Started +## Quick Start 1. Clone this repo 2. `cd` into this directory and run `yarn` or `npm install` @@ -13,6 +13,8 @@ There is a fully working Next.js app tailored specifically for this example whic 5. `open http://localhost:8000/admin` to access the admin panel 6. 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 A `pages` collection is created with `versions: { drafts: true }` and access control that restricts access to only logged-in users and `published` pages. On your front-end, a query similar to this can be used to fetch data and bypass access control in preview mode: @@ -38,10 +40,31 @@ The [`cors`](https://payloadcms.com/docs/production/preventing-abuse#cross-origi To enter preview mode we format a custom URL using a [preview function](https://payloadcms.com/docs/configuration/collections#preview) in the collection config. When a user clicks the "Preview" button, they are routed to this URL along with their http-only cookies and revalidation key. Your front-end can then use the `payload-token` and revalidation key to verify the request and enter into its own preview mode. -### Instant Static Regeneration (ISR) +### ISR -If your front-end is statically generated then you may also want to regenerate the HTML for each page as they are published. To do this, we add an `afterChange` hook to the collection that fires a request to your front-end in the background each time the document is updated. You can handle this request on your front-end and regenerate the HTML for your page however needed. +If your front-end is statically generated then you may also want to regenerate the HTML for each page as they are published, sometimes referred to as Incremental Static Regeneration. To do this, we add an `afterChange` hook to the collection that fires a request to your front-end in the background each time the document is updated. You can handle this request on your front-end and regenerate the HTML for your page however needed. + +## Development + +To spin up this example locally, follow the [Quick Start](#quick-start). ### Seed On boot, a seed script is included to create a user, a home page, and an example page with two versions, one published and one draft. + +> 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 deploy your app manually, check out the [deployment documentation](https://payloadcms.com/docs/production/deployment) for full details. + +## Questions + +If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/r6sCXqVk3v) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions). diff --git a/examples/preview/cms/src/seed/home.ts b/examples/preview/cms/src/seed/home.ts index c016770fbb..3b2fac01fc 100644 --- a/examples/preview/cms/src/seed/home.ts +++ b/examples/preview/cms/src/seed/home.ts @@ -32,7 +32,7 @@ export const home: Partial = { url: 'https://github.com/payloadcms/payload/tree/master/examples/preview/cms', children: [{ text: 'Preview Example' }], }, - { text: '. This example demonstrates how to implement preview into Payload CMS using ' }, + { text: '. This example demonstrates how to implement preview into Payload using ' }, { type: 'link', newTab: true, diff --git a/examples/preview/nextjs/README.md b/examples/preview/nextjs/README.md index 2513eb0aac..0aa825bc1c 100644 --- a/examples/preview/nextjs/README.md +++ b/examples/preview/nextjs/README.md @@ -4,9 +4,9 @@ This is a [Next.js](https://nextjs.org/) app made explicitly for Payload's [Prev ## Getting Started -### Payload CMS +### Payload -First you'll need a running CMS. If you have not done so already, open up the `cms` folder and follow the setup instructions. Take note of your server URL, you'll need this in the next step. +First you'll need a running Payload app. If you have not done so already, open up the `cms` folder and follow the setup instructions. Take note of your server URL, you'll need this in the next step. ### Next.js App @@ -22,14 +22,14 @@ Once running you will find a couple seeded pages on your local environment with To learn more about PayloadCMS and Next.js, take a look at the following resources: -- [Payload CMS Documentation](https://payloadcms.com/docs) - learn about Payload CMS features and API. +- [Payload Documentation](https://payloadcms.com/docs) - learn about Payload features and API. - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. -You can check out [the Payload CMS GitHub repository](https://github.com/payloadcms/payload/) as well as [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! +You can check out [the Payload GitHub repository](https://github.com/payloadcms/payload/) as well as [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! ## Deploy on Vercel The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. -Check out our [Payload CMS deployment documentaton](https://payloadcms.com/docs/production/deployment) or the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. +Check out our [Payload deployment documentation](https://payloadcms.com/docs/production/deployment) or the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. diff --git a/examples/redirects/cms/.env.example b/examples/redirects/cms/.env.example index 6edb5b544d..7b26105607 100644 --- a/examples/redirects/cms/.env.example +++ b/examples/redirects/cms/.env.example @@ -1,4 +1,4 @@ -PAYLOAD_PUBLIC_SITE_URL=http://localhost:3000 -PAYLOAD_PUBLIC_SERVER_URL=http://localhost:8000 MONGODB_URI=mongodb://localhost/payload-example-redirects PAYLOAD_SECRET=ENTER-STRING-HERE +PAYLOAD_PUBLIC_SITE_URL=http://localhost:3000 +PAYLOAD_PUBLIC_SERVER_URL=http://localhost:8000 diff --git a/examples/redirects/cms/README.md b/examples/redirects/cms/README.md index 2a4e96bd2f..7bece6011f 100644 --- a/examples/redirects/cms/README.md +++ b/examples/redirects/cms/README.md @@ -1,10 +1,12 @@ -# Redirects Example for Payload CMS +# Payload Redirects Example -This example demonstrates how to implement http redirects into Payload CMS using the official [Redirects Plugin](https://github.com/payloadcms/plugin-redirects). +This example demonstrates how to implement http redirects into Payload using the official [Redirects Plugin](https://github.com/payloadcms/plugin-redirects). -There is a fully working Next.js app tailored specifically for this example which can be found [here](../nextjs). Follow the instructions there to get started. If you are setting up redirects for another front-end, please consider contributing to this repo with your own example! +There is a fully working Next.js app made explicitly for this example which can be found [here](../nextjs). Follow the instructions there to get started. If you are setting up redirects for another front-end, please consider contributing to this repo with your own example! -## Getting Started +## Quick Start + +To spin up this example locally, follow these steps: 1. Clone this repo 2. `cd` into this directory and run `yarn` or `npm install` @@ -22,9 +24,28 @@ The [Redirects Plugin](https://github.com/payloadcms/plugin-redirects) automatic See the official [Redirects Plugin](https://github.com/payloadcms/plugin-redirects) for full details. +## Development + +To spin up this example locally, follow the [Quick Start](#quick-start). + ### Seed On boot, a seed script is included to create a user, a home page, and a the following redirects for you to test with: - From `/redirect-to-external` to `https://payloadcms.com` - From `/redirect-to-internal` to `/redirected` + +## 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 deploy your app manually, check out the [deployment documentation](https://payloadcms.com/docs/production/deployment) for full details. + +## Questions + +If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/r6sCXqVk3v) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions). diff --git a/examples/redirects/cms/src/seed/home.ts b/examples/redirects/cms/src/seed/home.ts index d5b7db2b69..162cbddae1 100644 --- a/examples/redirects/cms/src/seed/home.ts +++ b/examples/redirects/cms/src/seed/home.ts @@ -33,7 +33,7 @@ export const home: Partial = { ], }, { - text: '. This example demonstrates how to implement http redirects into Payload CMS using the official ', + text: '. This example demonstrates how to implement http redirects into Payload using the official ', }, { type: 'link', diff --git a/examples/redirects/nextjs/README.md b/examples/redirects/nextjs/README.md index 619356a98f..bed292b5a0 100644 --- a/examples/redirects/nextjs/README.md +++ b/examples/redirects/nextjs/README.md @@ -4,7 +4,7 @@ This is a [Next.js](https://nextjs.org/) app made explicitly for Payload's [Redi ## Getting Started -### Payload CMS +### Payload First you'll need a running CMS. If you have not done so already, open up the `cms` folder alongside this example and follow the setup instructions. Take note of your server URL, you'll need this in the next step. @@ -22,14 +22,14 @@ Once running you will find a couple seeded pages on your local environment with To learn more about PayloadCMS and Next.js, take a look at the following resources: -- [Payload CMS Documentation](https://payloadcms.com/docs) - learn about Payload CMS features and API. +- [Payload Documentation](https://payloadcms.com/docs) - learn about Payload features and API. - [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. - [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. -You can check out [the Payload CMS GitHub repository](https://github.com/payloadcms/payload/) as well as [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! +You can check out [the Payload GitHub repository](https://github.com/payloadcms/payload/) as well as [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! ## Deploy on Vercel The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. -Check out our [Payload CMS deployment documentaton](https://payloadcms.com/docs/production/deployment) or the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. +Check out our [Payload deployment documentation](https://payloadcms.com/docs/production/deployment) or the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. diff --git a/examples/virtual-fields/.env.example b/examples/virtual-fields/.env.example index 329d484c59..21ac7a48a1 100644 --- a/examples/virtual-fields/.env.example +++ b/examples/virtual-fields/.env.example @@ -1,3 +1,3 @@ -MONGODB_URI=mongodb://localhost/payload-example-virtual-fields +MONGODB_URI=mongodb://localhost/payload-example-vitual-fields PAYLOAD_SECRET=ENTER-STRING-HERE -PAYLOAD_PUBLIC_SERVER_URL=http://localhost:3000 +PAYLOAD_PUBLIC_SERVER_URL=http://localhost:8000 diff --git a/examples/virtual-fields/README.md b/examples/virtual-fields/README.md index 2aacaaa1da..14bbf85781 100644 --- a/examples/virtual-fields/README.md +++ b/examples/virtual-fields/README.md @@ -1,29 +1,25 @@ -# Virtual Fields Example for Payload CMS +# Payload Virtual Fields Example -This example demonstrates multiple use-cases for virtual fields. +This example demonstrates how to implement virtual fields into Payload. -## Getting Started +## Quick Start -First copy this example with [Degit](https://www.npmjs.com/package/degit) by running the following command at your terminal: +To spin up this example locally, follow these steps: -```bash -npx degit github:payloadcms/payload/examples/virtual-fields -``` +1. Clone this repo +2. `cd` into this directory and run `yarn` or `npm install` +3. `cp .env.example .env` to copy the example environment variables +4. `yarn dev` or `npm run dev` to start the server and seed the database +5. `open http://localhost:8000/admin` to access the admin panel +6. Login with email `dev@payloadcms.com` and password `test` -1. `cd` into this directory and run `yarn` or `npm install` -2. `cp .env.example .env` to copy the example environment variables -3. `yarn dev` or `npm run dev` to start the server and seed the database -4. `open http://localhost:3000/admin` to access the admin panel -5. Login with email `dev@payloadcms.com` and password `test` +## How it works - -## How It Works - -The term *virtual field* is used to describe any field that is not stored in the database and has its value populated within an `afterRead` hook. +The term _virtual field_ is used to describe any field that is not stored in the database and has its value populated within an `afterRead` hook. In this example you have three collections: Locations, Events and Staff. -#### Locations Collection +### Locations Collection In the locations collection, you have separate text fields to input a city, state and country. @@ -37,7 +33,7 @@ Everything else here are virtual fields: `staff`: Relationship field containing all staff associated with the location. -#### Events Collection +### Events Collection This collection takes an event name and date. You will select the event location from the options you have created in the location collection. @@ -45,7 +41,7 @@ Next we have the Ticket fields, you can input the ticket price, sales tax and ad `totalPrice`: Number field that is automatically populated by the sum of `price * tax + fees` -#### Staff Collection +### Staff Collection The staff collection contains text fields for a title, first and last name. @@ -57,6 +53,28 @@ This collection uses the following virtual field to format the staff name fields In the code, navigate to `src/collections` to see how these fields are populated and read more about `afterRead` hooks [here](https://payloadcms.com/docs/hooks). +## Development + +To spin up this example locally, follow the [Quick Start](#quick-start). + +### Seed + +On boot, a seed script is included to create a user, a home page, and a the following redirects for you to test with: + +- From `/redirect-to-external` to `https://payloadcms.com` +- From `/redirect-to-internal` to `/redirected` + +## 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 deploy your app manually, check out the [deployment documentation](https://payloadcms.com/docs/production/deployment) for full details. + ## Questions If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/r6sCXqVk3v) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions). diff --git a/examples/whitelabel/.env.example b/examples/whitelabel/.env.example index 38f6d662f9..f7b6c91ec9 100644 --- a/examples/whitelabel/.env.example +++ b/examples/whitelabel/.env.example @@ -1,2 +1,3 @@ -MONGODB_URI=mongodb://localhost/whitelabel-example-cms -PAYLOAD_SECRET=ENTER-STRING-HERE \ No newline at end of file +MONGODB_URI=mongodb://localhost/payload-example-whitelabel +PAYLOAD_SECRET=ENTER-STRING-HERE +PAYLOAD_PUBLIC_SERVER_URL=http://localhost:8000 diff --git a/examples/whitelabel/README.md b/examples/whitelabel/README.md index 893e7a94c9..b1779c694e 100644 --- a/examples/whitelabel/README.md +++ b/examples/whitelabel/README.md @@ -1,48 +1,19 @@ -# Whitelabeled Example for PayloadCMS +# Payload White-label Example -This example demonstrates how to rebrand the admin panel by modifying the favicon, icon, logo, ogImage and title suffix. +This example demonstrates how to re-brand or white-label the [Payload Admin Panel](https://payloadcms.com/docs/admin/overview#the-admin-panel) by modifying the favicon, icon, logo, ogImage and title suffix. -To use this example, you'll need the following software: -- Yarn or NPM -- NodeJS version 10+ -- A Mongo Database - IMPORTANT: you need to either have MongoDB running locally, or have signed up for a free MongoDB Atlas server in order to test this repo locally. +## Quick Start -## Running locally +To spin up this example locally, follow these steps: -[- Step 1. Copy example](#step-1-copy-example) +1. Clone this repo +2. `cd` into this directory and run `yarn` or `npm install` +3. `cp .env.example .env` to copy the example environment variables +4. `yarn dev` or `npm run dev` to start the server and seed the database +5. `open http://localhost:8000/admin` to access the admin panel +6. Login with email `dev@payloadcms.com` and password `test` -[- Step 2. Set up the environment variables](#step-2-set-up-the-environment-variables) - -[- Step 3. Start the development server](#step-3-add-dependencies-and-start-the-development-server) - -### Step 1. Copy example - -Copy the example by running the following command at your terminal: - -```bash -npx degit github:payloadcms/payload/examples/whitelabel -``` - -### Step 2. Set up the environment variables - -Copy the `.env.example` file in this directory to `.env`: - -```bash -cp .env.example .env -``` - -Typically, the only line that you'll need to change within your new .env for local development is the `MONGO_URI` value. If you have MongoDB running locally, then you can use the example connection string, but if you are using Mongo Atlas or similar, you'll want to fill this value in with your own connection string. - -### Step 3. Add dependencies and start the development server - -```bash -yarn -yarn dev -``` - -Your CMS should now be up and running on [http://localhost:3000/admin](http://localhost:3000/admin). - -## Rebranding walkthrough +## Re-branding walkthrough Start by navigating to the `payload.config.ts` file and then take a look at the admin property. @@ -52,7 +23,7 @@ The following sub-properties have already been configured: `ogImage`: Image that will appear in the preview when you share links to your admin panel online and through social media. -`titleSuffix`: Text that appends the meta/page title displayed in the browser tab — *must be a string*. +`titleSuffix`: Text that appends the meta/page title displayed in the browser tab — _must be a string_. `graphics.Logo`: Image component to be displayed as the logo on the Sign Up / Login view. @@ -60,6 +31,25 @@ The following sub-properties have already been configured: 👉 Check out this blog post for a more in-depth walkthrough: [White-label the Admin UI](https://payloadcms.com/blog/white-label-admin-ui) +## Development + +To spin up this example locally, follow the [Quick Start](#quick-start). + +### Seed + +On boot, a seed script is included to create a user. + +## 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 deploy your app manually, check out the [deployment documentation](https://payloadcms.com/docs/production/deployment) for full details. + ## Questions If you have any issues or questions, reach out to us on [Discord](https://discord.com/invite/r6sCXqVk3v) or start a [GitHub discussion](https://github.com/payloadcms/payload/discussions).