Kudu API Wrapper for Node.js

1.4.1 · abandoned · verified Wed Apr 22

The `kudu-api` package provides a Node.js wrapper for interacting with the Kudu REST API, a service primarily used within Azure App Service environments for managing deployments, executing commands, and accessing the file system. With its current stable version at 1.4.1, the package simplifies programmatic interactions by offering distinct modules for source control, command execution, virtual file system operations, zip archive handling, and deployment management. It abstracts away direct HTTP request handling, providing a callback-based interface for common Kudu operations. As indicated by its last publish date approximately ten years ago and lack of recent activity on its GitHub repository, the project appears to be abandoned, with no active development or planned releases. This means it primarily targets CommonJS environments and older Node.js versions, and users should be aware of potential compatibility issues with modern JavaScript ecosystems.

Common errors

```
TypeError: kudu is not a function
```
cause Attempting to use `kudu-api` directly after an `import` statement in an ES Module context, or calling it without passing the configuration object.

fix Ensure you are using `const kudu = require('kudu-api')({ website: '...', username: '...', password: '...' });`. The `require` statement immediately returns a factory function that needs to be invoked with the configuration object.
```
Error: unable to get local issuer certificate
```
cause This error typically occurs when Node.js cannot verify the SSL certificate of the Kudu endpoint. This can happen in restrictive network environments or with older Node.js versions.

fix Ensure your Node.js environment has up-to-date CA certificates. You might temporarily or for testing purposes set `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';`, but this is not recommended for production due to security implications.
```
'npm' is not recognized as an internal or external command, operable program or batch file.
```
cause This error often occurs when attempting to execute `npm` commands via `kudu.command.exec` if the Kudu environment's PATH variable does not correctly include the Node.js/npm installation directory, or if the command is run in a context where `npm` is not available.

fix Verify that the Kudu environment for your Azure App Service has Node.js and npm correctly configured and accessible in the system's PATH. For custom deployments, you might need to explicitly specify the full path to `npm` or ensure the command is executed in an appropriate directory.

Warnings

breaking The package is CommonJS-only and does not provide native ES Module support. Attempting to `import` it directly in an ESM environment will result in errors without specific loader configurations or transpilation.
Fix: Use `const kudu = require('kudu-api')` for Node.js projects, or a CommonJS-compatible bundler for browser environments. Consider using a modern HTTP client to interact directly with the Kudu REST API for new projects.
deprecated This package is effectively abandoned, with no updates in over 10 years. It uses callback-based asynchronous patterns which are less common in modern JavaScript in favor of Promises or async/await. There will be no security updates, bug fixes, or new features.
Fix: For new projects, consider implementing direct HTTP calls to the Kudu REST API using a modern HTTP client library (e.g., `axios`, `node-fetch`), which allows for promise-based syntax.
gotcha Authentication to the Kudu API requires basic authentication using deployment credentials (username and password). Storing these directly in code is a security risk. Kudu URLs also typically use a specific `scm` subdomain (e.g., `https://mysite.scm.azurewebsites.net/`).
Fix: Always use environment variables or a secure configuration management system to pass sensitive credentials. Ensure the `website` URL includes the `scm` subdomain for Kudu API endpoints.
gotcha The `kudu.vfs.uploadFile` method by default uses `If-Match: *`, which overwrites existing files. If you provide a specific ETag, the upload will only succeed if the server's ETag matches, otherwise it will return an error object indicating a mismatch.
Fix: When calling `kudu.vfs.uploadFile`, be mindful of the ETag parameter. If you need to conditionally update a file, first retrieve its ETag using `getFile` or `listFiles`.

Install

npm install kudu-api npm
yarn add kudu-api yarn
pnpm add kudu-api pnpm

Imports

kudu

wrong:

import kudu from 'kudu-api'; // CommonJS-only
import { kudu } from 'kudu-api'; // No named exports

correct:

const kudu = require('kudu-api')({ website: '...', username: '...', password: '...' });

This package is CommonJS-only and exports a factory function as its default. It is not compatible with ES Modules without a transpilation step or a CommonJS loader.

Quickstart

This quickstart demonstrates how to initialize the Kudu API client and perform basic operations like getting SCM info, executing a command, and listing files in the virtual file system.

const kudu = require('kudu-api')({
  website: process.env.KUDU_WEBSITE ?? 'your-website-name',
  username: process.env.KUDU_USERNAME ?? '$your-deployment-username',
  password: process.env.KUDU_PASSWORD ?? 'your-deployment-password'
});

kudu.scm.info(function(err, info) {
  if (err) {
    console.error('Error getting SCM info:', err);
    return;
  }
  console.log('SCM Info:', info);
});

kudu.command.exec("echo %CD%", function(err, result) {
  if (err) {
    console.error('Error executing command:', err);
    return;
  }
  console.log('Command Output:', result.Output);
});

kudu.vfs.listFiles("site", function(err, files) {
  if (err) {
    console.error('Error listing VFS files:', err);
    return;
  }
  console.log('Files in site folder:', files.map(f => f.name));
});

// Note: For real usage, ensure environment variables KUDU_WEBSITE, KUDU_USERNAME, KUDU_PASSWORD are set.

view raw JSON →