{"id":15937,"library":"windmill-client","title":"Windmill Client SDK","description":"The Windmill Client is the official JavaScript/TypeScript SDK for interacting with the Windmill API, designed for both browser and Node.js environments. It simplifies API calls, variable management, and task execution within the Windmill ecosystem. Currently at version 1.688.0, the package follows a rapid release cycle, suggesting frequent updates and feature additions. Its primary purpose is to provide a robust, type-safe interface for integrating Windmill functionalities into applications, abstracting away direct HTTP requests and handling authentication and data serialization. It's a key tool for developers building applications that leverage Windmill for backend tasks, workflows, or serverless functions by providing a consistent client experience across different JavaScript runtimes.","status":"active","version":"1.688.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install windmill-client","lang":"bash","label":"npm"},{"cmd":"yarn add windmill-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add windmill-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the Fetch API implementation for Node.js environments. It's a direct dependency for network requests.","package":"undici","optional":false}],"imports":[{"note":"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.","wrong":"const wmill = require('windmill-client');","symbol":"*","correct":"import * as wmill from 'windmill-client';"},{"note":"Use named imports for specific functions to enable tree-shaking and clearer code. The package ships with TypeScript types.","symbol":"getVariable","correct":"import { getVariable } from 'windmill-client';"},{"note":"The primary client class for advanced configuration or direct API access. Useful for initializing the client with custom options like 'apiUrl' and 'apiToken'.","symbol":"Windmill","correct":"import { Windmill } from 'windmill-client';"}],"quickstart":{"code":"import { Windmill } from 'windmill-client';\n\nasync function runExample() {\n  // Initialize the client. For Node.js, ensure WINDMILL_API_TOKEN is set in environment variables.\n  // For browsers, an API token might be provided client-side or retrieved securely.\n  // Replace 'https://app.windmill.dev/api/' with your Windmill instance URL if self-hosting.\n  const client = new Windmill({\n    apiUrl: process.env.WINDMILL_API_URL || 'https://app.windmill.dev/api/',\n    // In a real application, retrieve the token securely (e.g., from environment variables,\n    // a secure store, or a browser cookie/local storage with appropriate security measures).\n    // This example assumes it's available as an environment variable for Node.js.\n    apiToken: process.env.WINDMILL_API_TOKEN ?? '' // Ensure token is provided securely\n  });\n\n  try {\n    // Retrieve a variable from Windmill\n    // Replace 'u/foo/my_variable' with the actual path to your variable\n    const myVariable = await client.getVariable('u/foo/my_variable');\n    console.log('Retrieved variable:', myVariable);\n\n    // Example: Run a script\n    // await client.runScript('u/bar/my_script', { payload: { data: 'test_data' } });\n    // console.log('Script executed successfully.');\n\n  } catch (error) {\n    console.error('Error interacting with Windmill:', error);\n    if (error instanceof Error) {\n        console.error('Error message:', error.message);\n    }\n  }\n}\n\nrunExample();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"Hardcoding API tokens or exposing them in client-side browser code is a significant security risk. API tokens grant access to your Windmill resources.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<18.0.0 (Node.js)"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The provided API token is missing, invalid, or expired.","error":"Error: Request failed with status code 401 (Unauthorized)"},{"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.","cause":"The requested resource (e.g., variable, script path) does not exist or the client lacks permission to access it.","error":"Error: Request failed with status code 404 (Not Found)"},{"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.","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.","error":"ReferenceError: fetch is not defined"}],"ecosystem":"npm"}