Getting Started

Here we will walk you through the steps for building a simple Hello World app. It assumes basic knowledge of iOS, Android and Go development. Please go through the Installation guide if you have not already done so.


Crate a directory for your app in your $GOPATH.

mkdir -p $GOPATH/src/

Create a new go file in the directory with the following snippet. This is a lot to take in at once, but we’ll try to go through it step by step in the comments.

package tutorial

import (

// Here is our root view.
type TutorialView struct {
    // All components must implement the view.View interface. A basic implementation
    // is provided by view.Embed.
    TextColor color.Color

// This is our view's initializer.
func NewTutorialView() *TutorialView {
    return &TutorialView{}

// Similar to React's render function. Views specify their properties and
// children in Build().
func (v *TutorialView) Build(ctx view.Context) view.Model {
    l := &constraint.Layouter{}

    // Create a new textview.
    child := view.NewTextView()
    child.String = "Hello World"
    child.PaintStyle = &paint.Style{BackgroundColor: colornames.Blue}

    // Layout is primarily done using constraints. More info can be
    // found in the matcha/layout/constraints docs.
    l.Add(child, func(s *constraint.Solver) {

    // Returns the view's children, layout, and styling.
    return view.Model{
        Children: []view.View{child},
        Layouter: l,
        Painter:  &paint.Style{BackgroundColor: colornames.Lightgray},

Now that we have our view in Go, we need to be call it from Objective C and Java. We can do this with the package.

func init() {
    // Registers a function with the objc bridge. This function returns
    // a view.View, which can be displayed in a MatchaViewController.
    bridge.RegisterFunc(" New", func() view.View {
        // Call the TutorialView initializer.
        v := NewTutorialView()
        v.TextColor = colornames.Red
        return v

Build the Go code by running the following in the terminal.

matcha build


Now create a new Xcode workspace in the directory and add the projects found in $GOPATH/src/ There are 3 projects, Matcha, MatchaBridge, and Protobuf. You can do this by dragging the projects into your workspace. At this point you should be able to build the Matcha.framework.


Create a new Xcode project containing a Single View Application in your directory, and add it to the workspace.


Your workspace should now enclose 4 projects. We now need to make some changes to the Xcode project settings.


Now for the Objective C code. Add imports for Matcha in AppDelegate.m.

#import <Matcha/Matcha.h>

And replace application:didFinishLaunchingWithOptions: with the following.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {    
    // Call the function we registered with the objc bridge. This creates a view.Root containing our TutorialView.
    MatchaGoValue *rootView = [[[MatchaGoValue alloc] initWithFunc:@" New"] call:nil, nil][0];
    // Create a MatchaViewController and display the view.
    self.window = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    self.window.rootViewController = [[MatchaViewController alloc] initWithGoValue:rootView];
    [self.window makeKeyAndVisible];
    return YES;

And run your application! Well done!



We will be creating an Android Studio project in the original directory, with a minimum target API level of 16 (Jelly Bean) and an empty Activity.

android-tutorial-1 android-tutorial-2

Open your project’s settings.gradle and include the Matcha project.

include ':matcha'
project(':matcha').projectDir = new File("${System.env.GOPATH}/src/")

Open your module’s AndroidManifest.xml and add the required permissions.

<manifest xlmns:android...>
    <uses-permission android:name="android.permission.INTERNET" />
    <application ...

Open your module’s build.gradle and add $GOPATH/ to the repositories and the matcha project to the dependencies.

repositories {
    flatDir {
        dirs "${System.env.GOPATH}/src/"

dependencies {
    compile project(':matcha')

Now for the Java code. Add imports for Matcha in your

import io.gomatcha.bridge.GoValue;
import io.gomatcha.matcha.MatchaView;

And replace onCreate() with the following.

protected void onCreate(Bundle savedInstanceState) {

    GoValue rootView = GoValue.withFunc(" New").call("")[0];
    setContentView(new MatchaView(this, rootView));

And run your application! Well done!


Next Steps

More examples can be found in the examples directory. The Todo app is a great place to start.