Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

29.6 KB
Raw Blame

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Rallly is a meeting scheduling application built with Next.js that allows users to create polls to find the best meeting times. It supports both self-hosted and cloud-hosted deployments with a freemium model.

Core Technologies:

  • Next.js 16 with React 19
  • tRPC for API layer
  • Prisma with PostgreSQL
  • Better-Auth for authentication
  • TailwindCSS for styling
  • TypeScript throughout
  • Intl for all user-facing date and number formatting, wrapped in lib/datetime/ (format.ts, relative-time.tsx, duration.tsx). Converting between wall-clock times and instants goes through wallTimeToInstant/instantToWallTime in lib/datetime/wall-time.ts, which apply the time zone overrides. dayjs is legacy: it survives only for calendar arithmetic and machine-format ISO strings in the poll options form and CSV export, without its timezone plugin. Never add a new dayjs import and never use it to render a date to a user
  • Base UI (@base-ui/react) for primitives in packages/ui. Radix was removed; never reintroduce it

Development Commands

Getting Started

# Install dependencies
pnpm install

# Setup environment
cp apps/web/.env.sample apps/web/.env
cp packages/database/.env.sample packages/database/.env

# Generate Prisma client
pnpm db:generate

# Start development database
pnpm docker:up

# Reset/setup database with seed data
pnpm db:reset

# Start development server
pnpm dev

Common Commands

# Development
pnpm dev                    # Start web app dev server
pnpm dev:landing           # Start landing page dev server
pnpm dev:emails            # Start email template dev server
pnpm docs:dev              # Start docs site (Mintlify)

# Building
pnpm build                 # Build web app
pnpm build:web            # Build web app with version injection
pnpm build:landing        # Build landing page
pnpm build:test           # Build for testing

# Database
pnpm db:migrate           # Run database migrations
pnpm db:push              # Push schema changes
pnpm db:deploy            # Deploy migrations (production)
pnpm db:seed              # Seed an empty database (db:reset seeds after resetting)

# Testing
pnpm test:unit            # Run unit tests (Vitest)
pnpm test:integration     # Run integration tests (Playwright)

# Code Quality
pnpm check                # Run Biome linter/formatter
pnpm check:fix            # Auto-fix linting issues
pnpm lint                 # Run Oxlint; hosts the @shadcn/lint plugin (no rules enabled yet, add them in .oxlintrc.json)
pnpm type-check           # Run TypeScript type checking
pnpm check:structure      # Enforce the feature file vocabulary and no feature cycles
pnpm check:cascades       # Fail on User cascade relations the deletion code does not account for
pnpm check:locales        # Verify ICU brace balance in locale files

# Utilities
pnpm i18n:scan            # Scan for translation keys
pnpm --filter @rallly/web i18n:sync   # Push changed English defaults into app.json (no root script)
pnpm sherif               # Check package dependencies
pnpm screenshots          # Capture marketing screenshots (packages/screenshots)
pnpm release              # Cut a release (scripts/create-release.sh)
pnpm proxy:start          # Start the portless .localhost proxy (auto-starts with dev scripts)

Architecture

Monorepo Structure

  • apps/web/ - Main Next.js application
  • apps/landing/ - Marketing/landing page
  • apps/docs/ - Documentation site
  • packages/ - Shared packages:
    • database/ - Prisma schema and client
    • ui/ - Shared UI components
    • emails/ - Email templates
    • posthog/ - Analytics client
    • billing/ - Stripe integration
    • utils/ - Shared utilities
    • languages/ - Supported locale list
    • logger/ - Shared logger
    • screenshots/ - Playwright capture scripts for marketing screenshots
    • test-helpers/ - Shared test fixtures
    • tailwind-config/, tsconfig/ - Shared config

Key Features & Structure

  • Polls: Core scheduling functionality in apps/web/src/features/poll/
  • Spaces: Workspace/team organization in apps/web/src/features/space/
  • Authentication: Better-Auth config in apps/web/src/lib/auth.ts, domain logic in apps/web/src/features/auth/
  • tRPC API: Routers in apps/web/src/trpc/routers/
  • Feature Flags: Quick create and other toggles in apps/web/src/lib/feature-flags/

