Development & Contributing

This guide is for developers who clone the repository, run VideoSphere locally, change code, or update documentation.

If you only want to run VideoSphere in production (Docker, Portainer, homelab), start with the Deployment Guide on the home page instead.

First-time local setup

1. Clone the repo and run through Local Setup (environment variables, MongoDB, first admin account).
2. Follow the Daily Dev Workflow checklist before and after each coding session.

Before you open a pull request

Step	Doc
Format, lint, test, build	Daily Dev Workflow
ESLint, Prettier, export doc comments	Code Quality
Vitest and accessibility tests	Testing

Codebase reference

Topic	Doc
Uploads UI, livestreams, YouTube import, connections	Uploads, Livestreams & Distribution
MongoDB collections and platforms	MongoDB Data Model
Draft document JSON and manual upload testing	Draft Document & Upload Testing
Next.js route handlers	API Routes Guide
Generated symbol reference	API Reference and TypeDoc
TypeScript conventions	TypeScript
Accessibility expectations	Accessibility
Next.js performance patterns	Performance

Docker and production parity

• Local Docker Testing — build the production image from source and smoke-test with your .env.local before merging Dockerfile changes.

Contributor tooling (optional)

Tool	Doc
VS Code Dev Container	Dev Container
Context7 MCP (library docs in the IDE)	Context7 MCP Setup
Figma MCP (design tokens in Copilot)	Figma MCP Setup

Editing this documentation site

The docs are built with VitePress from the docs/ folder.

Command	Purpose
pnpm docs:dev	Local preview with live reload (regenerates API docs first)
pnpm docs:build	Production build — run before merging docs changes
pnpm docs:preview	Preview the built output locally
pnpm docs:api	Regenerate TypeDoc output at docs/public/typedoc

Typical workflow: edit markdown → pnpm docs:dev while writing → pnpm docs:build before opening a PR against dev.

Docs deploy automatically to videosphere.sarahpoulin.ca on pushes to main.