benloeffel/old.md

Last active April 14, 2024 16:57

Star () You must be signed in to star a gist
Fork () You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/benloeffel/3a73896031ba9c27fa7050619ca9db13.js"></script>
Save benloeffel/3a73896031ba9c27fa7050619ca9db13 to your computer and use it in GitHub Desktop.

Download ZIP

PayloadCMS, MongoDB, GitHub and Vercel Setup

Raw

readme.md

Modern Web Application Setup Guide (Next.js & PayloadCMS on GitHub and Vercel)

Welcome to your go-to guide for setting up a modern web application using Next.js and PayloadCMS, hosted on GitHub and deployed via Vercel. Let's begin by establishing the backbone of your application—a MongoDB database. Follow these detailed steps to ensure everything is set up correctly.

Create a MongoDB Database

Start by Logging into MongoDB
- Navigate to MongoDB Account Login and sign in with your credentials.
Create a New Project
- After logging in, select the option to create a new project.
Name Your Project
- Assign a meaningful name to your project, relevant to its purpose.
Tag Your Project
- Add a tag to help identify the environment type. Use key: environment and value: production.
Proceed to Team Setup
- Click "Next" to proceed, then add a team member and set their permissions, or select an existing member.
Create the Project
- Click on "Create Project."
Deploy a Database Cluster
- Once your project is ready, click on "Create" to deploy a new database cluster.
Select Cluster Type
- Choose the free "M0" cluster option for a cost-effective start.
Name Your Cluster
- Name your cluster appropriately, for example, prod-example-app.
Configure Your Cluster
- Ensure "Add a sample dataset" is unchecked.
- Choose your cloud provider and region, such as AWS in Frankfurt.
Tag Your Deployment
- Again, tag your deployment with key: environment and value: production.
Launch Your Cluster
- Click on "Create Deployment" to finalize the setup.
Set Up Database Access
- Create a database username, e.g., example-user, and auto-generate a secure password. Remember to store these credentials securely in your password manager.
Establish Connection
- Once your database is ready, click "Connect," then select "Drivers" to get the connection string.
- Store the connection string securely for future use. Example format:
```
mongodb+srv://example-user:<password>@prod-example-app.1xxerno.mongodb.net/?retryWrites=true&w&maj...
```
Configure Network Access
- Set network access to "Anywhere" to accommodate the dynamic IP address nature of Vercel deployments.

By following these steps, you're now well on your way to having a robust MongoDB database setup for your application. Next, we'll dive into setting up your project repository on GitHub and deploying via Vercel. Stay tuned, and keep the excitement going!

Create a GitHub Project

Welcome to the next step in setting up your modern web application: creating a GitHub repository. Follow these steps to ensure your project is up and ready for version control and collaboration.

Log Into GitHub
- Start by navigating to GitHub and logging in with your credentials.
Create a New Repository
- Once logged in, click on the "New repository" button to start the creation process.
Name Your Repository
- Provide a meaningful name for your repository, such as example-app, to reflect the nature of your project.
Set Repository Visibility
- Choose to make the repository private if you wish to restrict access to authorized users only.
Create the Repository
- Click on "Create repository" to finalize the setup.
Copy Repository SSH String
- After creating your repository, GitHub will display a variety of connection strings. Copy the SSH connection string, which looks like:
```
[email protected]:username/example-app.git
```

This sets the foundation for your project's version control using GitHub. With your repository ready, you can now proceed to push your local code and collaborate with your team effectively. Keep up the great work as you move forward with your project development!

Initial Project Setup

Now that your GitHub repository is ready, let's move on to setting up the project on your local machine and initializing your PayloadCMS application. Follow these steps carefully to ensure a smooth setup.

Create and Navigate to a New Directory
- Open your terminal and run:
```
mkdir example-directory && cd example-directory
```
Clone the Repository
- Clone your newly created GitHub repository:
```
git clone [email protected]:benloeffel/example.git
```
Reorganize the Project Directory
- Navigate into the cloned directory, move all files up one level, and remove the now empty directory:
```
cd example && mv .* ../ && cd .. && rmdir example
```
Create a PayloadCMS Application
- Start the PayloadCMS application setup using:
```
npx create-payload-app@beta
```
Name Your PayloadCMS Project
- When prompted, provide a project name, for instance:
```
example
```
Select a Project Template
- Choose a suitable template for your project, such as:
```
blank-3.0
```
Choose a Database
- Select the type of database you wish to use (MongoDB or Postgres).
Enter Your MongoDB Connection String
- Provide the MongoDB connection string you obtained earlier:
```
Enter your MongoDB connection string and press enter
```
Install Dependencies
- Wait for PayloadCMS to install all necessary dependencies.
Finalize Project Directory Structure
- Again, move all files from the subdirectory to the main directory and remove the empty folder:
```
cd example && mv * ../ && mv .* ../ && cd .. && rmdir example
```
Run Your Application
- Start your application using:
```
yarn dev
```
- Alternatively, follow any specific instructions in your project's README.md.
Initial Git Commit
- After verifying everything is set up and running correctly, make your initial commit and push to GitHub:
```
git add . && git commit -m "initial commit" && git push
```

