Skip to main content

Contributing to OpenBucket

Thanks for your interest in improving OpenBucket! This guide covers the dev setup, the Node requirements, and the workflow for changes.

By participating you agree to abide by our Code of Conduct.

Prerequisites​

  • Node.js 22 (>= 22.12) — a single version runs the whole stack: the backend (NestJS + libsql) and the frontend (Angular). It matches what CI and the Docker image use and is pinned in .nvmrc:

    nvm install 22 && nvm use 22   # or, with fnm: fnm use
    npm ci

    Earlier the backend needed Node 20 and the frontend Node 23 — that split is gone. Node 22 satisfies both: Angular 21 requires >= 22.12, and the SQLite driver (libsql) ships N-API prebuilds that are ABI-stable across Node majors (so no native compile is needed, on any supported Node).

  • A C/C++ toolchain is only required if a native-module prebuilt isn't available for your platform (libsql, argon2). On common platforms npm ci downloads prebuilts and no compiler is needed. If you do need to compile: python3 + make + a compiler (build-essential on Debian/Ubuntu, Xcode CLT on macOS, or the Visual Studio "Desktop development with C++" workload on Windows).

Setup​

git clone https://github.com/ProjectBay/openbucket.git
cd openbucket
npm ci

Common tasks​

This is an Nx workspace; run targets with nx <target> <project>.

# --- Backend ---
nx serve openbucket-backend            # run the standalone app
nx build openbucket-backend            # webpack bundle → dist/apps/openbucket-backend
nx test  nestjs                        # unit tests for the library/backend
nx e2e   openbucket-backend-e2e        # end-to-end (spawns the built app)

# --- Frontend ---
nx serve openbucket-frontend           # Angular dev server (port 4200)
nx build openbucket-frontend           # production SPA build

# --- Docs site (this site) ---
nx serve docs                          # Docusaurus dev server
nx build docs                          # static build → apps/docs/build

# --- Everything ---
nx run-many -t lint                    # ESLint across all projects
nx run-many -t test                    # all unit suites

The docs site (apps/docs) keeps its own dependencies outside the npm workspaces, so run npm --prefix apps/docs ci once before nx serve docs / nx build docs.

Running a single test file​

The repo uses Jest 30, whose flag is plural: --testPathPatterns (the old singular --testPathPattern is silently ignored and runs everything).

nx test nestjs --testPathPatterns="spa.controller"

Building the publishable library​

@openbucket/nestjs bundles the admin SPA, so building it is two steps:

nx build openbucket-frontend           # build the SPA
nx bundle-spa nestjs                    # tsc build + copy SPA → dist/libs/nestjs/assets/spa
# publishable artifact is dist/libs/nestjs

Releases are automated: pushing a nestjs-v<version> tag triggers the release workflow.

Code style​

  • Prettier + ESLint are enforced; run nx run-many -t lint and npx prettier --write . before pushing. An .editorconfig keeps editors consistent (LF, UTF-8, 2-space indent).
  • Match the surrounding code: comment density, naming, and idioms.
  • TypeScript strictness is on — no any escape hatches in new code.

Commit & PR workflow​

  1. Branch off main (feat/…, fix/…, docs/…).
  2. Use Conventional Commits for messages — e.g. feat(admin-ui): add bucket object-lock editor, fix(s3): …, docs(pkg): …, test(pkg): …. Scope by area.
  3. Keep PRs focused. Add or update tests for behavior changes. Update docs / CHANGELOG.md (the Unreleased section) when relevant.
  4. Open a PR against main. CI must be green — it's the functional gate.
  5. A maintainer reviews and merges.

Reporting bugs & requesting features​

Use the issue templates. For security vulnerabilities, do not open a public issue — follow SECURITY.md.

Project layout​

See Architecture for the repository layout, and the Whitepaper for the design in depth.