Environment Variables

Environment variables let you configure your app without hardcoding values. On device, they're stored in NVS (non-volatile storage) and persist across reboots.

Reading environment variables

Use import.meta.env to access environment variables in your code:

const {WIFI_SSID, WIFI_PASSPHRASE, API_KEY} = import.meta.env

Accessing an undefined variable throws a TypeError, so typos and missing config are caught early:

// throws TypeError: Environment variable "WFII_SSID" is not configured
const ssid = import.meta.env.WFII_SSID

You can also read environment variables programmatically with getEnv() from mikrojs/sys, which returns undefined instead of throwing:

import {getEnv} from 'mikrojs/sys'

const apiKey = getEnv('API_KEY') // string | undefined

Setting environment variables

With mikro env

The mikro env command reads and writes environment variables directly on the connected device.

Set a variable:

npx mikro env set API_URL https://api.example.com

Set a secret (prompts for the value, never displayed):

npx mikro env set API_KEY --secret

List all variables:

npx mikro env list

Secret values are masked in the output:

API_URL   https://api.example.com
API_KEY   ********

Delete a variable:

npx mikro env delete API_URL

TIP

Variable names can be up to 15 characters (NVS key limit). Use short, descriptive names like WIFI_SSID, API_KEY, MQTT_HOST.

With .env files

The mikro dev and mikro deploy commands can load environment variables from files:

npx mikro dev --env .env --secrets .secrets.env

Both files use standard dotenv format:

# .env
WIFI_SSID=MyNetwork
API_URL=https://api.example.com

# .secrets.env  (add this to .gitignore!)
WIFI_PASSPHRASE=hunter2
API_KEY=sk-abc123

Variables from --env are stored as regular env vars. Variables from --secrets are stored as secrets.

Secrets vs. regular variables

The --secret flag controls how a variable is displayed, not where it's stored. All environment variables (secret or not) are written to the same NVS storage and are equally available at runtime via import.meta.env.

The difference:

	Regular	Secret
Stored on device	Yes	Yes
Available in import.meta.env	Yes	Yes
Shown in mikro env list	Value visible	Masked (********)
Set via CLI	mikro env set KEY value	mikro env set KEY --secret

A variable name must be unique. Setting a variable with --secret overwrites any existing non-secret variable with the same name, and vice versa.

Simulator

When running with mikro sim, environment variables are loaded from a .env file in the project directory if one exists.