Skip to main content
This section contains tools, guides, and best practices for developing on the Tuturuuu platform.

​
Getting Started

​
Development Workflow

​
Documentation

  • Documenting - How to write and maintain documentation

​
Development Guidelines

​
Code Quality

  • Formatting and linting are handled by Biome (biome.json), not ESLint or Prettier. Use bun ff to format, lint, and check in one pass.
  • Run bun check before opening a PR — it is the repo’s verification gate for TypeScript, JavaScript, root-script, and config changes (run focused tests first).
  • Default to Server Components in apps/web; add 'use client' only for state, browser APIs, or interactivity.
  • Prefer typed expected errors and dependency services via @tuturuuu/utils/effect for new server/service orchestration.

​
Git Workflow

  • Use Conventional Commits for commit messages and branch names.
  • The branch checker only accepts these prefixes: feature/, feat/, fix/, bugfix/, hotfix/, release/, chore/, docs/, style/, refactor/, perf/, dependabot/, and claude/.
  • Keep commits atomic and write descriptive PR descriptions.
  • Do not manually bump TUTURUUU_PLATFORM_VERSION, package versions, or changelogs — Release Please owns version updates.

​
Testing

  • Tests run with Vitest. Use bun test for the full suite or filter to a single workspace (for example bun --filter @tuturuuu/web test).
  • Write unit tests for utilities and cover error scenarios.
  • Run focused tests before the full bun check gate.

​
Performance

  • Default to server-side rendering and Server Components where possible.
  • Use TanStack Query for client-side fetching and caching; avoid useEffect for data fetching.
  • Minimize bundle size and profile performance regularly.

​
Tools and Scripts

​
Package Management

Dependencies are always installed from inside the owning workspace — never by hand-editing the root package.json and never with a --workspace flag. 
# Install all dependencies
bun install

# Add a dependency to an app (e.g. apps/web)
cd apps/web && bun add <package>

# Add a dependency to a shared package (e.g. packages/ui)
cd packages/ui && bun add <package>

# Update dependencies across the monorepo
bun update-all

​
Development Commands

# Start all apps
bun dev

# Start a specific app
bun dev:web

# Run tests (Vitest)
bun test

# Run the full verification gate before a PR
bun check

​
Database Commands

# Start the local Supabase stack
bun sb:start

# Create a new migration
bun sb:new

# Apply pending migrations locally
bun sb:up

# Generate TypeScript types from the local schema
bun sb:typegen

# Reset the local database (re-runs all migrations + seeds)
bun sb:reset
bun sb:push and bun sb:linkpush push migrations to the remote Supabase project and are reserved for the maintainer applying production changes. Do not run them — prepare migrations locally with bun sb:up and let the user apply production changes.

​
Troubleshooting

​
Common Issues

  1. Build / Check Failures: Run bun check to surface TypeScript and Biome errors, and confirm dependencies are installed with bun install
  2. Database Issues: Ensure the local Supabase stack is running (bun sb:start) and migrations are applied (bun sb:up)
  3. Test Failures: Check environment setup and re-run the focused Vitest workspace before the full bun check gate
  4. Performance Issues: Use React DevTools and bundle analyzers

​
Getting Help

  • Check existing documentation
  • Search GitHub issues
  • Ask in team channels
  • Create detailed bug reports

​
Contributing

When contributing to the platform:
  1. Read the relevant documentation
  2. Follow the established patterns
  3. Write tests for new features
  4. Update documentation
  5. Submit a pull request with a clear description