Tutorial

This tutorial is written for developers to teach and explain a step-by-step introduction to Strapi. (The Quick Start Guide is a more concise How-to version.) This tutorial takes you through the beginning steps of how you start a project like "FoodAdvisor" (Github)(Demo).

You get a good overview of the features developers love found in Strapi.

By following this tutorial, you install and create your first Strapi project.

NOTE

You need to have Node.js and npm installed on your system before following these steps. If you do not have Node.js and npm installed (or are not sure), please visit our Installation Requirements.

Table of Contents

  1. Install Strapi and create project
  2. Create an Administrator and front-end User
  3. Create a new Content Type called, "Restaurant"
  4. Create a new Content Type called, "Category"
  5. Create a new Group and Repeatable Field called, "Hours of Operations"
  6. Manage and add content to the "Restaurant" Content Type
  7. Set Roles and Permissions
  8. Consume the Content Type API

1. Install Strapi and create a project

  • Navigate to your parent Projects/ directory from your command line.

Note: In this tutorial, the example assumes a Projects folder on your Desktop. However, this is not required, and you may put your project where you want.

Path: ~/Desktop/Projects/

Use only one of the following commands to create a new Strapi project:


yarn create strapi-app my-project --quickstart

or

  • Use npm/npx to install the Strapi project
npx create-strapi-app my-project --quickstart

The command creates a Strapi project my-project/ folder within your parent Projects/ directory.

NOTE

When you create a new Quick Start(--quickstart) project, Strapi downloads the node modules and the Strapi files needed. Using --quickstart automatically completes an additional step of building the administration panel for Strapi and then starting Strapi for you. This opens the browser for you and brings you to the Welcome page.

NOTE

You can replace the my-project name with any name you want. E.g., yarn create strapi-app my-foodadvisor-project --quickstart creates a folder ./Projects/my-foodadvisor-project.

You see something like this. The output below indicates that your Strapi project is being downloaded and installed.

yarn create v1.17.3
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
[4/4] 🔨  Building fresh packages...
success Installed "create-strapi-app@3.0.0-beta.14" with binaries:
      - create-strapi-app
