When dealing with headless CMSs the usual workflow would be to connect to REST API or use GraphQL to get the data from the API and display it on your frontend. 

If you are using Next.js (or some other SSR framework) with PayloadCMS you can take advantage of a feature called Local API. 

Local API allows you to get the data directly on the server and then display it on the frontend, which means that you don't need to deal with server latency or network speed and can interact directly with your database. 

In this video I'm going to show you how to setup Next.js and Payload to run on the same server, kind of like a monolith app, and then how to use Local API to get and filter the data.

### Next.js and Payload Setup

For this demo we are going to be using [official Payload/Next template from Github](https://github.com/payloadcms/nextjs-custom-server) . Of course you could set this up yourself but that is not a trivial task, so for the sake of time we are going to be using this.

Go to Github, click on "Code" and copy the path to this Github repo.

In your terminal do `git clone` and then paste the path to the repo, at the end add the name of your project. I'm going to call mine "payload-next":

```shell
git clone https://github.com/payloadcms/nextjs-custom-server payload-next
```

Now CD into it, and make sure that you are running at least 16 point something version of Node. 

Create `.env` file by copying `.env.example` file like this:

```shell
cp .env.example .env
```

Let's open this project in our code editor, and then open the newly created `.env` file.

First just add a random string for `PAYLOAD_SECERT` variable. 

Next, add your MongoDB connection to the `MONGODB_URI` variable. If you don't have MongoDB running on your local environment check the [previous video](https://watch-learn.com/payload-cms/let-s-checkout-payload-cms) for some ideas. I'm using Docker image of MongoDB for this demo.

Now let's do `npm install` to install all the dependencies. 

If you get an error like I did, run `npm install` with `legacy-peer-deps` flag.

```shel
npm install --legacy-peer-deps
```

Now we just run `npm run dev` and we should be good to go.

If you go to `localhost:3000` in your browser, you should be greeted with the 404 page. Not to worry, we will fix that later. For now let's go to the `localhost:3000/admin` , this is where Payload Admin UI lives. Create an admin account, and you should get to the Admin Dashboard.

### Creating collections

We are getting 404 on the front page of our app because we didn't setup a home page. Luckily we can seed the database with that data to get rid of that error. Or you can create a homepage manually. 

I'm going to go with the seed option in this demo, because I also want to seed the Products, Colors and Sizes that we are going to be filtering with Local API. Before we seed the database we need to create necessary collections.  

First I'm going to create `Colors` collection.

Create a file called `Colors.ts` inside the `collections` folder and add this code:

```ts
import { CollectionConfig } from 'payload/types';

const Colors: CollectionConfig = {
  slug: 'colors',
  admin: {
    useAsTitle: 'name',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'name',
      type: 'text',
      label: 'Color name',
    },
  ],
  timestamps: false,
};

export default Colors;
```

Check the [previous video](https://watch-learn.com/payload-cms/let-s-checkout-payload-cms) if you don't understand what is going on here - in short we are just creating Colors collection with one field called `name`.

Next create a file called `Sizes.ts` also in the `collections` folder. And add this code to it:

```ts
import { CollectionConfig } from 'payload/types';

const Sizes: CollectionConfig = {
  slug: 'sizes',
  admin: {
    useAsTitle: 'name',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'name',
      type: 'text',
      label: 'Size name',
    },
  ],
  timestamps: false,
};

export default Sizes;
```

It's pretty much the same as `Colors.ts` . 

Now we are going to create a "Products" collection that is going to be using "Sizes" and "Colors" as relational fields along with Product specific fields.

In the `collections` folder create a file called `Products.ts` and add this code to it.

```ts
import { CollectionConfig } from 'payload/types';

const Products: CollectionConfig = {
  slug: 'products',
  admin: {
    useAsTitle: 'name',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'name',
      type: 'text',
      label: 'Products name',
    },
    {
      name: 'price',
      type: 'number',
      label: 'price',
    },
    {
      name: 'colors',
      type: 'relationship',
      label: 'Colors',
      relationTo: 'colors',
      hasMany: true,
    },
    {
      name: 'sizes',
      type: 'relationship',
      label: 'Sizes',
      relationTo: 'sizes',
      hasMany: true,
    },
  ],
  timestamps: false,
};

export default Products;
```

This is a very simple collection, which consist of `name` and `price` fields, with two relational fields that are going to reference "Colors" and "Sizes". 

Great, now all we need to do is register these collections in `payload.config.ts` file. 

```ts
import { buildConfig } from 'payload/config';
import dotenv from 'dotenv';
import Page from './collections/Page';
import Media from './collections/Media';
import Products from './collections/Products';
import Sizes from './collections/Sizes';
import Colors from './collections/Colors';

dotenv.config();

export default buildConfig({
  serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL,
  collections: [
    Page,
    Media,
    Products,
    Sizes,
    Colors,
  ],
});
```


### Seeding the database

Now we are ready to seed the database. If you wanna follow along with this video, you can copy  `index.js` file from `seed` folder from the code used in this video (the link will be in the description below). By doing this you will seed the Database with 30 Products, a few Colors and Sizes along with the Homepage of our site. 

To seed the database first stop the server and run it again. So that we have all collections implemented. 

Stop the server again, and run:

```shell
npm run seed
```

If you go to `localhost:3000` we don't have 404 error anymore, but, more importantly, in the Admin UI you should now see Colors, Sizes and Products that we seeded.

Cool, we can now start using this data in Next.js with Local API.

### Generating types

Since Payload fully supports TypeScript, it would be nice to add typings for "Products", "Colors" and "Sizes" so that we can use it in our Next.js app. With Payload this is super easy, but we just need to setup the command first.

Add this code to your `package.json` file under the `scripts` object.

```shell
"generate:types": "PAYLOAD_CONFIG_PATH=./payload.config.ts payload generate:types"
```

Now in your terminal run:

```shell
npm run generate:types
```

And our types will be automatically generated.

You can check `payload-types.ts` file to see if the generator added our types. And sure enough they are here, "Products", "Colors" and "Sizes". 

Nice.

### Getting the products

Create `products.tsx` file inside `pages` folder. 

First I'm going to import everything I need. Two things are interesting here, and those are `payload`  from payload, which we will use to initiate Local API and also `Product` type that we just generated. 

```tsx
import React from 'react';  
import { GetServerSideProps } from 'next';  
import payload from 'payload';    
import Head from '../components/Head';  
import { Product } from '../payload-types';

interface ProductProps {
  products: [Product];
}
```

Next I'm going to create our component. Using `ProductProps` and prepare our products for display. Nothing to fancy here, we are just mapping through the `products` that we are going to get from Payload and displaying `name`, `price`, `colors` and `sizes`.

```tsx
const Products: React.FC<ProductProps> = ({ products }) => (
  <main className="products-page">
    <Head title="Product list" />
    <div className="container">
      <h2>
        Products (
        {products.length}
        )

      </h2>


      <ul className="product-list">
        {products.map((product) => (
          <li
            key={product.id}
            className="product-item"
          >
            <h3>{product.name}</h3>

            <strong className="price">
              $
              {' '}
              {product.price}
            </strong>


            <strong>Colors:</strong>
            <ul className="sub-list">
              {product.colors.map((color) => (<li key={color.id}>{color.name}</li>))}
            </ul>

            <strong>Sizes:</strong>
            <ul className="sub-list">
              {product.sizes.map((size) => <li key={size.id}>{size.name}</li>)}
            </ul>
          </li>
        ))}
      </ul>
    </div>
  </main>
);
```

Now it's time to get our data, remember Local API is only usable on the server, so we need to make our request for the data in `getServersideProps` .

```tsx
export const getServerSideProps: GetServerSideProps = async () => {
  
};
```

And in here we can query our products and send them to our component. Like this:

```tsx

const pageQuery = await payload.find({
    collection: 'products',
    limit: 30,
});
```

So here I'm using `payload` function that I imported, to find all the `products` and limit them to 30 results. `limit` property comes in very handy when you are developing pagination for your lists. 

Only thing we need to do now is send the Products to our component like this.

```tsx
return {
    props: {
      products: pageQuery.docs,
    },
};
```

Before we check this in the browser I will just add a bit of css to `style.css` to make this look a bit prettier.

```css
.products-page {
  background: #000000;
  padding-top: 1px;
  padding-bottom: 60px;
  color: #ffffff
}

.container {
  max-width: 960px;
  margin-left: auto;
  margin-right: auto;
}

.product-list, .sub-list {
  margin: 0;
  padding: 0;
  list-style: none;
}

.product-list h3 {
  font-size: 24px;
  margin: 0 0 40px;
}

.product-list strong {
  display: block;
}

.product-list strong.price {
  font-size: 18px;
  margin-bottom: 20px;
}

.product-item {
  border: 1px solid #2e2e2e;
  border-radius: 10px;
  background: #0a0a0a;
  margin-bottom: 20px;
  padding: 20px;
}

.sub-list {
  display: flex;
  margin-bottom: 20px;
}

.sub-list li {
  margin-right: 20px;
}
```

Ok. Now let's check it out in the browser. Great, we are getting our products, with only a few lines of code. This is nice, but Local API is so much more powerful than this.

### Filtering products

Getting just a list of products wouldn't be very useful if we couldn't filter it in some way. 
To filter the products we can use `where` property. Say for example that we want to get just the products that cost less that 100 dollars. 

We can do that by doing something like this.

```tsx
where: {
    price: {
        less_than: 100,
    },
},
```

So we use a `where` property, and then say that the price should be less than a hundred. And sure enough now we get only those products that have a price less than hundred.

To access nested properties, like `color` or `size` we would write something like this:

```tsx
where: {
    'colors.name': {
        equals: 'Green',
    },
},
```

Now we should get a list of Products that have a Green color in the colors options array.

Cool.

But what if we want to get the products that have the price less than 100 dollars AND have a Green color option. Easy, we can write our query within an `and` array, like this.

```tsx
where: {
    and: [
        {
          'colors.name': {
            equals: 'Green',
          },
        },
        {
          price: {
            less_than: 100,
          },
        },
    ],
},
```

Now we are getting products that have a price bellow 100 dollars and color option of Green. You can also use an `or` array, and not only that, you can nest `and` in it so you can do some pretty complicated queries. 

Kind of like this.

```tsx
where: {
    or: [
        {
          'colors.name': {
            equals: 'Red',
          },
        },
        {
          and: [{
            price: {
              greater_than: 100,
            },
            'sizes.name': {
              equals: 'XS',
            },
          }],
        },
    ],
},
```

Now we are displaying products that either have Red color option OR they have XS size option AND are less than 100 dollars. 

Very powerful stuff.

You can take a look at all the options you have available in the documentation. And also keep in mind that these filters are not available only to the Local API, you can use similar syntax when doing GraphQL queries and even REST queries, but for them it is best to use `qs` package to stringify your queries so that they don't look shitty.

Of course Local API is not only used for getting and filtering your data. You can also very easily use it to create, update and delete items. Local API is also used for authentication, so logging in users, resetting passwords and so on. 

I can't cover everything in this video, so checkout the docs if you are interested in other aspects of Local API.

In this video I'm going to show you how to setup Next.js and Payload to run on the same server, kind of like a monolith app, and then how to use Local API to get and filter the data.


PayloadCMS and Next.js With Local API

What I really like about Payload CMS is that everything is done through code, you don't have to go around clicking in the admin UI to setup things like you would do in WordPress, Strapi or even Directus. 

You just configure everything directly in code and use the Admin UI to add data to your app. Being a developer this is really appealing to me. It has a great developer experience, but the end users don't need to know anything about coding to add new data to the CMS easily.

Let me show you how this works.

### Install MongoDB

First of all you need to setup MongoDB to be able to use Payload, this is very easy and there are a few options. 

For this demo I'm going to use a Docker instance of MongoDB - if you want to setup MongoDB that way, you can follow [along with this tutorial](https://manglekuo.medium.com/running-mongodb-on-docker-with-macos-b08324f5aab2).

Another way is to visit [MongoDB docs](https://www.mongodb.com/docs/manual/installation/) and follow instructions there to install it on the system of your choice. 

And the third and probably the easiest way is to sign-up for [MongoDB Atlas](https://www.mongodb.com/atlas/database) and use their free tier to setup your DB. And then use that during Payload setup.

### Install Payload

Once you installed MongoDB, go to your terminal and run `npx create-payload-app` , just be sure that you have NodeJS version 10 or above running on your system. 

Now give it a name, I will call mine `payload-movies` since we are going to create a standard demo that I always use for these types of videos, a kind of movie database.

For project template I'm going to choose a `blog` so that we get some collections and fields right away. And then later we are of course going to add our own collections and fields to create a movie database type of site.

Now you need to enter your MongoDB connection, for me it's going to be `mongodb://root:root@localhost:27017`cd  since I'm using Docker setup. For you it may be something a bit different.

Wait a bit for project dependencies to be installed and then just cd into `payload-movies` directory and run `npm run dev` or `yarn dev` if you are using Yarn.

You should get an URL to the Payload Admin, which will usually be `http://localhost:3000/admin`  - go to that address in your browser.

You will be greeted by a welcome screen and be prompted to add a first user. Add your data here and click "Create" button.

### Admin interface

Admin interface for payload is very simple. You have access to Collections which were created during Payload installation. These Collections work the same way like in Directus, they are just collections of a specific data items.

Since we opted for a blog site during Payload installation, we get some standard ones like Posts, Categories and Tags.

Of course you also have Users, for user management and Media for media management.

When you click on any collection you can create an item in that collection, and then fill in the data in the fields assigned to that collection. Also all very similar to Directus. 

Once you create a new item you can check out API response for it by clicking on the "API URL" link. 

Now, this all looks very minimal, but don't confuse minimal with the lack of options or features. Remember, in Payload you setup everything through code, so you can make it as complex or feature full as you like, because the Admin interface is not for you - the developer, it's made for editors and non technical users and they need the UI to be as simple as possible for adding content to the site without much friction. 

And if you need some custom feature in the Admin UI, you can easily achieve that by adding in your own custom React components, using provided React Hooks and by customising CSS. So even the Admin interface is very extensible. Maybe I will show you how to do that in some other video. 

For this video let's try to cover the basics of creating Collections and Fields, and I'm also going to show you how to create data relations and how to add some custom functionality to your fields.

### Creating Actors Collection

Now open your code editor and let's get to work. Go to the `src` directory and then to collections and create a file called `Actors.ts` - Payload uses TypeScript which is great because you are going to get a lot of code hints and auto complete options in your editor so that you can work much faster. 

First we are going to import `CollectionConfig` from `payload/types`  so that we have typings for our Collection.

```ts
import { CollectionConfig } from 'payload/types';
```


Then we define our `Actors` collection with `CollectionConfig` type.

```ts
const Actors: CollectionConfig = {
...
}
```

And in it we are going to define `slug` for our collection, `useAsTitle`  which is going to be a title of the item in the collection that is going to be displayed in lists and on the item page. For now I'm going to set it to be `first_name` because we are going to create a field called `first_name` for  `Actors` .

After that we are going to set access to `read` so that this can be read by anyone. In Payload you can have very granular control over who can read what, but we will not cover that in this video. 

I will now add two fields `first_name` and `last_name` . Defining fields in Payload is very intuitive. You just define `name` , `type` and `label` for the field. For some fields it can be a bit more complex, but not much, I will show you that a bit later.

Lastly, I will just add `timestamp` property to be `false`. Now you just export your collection and we are done with the `Actors.ts` file for now. 

```ts

const Actors: CollectionConfig = {
  slug: 'actors',
  admin: {
    useAsTitle: 'first_name',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'first_name',
      type: 'text',
      label: "First name",
    },
    {
      name: 'last_name',
      type: 'text',
      label: 'Last name'
    }
  ],
  timestamps: false,
}

export default Actors;
```

One last thing we need to do is to register `Actors` in `payload.config.ts` file. First we just import `Actors` .

```ts
import Actors from "./collections/Actors";
```

Then you just add Actors to the `collections` array. And that's it. 

Go to the Admin in your browser and refresh the page. You should see `Actors` collection show up in the UI.

Click on it and try adding an Actor. Robert DeNiro for example, and click Save. 

Ok, so this works, but what I don't like is that the title of the Actor is just Robert without the last name. Let's try to fix that. 

Go to `Actors.ts` file and import `FieldHook` type.

```ts
import { FieldHook } from 'payload/types';
```

Then we are going to create a function that is going to return value of the `first_name` and `last_name` fields. I'm going to call this function `populateFullTitle` .

```ts
const populateFullTitle: FieldHook = async ({ data }) => {
  return `${data?.first_name} ${data?.last_name}`
}
```


Now we add a new field called `full_name` and hide it in admin UI, and then we use `beforeValidate` hook to populate this field automatically with the `populateFullName` function that we just created. 

```ts
{
  name: 'full_name',
  type: "text",
  admin: {
	components: {
	  Field: () => null
	}
  },
  hooks: {
	beforeValidate: [
	  populateFullTitle
	]
  }
}
    ```

We must not forget to set `useAsTitle` to be `full_name` instead of `first_name` .

```ts
useAsTitle: 'full_name',
```

Go to the browser refresh and save Robert DeNiro again. 

Also let's try adding one more actor. Brad Pitt this time. The name won't be filling up as you type, but it will populate first and last name once you hit save. Great.

### Creating Movies Collection.

Now let's add Movies collection. In the `collections` directory add a file called `Movies.ts`, and we follow the same pattern like we did for the Actors collection. 

```ts
import { CollectionConfig } from 'payload/types';

const Movies: CollectionConfig = {
  slug: 'movies',
  admin: {
    useAsTitle: 'title',
  },
  access: {
    read: () => true,
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      label: "Movie title"
    },
    {
      name: 'date',
      type: "date",
      label: "Release date"
    }
  ],
  timestamps: false,
}

export default Movies;
```

We are going to use `title` field for our `useAsTitle` property. I'm going to add two fields, `title` and `date` for now. Take note that the date field has the `type` of `date` this is going to give us a nice date widget in the Admin UI.

Now I want to add two more fields, `actors` for choosing the actors in the movie and also a `poster` for the movie poster.

Since we wanna add actors from our Actors collection, `actors` field is going to be of type `relationship` , for this type of field to work we also need to define what collection this field relates to. This is super easy, just add a property called `relationTo` and put `actors` as a value. Since the Movie can have many actors, we are going to set `hasMany` property to `true`. We also want the to create new actors from this field in the Admin UI, so we are going to set `allowCreate` property to `true`. 

```ts
{
  name: 'actors',
  type: "relationship",
  label: 'Actors',
  relationTo: 'actors',
  hasMany: true,
  admin: {
	allowCreate: true
  }
}
```

We need to set up one more field, for the movie poster. This field is going to be of `type` `upload` and for Upload fields you also need to set relation, just like for Relationship field type. I'm going to set `relationTo` property to be `media` . So that we can upload new media, but also use already existing Media. 

```ts
{
  name: 'poster',
  type: "upload",
  relationTo: 'media'
}
```

Save this and we are done with Movies collection, only thing left to do is to register it in `payload.config.ts` file. 

Now let's test it out in the browser. Refresh the Admin UI, and you should get Movies collection.

Create a new Movie. Movie title is going to be Goodfellas. I'm going to set release date to January, 1st 1990. And now we can select actors. 

I'm going to choose Robert DeNiro. 

And since we enabled creating Actors from this page, I'm also going to add Joe Pesci, by clicking on the plus button. Add Joe Pesci and click Save.

And for the movie poster I'm going to Upload New Media, and add poster for Goodfellas. Then click Save. And then Save again to save the Movie. 

And that is it, we can check out the API response by clicking on the API URL.

### Conclusion

I must say - Payload is pretty nice, it has a nice developer experience and is very easy to use for the editors. And since you can do everything in code you can easily share your code through git with your team or other developers you are working with.

This has been only a taste of what Payload can do, and I will for sure make a few more videos about it, since I find it very enjoyable to work with. And as always don't forget to read the docs if you wanna get your hands dirty with it.

What I really like about Payload CMS is that everything is done through code, you don't have to go around clicking in the admin UI to setup things like you would do in WordPress, Strapi or even Directus. 