Skip to main content
Ant exposes the Web Storage API — localStorage and sessionStorage — as global objects in every script. They work exactly as they do in the browser, with one important distinction: localStorage can persist its contents across separate ant invocations when you pass --localstorage-file <path>. This gives your scripts a simple key-value store that survives process restarts without adding any npm dependencies.

​
localStorage vs. sessionStorage

localStoragesessionStorage
PersistenceSurvives process exit when --localstorage-file is setLost when the process exits
ScopeShared across all scripts that use the same fileScoped to the current process
APIWeb Storage APIWeb Storage API (identical)
Without --localstorage-file, localStorage behaves exactly like sessionStorage — it is in-memory only and discarded when the process exits.

​
API reference

Both localStorage and sessionStorage implement the same interface.
​
localStorage.setItem(key, value)
void
Store value under key. Both arguments must be strings. If key already exists, its value is overwritten.
​
localStorage.getItem(key)
string | null
Retrieve the value stored under key. Returns null if the key does not exist.
​
localStorage.removeItem(key)
void
Delete key and its associated value. Has no effect if the key does not exist.
​
localStorage.clear()
void
Remove all key-value pairs from storage.
​
localStorage.length
number
The number of key-value pairs currently in storage.
​
localStorage.key(index)
string | null
Return the key at position index (zero-based). Returns null if index is out of range. The order of keys is not guaranteed to match insertion order.

​
Persisting data across runs

Pass --localstorage-file <path> to point localStorage at a JSON file on disk. Ant reads the file at startup and writes it back on exit. 
# Store a value on the first run
ant -e "localStorage.setItem('count', '1')" --localstorage-file ./storage.json
Ant creates the file if it does not exist. The file path can be absolute or relative to the working directory.

​
Example: a persistent visit counter

// counter.js
const count = parseInt(localStorage.getItem('count') || '0') + 1;
localStorage.setItem('count', String(count));
console.log('Visit number:', count);

ant counter.js --localstorage-file ./counter.json
# Visit number: 1

ant counter.js --localstorage-file ./counter.json
# Visit number: 2

ant counter.js --localstorage-file ./counter.json
# Visit number: 3
Because getItem returns null for missing keys, the || '0' fallback handles the first run cleanly without throwing.

​
Example: storing structured data

localStorage only stores strings. Serialize structured data with JSON.stringify and deserialize with JSON.parse. 
// config-store.js
const defaults = { theme: 'dark', fontSize: 14, notifications: true };

const raw = localStorage.getItem('config');
const config = raw ? JSON.parse(raw) : defaults;

// Modify a setting
config.fontSize = 16;

localStorage.setItem('config', JSON.stringify(config));
console.log('Saved config:', config);

ant config-store.js --localstorage-file ./app.json

​
Using sessionStorage

sessionStorage has the same API as localStorage but never persists to disk. Use it when you need a temporary scratch space that multiple functions can share within a single script run. 
// Accumulate results during a single run
sessionStorage.setItem('start', Date.now().toString());

// ... later in the same script ...
const start = parseInt(sessionStorage.getItem('start'));
console.log('Elapsed:', Date.now() - start, 'ms');
Prefer sessionStorage over module-level variables when you want a consistent key-value interface that mirrors what you would use in a browser context, or when the script is shared between environments.
localStorage data is stored as plain JSON in the file you specify. Do not use it to store secrets, tokens, or any sensitive information — the file is readable by any process with access to the path.