How to Integrate Bolt.new with Box

Create a Box application in the Box Developer Console at developer.box.com/console. Click 'Create New App', select 'Custom App', then choose 'User Authentication (OAuth 2.0)' — this is the standard flow for apps that access files on behalf of users. Give your app a name and finish creation. On the app configuration page, the Configuration tab shows your Client ID and Client Secret. Under OAuth 2.0 Redirect URI, add your Netlify callback URL: https://your-app.netlify.app/api/auth/box/callback. Also add http://localhost:3000/api/auth/box/callback for local development (Box allows multiple redirect URIs). Under Application Scopes, enable the permissions your app needs: Read all files and folders stored in Box (read access), Write all files and folders stored in Box (upload/delete), Manage enterprise properties (only needed for metadata and enterprise features). For basic file operations, read + write is sufficient. Copy the Client ID and Client Secret. Add them to your .env file as BOX_CLIENT_ID and BOX_CLIENT_SECRET. Never commit these to git — Box client secrets grant access to your users' files when used with their OAuth token.

1# .env
2BOX_CLIENT_ID=your_box_client_id
3BOX_CLIENT_SECRET=your_box_client_secret
4BOX_REDIRECT_URI=https://your-app.netlify.app/api/auth/box/callback
5
6# Box folder ID for document uploads (get from Box URL: box.com/folder/{ID})
7BOX_CONTRACTS_FOLDER_ID=0  # '0' means root folder
8
9# After deployment, add to Netlify Dashboard:
10# Site Settings → Environment Variables → add all four

Install the box-node-sdk package — Box's official Node.js SDK that wraps all API calls with proper authentication handling. The SDK handles token management, request retry on 429 rate limit errors, and response parsing. Install it with npm (or prompt Bolt) — it is a pure JavaScript package with no native dependencies. The Box OAuth 2.0 flow is standard: your initiation route builds an authorization URL with your client_id, redirect_uri, and state parameter, then redirects the user to Box's login page. After authorization, Box redirects to your callback URL with an authorization code. Your callback route exchanges this code for an access_token (valid 1 hour) and refresh_token (valid 60 days). Using the box-node-sdk for token exchange: BoxSDK.getAuthorizeURL() builds the auth URL, and the SDK's TokenManager.getTokensAuthorizationCodeGrant() exchanges the code for tokens. Alternatively, you can use direct fetch() calls to Box's token endpoint — both approaches work. Store the Box access token and refresh token in httpOnly cookies. The SDK's BoxClient can be initialized with a stored token: BoxSDK.getBasicClient(accessToken) for simple token-based access, or configure the SDK with token auto-refresh using the refresh token for a seamless experience that doesn't require re-authorization every hour.

1// lib/box.ts
2import BoxSDK from 'box-node-sdk';
3
4const sdk = new BoxSDK({
5  clientID: process.env.BOX_CLIENT_ID!,
6  clientSecret: process.env.BOX_CLIENT_SECRET!,
7});
8
9export function getBoxAuthUrl(state: string): string {
10  return sdk.getAuthorizeURL({
11    response_type: 'code',
12    redirect_uri: process.env.BOX_REDIRECT_URI,
13    state,
14  });
15}
16
17export async function exchangeCodeForTokens(
18  code: string
19): Promise<{ accessToken: string; refreshToken: string }> {
20  const res = await fetch('https://api.box.com/oauth2/token', {
21    method: 'POST',
22    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
23    body: new URLSearchParams({
24      grant_type: 'authorization_code',
25      code,
26      client_id: process.env.BOX_CLIENT_ID!,
27      client_secret: process.env.BOX_CLIENT_SECRET!,
28      redirect_uri: process.env.BOX_REDIRECT_URI!,
29    }),
30  });
31  const tokens = await res.json();
32  if (tokens.error) throw new Error(tokens.error_description);
33  return {
34    accessToken: tokens.access_token,
35    refreshToken: tokens.refresh_token,
36  };
37}
38
39export function getBoxClient(accessToken: string) {
40  return sdk.getBasicClient(accessToken);
41}