[#####################################################################] 71/71Creating a new Strapi application at /Users/paulbocuse/Desktop/Projects/my-project.

Creating a quickstart project.
Creating files.
Dependencies installed successfully.

Your application was created at /Users/paulbocuse/Desktop/Projects/my-project.

Available commands in your project:

  yarn develop
  Start Strapi in watch mode.

  yarn start
  Start Strapi without watch mode.

  yarn build
  Build Strapi admin panel.

  yarn strapi
  Display all available commands.

You can start by doing:

  cd /Users/paulbocuse/Desktop/Projects/my-project
  yarn develop

Running your Strapi application.

Next, you notice the following that builds your Strapi administration panel and automatically starts up Strapi:

> my-project@0.1.0 develop /Users/paulbocuse/Desktop/Projects/my-project
> strapi develop

Building your admin UI with development configuration ...

✔ Webpack
  Compiled successfully in 52.21s

[2019-07-30T15:21:17.698Z] info File created: /Users/paulbocuse/Desktop/Projects/my-project/extensions/users-permissions/config/jwt.json
[2019-07-30T15:21:17.701Z] info The server is restarting

[2019-07-30T15:21:19.037Z] info Time: Tue Jul 30 2019 17:21:19 GMT+0200 (Central European Summer Time)
[2019-07-30T15:21:19.037Z] info Launched in: 910 ms
[2019-07-30T15:21:19.038Z] info Environment: development
[2019-07-30T15:21:19.038Z] info Process PID: 70615
[2019-07-30T15:21:19.038Z] info Version: 3.0.0-beta.14 (node v10.16.0)
[2019-07-30T15:21:19.038Z] info To shut down your server, press <CTRL> + C at any time

[2019-07-30T15:21:19.038Z] info ☄️  Admin panel: http://localhost:1337/admin
[2019-07-30T15:21:19.039Z] info ⚡️ Server: http://localhost:1337

Strapi Registration Page

NOTE

Using the --quickstart flag installs Strapi using an SQLite database. You may, at any time, leave off the --flag, but you need to follow a few configuration steps for your database choice. You need to have your database choice installed and running locally before creating your project.

Note: An SQLite database is an excellent database to use for prototyping and developing Strapi projects. SQLite is a light database that ports effortlessly to the other relational databases (MySQL, PostgreSQL, and MariaDB). It is recommended to develop with SQLite and to use another relational database (MySQL, PostgreSQL or MariaDB) in production.

Note: If you would like to use MongoDB in production, you need to install, run, and use MongoDB to develop your Strapi project (in development).

You are now ready to create a new Administrator and new front-end User.

2. Create an Adminstrator and front-end User

The first step is to create an Administrator (or "root user") for your project. An Administrator has all administrator privileges and access rights. (You can read more about why Administrators and front-end Users are separate here.)

You need to complete the following fields:

  • Username, create a username for login access to your project, e.g., paulbocuse
  • Password, create a unique password for logging into your project
  • Email address, this is used for recovery
  • Check Receive news, this is optional but recommended
  • Click the Ready to Start button

Completed Registration Page

After your Administrator registration is complete, you see the Strapi Administration Dashboard:

Strapi Admininstration Dashboard

Administrators and front-end Users are separate roles.

A. An Administrator has access and rights to the Administration Dashboard (or backend) of Strapi. Administrators can, for example, add content, add plugins, and upload images.

B. A front-end User is someone who interacts with your project through the front-end. A front-end User can, for example, be an "Author" of an article, make a purchase, has an account, leaves a review, or leaves a comment.

Up until this point, you have created an Administrator, and so you next want to create a front-end User.

Note: It is not necessary to always create a front-end User for your Administrators; in this case, the Administrator is also a front-end User as an "Author" of content in the application.

  • Click on Users located under CONTENT TYPES in the left-hand menu
  • Click the blue + Add New User button in the top right corner
  • Next, complete the Username, Email, and Password fields
  • Select ON for the Confirmed toggle field
  • To the right, under Role, select Authenticated
  • Save the new user by clicking the blue Save button (top right)

New front-end User

You are now ready to create your first Content Type.

3. Create a new Content Type called "Restaurant"

Content Types are a collection of entered data represented by fields. For example, a Content Type called Restaurant may be intended to display information regarding restaurants. A restaurant Content Type could have fields that include a name, the main image, and a description - at a minimum. However, a restaurant could also have a category or multiple categories, and a restaurant could perhaps need to show hoursofoperation.

A Content Type can be considered a sort of blueprint for the data created. In other words, a Content Type is the schema of the data structure.

The next section guides you through the steps needed for each of these above Content Type fields.

NOTE

Additional Restaurant themed Content Types and fields can be seen in the FoodAdvisor demo site.

The Restaurant Content Type

  • Go to the Content Type Builder plugin, located in the left menu: Under PLUGINS: --> Content Type Builder

You are now able to see the three available Content Types. At this point, three Content Types are available Permission, Role, and Users.

Content Type Dashboard

You need to create a new Content Type for Restaurants.

  1. Complete these steps to Add a Restaurant Content Type:
  • Click the + Add A Content Type link (under existing CONTENT TYPES)
  • Enter a Name for your new Content Type (call this restaurant), and you can write Restaurant Listings for the Description
  • Click the Done button

Singular Name Entries for Content Type

NOTE

The Content Type Name is always singular. For example, restaurant not restaurants.

  1. You are now at the Field Selection panel:

You may add your first field, a String field for the Restaurant name.

Field Section Panel

  • Click on the String field
  • In the Name field, type name

Restaurant Name Input Field

  • Click on the ADVANCED SETTINGS tab
  • Check the Required field checkbox
  • Check the Unique field checkbox

Restaurant Name Advanced Settings

  • Click the + Add Another Field button

You are now ready to add the second field, a Rich Text field for the Restaurant description.

Field Section Panel

  • Click the Rich Text field

  • In the Name field, type description

Restaurant Rich Text Field

  • Click the + Add Another Field button

You are now ready to add the third field, a Media field for the Restaurant thumbnail image.

Field Section Panel

  • Click the Media field

  • In the Name field, type image

Restaurant Rich Image Field

  • Click on the ADVANCED SETTINGS tab
  • Check the Required field checkbox

Restaurant Rich Image Field Advanced Settings

  • Click the Done button

Your new Content Type called Restaurant is ready to be Saved.

Restaurant Save Screen

  • Click the Save button

  • Wait for Strapi to restart

Strapi Restart

After Strapi has restarted, you are ready to continue to create the Category Content Type.

4. Create a new Content Type called "Category"

The Category Content Type

The Category Content Type will have a String field named category, and a Relation field with a Many to Many relationship.

Category Add Content Type

  1. Complete these steps to add a Category Content Type:
  • Click the + Add A Content Type link
  • Enter a Name for your new Content Type (call this category)
  • Enter Restaurant Categories for the Description

Category Name Field

  • Click the Done button
  1. Now, you are ready to add fields to your Category:

Category Fields

  • Click on the String field
  • In the Name field, type name

Category Name Entry Field

  • Click on the ADVANCED SETTINGS tab
  • Check the Required field checkbox
  • Check the Unique field checkbox

Category Advanced Settings

  • Click the + Add Another Field button

You are now ready to add the second field, a Relation field for creating a Many to Many relationship between the Category and Restaurant Content Types.

  • Click on the Relation field

Category Add Field Panel

This brings you to the Add New Relation screen.

Category New Relation Field

  • Click on right dropdown with Permission (Users-Permissions) and change it to Restaurant

Category Relation Dropdown

  • Click the Many to Many icon (from the middle icon choices). It should now read, "Categories has and belongs to many Restaurants"

Category Relation Many to Many

  • Click the Done button

Category Save

  • Click the Save button

  • Wait for Strapi to restart

Category Save Strapi Restart

After Strapi has restarted, you are ready to create a Group and Repeatable Field called "Hours of Operations."

5. Create a new Group, and Repeatable Field called, "Hours of Operation"

The Hours of Operation Group

The Restaurant Content Type has a Group field named Hours_of_operation. This Group is Repeatable and for displaying the Opening hours and Closing hours of a Restaurant.

  1. Complete these steps to add a new Group:
  • Click the + Add A Group link to add a new Group
  • Enter a Name for your new Group (call this hours_of_operation), and you can write Hours of Operation for the Description

Hours of Operation Add Group

  • Click the Done button
  1. Now, you are ready to add fields to your Group:

Hours of Operation Add Fields

  • Click on the String field
  • In the Name field, type day_interval. This is to enter the Day (or Days) with Hours of Operation

Hours of Operation Days

  • Click on the ADVANCED SETTINGS tab
  • Check the Required field checkbox

Hours of Operation Days Advanced Settings

  • Click the + Add Another Field

You are now ready to add a second field, another String field for the Opening Hours.

Hours of Operation Opening Hours

  • Click on the String field
  • In the Name field, type opening_hours

Hours of Operation Opening Hours Name

  • Click the + Add Another Field button

You are now ready to add a third field, another String field for the Closing Hours.

Hours of Operation Closing Hours

  • Click on the String field
  • In the Name field, type closing_hours

Hours of Operation Closing Hours Name

  • Click the Done button

Hours of Operation Save

  • Click the Save button
  • Wait for Strapi to restart

Hours of Operation Strapi Restart

After Strapi has restarted, you are ready to assign this Hours_of_operation group to the Restaurant Content Type.

Note: It would be possible to assign the Hours_of_operation group to another Content Type, let's say, a Cafe Content Type. You have the option to reuse this group across your application.

  1. Next, you need to assign the Hours_of_operation Group to the Restaurant Content Type.

To access the Hours_of_operation Group from within the Restaurant Content Type, you need to edit the Restaurant Content Type in the Content Type Builder.

  • If needed, navigate back to the Content Type Builder

Edit Restaurant Content Type

  • Click on the Restaurant Content Type, under CONTENT TYPES

Edit Restaurant Add Another Field

  • Click one of the + Add Another Field buttons, to add the Group

Edit Restaurant Group Field

  • Click on the Group field

  • Ensure hours_of_operation is displayed in the Select a group dropdown

  • Provide a name for this group in the Restaurant Content Type. E.g., restaurant_hours

  • Check the Repeatable field box

Restaurant Group Inputs

  • Click on the ADVANCED SETTINGS tab
  • Check the Required field checkbox

Restaurant Group Advanced Settings

  • Click the Done button

Restaurant Group Save

  • Click the Save button

  • Wait for Strapi to restart

Restaurant Group Strapi Restart

After Strapi has restarted, you are ready to continue to the next section where you customize the user-interface of your Restaurant Content Type.

  1. Next, you edit the View Settings for the new Hoursofoperation Group from within the Content Manager.

You can drag and drop fields into a different layout, as well as, rename the labels as two examples of how you can customize the user interface for your Content Types.

  • Navigate to and click on the Content Manager, under PLUGINS in the left-hand menu

Content Manager

  • Click on the Groups(1) tab

Content Manager Groups Tab

  • Click on Hours_of_operation to modify the View Settings

Content Manager Hoursofoperation

  • Rearrange the fields and make them more user friendly. Grab the opening_hours and slide it next to closing_hours

Content Manager Hoursofoperation Rearrange Fields

Next, you will change the field labels to make them easier to understand:

  • Click on the day_interval field
  • Edit the Label to read, Day (or Days)
  • Add a Description, You can type in one day or a series of days to complete this field. E.g. "Tuesday" or "Tues - Wed"

Content Manager Hoursofoperation Day Interval

  • Click on the opening_hours field
  • Edit the Label to read, Opening Hours

Content Manager Hoursofoperation Opening Hours

  • Click on closing_hours field
  • Edit the Label to read, Closing Hours

Content Manager Hoursofoperation Closing Hours

  • Click the Save button, and then the Confirm button to save your settings

Your settings have now saved.

Whenever anyone enters in information for a Restaurant, the entry form is clear. With Strapi you can modify these and more settings to provide the best experience possible.

You are ready to start inputting actual content.

6. Manage and add content to a "Restaurant" Content Type

You are now ready to add some Restaurants and Categories.

  1. You are now going to enter a new Restaurant
  • Navigate to and click on the Restaurants, under CONTENT TYPES in the left-hand menu

Restaurants Content Type

  • Next, click on the + Add new Restaurant button (in the top right corner)
  • Enter in the following information for your first Restaurant called Biscotte Restaurant
    • In the Name field, enter Biscotte Restaurant
    • In the Description field, enter Welcome to Biscotte restaurant! Restaurant Biscotte offers a cuisine based on fresh, quality products, often local, organic when possible, and always produced by passionate producers.
    • Upload an Image to represent the Restaurant

Note: At this point, you would generally select the Categories for this Restaurant. You have not entered any Categories, so you do this step after entering this first Restaurant.

Restaurant Content Type Basic Data

  • Next scroll down to RestaurantHours|(0) and click the + ADD NEW ENTRY button
    • In the Create an Entry section, enter the following details:
      • In the Days (or Days) field, enter Sun - Mon
      • In the Opening Hours field, enter Closed
      • Skip the Closing Hours field, as this Restaurant is closed all day
    • Click the + ADD NEW ENTRY button to create another new entry
      • In the Days (or Days) field, enter Tues - Fri
      • In the Opening Hours field, enter 12:00
      • In the Closing Hours field, enter 22:30
    • Click the + ADD NEW ENTRY button to create the last entry
      • In the Days (or Days) field, enter Sat
      • In the Opening Hours field, enter 11:30
      • In the Closing Hours field, enter 16:00

You have now entered in all the information necessary, for your first Restaurant.

Restaurants Entry

  • Scroll up and click the Save button

Next, you need to enter in some Categories that can relate to the above and other Restaurants.

  • Navigate to and click on the Categories, under CONTENT TYPES in the left-hand menu

Categories Entry

You are going to enter two Categories, but you could add as many Categories as you need to. Later, you can add additional Categories and assign them to existing and new Restaurants.

  • Click on the + Add New Category button
    • In the Name field, enter French food
    • In the Restaurants(0) dropdown, select Biscotte Restaurant

Categories Entry 1

  • Click the Save button

You now enter your second Category.

  • Click on the + Add New Category button
    • In the Name field, enter Brunch
    • In the Restaurants(0) dropdown, select Biscotte Restaurant

Categories Entry 2

  • Click the Save button

You have now entered your first Restaurant Content Type. You have also assigned two Categories to this Restaurant. Your next step is to set the Roles and Permissions.

7. Set Roles and Permissions

By default, Strapi publishes all Content Types with restricted permissions. Which means you have to explicitly give permissions to each Content Type you create. You are going to give Public API (or URL) access to both the Restaurant Content Type and Category Content Type.

  • Click on the Roles & Permissions menu item, under PLUGINS in the left-hand-menu
  • Locate and click on the Roles & Permissions menu item under PLUGINS on the left menu

Roles and Permissions

  • Next, click on the Public Role

Roles and Permissions Public Role

  • Next, scroll down under Permissions and locate the Restaurant and Category Content Types
  • Click the checkbox for find and findone in the Restaurant Content Type
  • Click the checkbox for find and findone in the Category Content Type

Roles and Permissions Find Permissions

  • Scroll back to the top, and click the Save button

Roles and Permissions Save

You have now opened the API and are ready to consume your content.

8. Consume the Content Type API

Each of your Content Types are accessible by following their automatically generated routes.

Both your Restaurant and Category Content Types can now be accessed:

  • In your browser, follow http://localhost:1337/restaurants to return the data for the allowed Find value of your Restaurant Content Type

Restaurant Api

  • In your browser, follow http://localhost:1337/categories to return the data for the allowed Find value of your Category Content Type

Category Api

NOTE

If you have incorrectly or not set permissions to your content type, you get a "403" permission error. See the below example.

Forbidden Access Looks like this:

Forbidden Access to Restaurant Content Type

NOTE

If you would like to see the route of any specific Content Type, you need to navigate to the Content Type under the Roles and Permissions plugin and click the ⚙️ next to the value. On the right, you see the route:

Permission Routes

CONGRATULATIONS

👏 Congratulations, you have now completed the Strapi Getting Started Tutorial. Where to go next?