Development Setup

This guide gets Opndrive running locally for development. It reflects the actual scripts and tools in this repository, not idealized ones, so every command here should work as written.

Prerequisites

• Node.js 22 - Download here . The version is pinned in .nvmrc; if you use nvm, nvm use in the repo root picks it up. CI and the Dockerfile both use 22, so matching it locally avoids surprises.
• PNPM 10.7.0 - Install with npm install -g pnpm. The root package.json declares "packageManager": "pnpm@10.7.0", and CI uses the same version.
• Git - Download here 
• VS Code (recommended) - Download here 

Optional but Recommended

• AWS CLI - For S3 integration testing

Quick Start

1. Clone the Repository

git clone https://github.com/Opndrive/opndrive.git
cd opndrive

2. Install Dependencies

pnpm install

This installs every workspace listed in pnpm-workspace.yaml (frontend/, s3-api/, and docs/). It also runs the root prepare script, which sets up Husky and builds the @opndrive/s3-api workspace package.

3. Start the Development Server

pnpm dev:frontend

4. Open Your Browser

• Frontend: http://localhost:3000 

That’s it. Opndrive is configured through its UI, not environment files. The first time you visit the app you’ll see a “Get Started” button that takes you to /connect, where you enter your AWS credentials through a form. See Environment Variables for the small number of env vars the app actually reads (none of them are AWS credentials).

Project Structure Understanding

After setup, the directories you’ll touch most:

opndrive/
├── frontend/src/
│   ├── app/                 # Next.js pages and layouts
│   ├── features/            # Feature-based modules (dashboard, upload, settings, ...)
│   ├── shared/               # Reusable components
│   ├── context/              # React Context providers (auth, data, theme, ...)
│   └── services/             # Code that talks to @opndrive/s3-api
└── s3-api/                  # Workspace package, S3 integration layer

See Repository Structure for the full breakdown.

Development Workflow

1. Branch Strategy

git checkout -b feature/your-feature-name
git add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name

2. Code Quality Checks

Run these from the repository root before committing:

# Type-check both packages
pnpm typecheck
 
# Lint both packages
pnpm lint
 
# Format check
pnpm format:check
 
# Lint + format check together (what CI runs)
pnpm check

Husky runs lint-staged on every commit automatically (see .husky/pre-commit), so most formatting issues are caught before you even open a pull request.

3. Testing

pnpm --filter frontend test
pnpm --filter @opndrive/s3-api test
pnpm --filter @opndrive/s3-api test:watch
pnpm --filter @opndrive/s3-api test:coverage

Both packages use Vitest . The s3-api suite mocks the AWS SDK, so it needs no credentials and makes no network calls. There is no end-to-end test suite in this repository today. See Testing for what’s actually covered and how to add to it.

Working with Features

Adding a New Feature

mkdir -p frontend/src/features/your-feature/{components,types}
mkdir -p frontend/src/features/your-feature/components/{ui,views,layout}
touch frontend/src/features/your-feature/components/index.ts

Look at an existing feature (frontend/src/features/dashboard) for the pattern before starting a new one.

Component Template

'use client';
 
import { cn } from '@/lib/utils';
 
interface YourComponentProps {
  className?: string;
}
 
export function YourComponent({ className, ...props }: YourComponentProps) {
  return (
    <div className={cn('base-styles', className)} {...props}>
      {/* component content */}
    </div>
  );
}

Styling Guidelines

The project uses Tailwind CSS with CSS custom properties for theming, plus shadcn/ui  (configured in frontend/components.json) for component primitives.

<div className="bg-background text-foreground border border-border">
  <h1 className="text-2xl font-semibold text-primary">Title</h1>
  <p className="text-muted-foreground">Description</p>
</div>

These classes adapt automatically between light and dark mode - there’s no separate dark-mode variant to write by hand.

S3 Integration

Opndrive talks to S3 directly from the browser through the @opndrive/s3-api workspace package, wrapped by frontend/src/services/. There is no backend server in between. See S3 API Layer for what the package actually exposes (upload managers, multipart uploads, retry/concurrency helpers).

Debugging

Common Issues and Solutions

Module Resolution Errors

rm -rf frontend/.next
pnpm dev:frontend

TypeScript Errors

Restart the TS server in VS Code: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server”

Styling Not Applied

pnpm dev:frontend

Development Tools

• React DevTools - Browser extension for React debugging
• Next.js DevTools - Built-in development overlay
• Tailwind CSS DevTools - Browser extension for CSS debugging

Common Commands Reference

These are the scripts that actually exist in package.json today:

There’s no type-check (hyphenated), check-all, clean, or environment-specific build script (build:dev/build:staging/build:prod) in this repo, and no test:coverage in frontend/. If you’ve seen those referenced elsewhere, that’s stale documentation - please open an issue.

You’re all set. Continue to Repository Structure and Frontend Architecture to understand the codebase in more depth.