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.
BoxClient
✓ import { BoxClient } from 'box-typescript-sdk-gen'
✗ import BoxClient from 'box-typescript-sdk-gen'
BoxClient is a named export, not default. ESM import is required for tree-shaking; CJS require is also valid.
BoxDeveloperTokenAuth
✓ import { BoxDeveloperTokenAuth } from 'box-typescript-sdk-gen'
✗ import { DeveloperTokenAuth } from 'box-typescript-sdk-gen'
Class name includes 'Box' prefix, consistent with other auth types like BoxJWT, BoxCCG.
BoxOAuth
✓ import { BoxOAuth } from 'box-typescript-sdk-gen'
✗ const BoxOAuth = require('box-typescript-sdk-gen').BoxOAuth
Both ESM and CJS work, but TypeScript expects named import for type inference.
Authenticate with a developer token and retrieve current user info and root folder contents.
import { BoxClient, BoxDeveloperTokenAuth } from 'box-typescript-sdk-gen';
const auth = new BoxDeveloperTokenAuth({ token: process.env.BOX_DEV_TOKEN ?? '' });
const client = new BoxClient({ auth });
async function main() {
const me = await client.users.getUserById({ userId: 'me' });
console.log(`Logged in as ${me.name} (${me.login})`);
const items = await client.folders.getFolderItems({ folderId: '0' });
for (const item of items.entries) {
console.log(`${item.type}: ${item.name}`);
}
}
main().catch(console.error);
Debug
Known issues
gotchaESM imports must use named exports; default import is not available.fixUse import { BoxClient } from 'box-typescript-sdk-gen' instead of import BoxClient from 'box-typescript-sdk-gen'. affects: >=1.0.0
deprecatedOld Box TypeScript SDK (non-generated) is deprecated; migrate to this SDK.fixReplace old import paths with new generated SDK.
affects: <1.0.0
breakingConstructor arguments for auth classes changed to object parameter in v1.0.0.fixPass auth config as an object: new BoxDeveloperTokenAuth({ token: '...' }). affects: >=1.0.0
gotchaNode.js >=16 required; the SDK does not work in older Node versions due to fetch and other modern APIs.fixUpgrade Node.js to version 16 or later.
affects: >=1.0.0
deprecatedCJS require() works but is not recommended; ESM is preferred for tree-shaking and type safety.fixUse ESM imports (import ... from ...).
affects: >=1.0.0
breakingIn v1.18.0, form-data was bumped to 4.0.4, which may cause issues with older Node.js fetch implementations.fixUpdate to v1.19.1 or later which fixes ESM build.
affects: >=1.18.0 <1.19.0
gotchaWebhook signature verification changed in v1.16.0: body is now escaped before signing.fixUse the updated verifySignature method which handles both escaped and unescaped bodies.
affects: >=1.16.0
Errors
Common errors & fixes
Cannot find module 'box-typescript-sdk-gen'
Package not installed or wrong import path.
fixRun 'npm install box-typescript-sdk-gen' and ensure your Node.js version is >=16.
TypeError: BoxClient is not a constructor
Default import used instead of named import (or wrong import style).
fixUse 'import { BoxClient } from 'box-typescript-sdk-gen'' (curly braces). Uncaught TypeError: Cannot read properties of undefined (reading 'getUserById')
BoxClient not properly initialized due to missing auth or invalid token.
fixEnsure authentication is set up correctly, e.g., new BoxDeveloperTokenAuth({ token: process.env.BOX_DEV_TOKEN }) and pass to BoxClient. Error: connect ECONNREFUSED 127.0.0.1:443
Network issue; the SDK cannot reach Box API endpoints.
fixCheck network connectivity and proxy settings. Ensure the environment allows outbound HTTPS requests.
Audit
Dependencies
form-datarequiredUsed for multipart form data requests
node-fetchrequiredHTTP client for API calls