Skip to main content

Quick Start

One page summary of how to start a new FTL project.

Requirements

Install the FTL CLI

Install the FTL CLI on Mac or Linux via Homebrew, Hermit, or manually.

brew tap block/ftl && brew install ftl

Install the VSCode extension

The FTL VSCode extension provides error and problem reporting through the language server and includes code snippets for common FTL patterns.

Development

Initialize an FTL project

Once FTL is installed, initialize an FTL project:

ftl init myproject
cd myproject

This will create a new myproject directory containing an ftl-project.toml file, a git repository, and a bin/ directory with Hermit tooling. The Hermit tooling includes the current version of FTL, and language support for go and JVM based languages.

Create a new module

Now that you have an FTL project, create a new module:

ftl new go alice

This will place the code for the new module alice in myproject/alice/alice.go:

package alice

import (
"context"
"fmt"

"github.com/block/ftl/go-runtime/ftl" // Import the FTL SDK.
)

type EchoRequest struct {
Name ftl.Option[string]
}

type EchoResponse struct {
Message string
}

//ftl:verb
func Echo(ctx context.Context, req EchoRequest) (EchoResponse, error) {
return EchoResponse{Message: fmt.Sprintf("Hello, %s!", req.Name.Default("anonymous"))}, nil
}

Each module is its own Go module.

Any number of modules can be added to your project, adjacent to each other.

Start the FTL cluster

Start the local FTL development cluster from the command-line:

ftl dev

This will build and deploy all local modules. Modifying the code will cause ftl dev to rebuild and redeploy the module.

Open the console

FTL has a console that allows interaction with the cluster topology, logs, traces, and more. Open a browser window at http://localhost:8899 to view it:

FTL Console

Call your verb

You can call verbs from the console:

console call

Or from a terminal use ftl call to call your verb:

ftl call

And view your trace in the console:

console trace

Create another module

Create another module and call alice.echo from it with by importing the alice module and adding the verb client, alice.EchoClient, to the signature of the calling verb. It can be invoked as a function:

//ftl:verb
import "ftl/alice"

//ftl:verb
func Other(ctx context.Context, in Request, ec alice.EchoClient) (Response, error) {
out, err := ec(ctx, alice.EchoRequest{...})
...
}