Congratulations on setting up your project! You're now ready to develop and expand your application further.

Setup Conventional Commits

Ensuring that your project’s commit messages are consistent and standardized is crucial for maintaining the project’s history clarity and aiding in automated tools like semantic release. We'll set up CommitLint to enforce Conventional Commits standards.

Install CommitLint CLI
- Add the CommitLint CLI tool to your development environment:
```
yarn add -D @commitlint/cli
```
Install CommitLint Conventional Ruleset
- Also, install the conventional configuration for CommitLint to use the widely accepted ruleset:
```
yarn add -D @commitlint/config-conventional
```
Create a CommitLint Configuration File
- Create a new configuration file for CommitLint:
```
touch .commitlintrc && code .commitlintrc
```
- This command will create the file and open it in Visual Studio Code for editing.

Configure CommitLint

Copy the following JSON configuration into the .commitlintrc file you just opened:

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "body-max-line-length": [1, "always", 200]
  }
}

Commit Your Changes
- Use CommitLint to commit these new configurations to your repository:
```
git add . && git commit -m "chore: add commitlint" && git push
```

By following these steps, you'll have set up a robust system for managing your commit messages, ensuring they are informative and structured, which is beneficial for automated processes and maintaining a clear project history.

Setup Commitizen

Commitizen is a tool that prompts you to fill out any required commit fields at commit time, streamlining your commit process and helping you avoid common formatting issues. Here’s how to set it up:

Install Commitizen
- Add Commitizen to your project to streamline creating conventional commits:
```
yarn add -D commitizen
```
Initialize Commitizen
- Set up Commitizen with a conventional changelog ruleset:
```
npx commitizen init cz-conventional-changelog
```
- This command modifies your package.json to include Commitizen configuration:
```
"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}
```
Clean Up Package Files
- Remove the automatically created package-lock.json file, as we are using yarn.lock:
```
rm package-lock.json
```
Make Your First Commit Using Commitizen
- Run Commitizen to start the commit process:
```
npx cz
```
- Follow the prompts to craft a commit message:
  - Choose the type of change: chore
  - Skip the scope by pressing enter directly
  - For the description, enter: add commitizen
  - Skip the long description by pressing enter again
  - Answer "N" for the breaking changes prompt
  - Answer "N" for the affects open issues prompt
Push Your Changes
- Finalize your changes by pushing them to your repository:
```
git push
```

By integrating Commitizen, you ensure that every commit message is consistent and informative, which is essential for managing releases and understanding project history. This setup encourages all team members to adhere to a shared commit message format.

Setup Husky to Use Commitlint in Pre-Commit Hook

Husky is a tool that allows you to easily manage and execute Git hooks, ensuring that your commits, pushes, and more adhere to your project standards. Here's how to configure Husky to use Commitlint to check commit messages:

Install Husky and Initialize
- Begin by installing Husky and initializing it in your project:
```
npx husky-init && yarn install
```
Clean Up Default Hooks
- Husky creates a sample pre-commit hook that we won't need. Remove this file:
```
rm .husky/pre-commit
```
Create Commit Message Hook
- Set up a new commit-msg hook to run Commitlint each time a commit message is entered:
```
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'
```
- This command creates a .husky/commit-msg file with the following contents:
```
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no-install commitlint --edit "$1"
```
Test the Configuration
- Ensure that everything is set up correctly by making a commit:
```
git add . && git commit -m "chore: add husky" && git push
```

This setup will trigger Commitlint to verify your commit messages against the conventional commit format every time you attempt to commit, helping prevent non-compliant messages from entering your repository. This automation significantly enhances the consistency and quality of your project's commit history.

Install Semantic-Release

semantic-release automates the version management and package publishing process, which enhances the efficiency of releasing new versions. Here's how to set it up in your project.

