Curated meta-package for building on Box with JavaScript and TypeScript: one install surface anchored on the official SDK (and CLI), structured so additional Box developer tools can ship here over time.
For AI Agents & LLMs: See
llms.txtfor complete usage guide.
Add the box package to your project to use the Box SDK via subpath imports and the box CLI. Pick the command for your package manager:
npm
npm install boxYarn
yarn add boxBefore using this package, you need:
- A Box account - If you don't have one, you can create a free developer account at developer.box.com
- A Box Platform App - Create one at Box Developer Console
- Authentication credentials - Choose based on use case:
- Developer Token: Quick testing (expires in 60 minutes) - Generate in Developer Console → Configuration → Developer Token
- OAuth 2.0: User-based authentication for apps where users sign in with Box. Ideal for web or mobile integrations.
- Server Auth – JWT: Server account authentication without user sign-in. Ideal for automations and backend systems.
- Client Credentials Grant: Server account authentication with its own account to grant permissions. Ideal for internal tools and data pipelines.
For detailed setup instructions, see the Box Authentication Documentation.
The box package is a thin meta-package: it does not hide a new API. It exposes official Box tools through a small set of entry points so you can install once and stay on supported combinations of versions.
At a glance
- CLI — The
boxexecutable comes from@box/cli(Box CLI). Run it with your package manager’s usual patterns, for examplenpx box,yarn box, orpnpm exec boxafter a local install, or ephemeral runs such aspnpm dlx box/yarn dlx boxwhen you prefer not to add a dependency first. - Node SDK — The Box Node SDK (
box-node-sdk) is available under thebox/sdksubpath and nestedbox/sdk/*imports (see Usage).
Export architecture (current surfaces)
| Surface | Upstream | How you use it |
|---|---|---|
| CLI | @box/cli |
Shell: npx box …, yarn box …, pnpm exec box …, or other package-manager equivalents; same binary whether box is a project dependency or pulled ad hoc. |
| Node SDK | box-node-sdk |
import / require from box/sdk, box/sdk/managers, box/sdk/schemas, etc. (see Import from box). |
More rows will be added to the table above as additional Box developer tools are bundled into this package.
This is a namespace package. Import specific modules using subpath imports:
The npm package name is box, but the root entry has no exports. Use subpath imports such as box/sdk:
// ❌ This won't work - root has no exports
import something from 'box';
// ✅ Use subpath imports instead
import { BoxClient } from 'box/sdk';Available subpaths
| Subpath | Description |
|---|---|
box/sdk |
Main Box Node SDK - client and authentication |
box/sdk/managers |
All API resource managers (Files, Folders, Users, etc.) |
box/sdk/schemas |
TypeScript types and schema definitions |
box/sdk/parameters |
API method parameters and options |
box/sdk/networking |
Network client and session management |
box/sdk/serialization |
Serialization and deserialization utilities |
box/sdk/internal |
Internal utilities (advanced use) |
The official Box Node SDK (box-node-sdk) is re-exported from box/sdk. The other box/sdk/* paths in the table above map to the same SDK (managers, schemas, parameters, and so on).
Example
import { BoxClient, BoxDeveloperTokenAuth } from 'box/sdk';
// Get a developer token from: https://app.box.com/developers/console
// Navigate to the app → Look at the Right hand side → Generate Developer Token
const token = process.env.BOX_DEVELOPER_TOKEN; // Store in .env file, NEVER commit!
async function main() {
const auth = new BoxDeveloperTokenAuth({ token });
const client = new BoxClient({ auth });
const entries = (await client.folders.getFolderItems('0')).entries;
entries.forEach((entry) => console.log(entry));
}
void main();For production use, choose another *Auth class from box/sdk (for example BoxCcgAuth, BoxJwtAuth) as in the Box Node SDK docs.
This package also includes the Box CLI:
npx box --helpCommand and topic guides live in the Box CLI docs in the upstream repo. For authentication (developer token, JWT, CCG, OAuth, box login, environments), follow Authentication in the Box CLI.
- Node.js: 22.0.0 or higher
- TypeScript: 5.0 or higher (optional)
- Dual ESM/CJS support - Works with both
importandrequire() - Full TypeScript support - Complete type definitions
- Tree-shaking compatible - Excellent tree-shaking: type imports (0 bytes), auth classes (~67 KB), specific managers (~91 KB), vs full BoxClient (845 KB).
- Browser compatible - ESM builds work in modern browsers
- Zero runtime overhead - Pure re-exports of official packages
- llms.txt - Complete guide for AI agents and LLMs
- Box Node SDK docs
- Box Platform API Reference
- Box CLI docs
For information on how to contribute to this project, please see the Contribution guidelines.
Need to contact us directly? Browse the issues tickets! Or, if that doesn't work, file a new one and we will get back to you. If you have general questions about the Box API, you can post to the Box Developer Forum.
Copyright 2026 Box, Inc. All rights reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.