Environment Variables

Cloud UI template projects use environment variables to configure runtime behavior — things like which API to connect to, which hosts are allowed to embed the application, and where to load default context data from. How those variables are supplied depends on whether you are running the project locally or have deployed it to SAP BTP.

---

How Variables Are Resolved

The application reads configuration through a priority chain:

1. localStorage — values stored in the browser's local storage take highest priority. The Test Harness uses this when you authenticate manually.
2. window.config — a plain JavaScript object injected by config.js at page load. This is the primary mechanism for both local development and BTP deployment.
3. import.meta.env — Vite's built-in environment variable system, populated from .env files at build time. Used as a fallback.

In practice, window.config is the mechanism you will interact with most. The two environments — local development and BTP — each have their own way of populating it.

---

Local Development

When you run pnpm run dev, the Vite development server serves public/config.js as a static file. This file is loaded by index.html before the application starts, making its values available on window.config immediately.

The scaffolding tool (create-cloud-ui) generates this file for you during project creation, pre-populated with the values you entered at the prompts:

// public/config.js
window.config = window.config || {};
window.config.VITE_HOST = 'your-app.cfapps.us10.hana.ondemand.com';
window.config.VITE_API_HOST = 'https://your-link-service.cfapps.us10.hana.ondemand.com/your-route';
window.config.VITE_DEFAULTS_ENDPOINT = 'http://localhost:3000/initial-content-example.json';
window.config.VITE_LOG_LEVEL = 'info';

To change any value during local development, edit public/config.js directly and refresh the browser.

Note: public/config.js is only used during local development. It is included in the build output (dist/public/config.js) but is overridden at runtime on BTP — see BTP Deployment below.

---

BTP Deployment

When the application is deployed to SAP BTP Cloud Foundry, it is served by an nginx web server. Instead of serving the static config.js file from disk, nginx generates the file dynamically from BTP user provided variables at request time.

This is configured in package/nginx.conf:

location /config.js {
    default_type application/javascript;

    return 200 "window.config = window.config || {};
        window.config.VITE_HOST = '{{env "VITE_HOST" }}';
        window.config.VITE_LOG_LEVEL = '{{env "VITE_LOG_LEVEL" }}';
        window.config.VITE_API_HOST = '{{env "VITE_API_HOST" }}';
        window.config.VITE_DEFAULTS_ENDPOINT = '{{env "VITE_DEFAULTS_ENDPOINT" }}';
    ";
}

The {{env "..."}} placeholders are filled in by the nginx buildpack using the environment variables set on the BTP application. Every request to /config.js returns a fresh response with the current values — no rebuild required when you change a variable.

Environment variables are set on the BTP application via manifest.yml or the cf set-env CLI command. The manifest.yml in each template project pre-configures VITE_HOST:

applications:
  - name: ((name))
    buildpack: nginx_buildpack
    env:
      VITE_HOST: ((host))

Additional variables are set after deployment:

cf set-env MY-APP-NAME VITE_API_HOST https://your-link-service.cfapps.us10.hana.ondemand.com/your-route
cf set-env MY-APP-NAME VITE_DEFAULTS_ENDPOINT https://your-app.cfapps.us10.hana.ondemand.com/initial-content-example.json
cf set-env MY-APP-NAME VITE_LOG_LEVEL warn
cf restage MY-APP-NAME

Important: After setting or changing environment variables on BTP, run cf restage to apply them. The application does not need to be rebuilt — nginx picks up the new values on the next request.

---

Variable Reference

Variable	Required	Description
VITE_HOST	Yes	Semicolon-separated list of allowed host origins. Must include every domain that will embed Cloud UI in an iframe (for example, your Salesforce org URL).
VITE_API_HOST	Yes	Base URL of your enosix Link API Proxy service on SAP BTP.
VITE_DEFAULTS_ENDPOINT	Yes	URL of the JSON file used to pre-populate the Test Harness with default context data. Typically points to initial-content-example.json in the public/ folder.
VITE_LOG_LEVEL	No	Controls console logging verbosity. Accepted values: debug, info, warn, error. Defaults to warn if not set.
VITE_AUTH_USERNAME	No	SAP username pre-filled in the Test Harness authentication modal. For local development convenience only — DO NOT set this in production.
VITE_AUTH_PASSWORD	No	SAP password pre-filled in the Test Harness authentication modal. For local development convenience only — DO NOT set this in production.
VITE_AUTH_API_KEY	No	API key pre-filled in the Test Harness authentication modal. For local development convenience only — DO NOT set this in production.

---