Quickstart

Run your first Modus app in a few minutes

In this quickstart we’ll show you how to get set up with Modus and its CLI and build a simple app that fetches a random quote from an external API. You’ll learn how to use the basic components of a Modus app and how to run it locally.

Prerequisites

• Node.js - v22 or higher
• Text editor - we recommend VS Code
• Terminal - access Modus through a command-line interface (CLI)

Building your first Modus app

1. Install the Modus CLI

   The Modus CLI provides a set of commands to help you create, build, and run your Modus apps. You can install the CLI using cURL or npm.

   cURL

   curl -sSL http://install.hypermode.com/modus.sh | bash
   

2. Initialize your Modus app

   To create a new Modus app, run the following command in your terminal:

   modus new
   

   This command prompts you to choose between Go and AssemblyScript as the language for your app. It then creates a new directory with the necessary files and folders for your app.

3. Build and run your app

   To build and run your app, navigate to the app directory and run the following command:

   modus dev
   

   This command runs your app locally in a development mode and provides you with a URL to access your app’s generated API.

4. Add a connection

   Modus is a secure-by-default framework. To connect to external services, you need to add a connection in your app manifest.

   Add the following code into your modus.json manifest file:

   modus.json

   {
     "connections": {
       "zenquotes": {
         "type": "http",
         "baseUrl": "https://zenquotes.io/"
       }
     }
   }
   

5. Add a function

   Functions are the building blocks of your app. Let’s add a function that fetches a random quote from the ZenQuotes connection you just created.

   Go

   To add a function, create a new file in the root directory with the following code:

   quotes.go

   package main
   
   import (
     "errors"
     "fmt"
   
     "github.com/hypermodeinc/modus/sdk/go/pkg/http"
   )
   
   // this function makes a request to an API that returns data in JSON format, and
   // returns an object representing the data
   func GetRandomQuote() (*Quote, error) {
     request := http.NewRequest("https://zenquotes.io/api/random")
   
     response, err := http.Fetch(request)
     if err != nil {
       return nil, err
     }
     if !response.Ok() {
       return nil, fmt.Errorf("Failed to fetch quote. Received: %d %s", response.Status, response.StatusText)
     }
   
     // the API returns an array of quotes, but we only want the first one
     var quotes []Quote
     response.JSON(&quotes)
     if len(quotes) == 0 {
       return nil, errors.New("expected at least one quote in the response, but none were found")
     }
     return &quotes[0], nil
   }
   

   To add a function, create a new file in the root directory with the following code:

   quotes.go

   package main
   
   import (
     "errors"
     "fmt"
   
     "github.com/hypermodeinc/modus/sdk/go/pkg/http"
   )
   
   // this function makes a request to an API that returns data in JSON format, and
   // returns an object representing the data
   func GetRandomQuote() (*Quote, error) {
     request := http.NewRequest("https://zenquotes.io/api/random")
   
     response, err := http.Fetch(request)
     if err != nil {
       return nil, err
     }
     if !response.Ok() {
       return nil, fmt.Errorf("Failed to fetch quote. Received: %d %s", response.Status, response.StatusText)
     }
   
     // the API returns an array of quotes, but we only want the first one
     var quotes []Quote
     response.JSON(&quotes)
     if len(quotes) == 0 {
       return nil, errors.New("expected at least one quote in the response, but none were found")
     }
     return &quotes[0], nil
   }
   

   To add a function, create a new file in the assembly directory with the following code:

   quotes.ts

   import { http } from "@hypermode/modus-sdk-as";
   
   @json
   class Quote {
     @alias("q")
     quote!: string;
   
     @alias("a")
     author!: string;
   }
   
   // this function makes a request to an API that returns data in JSON format, and
   // returns an object representing the data
   export function getRandomQuote(): Quote {
     const request = new http.Request("https://zenquotes.io/api/random");
   
     const response = http.fetch(request);
     if (!response.ok) {
       throw new Error(
         `Failed to fetch quote. Received: ${response.status} ${response.statusText}`,
       );
     }
   
     // the API returns an array of quotes, but we only want the first one
     return response.json<Quote[]>()[0];
   }
   

   Then add the following to index.ts. This includes the getRandomQuote function on your generated API.

   index.ts

   export { getRandomQuote } from "./quotes";