Install Semantic-Release
- Add semantic-release to your project:
```
yarn add -D semantic-release
```
Install and Setup Semantic-Release CLI
- Install the CLI tool and run the setup:
```
yarn add -D semantic-release-cli && npx semantic-release-cli setup
```
Configuration Prompts
- Follow the setup prompts:
  - Repository privacy: Type Y for a private repository and press enter.
  - NPM registry: Accept the default by pressing enter.
  - NPM username: Enter your npm username and press enter.
  - NPM password: Enter your password and press enter.
  - Two-factor authentication code: Enter your NPM 2FA code and press enter.
GitHub Token
- Generate a new GitHub personal access token by visiting GitHub Token Page.
  - Ensure permissions are set only for "repo".
  - Set an expiration date, e.g., 30 days. Remember, expired tokens will stop semantic-release from working which can lead to delays and confusion. Document the token's expiration clearly or set a reminder to renew it.
  - After creating the token, copy it and paste it into the semantic-release CLI setup.
Configure CI and Secrets
- Select GitHub Actions as the CI to use and press Enter.
- Verify that the NPM_TOKEN is set correctly in the repository secrets on GitHub:
```
https://github.com/benloeffel/example/settings/secrets/actions
```
Set Permissions for GitHub Token
- When creating the token, choose the following permissions:
```
Contents: read/write, Issues: read/write, Metadata: read
```
NPM Login and Two-Factor Authentication Setup
- Log in to npm with the legacy auth type:
```
npm login --auth-type=legacy
```
- Enable two-factor authentication (2FA) in auth-only mode if it isn't already set up:
```
npm profile enable-2fa auth-only
```
- If you encounter any errors and you have previously set up 2FA, try resetting it:
  - Disable 2FA:
```
npm profile disable-2fa
```
  - Re-enable it:
```
npm profile enable-2fa auth-only
```

By completing these steps, you've successfully automated your release process, which will help in managing releases efficiently and transparently. Make sure to keep your documentation up-to-date with these configurations to aid your team or contributors in understanding the setup.

Vercel Setup Completion

Completing your Vercel setup involves linking your GitHub repository with Vercel using secrets for secure interactions and custom deployment settings. Follow these steps to integrate everything smoothly.

Configure GitHub Secrets for Vercel

Retrieve Vercel Access Token
- Generate an access token in Vercel to allow GitHub to securely interact with your Vercel account. Follow the instructions here: Create Vercel API Access Token.
Install and Login to Vercel CLI
- Install the Vercel CLI if not already installed, and log in:
```
npm install -g vercel
vercel login
```
Link Your Project with Vercel
- Navigate to your project directory and link your project to Vercel:
```
vercel link
```
- This command creates a .vercel directory in your project with a project.json file containing project and organization IDs.
Extract Project and Organization IDs
- Open the project.json in the .vercel directory and note the projectId and orgId.
Add Secrets to GitHub
- Go to your GitHub repository’s settings, navigate to 'Secrets', and add the following:
  - VERCEL_TOKEN: Your Vercel access token.
  - VERCEL_ORG_ID: The organization ID from Vercel.
  - VERCEL_PROJECT_ID: The project ID from Vercel.

Setup Deployment Configurations

To manage deployments effectively, especially to differentiate between production and preview deployments, it's essential to configure your deployment triggers and settings.

Add Vercel Configuration in Repository
- To prevent double deployment triggers (once from Vercel’s GitHub integration and once from your CI pipeline), create or update a vercel.json file in your repository with the following content:
```
{
  "git": {
    "deploymentEnabled": {
      "main": false
    }
  }
}
```
- This configuration disables direct Vercel deployments on pushes to the main branch, allowing your CI process to handle it instead.

By completing these steps, your project is fully integrated with Vercel, leveraging GitHub Actions for CI/CD while keeping Vercel for actual deployments. This setup ensures that all changes pushed to your repository are automatically built and deployed in a secure and controlled manner.

Your project is now set up for continuous integration and delivery with Vercel and GitHub, supporting efficient development workflows and robust deployment strategies.

Setup CI (GitHub Actions)

Setting up a Continuous Integration (CI) pipeline with GitHub Actions is a great way to automate your release process. Here’s how to set up a CI pipeline for automatic semantic releases:

Create GitHub Actions Workflow File
- Run these commands in your terminal to create the necessary directories and workflow file:
```
mkdir -p .github/workflows && touch .github/workflows/preview.yml && touch .github/workflows/production.yml
```

Configure GitHub Actions Workflow