Database

  • PostgreSQL with Prisma ORM
  • Multi-model schema split across files in packages/database/prisma/models/
  • Rate limiting uses Upstash Redis over REST (lib/kv.ts, lib/rate-limit/), configured by KV_REST_API_URL and KV_REST_API_TOKEN. There is no other Redis path; when the vars are absent rate limiting is off

Authentication & Authorization

  • Better-Auth with multiple providers (Google, Microsoft, OIDC, email OTP, guest)
  • CASL-based permissions system for spaces and polls
  • User roles: admin, member with tier-based abilities (free/pro)

Deployment Modes

  • Cloud Hosted: Full SaaS with Stripe billing on Vercel
  • Self Hosted: Docker-based deployment without billing features
  • Environment variable NEXT_PUBLIC_SELF_HOSTED=true toggles features
  • Every cloud vs self-hosted behavior difference lives in one of two files, one line per field with the reason on the line, so the files are the inventory:
    • Capabilities ("can this instance do X?") — lib/feature-flags/config.ts (featureFlagConfig, isFeatureEnabled server-side, useFeatureFlag client-side). Behavior forks key on a capability such as billing, never on isSelfHosted directly; "no billing ⇒ every paid feature is on" is derived once in features/billing/utils.ts (resolveSpaceTier).
    • Policies ("what does this instance's org decide for its spaces?") — features/instance-policy/ (deriveInstancePolicy in utils.ts is the inventory; getInstancePolicy from data.ts for server code, loadInstancePolicy from loaders.ts for pages, useInstancePolicy from client.tsx). When the organization layer lands this becomes the org's policy with the same field names.
    • isSelfHosted is for infrastructure wiring (Stripe webhook, licensing routes, updates route, storage). A few legacy product forks still key on it directly (account deletion mode, control panel footer links, API access, the guest poll upsell, the admin setup page, the license limit warning); they shrink toward zero and are never a precedent. components/environment.tsx (IfSelfHosted/IfCloudHosted) belongs to that legacy set, not to the sanctioned API. A new isSelfHosted product fork is a review blocker: add a capability or policy field instead.

Testing

Integration Tests (Playwright)

  • Located in apps/web/tests/
  • Use pnpm test:integration to run
  • Test utilities in apps/web/tests/test-utils.ts
  • Mailpit integration for email testing

Unit Tests (Vitest)

  • Use pnpm test:unit to run
  • Test files co-located with source code

Git Commits

Always use gitmoji prefixes in commit messages. Follow the gitmoji convention (https://gitmoji.dev) for the type of change (e.g. 📝 docs, ♻️ refactor, 🐛 fix, ✨ feature).

Code Standards

Styling

  • TailwindCSS with custom design system
  • Use cn() from @rallly/ui to compose classes
  • Biome for code formatting (indent: 2 spaces, double quotes)
  • Custom UI components in packages/ui/src/ (shadcn-ui components go here)

UI Copy

  • Sentence case for all UI copy: capitalize the first word and proper nouns only. Applies to buttons, dialog titles, page and section headings, setting row titles, empty states, form labels, menu items and toast titles.
  • Exceptions — the test is "does the string name a thing?", not "is it a heading?":
    • Proper nouns and brands: "Google Calendar", "Microsoft Calendar"
    • Initialisms stay uppercase, the rest lowercases: "API keys", "Download ICS file"
    • Product feature names: "Event Types", "Quick Create", "Control Panel"
    • Sample/placeholder data standing in for user content: "Jessie Smith", "My Team"
  • Headings and dialog titles are not exempt. Title Case has no single agreed rule (Chicago, AP and APA disagree), so it cannot be applied consistently; it degrades screen reader pronunciation and removes word-shape cues used by readers with dyslexia and low vision; and the same string often serves as both a button label and a dialog title, so a position-based rule would force two strings for one concept.
  • Changing defaults alone is not enough. pnpm i18n:scan will not overwrite an existing key's value — the UI keeps rendering the old copy. Run pnpm --filter @rallly/web i18n:sync (--sync-primary; there is no root script) to push changed English values through. Never run --sync-all; it clears other locales' translations.

Password Managers

An input that collects something other than the user's own credentials or contact details (someone else's email, a confirmation phrase, a display name) spreads passwordManagerIgnoreProps from @rallly/ui. autocomplete="off" is ignored by every manager; the constant carries each vendor's own opt-out attribute. Never write data-1p-ignore or its siblings inline.

Permission-Gated UI

