This section contains tools, guides, and best practices for developing on the Tuturuuu platform.
Getting Started
Development Workflow
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.
- 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.
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.
For a broad refresh, also update Rust (cargo update in apps/backend), Python
(uv lock --upgrade in apps/discord), and Flutter
(flutter pub upgrade --major-versions in apps/mobile). Keep native CocoaPods
locks aligned with Flutter plugins and retain stable versions when a registry’s
latest tag points at a prerelease. The configured npm release-age policy still
applies. Run bun check and affected app builds through ttr resources run.
Keep React and React DOM aligned at 19.2.8 while React Three Fiber 9.7.0
requires versions below 19.3. The root overrides also prevent transitive peer
dependencies from selecting a second runtime; revisit both overrides and
Hive workspace constraints when Fiber supports the next React minor. Keep
@types/react and @types/react-dom on the matching runtime minor as well.
Other packages retain compatible consumer ranges so the repository overrides do
not force a second React copy into published-package consumers.
React-PDF 11 requires Node.js 22.13 or newer; CI uses Node.js 24. Its default
Suspense behavior differs from version 10, so the shared PDF viewer explicitly
keeps its existing loading and error handling with suspense={false}. Mermaid 12
also changes visual defaults; the chat renderers set layout: 'dagre' and
look: 'classic' to preserve existing diagrams.
Development Commands
Database Commands
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
- Build / Check Failures: Run
bun check to surface TypeScript and Biome errors, and confirm dependencies are installed with bun install
- Database Issues: Ensure the local Supabase stack is running (
bun sb:start) and migrations are applied (bun sb:up)
- Test Failures: Check environment setup and re-run the focused Vitest workspace before the full
bun check gate
- 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:
- Read the relevant documentation
- Follow the established patterns
- Write tests for new features
- Update documentation
- Submit a pull request with a clear description