Paste the following configuration into your .github/workflows/production.yml file:

name: GitHub Actions Vercel Production Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
on:
  push:
    branches:
      - main
  permissions:
  contents: read
  jobs:
  deploy-production:
  name: Production Deployment
  runs-on: ubuntu-latest
  permissions:
  contents: write # to be able to publish a GitHub release
  issues: write # to be able to comment on released issues
  pull-requests: write # to be able to comment on released pull requests
  id-token: write # to enable use of OIDC for npm provenance
  steps: - name: Checkout
  uses: actions/checkout@v3
  with:
  fetch-depth: 0
        - name: Setup Node.js
          uses: actions/setup-node@v3
          with:
            node-version: 'lts/*'
            cache: 'yarn'
        - name: Clear Yarn Cache
          run: yarn cache clean
        - name: Install dependencies
          run: yarn install --frozen-lockfile
        - name: Create Release
          env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
            NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          run: npx semantic-release
        - name: Install Vercel CLI
          run: yarn global add vercel@latest
        - name: Pull Vercel Environment Information
          run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
        - name: Build Project Artifacts
          run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
        - name: Deploy Project Artifacts to Vercel
          run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

and preview.yml

name: GitHub Actions Vercel Preview Deployment
env:
  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
on:
  push:
    branches-ignore:
      - main
permissions:
  contents: read
jobs:
  deploy-preview:
    name: Preview Deployment
    runs-on: ubuntu-latest
    permissions:
      contents: write # to be able to publish a GitHub release
      issues: write # to be able to comment on released issues
      pull-requests: write # to be able to comment on released pull requests
      id-token: write # to enable use of OIDC for npm provenance
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "lts/*"
          cache: "yarn"
      - name: Clear Yarn Cache
        run: yarn cache clean
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Install Vercel CLI
        run: yarn global add vercel@latest
      - name: Pull Vercel Environment Information
        run: vercel pull --yes --environment=preview --token=${{ secrets.VERCEL_TOKEN }}
      - name: Build Project Artifacts
        run: vercel build --token=${{ secrets.VERCEL_TOKEN }}
      - name: Deploy Project Artifacts to Vercel
        run: vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}

Dry-run the CI
- Copy the release workflow file for a dry run:
```
cp .github/workflows/release.yml .github/workflows/release-dry-run.yml
```
- Modify the dry run file by changing the name to Release Dry-run and adding --dry-run to the semantic-release command.
Prepare the package.json
- Add "private": true, to your package.json to prevent accidental publishing to npm.
- Include the following configuration to disable npm publishing in the package.json:
```
"release": {
  "plugins": [
    [
      "@semantic-release/npm",
      {
        "npmPublish": false
      }
    ]
  ]
}
```
- If necessary, regenerate your yarn.lock by removing the existing one and running yarn install again.
Push the Setup to GitHub
- Use Commitizen to commit your changes:
```
npx cz
```
- Choose "chore" and enter the message: "add semantic-release configuration".
Manually Run the Dry-run Workflow
- Go to https://github.com/benloeffel/example/actions and manually trigger the dry-run workflow to ensure everything is configured correctly.

Setup Application Components and Styles

This part of the setup involves creating the necessary components and styles for your application. These files will form the basis of your app's structure and appearance.

Create Application Files

Start by creating directories and initial React component files:

mkdir -p src/app/\(app\) && cd src/app/\(app\) && touch layout.tsx page.tsx globals.scss

Add Layout Component

Open layout.tsx and paste the following React component code. This component will serve as the basic layout for your application:

import React from "react";
import "./globals.scss";

/* Our app sits here to not cause any conflicts with payload's root layout */
const Layout: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return (
    <html>
      <body>
        <main>{children}</main>
      </body>
    </html>
  );
};

export default Layout;

Add Page Component

Open page.tsx and input the following code. This page component includes some demo content and links, which illustrate how to use PayloadCMS with Next.js:

import Example from "@/components/Example";
import Link from "next/link";
import React from "react";

