Getting Started

This guide deploys your own VercelDrive instance on Vercel. Choose the permission model first, then create the Microsoft app, deploy the project, connect Redis, and complete OAuth. For deeper setup details, keep Advanced, Custom configs, and Cache open while you work.

Prerequisites

Before you start, make sure you have:

• A Microsoft account with OneDrive access
• Access to Microsoft Azure / Entra to create an App Registration (or ask your IT admin)
• A Vercel account (free tier works)
• An Upstash Redis database (free tier works; created through Vercel Integration)
• About 15–20 minutes for the full setup

No local development tools are needed. Everything is configured through web dashboards and environment variables.

If you want to run VercelDrive locally for development, you also need Node.js 18+ and a package manager (pnpm recommended).

1. Choose Access Mode

Read-only mode

What you get: Browse, preview, search, share, and download files. No upload or delete capability.

Required Graph permissions: User.Read, Files.Read.All, offline_access

Environment variables: Do not set UPLOAD_PASSWORD. Upload endpoints are disabled.

Read/write mode

What you get: Everything from read-only, plus browser-based file and folder uploads, and file deletion.

Required Graph permissions: User.Read, Files.ReadWrite.All, offline_access

Environment variables: Set UPLOAD_PASSWORD. Optionally set UPLOAD_CONFLICT_BEHAVIOR (rename, replace, or fail).

Security: Upload and delete actions require the UPLOAD_PASSWORD on every request. The password is verified server-side.

Protected folders (optional, any mode)

What you get: Password-protect specific folders. Visitors must enter the folder password before accessing file contents.

Configuration: Set NEXT_PUBLIC_PROTECTED_ROUTES (comma-separated paths). Place a .password file inside each protected folder in OneDrive.

Note: Protected folders do not hide file names from listings or search. Only file content access is restricted.

2. Create A Microsoft Entra App

Create a Microsoft Entra App Registration for the OneDrive account you want VercelDrive to access.

1. Add the delegated Microsoft Graph permissions for the mode you selected above. See Advanced API permissions.
2. Create a client secret. See Advanced client secret.
3. Prepare the CLIENT_ID and the AES-obfuscated CLIENT_SECRET value used by VercelDrive.
4. Confirm the OneDrive account email for USER_PRINCIPAL_NAME.

3. Prepare Environment Variables

Required for both modes:

• NEXT_PUBLIC_SITE_TITLE: title shown in the UI, for example 2Drive. See Custom configs.
• USER_PRINCIPAL_NAME: OneDrive account email, for example example@outlook.com.
• BASE_DIRECTORY: OneDrive folder exposed by the site, for example / or /Public Drive. See Custom configs.
• CLIENT_ID: Microsoft Entra App Registration client ID. See Advanced.
• CLIENT_SECRET: AES-obfuscated client secret. See Advanced.
• REDIS_URL: Redis connection string, usually injected by Upstash after deployment. See Cache.

Required only for read/write uploads:

• UPLOAD_PASSWORD: server-side password required before uploads start. See Advanced password upload gate.

Useful optional variables:

• NEXT_PUBLIC_PROTECTED_ROUTES: comma-separated protected folder paths, for example /private,/family. See Password protected folders.
• NEXT_PUBLIC_EMAIL: contact email shown in the header. See Custom configs.
• KV_PREFIX: Redis key prefix when multiple deployments share one Redis database. See Cache.
• UPLOAD_CONFLICT_BEHAVIOR: upload duplicate-name behavior, one of rename, replace, or fail. See Advanced upload conflict behavior.

Do not use the NEXT_PUBLIC_ prefix for secrets, Redis values, Microsoft tokens, USER_PRINCIPAL_NAME, BASE_DIRECTORY, CLIENT_ID, CLIENT_SECRET, or UPLOAD_PASSWORD.

4. Deploy To Vercel

Use one of these deployment buttons based on the mode and variables you need.

Read-only Deploy

Browsing, previews, sharing, and downloads.

Deploy with Uploads

Adds UPLOAD_PASSWORD for read/write mode.

Read-only with Protected Routes

Adds NEXT_PUBLIC_PROTECTED_ROUTES.

Full Setup

Uploads, protected routes, email, KV prefix, and conflict behavior.

5. Connect Redis

VercelDrive stores OAuth access_token and refresh_token values in Redis. Upstash Redis is recommended on Vercel because its integration can automatically add REDIS_URL to the project.

After REDIS_URL is available, redeploy the Vercel project so the new environment variable is loaded.

6. Authenticate VercelDrive

Open your deployed site, for example https://your-project.vercel.app. VercelDrive will guide you through OAuth authorization, token exchange, and Redis token storage.