# Mongonaut

## Contributing

> Category: Community

---

## Pages

- [About Mongonaut](https://mongonaut.org/about-mongonaut)
- [Installation](https://mongonaut.org/installation)

### Security

- [Authentication](https://mongonaut.org/security/authentication)
- [Zero Trust Tunnel](https://mongonaut.org/security/zero-trust-tunnel)

### Community

- [FAQ](https://mongonaut.org/community/faq)
- [Contributing](https://mongonaut.org/community/contributing)

---

# Contributing to Mongonaut

Mongonaut is an open source project under the [MIT License](https://github.com/withzu/mongonaut/blob/master/LICENSE). Contributions of any kind are welcome, from typo fixes in the docs to new features.

## Ways to contribute

- **Report a bug** open an issue on [GitHub](https://github.com/withzu/mongonaut/issues) with steps to reproduce, expected and actual behaviour, and the Mongonaut and MongoDB versions you are on.
- **Suggest a feature** open an issue describing the use case before sending a pull request. This avoids spending time on something that does not fit the direction of the project.
- **Send a pull request** for code or documentation changes. Small focused PRs are easier to review and ship.
- **Improve the documentation** the wiki you are reading right now is part of the project, corrections and clarifications are very welcome.

## Local development setup

Mongonaut is a [Next.js 16](https://nextjs.org/) application with [React 19](https://react.dev/), [TypeScript](https://www.typescriptlang.org/), [Tailwind CSS](https://tailwindcss.com/) and the official [MongoDB Node.js driver](https://www.mongodb.com/docs/drivers/node/current/).

### Prerequisites

- [Node.js 24](https://nodejs.org/) or newer
- [pnpm 10](https://pnpm.io/) (the project's package manager)
- A running MongoDB. The repository ships a `docker-compose.yml` that starts a local instance on port `27017`.

### Setup

```bash
git clone https://github.com/withzu/mongonaut.git
cd mongonaut
pnpm install

# Start a local MongoDB in another terminal
docker compose up -d

# Start the dev server
pnpm dev
```

Mongonaut is now available at [http://localhost:3000](http://localhost:3000) and talks to `mongodb://localhost:27017` by default. To point at a different MongoDB, create a `.env.local` file:

```env name=".env.local"
MONGO_CONNECTION_URL=mongodb://user:pass@host:27017
```

## Project layout

```
src/
  actions/        Server actions exposed to the UI
  app/            Next.js App Router (UI routes, API routes)
    (app)/        Authenticated application shell, database views
    api/auth/     Login, logout, session and OIDC routes
    login/        Login page
  components/     Reusable UI components
  hooks/          React hooks
  lib/
    auth/         Auth config, session signing, OIDC client
    errors/       Typed error classes
    types/        Shared TypeScript types
    env.ts        Small helpers around process.env
    mongoController.ts   Wrapper around MongoClient with all DB operations
```

If you are adding a new MongoDB operation, the pattern is to extend `MongoController`, expose it through a server action in `src/actions/databaseOperation.ts`, and consume it from the UI.

## Code style

- TypeScript everywhere, no implicit `any`.
- ESLint and Prettier enforce style. Run them locally before opening a PR:

```bash
pnpm lint
pnpm test:format
pnpm format   # auto fix formatting
```

- Avoid introducing new runtime dependencies unless there is a clear reason. Mongonaut intentionally stays small.
- For UI work, prefer composing existing primitives from `src/components/ui` over pulling in a new component library.

## Authentication and server actions

Mongonaut uses Next.js server actions for everything that touches MongoDB. When you add a new action that mutates data, make sure it respects the read only mode (`MONGONAUT_READONLY=true`) and, if applicable, requires an authenticated session.

The auth layer lives in `src/lib/auth`. See the [Authentication](/security/authentication) page for an overview of the available modes and how sessions are signed.

## Submitting a pull request

1. Fork the repository and create a feature branch from `master`.
2. Make focused commits with descriptive messages. Conventional commit prefixes like `feat:`, `fix:`, `docs:`, `chore:` are appreciated.
3. Run `pnpm lint` and `pnpm test:format` before pushing.
4. Open a pull request against `master` with a short description of what changed and why. Reference the related issue if there is one.
5. Be patient and responsive to review feedback. Reviews aim to keep the codebase consistent, not to gatekeep.

## License

By contributing to Mongonaut you agree that your contributions are licensed under the [MIT License](https://github.com/withzu/mongonaut/blob/master/LICENSE).