Choose the presentation by why the user lacks the capability, never ad hoc per surface:

  • Role or ownership (another member could act; the user has no self-serve path) → hide the control, nav item, or tile — including inline controls and destructive menu items (per-row: omit inapplicable items; omit the menu when empty). If a whole page exists for the capability, show a read-only view of the current values (general settings pattern) or a denied state naming who can act (billing settings pattern). Deep links get the denied state, never a silent 404.
  • Plan (the space gains it by paying) → keep the control enabled with a ProBadge; the click opens the pay wall via showPayWall. Never hide or plain-disable a plan-gated control. Turning a Pro setting off is always allowed. Upsells stay visible to all members; the pay wall routes non-owners to ask the space owner to upgrade.
  • Temporary state (seat limit reached, poll already scheduled, action in flight) → disabled with the reason discoverable in place (adjacent alert or tooltip).
  • Environment/config (self-hosted, feature flag) → hide client-side, notFound() server-side.
  • Composite gates: role wins. A member of a free space sees neither a disabled control nor a pay wall trigger.
  • Never enabled-but-broken. Any affordance whose action can fail server-side authorization must be gated client-side by the same ability the server checks.

Effect

  • Version: [email protected], pinned exact, apps/web only. Upgrades are deliberate PRs; never widen the range. No vendored copy of the Effect repo: the npm package ships src/, AGENTS.md and ai-docs/. Before writing Effect code, read apps/web/node_modules/effect/AGENTS.md and the ai-docs/ example it points at; the v4 API differs from v3 and from most online material.
  • Boundary rule: mutations.ts exports Effects, each an Effect.fn("<feature>.<name>") with its requirements visible in the type. data.ts stays Promise based and is lifted with fromPrisma from lib/effect/db.ts, which fails with DatabaseError. Non-Effect code (route handlers, cron) runs an Effect through the one ManagedRuntime in lib/effect/runtime.ts and provides feature layers at the call site with Effect.provide(<Service>.layer). The runtime is built from infrastructure layers only, so lib never imports a feature. actions.ts and the safe-action boundary are not yet covered; keep management mutations Promise based until that design lands.
  • Vocabulary mapping: no new feature file names. A Context.Service with its static layer lives in service.ts; a Context.Reference for configuration lives next to the service that reads it; a tagged error lives next to the code that produces it. Errors are Data.TaggedError by default; Schema.TaggedError only when the error is decoded from or encoded to a wire (RPC, HttpApi), because it pulls the whole Schema module into every chunk that imports the error. Reference shape: features/webhook/service.ts (WebhookSender, WebhookSendError, AllowPrivateTargets) and features/webhook/mutations.ts (deliverWebhooks).
  • Errors as data stay data: typed errors are for control flow inside a mutation. An outcome the database persists (a delivery attempt's { ok, status, error }) is folded back into a value with a trailing Effect.catchTags on the Effect.fn, so the mutation's error channel says exactly what can escape. A never error channel on a function that must not strand a row is the point: the compiler, not review, holds the convention.
  • Testing: stub layers replace one typed dependency and are allowed (Effect.provide(Layer.succeed(Service, stub)), Effect.provideService(Reference, value)). This amends the no-mock-heavy-tests rule: a layer replaces one dependency, vi.mock replaces the world. Tests never mutate process.env to reach a code path a Context.Reference already controls.

State Management

  • tRPC with TanStack Query for server state
  • React Context for client state (auth, preferences, etc.)
  • Form state with react-hook-form + Zod validation

TypeScript Conventions

  • Prefer inline prop types over named interfaces for simple component props
  • Example: function Component({ prop }: { prop: string }) instead of defining a separate interface
  • Only create named interfaces when they're reused or complex
  • Create separate import statements for types (use import type)
  • Prefer React.useState, React.useEffect, etc. over standalone imports (useState, useEffect)
  • Prefer implicit over explicit return types

Dialog Management

  • IMPORTANT: Always use the useDialog hook from @rallly/ui/dialog for managing dialog state instead of manual useState for open/close state
  • The hook provides dialog.trigger(), dialog.dismiss(), and dialog.dialogProps which should be spread onto the dialog component
  • Example usage:
    const dialog = useDialog();
    
    // Trigger dialog
    <Button onClick={() => dialog.trigger()}>Open</Button>
    
    // Dialog component
    <MyDialog {...dialog.dialogProps} />
    

Component Conventions

  • Prefer composable components in the style of shadcn UI over large monolithic components
  • Keep component props minimal — pass only the bare minimum information needed
  • Add "use client" directive to the top of any .tsx file that requires client-side JavaScript

Streaming & Server Data Access

These rules prepare the app for Next.js cacheComponents (static shell + streamed dynamic content). Follow them in all new and touched server code:

  • Never await runtime data (session, cookies(), headers(), tRPC prefetches) at the top of a layout or page. Extract the awaits into a private async component rendered under a <Suspense> boundary (see the gate pattern in app/[locale]/(space)/layout.tsx) so the shell streams immediately.
  • Pass params/searchParams promises down into Suspense-wrapped children and await them there, instead of awaiting at the top of the page.
  • Don't call argless dayjs(), new Date(), Date.now(), or Math.random() during server render outside request-bound components — synchronous IO fails prerendering once cacheComponents is enabled. Compute "now" on the client or behind a Suspense boundary after connection().

Clock-Classified Reads (upcoming/past/relative-to-now)

Reads filtered or grouped by the viewer's present ("upcoming", "past", agenda groupings) have no cacheable answer: the classification depends on the viewer's clock and timezone. All-day events are floating calendar dates (RFC 5545), so classifying them requires the viewer's current calendar date — never drop the timezone from such a query; that silently substitutes UTC as the viewer's zone. The device time zone cookie (written by TimeZoneMismatchDialog on every space page) gives the server the viewer's zone, so these reads render on the server like any other:

  • Resolve the zone device-cookie-first via getDeviceTimeZone() from @/lib/datetime/server, falling back to the stored user.timeZone, then UTC (see loadViewerTimeZone in features/space/loaders.ts). The session zone override is a poll-viewing aid and must not affect classification; getDeviceDateTimeConfig (which honors it) is for display on public pages.
  • Content of a long-lived surface (events list): server render the list through a loader and mount RefreshOnFocus from @/components/refresh-on-focus, which calls router.refresh() when the tab becomes visible again, so an event that has ended since stops showing as upcoming. Filter and page changes are router navigations inside the page's useTransition, which shows the list skeleton while pending (reference: app/[locale]/(space)/(dashboard)/events/).
  • Passing annotation on navigation chrome (a count badge on a tile): the same server snapshot, without the focus refresh.
  • A surface that still queries on the client passes getBrowserTimeZone(). Never server-prefetch such a query with a zone the client will disagree with (e.g. prefetching with the server's own zone and refetching after hydration); seed initialData from the device cookie zone or render a skeleton until the client fetch lands.

File Organization

  • Route handlers follow Next.js App Router conventions
  • Always use kebab-case for file names

Directory Structure (apps/web/src)

Layering — import direction is app → features → components → lib. Each layer may import from layers to its right, and anything may import lib. Nothing outside app/ imports @/app/*. Boundaries are lint-enforced via noRestrictedImports in apps/web/biome.json; existing violations live on a shrinking migration allowlist there.

  • app/ — routing only. Pages/routes are thin adapters composing features/*. A route-private components/ folder is allowed for exactly one route segment; the moment a second segment needs a component, it moves to the owning feature.
  • features/<domain>/ — the product (see below).
  • components/ — shared, domain-agnostic UI only. Admission test: "could this ship in a different product?" Must not import from features/ or app/. Cross-app reusables graduate to packages/ui.
  • lib/ — infrastructure and cross-cutting clients (auth config, cache, datetime, errors, feature flags, rate limiting, storage). Never imports from features/, components/, or app/.

What is a feature — a feature owns at least one of: a database entity, an external integration, or server-side lifecycle logic. UI-only folders are NOT features — they belong in components/ or an owning feature's components/. Create the folder when the first server logic for a new domain noun appears — never speculatively, never for a component alone. Sub-concerns are subdirectories of their parent feature (e.g. space/member/), not sibling features.

Feature file vocabulary — closed set, enforced by pnpm check:structure (scripts/check-feature-structure.mjs; update the script when the set changes). New file names require a team decision. Applies recursively in sub-concern directories:

  • data.ts — parameterized reads (Prisma queries), must start with import "server-only". Trusts its input: every query takes explicit arguments and carries its tenant scope in the where clause. Never reads the request — no next/headers, next/navigation, or session state (lint enforced)
  • loaders.ts — request facing reads: resolve the actor from the session, apply page semantics (redirects to /login and /setup, InvalidSessionError on bans), and delegate to data.ts with proven scope. Loaders always consume data.ts, never the reverse, and never import @rallly/database — so query logic cannot fork between the session path and the API path. Server components call loaders; API routes, webhooks and cron call data.ts with proven scope from their own gate (API routes are lint banned from @/features/**/loaders). Naming note: session-data.ts and queries.ts were considered and rejected
  • mutations.ts — writes + cache invalidation, must start with import "server-only". Trusts its input: takes explicit parameters (userId, not headers), no session reads, no headers(), callable from system contexts (webhooks, cron, moderation). Authorization happens in actions.ts (safe-action middleware + CASL against the database). Never call Better-Auth endpoints from a mutation — they resolve the target user from request headers and authorize against the session snapshot; use adapter-level APIs (authLib.$context → internalAdapter) instead
  • actions.ts — "use server" actions, thin wrappers over mutations, validated via safe-action + schema.ts. Owns authentication and authorization (safe-action clients + CASL checks against database state, never against the session snapshot). Exception to the thin-wrapper rule: writes whose target user is defined by the session (self-profile updates) call the Better-Auth endpoint directly in the action — the endpoint refreshes the session snapshot and cookie cache in one step. Rule of thumb: target user from a parameter → mutation via internalAdapter; target user from the session → Better-Auth endpoint in the action
  • schema.ts — Zod schemas (isomorphic, no Prisma imports)
  • types.ts — domain types
  • ability.ts — CASL permissions
  • constants.ts
  • utils.ts — pure domain helpers, co-located *.test.ts
  • client.tsx — client entry: providers, context, hooks, stores (no separate hooks.ts or store files)
  • service.ts — external integration client (class/factory wrapping a third-party API), must start with import "server-only"
  • components/ — feature UI (no components at feature root)
  • assets/ — static files used by the feature
  • NOT allowed: index.ts barrels, helpers.ts, queries.ts, hooks.ts, lib/, libs/

Read/write symmetry — the request facing / core split is the same on both sides:

Request facing (session, redirects, auth) Core (parameterized, trusts input)
Reads loaders.ts data.ts
Writes actions.ts mutations.ts

Loader placement — pages, layouts and route-private components never call data.ts directly: every read they consume goes through a loader in features/<domain>/loaders.ts, so the session gate that proves scope cannot be forgotten at the call site (lint-enforced: @/features/**/data is banned in app/**; existing violations sit on a shrinking migration allowlist in apps/web/biome.json). A loader bundles the gate and the read: import "server-only", named with a load* prefix, wrapped in React cache() so every consumer in a request shares one read, resolves the actor via the session gates (loadUser(), loadActiveSpace() — both trust the session cookie cache; loadOptionalUser() is the database-verified read for pages that need DB-fresh user state) and delegates to data.ts with proven scope. Reference shape: features/notifications/loaders.ts (loadNotificationPreferences). Every export from a loaders.ts is named load*, gates included (enforced by pnpm check:structure). The bare prefix means the loader applies page semantics: it redirects or throws when the actor is missing. A loader that returns null instead is loadOptional* (loadOptionalActiveSpace, loadOptionalUser, loadOptionalActor). No require*/get* prefixes: that behaviour belongs in the return type, which the Effect migration will make explicit. Route-private actions.ts files are the write side, not pages — they keep calling data.ts/mutations.ts with proven scope from their safe-action gate (loaders' page semantics, redirects, don't belong in actions) and are exempt from the lint ban.

DAL enforcement — @rallly/database may only be imported from features/**/data.ts and features/**/mutations.ts (lint-enforced via noRestrictedImports; existing violations sit on a shrinking migration allowlist in apps/web/biome.json; loaders.ts is absent from the allowlist, so database imports are banned there by default). Parameterized reads take their tenant scope as spaceId: AuthorizedSpaceId (from @/features/space/types); only the session gate (createSpaceDTO) and the API key middleware may cast to it. API routes under app/api/** (except tRPC and better-auth) must not import @/features/**/loaders — they authenticate their own way and pass proven scope to parameterized reads. The inverse holds for pages: app/** (outside app/api/** and route-private actions.ts) must not import @/features/**/data — reads reach pages only through loaders. api/private handlers own serialization and must parse response bodies through their zod schemas.

Cross-feature imports — allowed, public surface only (the vocabulary files above); never reach into another feature's internals. No cycles between features (CI-enforced). For UI, prefer composing multiple features at the page level in app/ over feature-to-feature component imports.

trpc/ is frozen legacy transport — queries only; routers call features/*/data.ts. No new mutations — writes are server actions calling features/*/mutations.ts.

PostHog Event Naming

  • Use the category:object_action pattern
  • Lowercase only, snake_case, present-tense verbs
    • category — the context/flow (e.g. poll_creation, account_settings)
    • object — the component/element (e.g. invite_link, manage_button)
    • action — what happened (e.g. click, copy, submit)
  • Example: posthog?.capture("poll_creation:manage_button_click")

i18n & Localization

  • i18next for internationalization
  • Translation files in public/locales/[lang]/
  • Crowdin integration for translation management
  • Use pnpm i18n:scan to extract new translation keys
  • IMPORTANT: When TypeScript errors occur for missing i18n keys, run pnpm i18n:scan instead of manually adding keys. This command automatically scans the codebase for Trans components and generates the necessary translation entries.
  • English locale files are generated, and their diffs are expected in feature PRs. pnpm i18n:scan writes new keys into apps/web/public/locales/en/*.json, apps/landing/public/locales/en/*.json and packages/emails/locales/en/*.json; a PR that adds a Trans or t() call ships the matching English entry. Never hand-type an entry into those files — run the scan so the key and default cannot drift from the source.
  • Non-English locale files belong to Crowdin. Never edit them in a feature PR; translations arrive through the "🌐 New Crowdin updates" PRs.
  • Pluralization: Always use ICU message format for plurals. Example: {count, plural, =0 {No items} one {1 item} other {# items}} instead of separate singular/plural translation keys.
  • i18n keys are in camelCase and should describe the message (e.g. "lastUpdated": "Last updated")
  • If an i18n key is not intended to be reused, prefix it with the component name in camelCase
  • In client components, use the <Trans> component from @/i18n/client with the defaults prop:
    import { Trans } from "@/i18n/client";
    <Trans i18nKey="menu" defaults="Menu" />
    
  • When a server component needs t or i18n itself — for a string outside JSX, or to render TransWithoutContext — get them from getTranslation in @/i18n/server (rendering the client Trans instead needs neither; see below):
    import { Trans } from "react-i18next/TransWithoutContext";
    import { getTranslation } from "@/i18n/server";
    
    const { t, i18n } = await getTranslation();
    t("menu", { defaultValue: "Menu" });
    <Trans t={t} i18n={i18n} ns="app" i18nKey="menu" defaults="Menu" />;
    
    Whenever you use TransWithoutContext, pass both t and i18n — omitting i18n falls back to the module-global instance, which can carry another request's language under concurrency.
  • Per-request instances are what make this safe. apps/web (i18n/client.tsx, initI18next) and packages/emails (createEmailI18n) both build a fresh instance per render via createInstance(), so nothing is shared between concurrent requests. Any new i18n entry point must do the same — never import i18next from "i18next" (the package default export is a process-wide singleton) and never mutate a shared instance with changeLanguage() to serve a request. apps/landing/src/i18n/ currently violates this and is the one place where passing i18n does not help, because the i18n it hands you is the singleton.
  • Where each Trans is required, and where it's a free choice:
    • Emails — TransWithoutContext only, with t and i18n from createEmailI18n(locale) (packages/emails/src/i18n.ts). Emails are sent from server components, where React context is unavailable, and each render builds its own locale-bound instance so a concurrent fan-out can't cross languages. Only a Next build catches a violation.
    • app/global-error.tsx — neither. It renders outside the [locale] segment that mounts I18nProvider, so there is no locale and no t. Copy there is hardcoded English.
    • Everywhere else — either import is correct. I18nProvider is mounted in app/[locale]/layout.tsx, the root layout, so every page (public poll pages included) is inside it. A server component may render the "use client" Trans from @/i18n/client: React serializes it as a client reference and the browser renders it against the per-tab instance, so there is no cross-request language bleed and no extra bundle weight (react-i18next is already loaded app-wide). Prefer TransWithoutContext in server components to keep static copy out of hydration, but don't make an otherwise-static page async just to do it — and don't file the client import as a bug.