Introduction

In this tutorial you will publish a module to the Central Registry and then create a second module that depends on the first.

Prerequisites

  • A GitHub account – this will let you authenticate to the Central Registry
  • A GitHub repository called frostyconfig – create it under your personal GitHub account (it doesn’t matter if it is public or private)
  • A Central Registry account – the Central Registry is in alpha testing: if you do not yet have access please request it in the Slack #modules channel or via email to contact@cue.works
  • The cue binary – follow the installation instructions if you don’t already use cue
  • A tool to edit text files – any text editor you have will be fine, such as VSCode, Notepad, or Vim
  • A command terminalcue works on all platforms, so you can use any Linux or macOS terminal, or a Windows terminal such as PowerShell, cmd, or WSL to run commands.
  • Some awareness of CUE schemata – the language tour’s pages on Constraints and Definitions are a good refresher

This tutorial is written using the following version of cue:

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

Create the module for the schema code

In this tutorial we will focus on an imaginary application called FrostyApp, which consumes its configuration in YAML format. You will define the configuration in CUE and use a CUE schema to validate it. We would like to be able to share the schema between several consumers, so we will publish it to the Central Registry.

1

Create a directory to hold the schema code:

TERMINAL
$ mkdir frostyconfig
$ cd frostyconfig
2

Enable the modules experiment:

TERMINAL
$ export CUE_EXPERIMENT=modules

3

Initialize the directory as a module:

TERMINAL
# Replace "cueckoo" with *your* GitHub username, lower-cased.
$ cue mod init github.com/cueckoo/frostyconfig@v0

The GitHub user cueckoo controls all the repositories under github.com/cueckoo/, so they can publish modules to the Central Registry inside that namespace. The same is true for your GitHub username.

4

Create the configuration schema:

frostyconfig/config.cue
package frostyconfig

// #Config defines the schema for the FrostyApp configuration.
#Config: {
	// appName defines the name of the application.
	appName!: string
	// port holds the port number the application listens on.
	port!: int
	// debug holds whether to enable debug mode.
	debug?: bool
	// features holds optional feature settings
	features?: {
		// logging enables or disables logging.
		logging?: bool
		// analytics enables or disables analytics.
		analytics?: bool
	}
}
5

As a one-off, login to the Central Registry:

TERMINAL
$ cue login

The Central Registry is in alpha testing - if you do not yet have access please request it in the Slack #modules channel or via email to contact@cue.works.

6

Ensure the module.cue file is tidy:

TERMINAL
$ cue mod tidy
7
If you haven’t already done so, create a repository called frostyconfig under your personal username at GitHub. It doesn’t matter if the repository is public or private.
8

Publish the first version of this module:

TERMINAL
$ cue mod publish v0.0.1
published github.com/cueckoo/frostyconfig@v0.0.1

Create a new frostyapp module that depends on the first module

Define the FrostyApp configuration, constrained by the schema you just published.

9

Create a directory for the new module and initalize it, changing cueckoo to your GitHub username, lower-cased:

TERMINAL
$ mkdir ../frostyapp
$ cd ../frostyapp
$ cue mod init github.com/cueckoo/frostyapp@v0
10

Create the code for the new module:

frostyapp/config.cue
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
package frostyapp

// Adapt this line to your GitHub username, lower-cased.
import "github.com/cueckoo/frostyconfig@v0"

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

Remember to change cueckoo to your GitHub username, lower-cased, on line 4.

11

Ensure the module is tidy, adding missing 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: "github.com/cueckoo/frostyapp@v0"
language: {
	version: "v0.9.0-alpha.1"
}
deps: {
	"github.com/cueckoo/frostyconfig@v0": {
		v: "v0.0.1"
	}
}

Evaluate the configuration

12

Export the configuration as YAML:

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

We can use this new module code just like any other CUE code.

Congratulations!

That’s it! You have just created a module and published it to the Central Registry, and then used the newly published module to check a concrete configuration held in a different module.