Open source CapCut alternative.
Frontend and Next.js Guidelines
How to work in the site Next.js app: route structure, server/client
boundaries, Tailwind styling, and data access.
The one rule: React components never call fetch(...) directly.
Client-side data access goes through TanStack Query hooks in src/queries/;
server-side data access stays in server code. If you're tempted to fetch
inline, the call belongs in a hook.
Project Shape
- Routes, layouts, pages, loading states, and route handlers live in
src/app. - Shared UI primitives live in
src/components; route-specific UI stays near the route, such assrc/app/_components/landingfor the home page. - Server-only helpers live in
src/lib. - Use absolute imports through the
@/*alias; avoid barrelindex.tsfiles. - Every string a person reads comes from a catalog; see Translations.
Components
- Components are Server Components by default. Add
"use client"only for state, effects, refs, event handlers, browser APIs, or client-only hooks. - Keep client boundaries small and close to the interactive control.
- Keep secrets and direct database access out of Client Components.
- Pass plain serializable props from Server Components into Client Components.
Rendering
Cache Components is on. A page prerenders to a static shell, and anything that
reads request data — cookies(), headers(), params, searchParams — or
fetches uncached has to sit behind its own <Suspense> boundary and streams in
after the shell. Data that rarely changes goes behind use cache, as close to
the read as you can put it.
The blog is the worked example of a public page built this way: cached, tagged reads that the CMS expires on save (see The Blog).
The old route segment configs are gone with it. dynamic, revalidate,
fetchCache, and runtime fail the build; a handler that must run per request
awaits connection() from next/server, and a cache duration is cacheLife
inside a use cache scope.
A page that should feel instant declares it:
export const instant = true;
Next then checks in dev that the route produces a shell at every entry point, and names the component that would block the navigation. The public pages carry it, and so do the app's home surfaces.
Getting the app there set the boundary the whole subtree is built around. The
chrome — the surface, the sidebar, the connect banner — renders with no session
and no account, and is what a cold load paints. Everything that reads the engine
waits behind SessionGate for the account id, because every engine URL carries
it. A new surface picks a side: chrome, or behind the gate with a skeleton.
Two things keep metadata out of the way of a static shell, and both are set in
the root layout: metadataBase, so a relative card URL resolves against the
canonical host, and icons, which declares the favicon and Apple icon. Dropping
those in src/app as files makes them file-based metadata, which resolves per
request and holds back the shell of every page in the app.
Navigating away no longer unmounts a page. Next keeps the last few routes
mounted in a hidden React <Activity>, so their DOM and state survive a trip
away and back. Effects are torn down on the way out and re-run on the way back,
so anything holding a real resource — a decoder, an audio graph, a timer —
releases it in an effect cleanup, and anything transient that should not come
back open, like a dropdown, closes in a useLayoutEffect cleanup.
A document-wide DOM query sees those hidden pages too, portals included, so a
scan that asks whether something is on screen checks checkVisibility().
Navigation
- Use the
next/link<Link>component for internal routes (anything starting with/) so navigation stays client-side and prefetches. Use a plain<a>only for external URLs,mailto:, and other non-route links. - When a shared control accepts an arbitrary
href(such as the landingPillButton), let the control pick<Link>vs<a>from the href instead of duplicating that choice at every call site.
Styling
- Tailwind utility classes are the default for all UI, with no exceptions by
area. Do not write React inline
styleobjects for layout, spacing, typography, colors, borders, or responsive behavior. Reserve inlinestylestrictly for genuinely runtime values: a dimension computed from props or state, CSS custom properties derived from data, or a third-party style API. - Tailwind is configured via CSS (
@themeinsrc/app/globals.css), not atailwind.config.*file; its absence is not a reason to use inline styles. - When a style genuinely exceeds utilities — a custom
@keyframesanimation, a layeredbox-shadow— put it in a plain.cssfile beside the feature and pull it into the bundle with a side-effect import (import "./thing.css") from the module that owns the class. Reserveglobals.cssfor base and theme styles; feature CSS lives with its feature. Apply the class through the normalclassName, composing with utilities viacn. - Use the brand tokens defined in
globals.cssrather than repeating raw hex:text-ink/bg-ink/border-ink(near-black),bg-coral/text-coral,bg-cream,bg-background(page sand), andfont-system/font-code. Reach for a Tailwind arbitrary value (text-[#454545],text-[clamp(45px,9.6vw,134px)]) only for genuinely one-off values not worth a token. - Use Tailwind responsive variants for breakpoints (
md:*, and arbitrary variants likemin-[900px]:*for a non-standard breakpoint). Do not add client-only media-query hooks to choose styling. When an element only differs by visibility, toggle it withhidden/md:blockrather than conditional rendering. - Compose conditional classes with the
cnhelper from@/lib/utils. - Prefer existing icon components for buttons and compact actions when an icon fits the control.
- On dark surfaces, the donkey mark sits on a white tile (
DonkeyMark). - Keep controls at stable dimensions so hover states, icons, labels, and loading states do not shift layout.
- Keep cards for repeated items, modals, and genuinely framed content. Avoid nesting cards inside cards.
Data and APIs
- Route Handlers live in
src/app/api/**/route.tsand followdocs/guides/backend-apis.md— authenticated by default, Zod-validated, explicit responses. - Every query/mutation hook lives in
src/queries/so the cache surface is auditable in one place. Components import the hooks; they do not fetch inline. The shared fetch wrapper and error type aresrc/queries/apiClient.ts. Define each query's key as a constant alongside its hook in the same module (export it if another module needs to invalidate it). MountQueryProvideronce at the root layout. - Per-user account views (
/app/settings, including usage) are client-rendered and read their data through these hooks. The route handlers still enforce auth server-side, so a client guard is for UX, not security. - Use database clients only from server-side code, and never run migrations or schema pushes casually; choose the migration workflow deliberately for the target database.
TypeScript
- Use
typefor props and local data shapes; prefer a shortPropsname when there is only one props type in the file. - Do not use
any; define the narrowest useful type or stop and clarify. - Prefer optional chaining (
a?.b) overa && a.bor!a || !a.bwhen reading a possibly-absent member. - Keep imports direct and explicit.
- Include real dependencies in hooks; store callbacks in refs when they should not trigger re-renders.
Checks
- Do not commit
.envor secrets. - Run
npm run lintandnpm run buildbefore shipping frontend changes.