With the Box SDK initialized, implement the file operations your app needs. The box-node-sdk exposes file and folder operations through a consistent API — most operations return Promises that resolve with Box item objects. Key SDK method groups: - client.folders.getItems(folderId, options) — list folder contents (pass '0' for root) - client.files.get(fileId, options) — get file metadata - client.files.download(fileId) — returns a readable stream of file content - client.files.previewLink(fileId) — generates a Box-hosted preview URL - client.files.getDownloadURL(fileId) — returns a temporary direct download URL - client.files.createSharedLink(fileId, options) — creates a shared link with access level - client.files.uploadFile(parentFolderId, filename, content) — uploads a new file - client.files.uploadNewFileVersion(fileId, content) — uploads a new version of an existing file - client.folders.create(parentFolderId, folderName) — creates a new folder Box folder/file items have a consistent structure: id, name, type ('file' or 'folder'), created_at, modified_at, size, created_by, modified_by. Files also have extension, content_version, and sha1. For file listings, items are returned in a PagingIterator — iterate with hasNextPage() and nextPage() for large folders. The Content Preview URL (from previewLink) is an HTTPS URL to Box's hosted document viewer. Embed it in an iframe for in-app document viewing without downloading the file. The preview URL requires the user to be authenticated with Box — it uses the access token implicitly for users who are already logged in to Box.

1// app/api/box/folders/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { getBoxClient } from '@/lib/box';
4
5export async function GET(request: NextRequest) {
6  const accessToken = request.cookies.get('box_at')?.value;
7  if (!accessToken) return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
8
9  const { searchParams } = new URL(request.url);
10  const folderId = searchParams.get('folderId') || '0'; // '0' = Box root folder
11
12  const client = getBoxClient(accessToken);
13
14  try {
15    const items = await client.folders.getItems(folderId, {
16      fields: 'id,name,type,size,modified_at,extension',
17      limit: 100,
18    });
19
20    const formattedItems = items.entries.map(
21      (item: {
22        id: string;
23        name: string;
24        type: string;
25        size?: number;
26        modified_at: string;
27        extension?: string;
28      }) => ({
29        id: item.id,
30        name: item.name,
31        type: item.type,
32        size: item.size,
33        modified_at: item.modified_at,
34        extension: item.extension,
35      })
36    );
37
38    return NextResponse.json({ items: formattedItems, total: items.total_count });
39  } catch (error: unknown) {
40    const e = error as { statusCode?: number; message: string };
41    if (e.statusCode === 401) return NextResponse.json({ error: 'Token expired' }, { status: 401 });
42    return NextResponse.json({ error: e.message }, { status: 500 });
43  }
44}

Build a React file browser component that uses your Box API routes to navigate folders and preview documents in-app. Box's Content Preview is the standout feature that differentiates it from simpler storage APIs — you can embed a full-fidelity document viewer for 120+ file formats in your Bolt app without any additional libraries. The Content Preview URL returned by client.files.previewLink() opens Box's hosted viewer. Embed it in an iframe: the viewer renders PDFs, Word documents, Excel spreadsheets, PowerPoint presentations, images, videos, and code files with formatting intact. The iframe requires width and height styling — 100% width and a fixed height (e.g., 700px) works well. Box's viewer automatically adjusts to the iframe dimensions. For the file browser layout, a two-panel design works well: a left sidebar for folder navigation with a folder tree, and a right panel showing the current folder's contents as a table or grid. Clicking a folder navigates into it (fetch new folder items). Clicking a file opens the preview in a modal or in the right panel. Include breadcrumb navigation showing the current path. File type icons help users quickly identify content. Box's type system distinguishes 'file' (with extension) from 'folder'. Map common extensions to icon types: pdf, docx, xlsx, pptx, txt, jpg, png, mp4. Use Lucide React icons (which Bolt includes by default) for file type representation.

1// Utility: generate Box file type icon from extension
2function getBoxFileIcon(item: { type: string; extension?: string }): string {
3  if (item.type === 'folder') return '📁';
4  const ext = (item.extension || '').toLowerCase();
5  const iconMap: Record<string, string> = {
6    pdf: '📄',
7    docx: '📝', doc: '📝',
8    xlsx: '📊', xls: '📊',
9    pptx: '📑', ppt: '📑',
10    jpg: '🖼️', jpeg: '🖼️', png: '🖼️', gif: '🖼️', webp: '🖼️',
11    mp4: '🎬', mov: '🎬', avi: '🎬',
12    mp3: '🎵', wav: '🎵',
13    zip: '📦', tar: '📦', gz: '📦',
14    txt: '📋', csv: '📋', md: '📋',
15  };
16  return iconMap[ext] || '📎';
17}
18
19// Usage in the file browser:
20// <span>{getBoxFileIcon(item)}</span>
21// <span>{item.name}</span>