Users frequently need to load JSON, YAML, or other types of files into their CUE code. Because CUE’s import declarations only allow references to CUE packages, some workflows resort to using the tooling layer (cue cmd) to load non-CUE files. This can complicate the process if the tooling layer’s advanced features aren’t otherwise needed.

The @embed() attribute is designed to simplify workflows that require data to be loaded at evaluation time.

Using @embed() requires CUE version v0.10.0 or later. This guide demonstrates the following version:

TERMINAL
$ cue version
cue version v0.11.1
...

Embedding files in an evaluation

1

Enable the embed experiment:

TERMINAL
$ export CUE_EXPERIMENT=embed
2

Initialize a CUE module, or use an existing module if that’s appropriate in your situation:

TERMINAL
$ cue mod init
3

Include the @extern(embed) directive at the top of each CUE file that uses the @embed() attribute. Use @embed() to embed either a single named file, or a glob identifying multiple files:

example.cue
@extern(embed)

package p

oneFile:   _ @embed(file=README.md,type=text)
manyFiles: _ @embed(glob=*.json)
{
    "aField": "a value"
}
{
    "aList": [
        1,
        2,
        3
    ]
}
{
    "anObject": {
        "foo": "a",
        "bar": "b",
        "baz": "c"
    }
}
# How to use this project

## Installation

Fetch the latest release from the official site,
and unpack it in your home directory. Next ...

By default, files are decoded using the encoding implied by their filename extension, and it’s an error if the extension is not known. Files or globs with an unknown filename extension can be loaded by adding the type=<filetype> parameter, where <filetype> can be any type described in cue help filetypes.

4

Export the resulting configuration:

TERMINAL
$ cue eval
oneFile: """
    # How to use this project

    ## Installation

    Fetch the latest release from the official site,
    and unpack it in your home directory. Next ...

    """
manyFiles: {
    "a.json": {
        aField: "a value"
    }
    "b.json": {
        aList: [1, 2, 3]
    }
    "c.json": {
        anObject: {
            foo: "a"
            bar: "b"
            baz: "c"
        }
    }
}

Next steps

The embedding proposal contains more detail about the @embed() feature. Your feedback on the proposal is most welcome - please submit it via discussion #3264.

Discussion #3264 will be updated when the embedding proposal is accepted or modified, and when feedback is posted: please subscribe to the discussion to receive these updates.