Simply copy and paste the following command line in your terminal to create your first Strapi project.
npx create-strapi-app
my-project
Article updated to v4 by: Fredrick Emmanuel
Strapi is an open-source headless CMS for creating quick and readily-manageable APIs. It allows developers to create flexible API structures with a beautiful user interface easily. It is also self-hosted, meaning you can build your APIs in the UI, and Strapi will still host and server the API endpoints for you. You can push your Strapi server to any cloud host for the world to use your APIs.
APIs are built-in Strapi in the name of collections, although they now support single-type APIs.
For example, if we create a collection called Animals
, Strapi will provide us with the following endpoints:
/api/animals
GET: This endpoint will return all the animals on the server./api/animals/:id
GET: This will return a specific animal from the server using the id to find the animal. The id is a globally unique identifier the server sets to identify/marl each animal resource in the back-end uniquely./api/animals/:id
PUT: This edits an animal resource in the collection. The id is the id of the animal to edit. This request body will contain the new info about the animal that will be edited./api/animals/:id
DELETE: This endpoint deletes/removes an animal from the collection./api/animals
POST: This endpoint adds a new animal to the mix. The request body will contain the data of the new animal to be created.That's the power of Strapi, we don't have to write the code for each endpoint, and we don't have to set up any database; everything is provided for us from the start.
Strapi has plugins and configurations that enable us to add extra custom features to Strapi. For example, you can add a database (PostgreSQL, MySQL, etc.). This will make Strapi use your database instead of its inbuilt DB.
Strapi is very flexible and allows developers to configure the back-end to their liking easily.
We will need a few tools installed on our machine for this article.
Pagination is the breaking up of web data into discrete parts. This optimization technique requires the whole page to be broken up and delivered into pages.
For example, a news app can have up to 10,000 news in its backend. Thus, displaying the news in one fell swoop will significantly impact client and server performance.
It will take time for the server to get all 10K news posts and send them to the client. The payload will be massive, and it will cause latency and high network usage on the server.
On the client side, the news post requests will take time for the response to reach the client, so there will be a huge load time. Then, whenever the response comes, the UI framework will loop through the 10K news posts and render them on the UI. The looping alone will have a performance problem on the JS engine, then combine it with the rendering of each news post up to that large number.
Our browser might become unresponsive when it loops and renders 10K news posts. The solution is to collect the news posts from the server chunk by chunk. We will request a small chunk of the dataset, render it, and when the next dataset is needed, a request is sent, and the next chunk in-line is sent from the server. We will render the whole dataset in the browser without affecting the performance. Doing is called pagination.
The 10K news posts are broken into pages. A page represents a chunk or slice of the datasets rendered at a time.
Since we have 10K records, and we want 20 records in a chunk, that means we will have 500 pages (10,000/20). Each page will have 20 records. We can set the limit, which will require re-calculating the number of pages that it will generate because changing the limit of records to 10 records will mean that our news app will have 1000 (10,000/10) pages. In the next section, we will look into the types of pagination.
There are two types of ways we can achieve pagination. They are:
Let's start with offset-based pagination
.
Offset-based pagination uses the concept of start and limits to get discrete parts from the database.
The process involves setting the number of records to fetch and the number of records to skip. This is usually done by using the limit and offset.
The limit
sets the number of records to return. The offset
specifies the index from where the record collection/fetching will start.
For example, we have this dataset.
0. data_1
1. data_2
2. data_3
3. data_4
4. data_5
5. data_6
6. data_7
7. data_8
8. data_9
9. data_10
10. data_11
11. data_12
12. data_13
13. data_14
Each record has a unique global identifier, no two records can have the same identifier. Therefore, we can fetch the data in discrete parts by specifying the index in the datasets to start from and the maximum amount to return.
For instance, we want to get five items per request. So, we send the request along with limit and offset values in the initial request.
limit: 5
offset: 0
The index of the first record is zero
This will start with the 1st record data_1
and take the following four records. The result will be:
0. data_1
1. data_2
2. data_3
3. data_4
4. data_5
Now, on the next request, the limit and values will be:
limit: 5
offset: 5
This will start with the 6th record and get the next four records. The result will be:
6. data_6
7. data_7
8. data_8
9. data_9
10. data_10
This result is appended to the previous result and displayed on the UI. These techniques do away with the performance bottleneck we experienced before when fetching the whole data. Now we won't experience any unresponsive UI, and the load time will be much lesser because each response will have a small payload size. The data are fetched in batches, and each batch contains a small subset of the whole dataset.
Coming from an SQL background, we can use clauses in SQL to fetch rows from tables in batches.
SELECT column FROM table LIMIT 10 OFFSET 10
The LIMIT
states the number of rows to retrieve/return from the table. The OFFSET
tells the SQL engine to start from the 11th row in the table. With the above SQL statement, we have achieved offset-based pagination in SQL.
Problems with offset-based pagination
Problems occur when data are inserted and removed from the datasets while the pagination continues. Offset-based pagination uses an index, which is the record's position in the list. When a record is removed from the list, the indexes change.
For example, in our data list above, if data_1
is removed, the indexes change, and it affects the next set of records to be fetched because offset pagination works on the indexes. This results in missing records or duplicates records.
Since indexes in offset-based pagination are not reliable, we can identify the records directly in the datasets and use them as a pivot point. This point of pivot is the cursor, hence the name cursor-based pagination.
The point of pivot/cursor must be globally unique to all records in the dataset. This is useful, so even if duplicate records exist in the dataset, their unique IDs will stand out. IDs are usually used as the cursor because it is sequential and unique.
Cursor-based pagination involves selecting a specific record from the dataset and then collecting the following nth records. Unlike offset-based pagination, which uses an index in the dataset, cursor-based pagination uses the field in the record.
A request in cursor-based pagination will be like this:
cursor: 2
limit: 5
Using id
as the cursor in the records field. This request will start from the record with an id
field with two and collect the next four records.
In SQL, cursor-based pagination will look like this when getting from a blogPosts table:
select * from blogPosts where id > 0 limit 2
This statement will select blog posts from the blogPosts
table starting from the record whose id
field is greater than 0. Thus, the maximum number of blog post rows to select is two records only.
The blogPosts
table is this:
{ id: 1, post: "Post_1"},
{ id: 2, post: "Post_2"},
{ id: 3, post: "Post_3"},
{ id: 4, post: "Post_4"},
{ id: 5, post: "Post_5"},
{ id: 6, post: "Post_6"},
{ id: 7, post: "Post_7"},
{ id: 8, post: "Post_8"},
{ id: 9, post: "Post_9"},
{ id: 10, post: "Post_10"}
The result will be this:
{ id: 1, post: "Post_1"},
{ id: 2, post: "Post_2"},
On the next request, we will increase the value to fetch rows whose id
field value is greater than
This is because the last record in our result has an id
of 2.
select * from blogPosts where id > 2 limit 2
Let’s look at how we achieve pagination in a GraphQL API.
GraphQL is an open-source query language for data APIs created by Facebook in 2012. It uses the concept of a query (read), mutation (write), and subscription (continuous read) to fetch data from an API.
GraphQL is a runtime in the backend. This runtime provides a structure for servers to describe the data to be exposed in their APIs. Clients can then write the structure of data they want from the server using the GraphQL language. Finally, the language text is sent to the GraphQL server via the HTTP POST request.
The GraphQL runtime receives the GraphQL language, runs it, puts together the data as requested, and sends it back to the client.
Note: following examples are general GraphQl examples and not specific to Strapi. We will cover that later in the tutorial.
A simple Graphql query looks like this:
1
2
3
4
5
6
7
8
query {
posts {
data {
title
body
}
}
}
This tells the GraphQL runtime to give us an array of posts, on each post record, we want the title
and body
fields present.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
"data": [
{
"title": "Intro to React",
"body": "Body content of React"
},
{
"title": "Intro to Angular",
"body": "Body content of Angular"
},
{
"title": "Intro to Vue",
"body": "Body content of Vue"
},
{
"title": "Intro to Svelte",
"body": "Body content of Svelte"
},
{
"title": "Intro to Preact",
"body": "Body content of Preact"
},
{
"title": "Intro to Alpine",
"body": "Body content of Alpine"
}
]
}
If the number of post records in our GraphQL server is huge, we will experience lag and poor performance.
It seems complex to do with all those weird language structures used to fetch data. Yes, but it is simple to achieve.
The limit
and offset
arguments are used to implement offset-based pagination in GraphQL endpoints.
The limit
sets the number of records to return from the endpoint. The offset
sets the index in the dataset to start from.
1
2
3
4
5
6
7
8
query {
posts(limit: 2, offset: 7) {
data {
title
body
}
}
}
The query above will start from index 7 in the record list and return two records below it. To get the next records, we know that the next index to start is 9. the query will be this:
1
2
3
4
5
6
7
8
query {
posts(limit: 2, offset: 9) {
data {
title
body
}
}
}
The next query will be from offset 11:
1
2
3
4
5
6
query {
posts(limit: 2, offset: 11) {
title
body
}
}
From the query resolver, we will have to get the limit
and offset
args and use them to return the records.
The args
param will have the arguments in our query in its object body. So we destructure them:
1
2
3
4
5
6
Query: {
posts: (parent, args, context, info) => {
const { limit, offset } = args
...
};
}
Then, we use them to get the data in discrete parts.
1
2
3
4
5
6
7
const postArray = [];
Query: {
posts: (parent, args, context, info) => {
const { limit, offset } = args;
return postsArray.slice(offset, limit);
};
}
We have our DB in an array, so we use the Array#slice
method to get the posts off the postsArray
using the limit
and offset
as the starting index and the amount to slice, respectively.
The main point here is that we have the limit
and offset
arguments. We can then use them to get records in parts from our database (e.g., PostgreSQL, MySQL, in-memory database, etc.)
That's a simple way to achieve offset-based pagination in GraphQL.
To implement cursor-based pagination in GraphQL, we use the cursor
and limit
arguments. The argument's names can be whatever you want in your implementation, and we chose these names to describe what they do.
A query will be like this:
1
2
3
4
5
6
7
8
query {
posts(cursor: 4, limit: 7) {
data {
title
body
}
}
}
The cursor
is set to 4, the id of the record in the dataset to start from, and the limit
is the number of records to return.
We know the cursor is not always the id
of the records in the list. The cursor can be any field in your records; the important thing is that the cursor should be globally unique in your records.
Strapi supports GraphQL, and this is done by installing the GraphQL plugin to the Strapi mix.
With the Strapi GraphQL, we can use Strapi filters start
and limit
filters to achieve offset-based pagination in our Strapi endpoint. Now, we build a GraphQL Strapi API to show how to use pagination in GraphQL-Strapi.
First, we will create a central folder newsapp-gpl
:
mkdir newsapp-gpl
Move into the folder and scaffold the Strapi project.
cd newsapp-gpl
we will scaffold a Strapi project
npx create-strapi-app@latest newsapp-gpl-api --quickstart
The above command will create a Strapi folder newsapp-gpl-api
and also start the Strapi server at localhost:1337
. This is the URL from which we can build our collections and call the collections endpoints.
Strapi will open a page to register an admin before we can start creating endpoints: http://localhost:1337/admin/auth/register-admin.
Now, by default, Strapi creates REST endpoints for the collections. To enable the GraphQL endpoint, we will have to add the GraphQL plugin.
To do that, we run the below command:
➜ newsapp-gpl-api yarn strapi install graphql
Re-start the server to save changes.
Open the link http://localhost:1337/graphql
. The GraphQL playground will open up.
Now, we can’t perform any op (query or mutation).
We must register ourselves before we can do anything. Open a new tab in the playground and run the below mutation:
1
2
3
4
5
6
7
8
9
mutation {
register(input: { username: "nnamdi", email: "kurtwanger40@gmail.com", password: "nnamdi" }) {
jwt
user {
username
email
}
}
}
See the result:
This will create a new user in the User
collection type in our admin panel.
Now, we will create a Content Model named News Posts. To do this, we will click on Content-Type Builder in our Strapi's admin panel and click on Create new collection type.
Next, we will give the collection a name. You can decide to name it anything you like but in this tutorial, the name is News Post.
Now, configure the collection as shown using the following:
title -> Text, Short text
body -> Text, Long text
image -> Text, Short text
writtenBy -> Text, Short text
Once we are done configuring the collection, we will have an output similar to the one shown below. Click on Save and let Strapi restart the server.
Then, populate the collection with news
data. Add data up to 15 items.
Strapi will not generate REST endpoints for our News Post collection. Instead, it will create GraphQL mutations and queries for the News Post collection.
We have to enable role access for the News Post collection. Go to "Settings" -> "Roles" -> "Public". Enable "Select all" for newsPost
. Then, scroll up and click on "Save".
Here, we will build a news app using React.js. This app will display all the news in our back-end in a list. We will paginate the news list in a form with "Next" and "Prev" buttons. These buttons will be used to navigate the pages of the news list.
The news list page will display a maximum of two news posts per page. If the "Next" button is pressed, it loads the next page. Likewise, if the "Prev" button is pressed, it loads the previous page.
We will use a React starter file for this project to concentrate more on the Graphql aspect.
Our app will look like this:
It will have the following components:
Go to the GitHub repo, clone it and run one of the commands below to install all the dependencies.
npm install
or
yarn install
Start the server:
npm start
or
yarn start
Go to your browser and navigate to localhost:3000. From the starter file, our news application has two routes(pages):
Now that we have our React app ready, we can implement pagination in our application. Strapi supports two kinds of pagination.
This type of pagination divides the results into sections. It takes two arguments, page
and pageSize
. The argument pageSize
specifies the number of results a page can contain while another argument, page
, defines the page of results.
For instance, we have 100news. When we set the pageSize
to 5 and the page
argument to 2. It will split the 100news into 20 pages and display the 2nd page.
Let's see how it works in our react project.
Open the index.js
file in the NewsListPage
folder and add the following lines of code.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
//Path: newsapp-gpl/newsapp-strapi/src/pages/NewsListPage/index.js
//...
export default function NewsList() {
//...
const [pageSize] = useState(2)//Setting the pageSize
const [page, setPage] = useState(1)//Creating the page argument
useEffect(() => {
async function fetchData() {
const {
data
} = await axios.post('http://localhost:1337/graphql', {
query: `
query GetNewsPost{
newsPosts(pagination: {page: ${page}, pageSize: ${pageSize}}){
data{
id
attributes{
title
writtenBy
image
createdAt
body
}
}
meta{
pagination{
total
pageCount
}
}
}
}
`,
});
setPageDetails(data?.data?.newsPosts?.meta?.pagination); //Storing the total pages
setNewsList(data?.data?.newsPosts?.data); //Storing the news post
}
fetchData();
}, [start]);
//...
}
Three dots,
...
, represents missing lines of code
Above, we created a function to handle the fetching of our paginated newsPosts
from Strapi's graphql API. In the function, we specified the current page
and pageSize
then we passed these variables to the query and got our paginated newsPost
.
Once we get a successful response, we store the metadata and the news post in the pageDetails
and newsList
state variables, respectively.
Now that we've got our news post let's handle the prev
and next
buttons. These buttons will help us to fetch the previous or next page.
Still, in the NewsListPage
folder, add the following to the index.js
file.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
//Path: newsapp-gpl/newsapp-strapi/src/pages/NewsListPage/index.js
// ...
export default function NewsList() {
//...
const [page, setPage] = useState(1); //Creating the page argument
//...
function nextPage() {
setStart(pageSize + start);
setPage(page + 1);//Setting the value of the next page
}
function prevPage() {
setStart(start - pageSize);
setPage(page - 1);//Setting the value of the previous page
}
//...
}
From the above lines of code, we increased the value of the page
variable when we click on the Next
button. Doing this will fetch the results for the next page and vice versa for the Prev
button.
Now, we will learn the offset method of paginating our results.
Open the index.js
file in the NewsListOffset
folder and add the following lines of code.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
//Path: newsapp-gpl/newsapp-strapi/src/pages/NewsListOffset/index.js
//...
export default function NewsList() {
//...
const [limit] = useState(2)//Setting the pageSize
const [startOffset, setStartOffset] = useState(0);//Setting the start index for our request
useEffect(() => {
async function fetchData() {
const { data } = await axios.post('http://localhost:1337/graphql', {
query: `
query GetNewsPost{
newsPosts(pagination: {start: ${start}, limit: ${limit}}){
data{
id
attributes{
title
writtenBy
image
createdAt
body
}
}
meta{
pagination{
total
pageCount
}
}
}
}
`,
});
setPageDetails(data?.data?.newsPosts?.meta?.pagination);
setNewsList(data?.data?.newsPosts?.data);
}
fetchData();
}, [start, limit, page]);
//...
}
In the above, we set the position of the first value to be retrieved using the startOffset
variable and specified the maximum number of results using the limit
variable. Then we stored the metadata and the news post in the pageDetails
and newsList
state variables, respectively.
How it works
We specified the index position of our first value to be 0
meaning, it will get the result at index position 0
. Then we specified the maximum number of results to be got as 2
. Doing this will retrieve the first and second results from the content model in Strapi.
Next, import the NewsListOffset/index.js
into our App.js
file
1
2
3
4
5
//Path: newsapp-gpl/newsapp-strapi/src/App.js
//...
// import NewsList from './pages/NewsListPage';
import NewsList from './pages/NewListOffset';//Replacing the Page pagination with the Offset pagination
Now, let's add the Next
and Prev
functionality.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
//Path: newsapp-gpl/newsapp-strapi/src/pages/NewsListOffset/index.js
//...
export default function NewsList() {
//...
const [startOffset, setStartOffset] = useState(0);//Setting the start index for our request
//...
function nextPage() {
setStart(limit + start);
setStartOffset(startOffset + limit);
}
function prevPage() {
setStart(start - limit);
setStartOffset(startOffset - limit);
}
//...
}
Above, we added the maximum result count to our current first index value when the Next
button is clicked. Doing this, we will get the next two results from Strapi, using the outcome from the sum as the starting index value.
In our News app, users can create a news posts in the application. To create this functionality, we will get the news data from the user and send a POST request to Strapi's graphql API using the data. The user will provide this data using the modal provided when the user clicks on Add News.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
//Path: newsapp-gpl/newsapp-strapi/src/components/AddNewsDialog/index.js
import { useState } from 'react';
import axios from 'axios';
export default function AddNewsDialog({ closeModal }) {
//...
async function saveNews() {
const title = window.newsTitle.value;
const imageUrl = window.newsImageUrl.value;
const writtenBy = window.newsWrittenBy.value;
const body = window.newsBody.value;
if (title && imageUrl && writtenBy && body) {
const data = await axios.post('http://localhost:1337/graphql', {
query: `
mutation CreateNewsPost{
createNewsPost(data: {title: "${title}",image: "${imageUrl}", body: "${body}", writtenBy: "${writtenBy}"}){
data{
id
attributes{
title
image
writtenBy
body
}
}
}
}
`,
});
console.log(data);
} else {
alert('Fill up the fields');
}
}
//...
}
By Default, Strapi enables the draftAndPublish
option which prevents data from being published using a POST
request. This means that all data will be saved as draft and demands that the admin user manually publishes the data. We don't need this feature for this application.
To change this, open the schema.json
file in the newsapp-gpl\newsapp-gpl-api\src\api\news-post\content-types\news-post
folder and change the draftAndPublish
option to false
.
1
2
3
4
5
6
7
8
//Path: newsapp-gpl/newsapp-gpl-api/src/api/news-post/content-types/news-post/schema.json
{
//...
"options": {
"draftAndPublish": false
},
//...
}
Here, we will display the news that the user clicks on. Once the user clicks on the news, we will get the id
and make a GET request to Strapi using the news' id
.
We can do this by adding the following lines of code to the index.js
file in the NewsView
folder.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
//Path: newsapp-gpl/newsapp-strapi/src/pages/NewsView/index.js
//...
import { useParams } from 'react-router-dom';
export default function NewsView() {
let { id } = useParams();
useEffect(() => {
async function getNews() {
const data = await axios.post('http://localhost:1337/graphql', {
query: `
query{
newsPost(id: ${id}) {
data{
id
attributes{
title
body
image
writtenBy
createdAt
}
}
}
}
`,
});
setNews(data?.data?.newsPost?.data?.attributes);
}
getNews();
}, []);
//...
}
We got the id
from the URL using the react-router-dom
package in the code above. Once we get the id
we used it to fetch the news post for that particular news. When we get the fetched we stored the data in the news
state variable.
Now, we will put display the news post.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
//Path: newsapp-gpl/newsapp-strapi/src/pages/NewsView/index.js
//...
export default function NewsView() {
//...
return (
<div className="newsview">
<div style={{ display: 'flex' }}>
<a className="backHome" href="/news">
Back
</a>
</div>
<div
className="newsviewimg"
style={{ backgroundImage: `url(${news?.image})` }}
></div>
<div>
<div className="newsviewtitlesection">
<div className="newsviewtitle">
<h1>{news?.title}</h1>
</div>
<div className="newsviewdetails">
<span style={{ flex: '1', color: 'rgb(99 98 98)' }}>
Written By: <span>{news?.writtenBy}</span>
</span>
<span style={{ flex: '1', color: 'rgb(99 98 98)' }}>
Date:{' '}
<span>
{new Date(news?.createdAt).toLocaleDateString(
'en-us',
{
weekday: 'long',
year: 'numeric',
month: 'short',
day: 'numeric',
}
)}
</span>
</span>
<span>
<button className="btn-danger" onClick={deleteNews}>
Delete
</button>
</span>
</div>
</div>
<div className="newsviewbody">{news?.body}</div>
</div>
</div>
)
}
You can test it out by clicking on the news on the Homepage. You should get similar output to the one shown below.
We can view a particular news post; let's add a delete functionality to the news application.
We will use the id
got from the URL to delete the news post from Strapi and then redirect the user back to the homepage.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
//Path: newsapp-gpl/newsapp-strapi/src/pages/NewsView/index.js
//...
export default function NewsView() {
//...
async function deleteNews() {
if (window.confirm('Do you want to delete this news?')) {
await axios.post('http://localhost:1337/graphql', {
query: `
mutation{
deleteNewsPost(id: ${id}){
data{
attributes{
title
}
}
}
}`,
});
window.history.pushState(null, '', '/news');
window.location.reload();
}
}
//...
}
Load the app on localhost:3000. Then, press the Next and Prev buttons to navigate the pages.
Find the source code of this project below:
First, we learned what Strapi is, and then next, it was GraphQL and pagination. We demonstrated how to add pagination to our Strapi GraphQL endpoint by building a news app. In the news app, we used the next-prev type of UX pagination to demo pagination.
There are more UX pagination types:
I urge you to implement these to learn more about both paginations in the back-end and UX.
Author of "Understanding JavaScript", Chidume is also an awesome writer about JavaScript, Angular, React and other web technologies.