Using modules with the Go API | CUE

Paul Jolly

Jonathan Matthews

Introduction

In this tutorial you will use CUE’s Go API to work with a CUE module dependency fetched from the Central Registry.

Along the way you will:

Login to the Central Registry, and authenticate the cue command
Create a CUE module that depends on an existing, well-known module
Use cue mod tidy to fetch and organise your module’s dependencies
Load your CUE using the Go API working in a modules-aware mode

Prerequisites

Access to the Central Registry – if you need to practise using the Central Registry, then first follow the tutorial Working with modules and the Central Registry
A tool to edit text files – any text editor you have will be fine; for example: VSCode or Vim
A command terminal – the cue command works on all platforms; use any terminal on Linux or macOS, or PowerShell, cmd.exe or WSL on Windows.
An installed go binary – installation details
An installed cue binary – installation details

This tutorial uses the following version of CUE:

TERMINAL

$ cue version
cue version v0.12.0-alpha.1.0.20241227102828-e3359f51a4f9
...

Set up the `cue` command

Authenticate the cue command with the Central Registry:

TERMINAL

$ cue login

Later in this tutorial the cue command will fetch a well-known module from the Central Registry, which requires authentication.

Create a CUE module

Initialize a new main CUE module in an empty directory:

TERMINAL

$ cue mod init an.example/config@v0

You won’t publish this module, so the name you give it is unimportant.

Create the file main.cue, holding the code for the main module:

package config

import "github.com/cue-labs/examples/frostyconfig@v0"

config: frostyconfig.#Config & {
	appName: "alpha"
	port:    80
	features: logging: true
}

Your main module defines some concrete values for a configuration, constrained by the frostyconfig.#Config schema.

Your module imports and uses the frostyconfig package first introduced in the tutorial Working with a custom module registry. You don’t need to follow that tutorial right now - it’s only mentioned for context.

Ensure the CUE module is tidy:

TERMINAL

$ cue mod tidy

This fetches the frostyconfig module (and any dependencies it might have) from the Central Registry.

Export the configuration from your CUE module:

TERMINAL

$ cue export
{
    "config": {
        "appName": "alpha",
        "port": 80,
        "features": {
            "logging": true
        }
    }
}

This export shows that your CUE is valid and you can successfully use a dependency from the Central Registry.

Create a Go module and program

Initialize a Go module for your program:

TERMINAL

$ go mod init an.example/config
...

You won’t publish this module, so the name you give it is unimportant.

Create the file main.go containing this Go program:

package main

import (
	"fmt"
	"log"

	"cuelang.org/go/cue"
	"cuelang.org/go/cue/cuecontext"
	"cuelang.org/go/cue/load"
	"cuelang.org/go/mod/modconfig"
)

func main() {
	ctx := cuecontext.New()

	// Create a registry client. Passing a nil config
	// will give us client that behaves like the cue command.
	reg, err := modconfig.NewRegistry(nil)
	if err != nil {
		log.Fatal(err)
	}

	// Load the package from the current directory.
	// We don't need to specify a Config in this example.
	insts := load.Instances([]string{"."}, &load.Config{
		Registry: reg,
	})

	// The current directory just has one file without any build tags,
	// and that file belongs to the example package, so we get a single
	// instance as a result.
	v := ctx.BuildInstance(insts[0])
	if err := v.Err(); err != nil {
		log.Fatal(err)
	}

	// Lookup the 'config' field and print it out
	config := v.LookupPath(cue.ParsePath("config"))
	fmt.Println(config)
}

This program loads the CUE package in the current directory, and then prints a message based on the config field.

Add a dependency on cuelang.org/go and ensure the Go module is tidy:

TERMINAL

$ go get cuelang.org/go@v0.12.0-alpha.1.0.20241227102828-e3359f51a4f9
...
$ go mod tidy
...

You can use @latest in place of the specific version mentioned here.

Run the Go program

Run the Go program:

TERMINAL

$ go run .
{
	appName: "alpha"
	port:    80
	features: {
		logging: true
	}
}

Summary

Well done - you’ve finished this tutorial! In completing it, you:

created a main module that depends on a well-known module from the Central Registry, and
used the Go API to load the main module, transparently using the module’s dependencies.

Reference: CUE Modules
Tutorial: Working with a custom module registry

Introduction

Prerequisites

Set up the cue command

Create a CUE module

Create a Go module and program

Run the Go program

Summary

Related content

Set up the `cue` command