# Liquid Environment

Modyo serves a widget as a Liquid template: before the page reaches the browser, the site replaces every `{{ … }}` tag in the bundle (`{{site.language}}`, `{{vars.api-base-url}}`, …). Widgets built from the canonical template read site context and site variables through those tags, resolve them locally with mock values during development, and stop when a required variable is missing.

---

## Files

| File | Role |
|------|------|
| `src/config/widgetConfig.ts` | Reads every site variable once and exports constants; declares the required ones |
| `src/config/liquid.json` | Local values of the tags, for `npm run dev` |
| `src/config/liquidConfig.ts` | Initializes the parser with `liquid.json`, only in development |
| `src/shared/lib/liquidParser.ts` | Resolves a tag in development; returns it untouched otherwise |

---

## Reading a site variable

Declare each variable once in `src/config/widgetConfig.ts` with `liquidParser.parse(...)` and import the constant everywhere else:

```ts
// src/config/widgetConfig.ts
export const SITE_NAME = liquidParser.parse('{{site.name}}');

// any other module
import { SITE_NAME } from '@/config/widgetConfig';
```

Only `widgetConfig.ts` imports `liquidParser` directly.

### Required variables

A variable the widget cannot work without is declared with `requireVariable`:

```ts
export const API_BASE_URL = requireVariable('vars.api-base-url', liquidParser.parse('{{vars.api-base-url}}'));
export const USE_MOCKS = liquidParser.parse('{{vars.use-mocks}}') === 'true';
```

- The name goes **without braces** and the tag is written literally with the **same name**. Modyo replaces every `{{…}}` in the bundle, including one that would only serve as a label. The validator checks this (*Required Variables* / *Variable Name Matches Tag*, error), and so does `tests/config/widgetConfig.test.ts`.
- The core only requires `vars.api-base-url`. The currency variables (`vars.currency-*`) are optional: if one arrives unresolved, the widget does not set the currency and Dynamic UI uses its default format.

| Function | What it does |
|----------|--------------|
| `requireVariable(name, value)` | Registers the variable as required and returns its value |
| `isUnresolved(value)` | `true` when the value is empty or still contains the Liquid tag |
| `getMissingVariables()` | Names of the required variables that arrived unresolved; none when `USE_MOCKS` is `true` |

When rendering, `App` calls `getMissingVariables()`. If a required variable is missing, the widget shows "Missing configuration variables" with the list of names instead of the page.

### Mock data: `vars.use-mocks`

`USE_MOCKS` is `true` when `vars.use-mocks` is `"true"`. Then:

- each feature's `api/` layer returns its `*.mock.ts` data instead of calling the network (`modyo://docs/widgets/patterns-api-clients`);
- no variable is required.

---

## Where the API base URL comes from

The HTTP client in `src/shared/http/client.ts` takes its base URL in this order:

```ts
export const api = axios.create({
  baseURL: API_BASE_URL || import.meta.env.VITE_API_BASE_URL || '/api',
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
});
```

1. `API_BASE_URL`: the value of the site variable `vars.api-base-url`, read with `requireVariable` in `src/config/widgetConfig.ts` (in development, from `src/config/liquid.json`).
2. If that value is empty: `import.meta.env.VITE_API_BASE_URL`, a Vite environment variable.
3. Otherwise: `'/api'`.

`vars.api-base-url` is required, so with `vars.use-mocks` other than `"true"` an empty value stops the widget at the missing-variables screen before any request.

---

## By environment

### Development (`npm run dev`)

`src/config/liquidConfig.ts` initializes the parser with `src/config/liquid.json` only when `import.meta.env.DEV` is true:

```ts
if (import.meta.env.DEV) {
  liquidParser.init(liquidConfig, { Liquid });
}
```

Tags then resolve against these values (excerpt):

```json
{
  "site": {
    "language": "en",
    "name": "My Site"
  },
  "vars": {
    "api-base-url": "/api",
    "currency-decimal": ",",
    "currency-precision": 2,
    "currency-separator": ".",
    "currency-symbol": "$",
    "dashboard-path": "#",
    "other-var": "Some value",
    "use-mocks": "true"
  }
}
```

Keys in `src/config/*.json` must be in alphabetical order (ESLint; `npx eslint --fix` reorders them).

### On the site

In a build the condition is false, so neither `liquid.json` nor `liquidjs` reach the bundle. `liquidParser.parse()` returns each tag untouched and Modyo resolves it on the server with the site's values. Define the widget's variables as site variables in Modyo.

`liquid.json` must never hold real credentials: building with an inherited `NODE_ENV=development` keeps the development block, and the file, inside the bundle.

### `npm run preview`

It serves the built `dist/`, where nobody resolves the tags, so the widget shows the missing-variables screen. Use `npm run dev` for local values, or the Modyo CLI preview for the real site.

---

## Liquid sequences in the bundle

Because Modyo interprets every `{{ }}` and `{% %}` in the bundle:

- The `escapeLiquidInStrings` build plugin (`.vite/plugins/escapeLiquidInStrings.ts`) rewrites the exact string literals `"{{"` and `"}}"`, which some dependencies ship, as `"\u007B\u007B"` and `"\u007D\u007D"`: Unicode escape sequences that JavaScript reads as the same characters and that Liquid does not recognize. A string that contains `{{` along with other text is not escaped.
- Texts and translations must not contain `{{` or `}}`. Translations interpolate with single braces (`{lang}`).

---

## See also

- `modyo://docs/widgets/reference-architecture` — required variables and the configuration gate
- `modyo://docs/widgets/patterns-api-clients` — `USE_MOCKS` in the `api/` layer
- `modyo://docs/widgets/patterns-i18n` — single-brace interpolation
