Windmill Client SDK

Common errors

• Error: Request failed with status code 401 (Unauthorized)

  cause The provided API token is missing, invalid, or expired.
  fix Verify 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)

  cause The requested resource (e.g., variable, script path) does not exist or the client lacks permission to access it.
  fix Double-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

  cause 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.
  fix Upgrade 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.

Warnings

• breaking Major 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.
  Fix: Consult the official Windmill Client release notes and migration guides for your target major version. Update client initialization, method calls, and data structures as necessary.
• gotcha Hardcoding API tokens or exposing them in client-side browser code is a significant security risk. API tokens grant access to your Windmill resources.
  Fix: For 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.
• gotcha The 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.
  Fix: Ensure 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.

Install

• npm install windmill-client npm
• yarn add windmill-client yarn
• pnpm add windmill-client pnpm

Imports

• *
  wrong:

  const wmill = require('windmill-client');

  correct:

  import * as wmill from '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'.

Quickstart

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();