const Page = () => {
  return (
    <article className={["container"].filter(Boolean).join(" ")}>
      <h1>
        Payload 3.0 <span className="rainbow">BETA</span>!
      </h1>
      <p>
        This BETA is rapidly evolving, you can report any bugs against{" "}
        <a
          href="https://github.com/payloadcms/payload-3.0-demo/issues"
          target="_blank"
        >
          the repo
        </a>{" "}
        or in the{" "}
        <a
          href="https://discord.com/channels/967097582721572934/1215659716538273832"
          target="_blank"
        >
          dedicated channel in Discord
        </a>
        .
      </p>

      <p>
        <strong>
          Payload is running at <Link href="/admin">/admin</Link>
        </strong>
      </p>

      <p>
        <Link href="/my-route" target="_blank">
          /my-route
        </Link>{" "}
        contains an example of a custom route running the Local API.
      </p>

      <p>You can use the Local API in your server components like this:</p>
      <pre>
        <code>
          {`import { getPayload } from 'payload'
import configPromise from "@payload-config";
const payload = await getPayload({ config: configPromise })

const data = await payload.find({
  collection: 'posts',
})`}
        </code>
      </pre>
    </article>
  );
};

export default Page;

Add Global Styles

Now, add the following CSS to globals.scss to style your application. These styles include a custom rainbow text effect:

html,
body {
  font-family: "Roboto", "Inter", sans-serif;
}

.container {
  max-width: 37.5rem;
  padding: 0 2rem;
  margin-left: auto;
  margin-right: auto;
}

h1 {
  font-size: 4rem;
}

.rainbow {
  font-family: monospace;
  letter-spacing: 5px;
  background: linear-gradient(
    to right,
    #6666ff,
    #0099ff,
    #00ff00,
    #ff3399,
    #6666ff
  );
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
  animation: rainbow_animation 6s ease-in-out infinite;
  background-size: 400% 100%;
}

@keyframes rainbow_animation {
  0%,
  100% {
    background-position: 0 0;
  }

  50% {
    background-position: 100% 0;
  }
}

Start the Application
- Navigate back to the root directory and start the application with yarn dev. Ensure it spins up without issues.
Commit and Release
- Once your app is functional and the files are created, commit them using npx cz. Choose "feat" as the type and add "add initial layout and page file" as

Add Release Notes to Documentation

Automating the creation of release notes and changelogs can significantly improve the maintainability and transparency of your project. Here's how to configure your project to automatically generate and update a changelog with each release:

Install Necessary Packages
- Add the required Semantic Release plugins to your project:
```
yarn add -D @semantic-release/changelog @semantic-release/git
```

Configure Semantic Release for Changelogs

Update your package.json to include the changelog plugin configurations. Add the following to your existing Semantic Release configuration:

"release": {
  "plugins": [
    "@semantic-release/github",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/npm",
      {
        "npmPublish": false
      }
    ],
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    [
      "@semantic-release/git",
      {
        "assets": ["CHANGELOG.md"]
      }
    ]
  ]
}

Commit Changes with a Breaking Change Note
- Commit these changes to your repository. Use a semantic commit message that includes a breaking change note to ensure a new release is triggered:
```
git add .
npx cz
```
- When prompted by Commitizen, select "feat" for the type of change, and use the message "add changelog automation". Be sure to indicate that this is a breaking change when prompted.
Run the Release Workflow
- Push your changes and navigate to your GitHub Actions page to run the release workflow:
```
git push
```
- Go to https://github.com/benloeffel/example/actions and manually trigger the release workflow if necessary.
Verify the Release
- Confirm that the release was successful and that the CHANGELOG.md was updated and included in the release notes on GitHub.

By following these steps, your project now automatically generates a changelog with each release, documenting all changes in a standardized format. This not only saves time but also provides clear documentation for users and contributors about what changes have been made in each version of the project.

Import Project into Vercel

Deploying your project with Vercel ensures that your application is up and running on a robust, scalable cloud platform. Here's how to import and deploy your project on Vercel:

Log In to Vercel
- Navigate to Vercel's website and log in with your account credentials.
Import Project from GitHub
- Click on the "New Project" button and choose to import a project from GitHub. Follow the prompts to locate and select your repository.
Configure Project Settings
- Give your project a name that corresponds with its purpose or identity within Vercel.
Set Environment Variables
- Enter any necessary environment variables required for your project. These could include API keys, database URLs, or custom configuration values that should not be hard-coded in your project code.
Deploy Your Project
- Click the "Deploy" button to start the deployment process. Vercel will automatically build and deploy your project based on the settings defined in your package.json or other configuration files.
Monitor Deployment
- Wait for the deployment to complete. You can monitor the progress directly on the Vercel dashboard where the status of your build and deployment will be displayed.
Verify Deployment
- Once the deployment is complete, check the provided Vercel URL to ensure everything is working as expected. Test the deployed application to confirm that all functionalities are operational.

By completing these steps, your project is now live on Vercel! You're ready to share your application with the world or move forward to additional steps like custom domain configuration if necessary.

