NextExplorer

Appearance

Contributing to nextExplorer ​

Thanks for helping improve nextExplorer! This guide keeps contributions smooth, minimal, and maintainable.

Ways to Contribute ​

  • Report bugs and propose features via GitHub Issues.
  • Improve docs and examples in docs/.
  • Fix bugs or add focused enhancements.

Code Style (Keep It Simple) ​

  • Modular, clean, minimal. Avoid unnecessary code and deps.
  • Use project libraries and patterns instead of reinventing: Vue 3 + Pinia + Axios on the frontend; Express + Pino on the backend.
  • Prefer small, composable functions. Clear names over comments; comment only where needed.
  • Handle errors explicitly. Never log secrets or tokens.
  • Keep changes focused; one concern per PR.

Project Layout ​

  • frontend/ – Vue 3 + Vite app (Pinia, TailwindCSS, Vitest, ESLint).
  • backend/ – Express API (Node 24, Pino logging, OIDC via express-openid-connect).
  • docs/ – VitePress docs (site content and guides).
  • Dockerfile – Multi-stage build packaging the full app.

Prerequisites ​

  • Node.js 24 (the version the image and CI run) and npm 9+.
  • Docker + Docker Compose v2 (optional, recommended for end-to-end dev).
  • FFmpeg/ffprobe available if running backend outside Docker.

Local Development ​

Option A — single-port dev via Compose (recommended):

docker compose -f docker/docker-compose.development.yml up --build
  • Frontend served at http://localhost:3000.
  • Backend listens on 3001 inside the Compose network; Vite proxies API calls.

Option B — run services locally in two terminals:

# Terminal 1: backend
npm install
PORT=3001 CONFIG_DIR=$PWD/.config CACHE_DIR=$PWD/.cache
npm run dev -w backend

# Terminal 2: frontend
VITE_BACKEND_ORIGIN=http://localhost:3001 npm run dev -w frontend

Environment tips:

  • Set PUBLIC_URL when running behind a reverse proxy; OIDC defaults derive from it.
  • OIDC: set OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, optional OIDC_SCOPES/OIDC_ADMIN_GROUPS.
  • OnlyOffice (optional): ONLYOFFICE_URL, ONLYOFFICE_SECRET, ONLYOFFICE_LANG.

Tests & Linting ​

  • Backend tests (Vitest + supertest):
cd backend && npm test
  • Frontend unit tests (Vitest):
cd frontend && npm run test:unit
  • Frontend lint (ESLint + vue):
cd frontend && npm run lint
  • Browser tests (Playwright). The app project starts the real server serving the real build, on a throwaway install, and walks through setting it up, signing in, opening a volume, uploading and sharing — so build first:
npm run build && npm run test:e2e

What CI holds every push to ​

A change in behaviour arrives with its test, in the same commit. A commit that touches backend/src or frontend/src without touching a test is refused. Some changes rightly carry none — a refactor under tests that already exist, a move, a rename — and those say so with a trailer, so the exception is a decision written down rather than something nobody noticed:

Split the share decision into the three questions it asks

No-test: pure extraction, held by tests/routes/shares.test.js

Run the same check before pushing with scripts/check-commit-tests.sh origin/main..HEAD.

Coverage does not go down. The floors live in coverage-thresholds.json and fail the test run when a figure drops below them. The frontend floors apply everywhere; the backend ones apply in CI only, because several backend suites skip themselves without 7-Zip, ffmpeg, ripgrep or pdftotext, and a machine without those covers a little less for no fault of the change. Each floor keeps half a point of room under the CI figure, so a run that happens to miss a few lines does not turn red. When a figure climbs far enough to raise its floor and still keep that room, CI says so — raise it in the same pull request, so the ground gained cannot be lost again.

Build ​

  • Production container:
docker build -t nextexplorer:dev .
  • Frontend bundle only:
cd frontend && npm run build && npm run preview

Pull Requests ​

  • Keep PRs small and atomic. Describe the problem and the approach.
  • A change in behaviour comes with its test in the same commit, or a No-test: trailer saying why (see above).
  • Update docs in docs/ and user-facing README.md when behavior or settings change.
  • Run tests and linters locally before submitting.

Checklist:

  • [ ] Focused changes; no unrelated diffs
  • [ ] Tests pass locally (backend/frontend)
  • [ ] Lint passes (frontend)
  • [ ] Docs and examples updated if needed

Commit Messages & Branching ​

  • Use clear, descriptive titles (e.g., "auth: fix token refresh on reverse proxy").
  • Reference issues where relevant (e.g., "Closes #123").
  • Branch naming: feat/*, fix/*, or docs/*.

Security ​

  • Do not include secrets in code or logs.
  • Avoid permissive TRUST_PROXY settings; rely on PUBLIC_URL-derived defaults or explicitly set safe values.
  • Report vulnerabilities privately via GitHub Security Advisories.

Where to Look First ​

  • Backend configuration: backend/config/index.js, backend/config/trustProxy.js.
  • Logging: backend/utils/logger.js (Pino).
  • Auth routes and middleware: backend/routes/auth.js, backend/middleware/authMiddleware.js.
  • Frontend state and API: frontend/src/stores/*, frontend/src/api/index.js.

Thanks again for contributing!