Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
*
✓ import * as wmill from 'windmill-client';
✗ const wmill = require('windmill-client');
Recommended for general usage to access all exports under a namespace. CommonJS 'require' is not directly supported without a build step or bundler configuration for modern ESM-first packages.
getVariable
✓ import { getVariable } from 'windmill-client';
Use named imports for specific functions to enable tree-shaking and clearer code. The package ships with TypeScript types.
Windmill
✓ import { Windmill } from 'windmill-client';
The primary client class for advanced configuration or direct API access. Useful for initializing the client with custom options like 'apiUrl' and 'apiToken'.
Demonstrates how to initialize the Windmill client, authenticate using an API token, and retrieve a variable from the Windmill API, handling potential errors and suggesting secure token management.
import { Windmill } from 'windmill-client';
async function runExample() {
// Initialize the client. For Node.js, ensure WINDMILL_API_TOKEN is set in environment variables.
// For browsers, an API token might be provided client-side or retrieved securely.
// Replace 'https://app.windmill.dev/api/' with your Windmill instance URL if self-hosting.
const client = new Windmill({
apiUrl: process.env.WINDMILL_API_URL || 'https://app.windmill.dev/api/',
// In a real application, retrieve the token securely (e.g., from environment variables,
// a secure store, or a browser cookie/local storage with appropriate security measures).
// This example assumes it's available as an environment variable for Node.js.
apiToken: process.env.WINDMILL_API_TOKEN ?? '' // Ensure token is provided securely
});
try {
// Retrieve a variable from Windmill
// Replace 'u/foo/my_variable' with the actual path to your variable
const myVariable = await client.getVariable('u/foo/my_variable');
console.log('Retrieved variable:', myVariable);
// Example: Run a script
// await client.runScript('u/bar/my_script', { payload: { data: 'test_data' } });
// console.log('Script executed successfully.');
} catch (error) {
console.error('Error interacting with Windmill:', error);
if (error instanceof Error) {
console.error('Error message:', error.message);
}
}
}
runExample();
Debug
Known issues
breakingMajor versions (e.g., v1 to v2) may introduce breaking changes to the API client's methods, parameter signatures, or class constructors to align with evolving Windmill API specifications. Always review the release notes when upgrading major versions.fixConsult the official Windmill Client release notes and migration guides for your target major version. Update client initialization, method calls, and data structures as necessary.
affects: >=1.0.0
gotchaHardcoding API tokens or exposing them in client-side browser code is a significant security risk. API tokens grant access to your Windmill resources.fixFor Node.js, use environment variables (e.g., process.env.WINDMILL_API_TOKEN). For browser applications, fetch tokens from a secure backend endpoint, use a proxy, or secure cookie-based authentication, ensuring tokens are never directly committed to source control or exposed publicly.
affects: >=1.0.0
gotchaThe SDK relies on the Fetch API. In older Node.js environments (< v18), the global 'fetch' might not be available, leading to runtime errors unless a polyfill or 'undici' is correctly configured or bundled.fixEnsure your Node.js version is 18 or higher. The package directly depends on 'undici', which provides fetch in Node.js, so ensure your bundler/runtime correctly resolves this dependency if issues persist.
affects: <18.0.0 (Node.js)
Errors
Common errors & fixes
Error: Request failed with status code 401 (Unauthorized)
The provided API token is missing, invalid, or expired.
fixVerify that 'apiToken' is correctly set during client initialization and that the token has the necessary permissions and is still active in your Windmill account. Check for typos or leading/trailing spaces.
Error: Request failed with status code 404 (Not Found)
The requested resource (e.g., variable, script path) does not exist or the client lacks permission to access it.
fixDouble-check the exact path to the Windmill resource (e.g., 'u/foo/my_variable'). Ensure the API token has read/execute permissions for that specific resource in your Windmill instance.
ReferenceError: fetch is not defined
Running in an older Node.js environment where the native Fetch API is not globally available, and 'undici' is not being correctly picked up or polyfilled.
fixUpgrade your Node.js environment to version 18 or newer. If an upgrade is not possible, ensure your build process or runtime environment explicitly makes a global 'fetch' API available, although the SDK's 'undici' dependency should handle this automatically in most modern Node setups.
Audit
Dependencies
undicirequiredProvides the Fetch API implementation for Node.js environments. It's a direct dependency for network requests.