Publishing modules to the Central Registry | CUE

Paul Jolly

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 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 terminal – cue 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.12.0-0.dev.0.20241122172925-7d64696b0129
...

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.

Create a directory to hold the schema code:

TERMINAL

$ mkdir frostyconfig
$ cd frostyconfig

You need to adapt the command shown in the next step.

Don’t simply paste the command into your terminal and run it.

Before running the command, replace the example username, cueckoo, with the lower-cased form of YOUR GitHub username. For example: if your GitHub username is _TomHanks then you would replace cueckoo with _tomhanks.

You need to make this replacement everywhere you see the username cueckoo in this tutorial.

Initialize the directory as a git repository and a CUE module:

TERMINAL

$ git init -q

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

The --source=git flag tells cue to use the same file-inclusion rules as git, when publishing this module.

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.

Create the configuration schema:

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
	}
}

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

TERMINAL

$ cue login

The Central Registry is in alpha testing - please give us your feedback about the service in the #modules channel on Slack or on Discord!

Ensure the module.cue file is tidy:

TERMINAL

$ cue mod tidy

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.

Create a git commit:

TERMINAL

$ git add -A
$ git commit -q -m 'Initial commit'

Earlier, you initialized this module with --source=git, which told the cue command that it should publish only those files that git knows about. The git commit you just created leaves the directory in a “clean” state, which is necessary for cue to know exactly which files to include in the published module.

Publish the first version of this module:

TERMINAL

$ cue mod publish v0.0.1
...

This command should mention your GitHub username, and should publish the module successfully.

If the command fails with an error message that mentions your GitHub username then you probably haven’t created the frostyconfig repository under your GitHub username. Create it, and try the step again.

If the command fails with an error message that mentions cueckoo/frostyconfig then you probably forgot to adapt the command in step 3, above. Don’t worry - this isn’t a serious problem!

The easiest way to fix this is to delete your frostyconfig directory and restart the tutorial from step 1.

Create a new `frostyapp` module that depends on the first module

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

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

TERMINAL

$ mkdir ../frostyapp
$ cd ../frostyapp
$ git init -q
$ cue mod init --source=git github.com/cueckoo/frostyapp@v0

Create the code for the new module:

 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.

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.12.0"
}
source: {
	kind: "git"
}
deps: {
	"github.com/cueckoo/frostyconfig@v0": {
		v: "v0.0.1"
	}
}

Evaluate the configuration

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.

Tutorial: Working with modules and the Central Registry
Tutorial: Working with a custom module registry
Reference: CUE Modules

Introduction

Prerequisites

Create the module for the schema code

Create a new frostyapp module that depends on the first module

Evaluate the configuration

Congratulations!

Related content

Create a new `frostyapp` module that depends on the first module