Setup Custom Domain

Customizing the domain for your project adds professionalism and branding. Vercel provides multiple options for linking your custom domain to your deployed projects. Here's how you can set it up:

Options for Custom Domain Setup

Purchase Domain via Vercel
- If you don't already own a domain, you can purchase one directly from Vercel. This integration allows for seamless management and configuration directly within your Vercel dashboard.
Transfer Domain to Vercel
- If your domain is registered with another provider and you prefer to manage everything in one place, you can transfer it to Vercel. This method also simplifies DNS management and ensures better compatibility with Vercel's features.
Point Domain to Vercel Servers via A Record
- If you prefer to keep your domain registered with an external provider, you can point it to Vercel's servers using A records. This method is less flexible than using Vercel's nameservers because it doesn’t support root domains with CNAME records, which are required for some of Vercel’s functionalities.
Point Domain to Vercel's Nameservers
- Vercel recommends using their nameservers. This approach not only simplifies setup but also enhances features like automatic SSL and preview deployments. Point your domain's DNS settings to Vercel’s nameservers from your domain registrar’s control panel.

Implementation Steps

Log In to Vercel and Navigate to Your Project
- Go to your project’s dashboard on Vercel.
Add Your Custom Domain
- Navigate to the 'Settings' tab, find the 'Domains' section, and click 'Add'.
- Enter your domain name and follow the on-screen instructions to verify ownership.
Configure DNS Settings
- Depending on the option you chose:
  - For nameserver pointing, change your domain's nameservers to the ones provided by Vercel.
  - For A record pointing, add the A records as specified by Vercel during the setup.
Verify Domain Configuration
- Once configured, Vercel automatically checks and verifies the DNS settings. This process might take some time as DNS changes need to propagate.
SSL and Deployment
- Vercel automatically provisions an SSL certificate for your domain and makes your site accessible via HTTPS.

Additional Notes

Preview Deployments
- Vercel’s nameserver option supports preview deployments, which is ideal for testing changes in a production-like environment before going live. If using A records and you need preview deployments, follow the guide here: Preview Deployment Suffix without Vercel Nameservers.

By setting up your custom domain on Vercel, you ensure that your project maintains a professional appearance and is accessible under your brand. Choose the method that best suits your operational style and needs.

Raw

old.md

Modern Web Application Guide (Next.js & PayloadCMS on GitHub and Vercel)

Create a MongoDB database

Go to https://account.mongodb.com/account/login and login
Once logged in, create a new project.
Give the project a name
Give the project a tag like key environment and value production
Click on "Next"
Add a amember and set permissions or select an existing member.
Proceed with clicking on "Create Project"
Once the project has been created, click on the "Create" button to create a deployment
Select the free "M0" database cluster
Give the cluster a suitable name such as prod-example-app
Uncheck "Add a sample dataset"
Choose the provider like AWS and Region like Frankfurt
Give the project a tag like key environment and value production
Click on Create Deployment Button
Create a database username like example-user and auto generate a secure password. Save these credentials in your password manager.
Once the database deployment has been created click on the "connect" button followed by "Drivers"
Copy the connection string and store it somewhere for later: mongodb+srv://example-user:<password>@prod-example-app.1xxerno.mongodb.net/?retryWrites=true&w=majority&appName=prod-example-app
Network access needs to be open so Anywhere since Vercel uses a Dynamic IP address.

Create a GitHub project

Login at [https://github.com/]
Click on "New repository"
Provide a repository name such as "example-app"
Make the project private
Click on "Create repository"
Copy the repositories ssh string like: [email protected]:benloeffel/example.git

Initial setup

Create a new directory mkdir example-directory && cd example-directory
Type git clone [email protected]:benloeffel/example.git .
Create a payloadcms application with npx create-payload-app@beta
Provide a project name like "example"
Choose a project template like "blank-3.0"
Select a database (MongoDB or Postgres).
Enter your MongoDB connection string of earlier and press enter
Wait for the dependencies to install
Type cd example && mv * ../ && mv .* ../ && cd .. && rmdir example
Run the application with yarn dev or follow directions in README.md
If everything is working, run git add . && git commit -m "initial commit" && git push to run the initial commit.

Setup Conventional Commits

Install CommitLint CLI yarn add -D @commitlint/cli
Install CommitLint Conventional Rulesetyarn add -D @commitlint/config-conventional
Create a CommitLint configuration file by running touch .commitlintrc && code .commitlintrc
Paste the following configuration:

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "body-max-line-length": [1, "always", 200]
  }
}

