TideMeter
Skip to Content
Contributing

Contributing

We welcome contributions to TideMeter! Whether it’s fixing bugs, adding features, improving documentation, or spreading the word — every contribution matters.

Getting Started

1. Fork and Clone

git clone https://github.com/YOUR-USERNAME/tidemeter.git
cd tidemeter

2. Install Dependencies

pnpm install

3. Set Up the Dev Environment

cp .env.example .env
docker compose -f docker/docker-compose.yml up -d
pnpm dev

4. Make Your Changes

Create a new branch for your work:

git checkout -b feature/your-feature-name

Code Conventions

TideMeter follows strict coding conventions:

  • TypeScript strict mode — No any types unless absolutely necessary
  • Named exports — For all modules (no default exports except Next.js pages/layouts)
  • Functional patterns — Pure functions, immutable data where practical
  • No .js extensions — In TypeScript imports (Turbopack doesn’t resolve them)
  • Tailwind CSS 4 — CSS-first config with @theme in globals.css
  • cn() utility — From @tidemeter/ui for class merging

Project Structure

apps/web/src/
├── app/              # Next.js App Router
├── components/       # React components
├── hooks/            # Custom React hooks
├── lib/              # Utilities and business logic
└── payload/          # PayloadCMS collections

packages/
├── analytics/        # Database adapters and schema
├── tracker/          # Tracking script
├── ui/               # Shared UI components
└── tsconfig/         # Shared TS configs

Testing

Run all tests before submitting:

pnpm test

Run tests for a specific package:

pnpm --filter @tidemeter/analytics test

Build Check

Always verify the build passes:

DATABASE_URL="postgresql://x:x@localhost:5480/x" pnpm build

Note: The web app build requires DATABASE_URL to be set (even a dummy value works for type-checking).

Pull Request Guidelines

  1. Keep PRs focused — One feature or fix per PR
  2. Write clear descriptions — Explain what and why
  3. Add tests — For new features and bug fixes
  4. Follow conventions — Match the existing code style
  5. Update docs — If your change affects user-facing behavior

Important Boundaries

  • Do NOT modify files in old1/ or old2/ directories
  • Do NOT commit .env or secrets
  • Do NOT use middleware.ts — Use proxy.ts (Next.js 16 pattern)
  • Do NOT use .js extensions in TypeScript imports

Reporting Issues

Found a bug? Please open an issue  with:

  1. Steps to reproduce
  2. Expected behavior
  3. Actual behavior
  4. Environment details (OS, Node.js version, browser)

License

By contributing, you agree that your contributions will be licensed under the MIT License.

DeploymentFAQ