search

stevensblueprint / c4p-payload

1 stars 1 forks source link

readme

TODO for Blueprint Developers on Team C4P

Add yourself to the Contributors File

You must have git installed and be added to the Blueprint organization on GitHub. To officially get started on the repository please follow these steps:

  1. Clone the repository: git clone git@github.com:stevensblueprint/c4p-payload.git
  2. Create a branch: git checkout -b contributor/REPLACEWITHYOURNAME
  3. Add your name to ./github/CONTRIUBTORS.md account

  4. Commit your changes:

    git add ./CONTRIBUTORS.md
git commit -m "Added Name to Contributors file"
git push

    This last command may give you an error, just read the error message and follow it to resolve the issue Link Issue #2 in the description of the PR..

  5. Create a Pull Request on GitHub

Payload Website Template

This is the official Payload Website Template. Use it to power websites, blogs, or portfolios from small to enterprise. This repo includes a fully-working backend, enterprise-grade admin panel, and a beautifully designed, production-ready website.

This template is right for you if you are working on:

Core features:

Quick Start

To spin up this example locally, follow these steps:

Clone

If you have not done so already, you need to have standalone copy of this repo on your machine. If you've already cloned this repo, skip to Development.

Method 1 (recommended)

Go to Payload Cloud and clone this template. This will create a new repository on your GitHub account with this template's code which you can then clone to your own machine.

Method 2

Use the create-payload-app CLI to clone this template directly to your machine:

npx create-payload-app@latest my-project -t website

Method 3

Use the git CLI to clone this template directly to your machine:

git clone -n --depth=1 --filter=tree:0 https://github.com/payloadcms/payload my-project && cd my-project && git sparse-checkout set --no-cone templates/website && git checkout && rm -rf .git && git init && git add . && git mv -f templates/website/{.,}* . && git add . && git commit -m "Initial commit"

Development

  1. First clone the repo if you have not done so already
  2. cd my-project && cp .env.example .env to copy the example environment variables
  3. yarn && yarn dev to install dependencies and start the dev server
  4. open http://localhost:3000 to open the app in your browser

That's it! Changes made in ./src will be reflected in your app. Follow the on-screen instructions to login and create your first admin user. Then check out Production once you're ready to build and serve your app, and Deployment when you're ready to go live.

How it works

The Payload config is tailored specifically to the needs of most websites. It is pre-configured in the following ways:

Collections

See the Collections docs for details on how to extend this functionality.

Globals

See the Globals docs for details on how to extend this functionality.

Access control

Basic role-based access control is setup to determine what users can and cannot do based on their roles, which are:

This applies to each collection in the following ways:

For more details on how to extend this functionality, see the Payload Access Control docs.

Premium Content

Posts can optionally restrict access to content or digital assets behind authentication. This will ensure that only members of your site can access the full post data and its resources. To do this, a premiumContent field is added to the posts collection with read access control set to check for an authenticated user on the request. Every time a user requests a post, this will only return data to those who have access to it:

{
  name: 'premiumContent',
  label: 'Premium Content',
  type: 'blocks',
  access: {
    read: isLoggedIn,
  },
  fields: [
    // content
  ]
}

Comments

Users can leave comments on posts for editors to review and approve before they are published to the website. To do this, a comments collection is added with drafts set to true so that all comments are saved as drafts and inaccessible until an admin approves them. Each comment references a single user and a doc for cross reference. To leave a comment you must be logged-in, and to publish a comment you must has the role admin.

Layout Builder

Create unique page, post, or project layouts for any type of content using a powerful layout builder. This template comes pre-configured with the following layout building blocks:

Each block is fully designed and built into the front-end website that comes with this template. See Website for more details.

Draft Preview

All posts, projects, and pages are draft-enabled so you can preview them before publishing them to your website. To do this, these collections use Versions with drafts set to true. This means that when you create a new post, project, or page, it will be saved as a draft and will not be visible on your website until you publish it. This also means that you can preview your draft before publishing it to your website. To do this, we automatically format a custom URL which redirects to your front-end to securely fetch the draft version of your content.

