CLI

The mockly command checks and builds a site from a folder on your computer, with the same compiler the studio runs. Use it to check a site before you publish, to look at the HTML each variant produces, or to stop a broken change in CI.

It has two commands:

mockly check <dir> [--json]mockly build <dir> --out <dir> [--base-path /s/acme/demo] [--site-url https://example.com]

The site folder#

A site folder has the same layout as a site in the studio: pages in pages/, components in components/, and images, fonts, and other files in public/. The CLI reads every .tsx file in the folder and its subfolders, and every file in public/. When it looks for .tsx files, it skips node_modules and anything whose name starts with a dot.

Check a site#

mockly check compiles and type checks every file, then prints each diagnostic and a summary. It doesn't fetch data or write any files.

$ mockly check ./site2 file(s): 0 error(s), 0 warning(s)

When something is wrong, each diagnostic shows its place, its severity, its code, and its message, then the lines around it with the problem underlined, and a hint when there is one:

$ mockly check ./sitepages/index.tsx:6:8  error  MK4005  Experiment "hero" needs exactly one variant named "control".  5 |     <Page title="Acme">> 6 |       <Experiment name="hero" goal="signup">    |        ^^^^^^^^^^  7 |         <Variant name="original">  hint: Name the baseline variant "control".1 file(s): 1 error(s), 0 warning(s)

In a terminal, errors are red and warnings are yellow. Output sent to a file or another program has no color, and setting the NO_COLOR environment variable turns it off in the terminal too.

JSON output#

--json prints the result as JSON instead, for scripts, editors, and agents:

$ mockly check ./site --json

{  "ok": false,  "diagnostics": [    {      "code": "MK4005",      "severity": "error",      "message": "Experiment \"hero\" needs exactly one variant named \"control\".",      "file": "pages/index.tsx",      "range": {        "start": {          "line": 6,          "column": 8,          "offset": 128        },        "end": {          "line": 6,          "column": 18,          "offset": 138        }      },      "hint": "Name the baseline variant \"control\"."    }  ]}

ok is false when there's at least one error. Each diagnostic has these fields:

Codes don't change meaning, so a script can rely on them. See Diagnostics for every code.

Exit codes#

A command can't run when the command is missing or unknown, the folder doesn't exist, or a file in public/ can't be hosted, such as a file whose contents don't match its extension. For mockly build, it's also a missing --out, or a --site-url that isn't an http or https URL. The reason and the usage go to standard error.

Build a site#

mockly build does what publishing does: it checks the site, fetches its data, renders every variant of every page, and builds the stylesheet and scripts. Instead of putting the result live, it writes it to a folder.

$ mockly build ./site --out ./outwrote out/index.htmlwrote out/index.hero=bold.htmlwrote out/signup.htmlBuilt 3 HTML file(s) · 04e347dd8117645b · style.css 5.1 KB, 1 script file(s), at most 1.8 KB per page

The last line gives the build's hash, the size of the stylesheet, the number of script files, and the most script any one page loads. Warnings found while building, such as MK4018 for a variant that looks exactly like control, print before it. When there are errors, it prints them and "Build failed.", and writes nothing.

What it writes#

Each page is rendered the way a first-time visitor gets it. The files are for looking at, comparing between builds, and testing. There's no server behind them, so nothing assigns variants or records goals. To run experiments, publish the site from the studio. See Publishing and history.

Options#

The site's name, which pages carry for share previews, is the name of the folder.

Secrets#

A page that fetches data with fetchJson() can send a secret header value with secret("NAME"). In the studio, you set secrets in Data, in the editor's sidebar. The CLI reads each one from an environment variable named MOCKLY_SECRET_ followed by the secret's name:

$ export MOCKLY_SECRET_CMS_TOKEN="your-token"$ mockly build ./site --out ./out

An empty variable counts as unset, and a secret that isn't set fails the build with MK6003. mockly check doesn't fetch data, so it doesn't need secrets. See Data from APIs.

In CI#

Run mockly check on every change. It exits with 1 when the site has an error, which fails the step:

$ mockly check ./site

Some problems only show up when the pages render: a page that throws while rendering (MK1014), data that can't be fetched (MK6002), or a variant that looks exactly like control (MK4018, a warning). Run mockly build to catch those too:

$ mockly build ./site --out ./out

Warnings don't fail either command. To fail on them as well, read the JSON. For example, with jq, which exits with 1 when the expression is false:

$ mockly check ./site --json | jq -e '.diagnostics | length == 0'