Quickstart: Build a model and explore the CRUD API

Time to build: approx. 2 minutes

Hello and welcome to Gadget!

In this quickstart, you are going to create a model, add a new field to that model, and use the automatically generated CRUD API to add a record. This is similar to adding a new database table, adding a column to that table, and inputting a single row. You're going to build a simple backend app to keep track of student names.

• Start by creating a new Gadget app

• Click the + button in the Models section of the toolbar to create a new model
• Rename your model to Student

• Click the + Add Field (F) button or use the hotkey F to create a new field
• Rename your field to Name

• Click the API Reference link to open the API docs

• Click on Student to open your model's API documentation. This API is automatically generated for you by Gadget as you edit your model and its fields

• Go to the Student Create section on the Student API documentation page
• Pick the GraphQL option in the EXAMPLE CREATE INVOCATION snippet to see a sample GraphQL snippet for creating a new record

• Click Open in Playground to open the GraphQL playground with the create snippet pre-loaded OR paste the following snippet in the playground

GraphQL
Copy
1mutation ($student: CreateStudentInput) {
2  createStudent(student: $student) {
3    success
4    errors {
5      message
6      ... on InvalidRecordError {
7        validationErrors {
8          apiIdentifier
9          message
10        }
11      }
12    }
13    student {
14      __typename
15      id
16      state
17      createdAt
18      name
19      updatedAt
20    }
21  }
22}

• Add the following snippet to the Query Variables section in the playground

json
Copy
{
  "student": {
    "name": "Taylor Redding"
  }
}

• Click the run button OR use the Ctrl + Enter hotkey to run the GraphQL query - you should get a response with success: true and your created model

• Return to Gadget
• Click on the Data button for Student to see the record you have just added

You have successfully built a new model, added a custom field to that model, and used Gadget's generated CRUD API to add a record to that model. Now you are going to add some custom code that runs as a code effect when we create a new record for Student.

Bonus: Run a code effect

You can also run custom code effects when our CRUD actions run. You are going to add some custom code that prints to Gadget's logger each time a new student is created in your app.

• Click on the Behaviour button for Student

• Click on the Create arrow in the state machine, OR click the Create in the Actions panel

• Click + Add Success Effects and select Run Code Snippet

• Name your file logStudentRecord.ts and click Enter to create a new file

• Click on the Go to file button to open the code file OR click on the file in the Files explorer in the Gadget toolbar

• Paste the following snippet, which will print a message and the fields of your new Student record to the Logger each time a Student is created

TypeScript
Copy
1/**
2 * Effect code for Create on Student
3 * @param { import("gadget-server").CreateStudentActionContext } context - Everything for running this effect, like the api client, current record, params, etc
4 */
5module.exports = async ({ api, record, params, logger }) => {
6  logger.info({ record }, "Hello, student!");
7};

• Go back to your API Playground and re-run the create mutation for Student
• Click on Logs back in Gadget to open the logger

• Toggle User events only on to see the message printed in the Logs

If you go back to Student's data page, you will see a second record has been added as well.

Congrats! You have just added a custom code effect that runs each time you add a new record to Student.

Next steps

We recommend the following tutorials as the next steps: