Introduction

In this tutorial you will learn how to create and work with CUE modules, using the Central Registry.

Along the way you will:

  • Login to the Central Registry, and authenticate the cue command
  • Create a module that depends on an existing, well-known module
  • Use cue mod tidy to automatically add dependencies and their versions to the module.cue file

Note that this guide depends on a pre-release version of CUE:

TERMINAL
$ cue version
cue version v0.9.0-alpha.1
...

Enable the modules experiment

TERMINAL
$ export CUE_EXPERIMENT=modules

Discussion #2939 introduces v3 of the proposal to introduce modules and dependency management for CUE. The v0.8.0 release included experimental support for modules that implements part of that proposal. If we accept #2939, then modules and package management will become a first-class citizen of CUE. Until then, we need to set the CUE_EXPERIMENT environment variable.

Login to the Central Registry

1
Visit https://registry.cue.works and login via GitHub.

Authenticate the cue command

2

Authenticate the cue command (a one-off process):

TERMINAL
$ cue login

Create a module

3

Initialize a local CUE module. We will not publish this module:

TERMINAL
$ cue mod init glacial-tech.example/frostyapp@v0

We refer to such a module as the main module. Because we won’t publish this module, its module path is not significant. The module path we have chosen makes this guide consistent with the companion tutorial on working with a custom registry.

4

Create the code for the new module:

config.cue
package frostyapp

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

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

This imports the frostyconfig package first introduced in the tutorial on working with a custom registry. Instead of depending on a version of that module published to a custom registry, we have instead published a version to the Central Registry. In our local module we define some concrete values for the configuration, constrained by the frostyconfig.#Config schema.

5

Ensure the module is tidy, pulling all dependencies:

TERMINAL
$ cue mod tidy

We can see that the dependencies have now been added to the cue.mod/module.cue file:

TERMINAL
$ cat cue.mod/module.cue
module: "glacial-tech.example/frostyapp@v0"
language: {
	version: "v0.9.0-alpha.1"
}
deps: {
	"github.com/cue-labs/examples/frostyconfig@v0": {
		v: "v0.0.1"
	}
}

Evaluate the configuration

6

Export the configuration as YAML:

TERMINAL
$ cue export --out yaml
config:
  appName: alpha
  port: 80
  features:
    logging: true

Congratulations!

That’s it, you have just created a local module that depends on a well-known module from the Central Registry!