Commit with Commitlint git add . && git commit -m "chore: add commitlint" && git push

Setup Commitizen

Install commitizen yarn add -D commitizen
Install commitizen ruleset with npx commitizen init cz-conventional-changelog, this will add this section to our package.json file:

"config": {
  "commitizen": {
    "path": "./node_modules/cz-conventional-changelog"
  }
}

Remove the automatically created package-lock.json that we don't need since we use yarn.lock
. Create a commit with npx cz
Choose "chore"
Skip the optional scope
Write "add commitizen" and hit enter
Skip the long description
Type "N" and press enter to the breaking changes question
Type "N" and press enter to the affects open issues question
Finally, push the changes with "git push"

Setup Husky to use Commitlint in Pre-Commit Hook

Install husky and initialize it with npx husky-init && yarn install
This create a pre-commit file we can delete as we're not using it
Now create our own pre-commit file with npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
This will create the file .husky/commit-msg with the following contents:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx --no -- commitlint --edit "$1"

Let's test out if it works by running git add . && git commit -m "chore: add husky" && git push

Install semantic-release

Install semantic-release yarn add -D semantic-release
Install semantic-release cli and set it up yarn add -D semantic-release-cli && npx semantic-release-cli setup
Choose if the repository is private, in this case "Y" and press enter.
What is your npm registry, accept the default by pressing enter
What is your username, enter your npm username and press enter.
What is your passwrod, enter the password and press enter.
What is your NPM two-factor authentication code, enter the code and press enter.
Visit
Check that permissions are only enabled for "repo".
Set an expiration date of for example 30 days but note:

For security reasons, the token should have an expiration date. But be aware that it can be confusing and frustrating, even expensive, when semantic-release suddenly stops working. It’s not so easy to dig out the reason when it’s the token being expired. Note this well in your project docs so others won’t need to spend too much time searching for the cause. Even better, create a recurring reminder to renew the token in time.
Press generate token and copy the token ghp_lkNYvNHEOHb43QmkXXXXXXXXXXXXXXXXXXXX and pase it into the semantic-releases cli
Select the CI to use, in our case that's GitHub Actions and Press Enter
On GitHub check that the NPM_TOKEN is not shown in the repository secrets: https://github.com/benloeffel/example/settings/secrets/actions
Set the following permissions for the fine-grained personal access tokens: Contents: read/write, Issues: read/write, Metadata: read
Click on create token, and copy the token: github_pat_11ADXYIGI0cXZUv5VrAxl2_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX and pase it into the cli
Login to npm using npm login --auth-type=legacy, and provide the username, password and one time password
Since semantic-releases only supports the auth-only mode with 2FA, we need to enable it using: npm profile enable-2fa auth-only
If you experience an error here and you already have set up 2FA for your npm account, set up 2FA again from scratch may help. Unset it first: npm profile disable-2fa and then enabling it again with npm profile enable-2fa auth-only

Setup CI (Github Actions)

Create a release.yml with mkdir .github && mkdir .github/workflows && touch .github/workflows/production.yml && touch .github/workflows/preview.yml
In the file pase the following configuration for GitHub Actions:

name: Release
on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write # to be able to publish a GitHub release
      issues: write # to be able to comment on released issues
      pull-requests: write # to be able to comment on released pull requests
      id-token: write # to enable use of OIDC for npm provenance
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 'lts/*'
      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Audit dependencies for security vulnerabilities
        run: yarn audit
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

Let's dry-run the ci by first copying the file cp .github/workflows/release.yml .github/workflows/release-dry-run.yml
In the dry-run file, replace the name: Release Dry-run and the run: npx semantic-release --dry-run
Add "private": true, to the package.json
To ensure that we're not releasing to npm add the following to the package.json, it may be required to remove the yarn.lock and create it again with yarn install

"release": {
  //...
  "plugins": [
    [
      "@semantic-release/npm",
      {
        "npmPublish": false
      }
    ]
  ]
}

Push the changes to main. npx cz, select "chore" and message: "add semantic-releases"
Now navigate to https://github.com/benloeffel/example/actions and manually run our dry-run workflow. If everything worked fine, we can create the first release.
Before we release, let's create our app mkdir src/app/$app$ && cd src/app/$app$ && touch layout.tsx page.tsx globals.scss
Add this to the layout.tsx

import React from 'react'
import './globals.scss'

