Create the Backend | React Todos
Table of Contents
- Step 1 - Create a New App
- Step 2 - Create an Entity
- Step 3 - Create a Role
- Step 4 - Assign Permissions
- Step 5 - Connect to GitHub
- Step 6 - Build the Backend
- Step 7 - Run the Backend
- Step 8 - Wrap Up
Step 1 - Create a New App
Hopefully, you've had the chance to create an Amplication account, but if not, don't fret! Visit https://app.amplication.com/ and you'll be directed to the login screen. Here you can log in to an existing Amplication account, or create one, by signing in with a GitHub account.
You should end up at the
New App
page, but if not you can get to it here.Click the
New App
button in the top right corner.Name your application whatever you'd like, and then click "Create Project."
Click "New service +," in the top right corner, and then "Create Service" in the bottom right of the new page.
Step 2 - Create an Entity
An entity is equivalent to a collection in a NoSQL database or a table in a relational database. By default, a User entity is created for you. This entity will eventually help us handle authentication. But first, let's deal with the backend. The main entity will be used to store tasks created by users.
Click the "Entities" button in the left hand bar to go to the entities page.
Click
Add entity
.When a
New Entity
modal appears, inputTask
into the input field and clickCreate Entity
.With the entity created we'll want to define a few fields for task elements.
On the left-hand panel, you'll see the
Fields
this entity has, and at the very bottom, there will be an option to add a field.The first field will be
Text
. Type that into theAdd field
input and hitenter
.The new field will be created and a few options will appear.
Notice a dropdown for the
Data Type
of this field is set toSingle Line Text
. That's perfect as it'll be a string input of a task. There are many different data types Amplication can enforce for fields.The only change that needs to be made here is this will be a required field. Toggle the
Required Field
switch.Changes will be automatically saved.
Like before, create a new field called
Completed
. This field should also be a required field, but we will change the data type. Click theData Type
dropdown and change this field to be aBoolean
.The final field we will need to create should be called
UID
. This field will be used to relate a task to a user. Mark this as a required field. In theData Type
dropdown selectRelation to Entity
.The
Related Entity
dropdown should appear, selectUser
. A modal asking to create a relation between a Task and a User will appear. ClickCreate
to create the relation. To learn more about entity relations, there's an article on the docs website here.
Step 3 - Create a Role
Amplication allows for granular permission to create, read, update, and delete entries in the different entities of the backend.
User's who will be creating tasks in the Todo app will need to be granted certain permissions to create, read, and update their tasks and prevent them from doing other things.
Click the
Roles
icon on the left-hand panel.Then, much like the properties, we added to the
Task
entity, create a role calledTodo User
.
Step 4 - Assign Permissions
With a role for users of the Todo app created, we'll want to assign certain permissions to the Todo User
role.
Return to the entities page by clicking the
Entities
icon on the left-hand panel, again.By default, every role has CRUD (create, read, update, and delete) access to every entity. It is important to limit the scope of our Todo users.
Select the
User
entity from the list of entities, and on the left-hand, panel selectPermissions
.Every type of command is granted to
All Roles
. Users with theUser
orTodo User
role have full access to theUser
entity. This can be dangerous.The default admin account created by the backend has the role
User
, so we don't want to mess with that. What we will eventually do is have it so all new users are assigned theTodo User
role, and we will limit their access to certain commands.Toggle the permissions for each of the entity's commands to
Granular
and toggle on theUser
role. Now the only user who can accessUser
accounts will have theUser
role, which will belong only to the admin account.Return to the
Entities
page and now select theTask
entity. ClickPermissions
. Toggle theDelete
command, toGranular
and enable access to theUser
role. BothUser
s (the admin) andTodo User
s (regular users of the app) will be able to create, read, and update tasks; but onlyUser
s will be able to delete tasks.
Step 5 - Connect to GitHub
Amplication provides code sync with GitHub. We'll want to set this up with the repository we created in the previous step.
If you're an Enterprise plan user you can also sync with other git providers like Bitbucket.
Click the
Connect to Github
icon on the left-hand panel. Then clickGo to project settings.
Click
Connect to Github.
This will allow you to connect with either your GitHub account, or with a GitHub organization.Finally click
Select repository.
From here select the GitHub repository we created previously.
Step 6 - Build the Backend
With the new Task entity created, and a relation with User's created, and connecting our project with GitHub. We're now ready to commit our changes and build the application.
On the right-side panel is the Pending changes
where the changes to Task
and User
, as well as other changes, will appear.
Click
Commit changes & build
to finalize the changes and to create a Pull Request on GitHub with the backend we created.Amplication by default creates a secure environment where all requests need to be authenticated. For this use case, we will want to ease some of those protections. Thanks to Amplication's extensibility, we can build on top of everything that was generated for us.
Visit GitHub and navigate to the repository that's linked to this project. You'll see that a new pull request has been opened!
Review the pull request and the code that was generated for yourself, then merge the pull request.
Finally, return to your code editor and pull down the changes made on GitHub.
Step 7 - Run the Backend
The
admin-ui
andserver
folders generated by Amplication are two new node projects that need to be set up. One thing both will need is their dependencies. In thepackage.json
update thepostinstall
script:"postinstall": "npm i --prefix web && npm i --prefix apps/first-service-admin && npm i --prefix apps/first-service"
Make sure that you replace first-service
with the name of the service that you created in Step 1 in the above postinstall
script.
Open a new terminal and run this command
npm run postinstall
This command will install the dependencies of all the subfolders. Another useful aspect of this command is that if you were to push this project to GitHub and cloned the repo when you run
npm install
this script will occur after the install to install the dependencies of the subfolders automatically.There will be some minor conflicts with the code
create-react-app
created for us and the code Amplication created for us. This should be easy to correct though.Installcross-env
andnpm-run-all
as a dev dependency as follows:npm install -D cross-env npm-run-all
Update the
start
script inpackage.json
and add the following script as well:"start": "npm-run-all -p start:frontend start:backend",
"start:frontend": "cross-env PORT=5000 npm --prefix web start",
"start:admin": "npm --prefix admin-ui start",
"start:backend": "npm --prefix server start",By doing this the Todo app UI will now run on port
5000
during development so it won't conflict with Amplication's default port for the server (which is3000
).We've also set the start to script to run our frontend and backend code at the same time.
Before starting the server there are a few additional steps required. Read
server/README.md
for directions to:- Create a Prisma client
- Start a database in Docker
- Initiate the database
When those steps have been completed run the following command:
npm run start
Step 8 - Wrap Up
The frontend of the Todo app will be running at http://localhost:5000/, and the backend will be running at http://localhost:3000/.
Visiting http://localhost:3000/ will greet you with a 404
error. Instead, visit http://localhost:3000/api/ to see all the endpoints of the backend and to see what our REST endpoints will look like.
With our backend created and running locally, we're almost ready to link it to the frontend. First, we'll need to make some additions to the code.
To view the changes for this step, visit here.