Skip to main content

Scripting ›dotfetch.env

تعديل على GitHub

هذا التوثيق متاح باللغة الإنجليزية.

dotfetch.env

dotfetch.env reads and writes environment variables from a script. It works in both Pre-Request and Post-Response scripts.

MethodReturnsWhat it does
get(name)string or undefinedRead a variable
set(name, value)—Create or change a session variable
unset(name)—Remove a session variable
resolve(text)stringFill in every {{VARIABLE}} in text

Where values come from

get() looks in three places and returns the first match:

CODE
1. set() earlier in this same script
2. Session variables set by earlier scripts (for the active environment)
3. The active environment's .env file

set() never writes to your .env file. It writes a session variable that lives in memory until you close the Request Builder tab. See Session variables.

get

JS
dotfetch.env.get(name)

Returns the value as a string, or undefined if the variable doesn't exist.

BASH
# .env
BASE_URL=https://api.example.com
PAGE_SIZE=20
JS
dotfetch.env.get('BASE_URL');   // 'https://api.example.com'
dotfetch.env.get('PAGE_SIZE');  // '20'  ← always a string
dotfetch.env.get('MISSING');    // undefined

Values are strings. Convert them when you need a number:

JS
const pageSize = Number(dotfetch.env.get('PAGE_SIZE') ?? 10);

Use ?? for a fallback when a variable may be missing:

JS
const region = dotfetch.env.get('REGION') ?? 'eu-west-1';

set

JS
dotfetch.env.set(name, value)

Creates or changes a session variable for the active environment. value is converted to a string.

JS
dotfetch.env.set('TS', Date.now());      // stored as '1767225600000'
dotfetch.env.set('ENABLED', true);       // stored as 'true'
dotfetch.env.set('USER', { id: 1 });     // stored as '[object Object]' ← probably not what you want
dotfetch.env.set('USER', JSON.stringify({ id: 1 })); // stored as '{"id":1}'

Used by the same request

A variable set in a Pre-Request script is filled in for the request that's about to be sent:

JS
// Pre-Request
dotfetch.env.set('TS', String(Date.now()));
Header: X-Timestamp: {{TS}} → X-Timestamp: 1767225600000

Used by later requests

A variable set in a Post-Response script is there for every request after it:

JS
// Post-Response on POST /auth/login
const { token } = dotfetch.response.json();
dotfetch.env.set('ACCESS_TOKEN', token);
CODE
Any later request:
Authorization: Bearer {{ACCESS_TOKEN}}

If a script fails, everything it set() is discarded. A half-finished script never leaves half-updated variables.

unset

JS
dotfetch.env.unset(name)

Removes a session variable once the script finishes. If the .env file has a value with the same name, that value is used again.

JS
// Post-Response on POST /auth/logout
dotfetch.env.unset('ACCESS_TOKEN');

unset() never deletes anything from your .env file.

resolve

JS
dotfetch.env.resolve(text)

Returns text with every {{VARIABLE}} filled in, exactly as DotFetch will do when sending. Unknown variables are left as {{NAME}}.

This matters in Pre-Request scripts, because the request you're looking at still contains the {{...}} placeholders:

BASH
# .env
USER_ID=42
Body: {"user":"{{USER_ID}}","action":"refund"}
JS
// Pre-Request
dotfetch.request.body;                          // '{"user":"{{USER_ID}}","action":"refund"}'
dotfetch.env.resolve(dotfetch.request.body);    // '{"user":"42","action":"refund"}'  ← what's sent

So when you sign a body, sign the resolved text:

JS
const secret = dotfetch.env.get('WEBHOOK_SECRET');
const body = dotfetch.env.resolve(dotfetch.request.body);
dotfetch.request.headers['X-Signature'] = dotfetch.crypto.hmac('sha256', secret, body);

resolve() also sees values you set() earlier in the same script:

JS
dotfetch.env.set('NONCE', 'abc');
dotfetch.env.resolve('id={{NONCE}}');  // 'id=abc'
dotfetch.env · DotFetch Docs | dotsuite