/* Our app sits here to not cause any conflicts with payload's root layout  */
const Layout: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return (
    <html>
      <body>
        <main>{children}</main>
      </body>
    </html>
  )
}

export default Layout

Add this to the page.tsx

import Example from '@/components/Example'
import Link from 'next/link'
import React from 'react'

const Page = () => {
  return (
    <article className={['container'].filter(Boolean).join(' ')}>
      <h1>
        Payload 3.0 <span className="rainbow">BETA</span>!
      </h1>
      <p>
        This BETA is rapidly evolving, you can report any bugs against{' '}
        <a href="https://github.com/payloadcms/payload-3.0-demo/issues" target="_blank">
          the repo
        </a>{' '}
        or in the{' '}
        <a
          href="https://discord.com/channels/967097582721572934/1215659716538273832"
          target="_blank"
        >
          dedicated channel in Discord
        </a>
        .
      </p>

      <p>
        <strong>
          Payload is running at <Link href="/admin">/admin</Link>
        </strong>
      </p>

      <p>
        <Link href="/my-route" target="_blank">
          /my-route
        </Link>{' '}
        contains an example of a custom route running the Local API.
      </p>

      <p>You can use the Local API in your server components like this:</p>
      <pre>
        <code>
          {`import { getPayload } from 'payload'
import configPromise from "@payload-config";
const payload = await getPayload({ config: configPromise })

const data = await payload.find({
  collection: 'posts',
})`}
        </code>
      </pre>
    </article>
  )
}

export default Page

Add this to the globals.scss

html,
body {
  font-family: 'Roboto', 'Inter', sans-serif;
}

.container {
  max-width: 37.5rem;
  padding: 0 2rem;
  margin-left: auto;
  margin-right: auto;
}

h1 {
  font-size: 4rem;
}

.rainbow {
  font-family: monospace;
  letter-spacing: 5px;
  background: linear-gradient(to right, #6666ff, #0099ff, #00ff00, #ff3399, #6666ff);
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
  animation: rainbow_animation 6s ease-in-out infinite;
  background-size: 400% 100%;
}

@keyframes rainbow_animation {
  0%,
  100% {
    background-position: 0 0;
  }

  50% {
    background-position: 100% 0;
  }
}

Start the application with yarn dev, if it spins up without issues you can commit with npx cz and choose "feat" with the text "add initial layout and page file. You need to mark this as a breaking change otherwise there won't be a release, simply a tag.
Once that's done we can manually execute out release job and watch the magic happen.

Import Project into Vercel

Login to Vercel
Import Project via Github and select the project to import
Give the project a name
Pase in the environment variables
Press deploy
Wait for the deployment to complete
Once the deployment is complete and everything is working correctly we can move onto the domain part.

Setup Custom Domain

Setup of a custom domain we can choose if we want to:

Purchase the domain directly via Vercel
Transfer the domain from external to Vercel
Leave the domain external and point to Vercel Servers via A record
Leave the domain external and point to Vercels Nameservers

It's important to note that Vercel prefers the nameserver approach so it's easy to create preview deployments. If thats not possible, apparently there is a workaround: https://vercel.com/guides/preview-deployment-suffix-without-vercel-nameservers

VERCEL SETUP

Finally, let’s add the required values from Vercel as secrets in GitHub:

Retrieve your Vercel Access Token
Install the Vercel CLI and run vercel login
Inside your folder, run vercel link to create a new Vercel project
Inside the generated .vercel folder, save the projectId and orgId from the project.json
Inside GitHub, add VERCEL_TOKEN, VERCEL_ORG_ID, and VERCEL_PROJECT_ID as secrets.

To setup Vercel with preview and production deployments we need the following details: VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }} -> YPPQDdLDmHCULxBFFOLaVFtF VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }} -> prj_l4AznSpYJmnYYoilYjYIjnAoO7dH VERCEL_TOKEN: ${{secrets.VERCEL_TOKEN}} -> 7Hy7xxMqfn3x0P9DMXYAe7Tr (How to create a token: https://vercel.com/guides/how-do-i-use-a-vercel-api-access-token)

You can find the org and project IDs in the project.json file in the .vercel folder of your local project.

Your "Org ID" is also called your user ID, and it's found at vercel.com/account > settings > general -- at the bottom Your "Project ID" is found at vercel.com/dashboard > your project name > settings > general -- at the bottom

To prevent pushing main branch twice, once via vercel auto deployment and once via the semantic-release bot add a vercel.json

{
    "git": {
        "deploymentEnabled": {
            "main": false
        }
    }
}