Since the front-end of this template is statically generated, this also means that pages, posts, and projects will need to be regenerated as changes are made to published documents. To do this, we use an afterChange hook to regenerate the front-end when a document has changed and its _status is published.

For more details on how to extend this functionality, see the official Draft Preview Example.

SEO

This template comes pre-configured with the official Payload SEO Plugin for complete SEO control from the admin panel. All SEO data is fully integrated into the front-end website that comes with this template. See Website for more details.

Redirects

If you are migrating an existing site or moving content to a new URL, you can use the redirects collection to create a proper redirect from old URLs to new ones. This will ensure that proper request status codes are returned to search engines and that your users are not left with a broken link. This template comes pre-configured with the official Payload Redirects Plugin for complete redirect control from the admin panel. All redirects are fully integrated into the front-end website that comes with this template. See Website for more details.

Website

This template includes a beautifully designed, production-ready front-end built with the Next.js App Router, served right alongside your Payload app in a single Express server. This makes is so that you can deploy both apps simultaneously and host them together. If you prefer a different front-end framework, this pattern works for any framework that supports a custom server. If you prefer to host your website separately from Payload, you can easily Eject the front-end out from this template to swap in your own, or to use it as a standalone CMS. For more details, see the official Custom Server Example.

Core features:

Cache

Although Next.js includes a robust set of caching strategies out of the box, Payload Cloud proxies and caches all files through Cloudflare using the Official Cloud Plugin. This means that Next.js caching is not needed and is disabled by default. If you are hosting your app outside of Payload Cloud, you can easily reenable the Next.js caching mechanisms by removing the no-store directive from all fetch requests in ./src/app/_api and then removing all instances of export const dynamic = 'force-dynamic' from pages files, such as ./src/app/(pages)/[slug]/page.tsx. For more details, see the official Next.js Caching Docs.

Eject

If you prefer another front-end framework or would like to use Payload as a standalone CMS, you can easily eject the front-end from this template. To eject, simply run yarn eject. This will uninstall all Next.js related dependencies and delete all files and folders related to the Next.js front-end. It also removes all custom routing from your server.ts file and updates your eslintrc.js.

Note: Your eject script may not work as expected if you've made significant modifications to your project. If you run into any issues, compare your project's dependencies and file structure with this template. See ./src/eject for full details.

For more details on how setup a custom server, see the official Custom Server Example.

Development

To spin up this example locally, follow the Quick Start. Then Seed the database with a few pages, posts, and projects.

Docker

Alternatively, you can use Docker to spin up this template locally. To do so, follow these steps:

  1. Follow steps 1 and 2 from above, the docker-compose file will automatically use the .env file in your project root
  2. Next run docker-compose up
  3. Follow steps 4 and 5 from above to login and create your first admin user

That's it! The Docker instance will help you get up and running quickly while also standardizing the development environment across your teams.

Seed

To seed the database with a few pages, posts, and projects you can run yarn seed. This template also comes with a GET /api/seed endpoint you can use to seed the database from the admin panel.

The seed script will also create two users for demonstration purposes only:

  1. Demo Author
    • Email: demo-author@payloadcms.com
    • Password: password
    • Role: admin
  2. Demo User
    • Email: demo-user@payloadcms.com
    • Password: password
    • Role: user

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. 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.
  2. Finally run yarn serve or npm run serve to run Node in production and serve Payload from the ./build directory.
  3. When you're ready to go live, see Deployment for more details.

Deployment

Before deploying your app, you need to:

  1. Ensure your app builds and serves in production. See Production for more details.

The easiest way to deploy your project is to use Payload Cloud, 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 for full details.

Questions

If you have any issues or questions, reach out to us on Discord or start a GitHub discussion.