Feature Development

Contribute code to FileBrowser Quantum by adding features or fixing bugs.

Prerequisites link

Before starting development:

• Go 1.25+ (see backend/go.mod)
• Node.js 18.0.0+ with npm 7.0.0+ (see frontend/package.json)
• Git
• make (for build commands)

Optional Tools link

For media features:

• ffmpeg - Thumbnails, subtitles, HEIC conversion
  • Ubuntu/Debian: sudo apt-get install ffmpeg
  • macOS: brew install ffmpeg
  • Windows: Download from ffmpeg.org

For PDF previews:

• mupdf-tools - PDF preview generation
  • Ubuntu/Debian: sudo apt-get install mupdf-tools
  • macOS: brew install mupdf-tools
  • Windows: Download from mupdf.com

Quick Start link

# 1. Clone the repository
git clone https://github.com/gtsteffaniak/filebrowser.git
cd filebrowser

# 2. Initial setup - installs dependencies and creates test config
make setup

# 3. Run in development mode with hot-reloading
make dev

What make setup does:

• Installs backend Go dependencies
• Installs frontend npm dependencies
• Creates backend/test_config.yaml for local testing

What make dev does:

• Builds frontend with hot-reloading
• Starts backend server
• Automatically rebuilds on file changes

Release Strategy link

FileBrowser uses a structured release workflow:

Branch Structure link

1. dev/vX.X.X - Development branches (may be broken/non-functional)
2. beta/vX.X.X - Beta releases with binaries
3. stable/vX.X.X - Stable releases (separated by weeks)
4. main - Latest code, triggers latest Docker image

Development Flow link

1. Feature branch created from dev/vX.X.X (e.g., my-new-feature)
2. Pull request to dev/vX.X.X
3. When ready, dev/vX.X.X promoted to beta/vX.X.X
4. Beta tested, then promoted to stable/vX.X.X

Release Cadence link

Beta: Frequent releases, may include every minor version
Stable: Separated by weeks, may skip minor versions

Example: beta/v1.1.1 → beta/v1.1.2, but stable/v1.1.1 may be skipped if stable/v1.1.2 is ready within the stable release window.

GitHub Workflow link

Automated Tests link

Every branch/PR runs:

• Unit tests: Code compilation and basic functionality
• Linting: Code standard checks
• Playwright tests: Integration tests (UI automation)

Automated Releases link

• stable/vX.X.X and beta/vX.X.X: Auto-generate releases with binaries (via goreleaser)
• main: Updates latest Docker image tag

Contributing as Unofficial Contributor link

If you don’t have write access:

1. Fork the repository
2. Create feature branch from main
3. Open pull request against main
4. Maintainer may change base to current dev/vX.X.X branch

Pull Request Requirements link

• ✅ Clear description of why it was opened
• ✅ Short descriptive title
• ✅ Passes unit and integration tests
• ✅ Additional details for functionality not covered by tests

Project Architecture link

Backend (Go) link

• Entry Point: backend/main.go → backend/cmd/
• HTTP Server: backend/http/ - API routes, middleware, auth
• Storage: BoltDB via backend/database/storage/
• Authentication: Multiple providers in backend/auth/
• Indexing: Real-time search in backend/indexing/
• Previews: Image/video/document generation in backend/preview/

Frontend (Vue.js + TypeScript) link

• Framework: Vue 3 + Vite + TypeScript
• State: Custom store in frontend/src/store/
• API Client: Axios-based in frontend/src/api/
• i18n: 25+ languages with English as main
• Components: Feature-based organization

Development Commands link

Essential Commands link

make dev          # Start development server with hot-reloading
make test         # Run all tests
make lint         # Check code quality
make check-all    # Lint + tests (run before PR)

make build-frontend  # Build frontend only
make build-backend   # Build backend only
make build          # Build Docker image

Testing Commands link

make test              # All tests
make test-backend      # Go tests with race detection
make test-frontend     # Frontend unit tests
make test-playwright   # E2E tests in Docker

Frontend-Specific link

cd frontend
npm run lint:fix   # Auto-fix linting issues
npm run i18n:sync  # Sync translation changes

Windows Development link

Windows requires manual build process:

# Compile frontend
cd frontend
npm run build-windows

# Run backend
cd ../backend
go run . -c test_config.yaml

Testing link

Test Coverage link

cd backend
./run_check_coverage.sh  # Coverage report with HTML output

View report: Open backend/coverage.html after running.

Coverage Requirements:

• Maintain 80%+ coverage for critical packages
• CI enforces coverage checks
• Use go test -cover for quick package coverage

E2E Tests link

Playwright tests run with three authentication modes:

• Standard authentication
• No authentication
• Proxy authentication

make test-playwright  # Run all E2E tests

Performance Testing link

cd backend
./run_benchmark.sh  # Run benchmarks

Contributing as Official Contributor link

Official contributors have write access:

• Follow release strategy directly (no fork needed)
• Handle incoming PRs
• Answer GitHub issues/discussions
• Manage releases

To become an official contributor, email info@quantumx-apps.com with your GitHub username and contribution history.

Getting Help link

• Wiki: Project Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Roadmap: Project Roadmap

Troubleshooting link

For common development issues, see the Troubleshooting guide.

Code Standards link

Backend (Go) link

• Linting: backend/.golangci.yml with 30+ checks
• Format: Use gofmt (automated in CI)
• Testing: Maintain 80%+ coverage
• Errors: Handle all errors explicitly
• Style: Follow existing patterns in the codebase

Frontend (Vue.js) link

• Linting: ESLint with Vue 3 + TypeScript rules
• i18n: English is master locale, all text must use $t('key')
• Types: Use TypeScript everywhere
• Fix: Run npm run lint:fix before committing
• Components: Use Vue 3 Composition API

Configuration link

• Test Config: backend/test_config.yaml (auto-generated by make setup)
• Never commit test configuration changes
• Use environment variables for secrets

Pull Request Process link

Before Submitting link

1. Fork and branch: Create a feature branch from main
2. Make changes: Follow code standards and existing patterns
3. Test: Run make dev to test your changes locally
4. Verify: Run make check-all to ensure tests and linting pass
5. Document: Update documentation if needed

PR Requirements link

• ✅ Clear description of changes
• ✅ All tests must pass
• ✅ Follows existing code patterns
• ✅ Updated documentation (if applicable)
• ✅ No new linting errors

Commit Format link

Use conventional commits:

type(scope): description

Types: feat, fix, docs, refactor, test, chore

Examples:

feat(search): add fuzzy search support
fix(auth): resolve OIDC callback redirect issue
docs(api): update share endpoint documentation

Build & Deployment link

Single Binary Build link

The project builds into a single binary with embedded frontend:

make build-frontend  # Build Vue.js app
make build-backend   # Build Go binary with embedded assets

The frontend is embedded into the Go binary, creating a portable executable.

Docker Build link

make build  # Full image with ffmpeg and muPDF

Includes:

• FileBrowser binary
• FFmpeg for media processing
• muPDF tools for PDF previews

Next Steps link

• Translation guide
• Documentation guide