Development Guide

Before you start

Get the app running: Run the app locally
Skim the architecture guide, especially the data layer
Find your feature in Features & Routes

Where does my code go?

You’re building…	It goes in…
A UI element used by one feature	`src/features/<feature>/components/`
A UI element used by two or more features	`src/shared/components/ui/`
The composition a route renders	`src/features/<feature>/views/`
A call to the API	`src/features/<feature>/services/`
A hook that reads data	`src/features/<feature>/hooks/*.queries.ts`
A hook that writes data	`src/features/<feature>/hooks/*.mutations.ts`
Form validation	`src/features/<feature>/validations/*.schema.ts`

Start inside a feature. Promote to shared/ on the second use, not the first.

Recipe: add a new API call

Add the service function

Services are plain async functions built on the shared client. Use apiData when the endpoint returns a single resource, apiRequest when you need the pagination envelope too.

// src/features/projects/services/project.service.ts
export function getProjectContributors(
  projectId: string,
  params?: PaginationParams,
  context: ApiRequestContext = {}
): Promise<PaginatedResponse<Contributor>> {
  return apiRequest<PaginatedResponse<Contributor>>(
    withQueryParams(`/projects/${projectId}/contributors`, params),
    context
  );
}

Always accept and forward context. It carries the abort signal and, server-side, cookies.

Add a query key

// src/features/projects/hooks/project.keys.ts
export const projectKeys = {
  // …existing keys
  contributors: (projectId: string) =>
    [...projectKeys.detail(projectId), "contributors"] as const,
};

Nesting under detail(projectId) means invalidating the project also invalidates its contributors.

Add the hook

// src/features/projects/hooks/project.queries.ts
export function useProjectContributorsQuery(projectId: string) {
  return useQuery({
    queryKey: projectKeys.contributors(projectId),
    queryFn: ({ signal }) => getProjectContributors(projectId, {}, { signal }),
    enabled: !!projectId,
  });
}

Use it in a component

const { data, isPending, error } = useProjectContributorsQuery(projectId);

Components call hooks. They never call services or fetch directly.

Mock the endpoint

Local development will return 501 until the mock knows the route. See the Mock API guide.

Recipe: add a mutation

// src/features/projects/hooks/project.mutations.ts
export function useBookmarkProjectMutation() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationKey: projectMutationKeys.bookmark(),
    mutationFn: (projectId: string) => addProjectBookmark(projectId),
    onSuccess: (_data, projectId) => {
      queryClient.invalidateQueries({
        queryKey: projectKeys.detail(projectId),
      });
      queryClient.invalidateQueries({ queryKey: profileKeys.bookmarks() });
    },
  });
}

Invalidate everything the write affected, including keys owned by other features, as here where bookmarking a project changes the profile’s bookmark list. Surface failures to the user with getErrorMessage() from src/shared/lib/get-error-message.ts and a sonner toast, which is the pattern the rest of the app follows.

Recipe: add a page

Create the route

// src/app/projects/[projectId]/contributors/page.tsx
export default async function ContributorsPage({
  params,
}: {
  params: Promise<{ projectId: string }>;
}) {
  const { projectId } = await params;
  return <ContributorsView projectId={projectId} />;
}

Keep route files thin: resolve params, render a view.

Create the view

The view is a client component in the feature that calls the hooks and composes components: src/features/projects/views/contributors.view.tsx.

Protect it if needed

Add the path to the protected list in src/middleware.ts, and to the disallow list in src/app/robots.ts if it shouldn’t be indexed.

Recipe: add a UI component

Check src/shared/components/ui/ first. There are already 60-odd components covering uploads, comboboxes, cards, tables, pagination, and markdown rendering. For a new shadcn primitive:

pnpm dlx shadcn@latest add <component>

Compose classes with cn(), and use design tokens rather than raw colours:

import { cn } from "@/shared/lib/utils";

<div className={cn("rounded-lg border bg-card p-4", className)} />;

New design tokens go in src/app/globals.css. There is no tailwind.config.js.

Style rules that will fail your build

Biome runs in CI, and a few rules surprise people:

TypeScript `enum` is banned (noEnum)

Use a union type or a const object:

// ✗ fails lint
enum Provider { GitHub = "github", GitLab = "gitlab" }

// ✓
export type AuthProvider = "github" | "gitlab";

// ✓ when you need the values at runtime
export const PROVIDERS = { gitHub: "github", gitLab: "gitlab" } as const;

Formatting is enforced, not suggested

80-column lines, 2-space indent, double quotes, ES5 trailing commas, semicolons always. pnpm lint fails on drift. Run pnpm lint:write.

Import order is enforced

Biome’s organizeImports assist sorts imports. Don’t reorder them by hand; let pnpm lint:write do it.

Other rules at error level

noInferrableTypes, noParameterAssign, noUselessElse, useAsConstAssertion, useDefaultParameterLast, useSingleVarDeclarator, useNumberNamespace.noUnusedVariables and useExhaustiveDependencies are warnings. They won’t fail CI, but fix them anyway.

Several accessibility rules are disabled project-wide. Lint passing does not mean your component is accessible. Check keyboard navigation and labelling yourself.

Before you push

pnpm lint
pnpm type-check
pnpm test:mock
pnpm build
pnpm worker:build

That’s exactly what CI runs. The last two catch build-time errors that type-check won’t.

Contribution workflow

Branches, commits, and opening the pull request.

Overview

Getting started

Development

Before you start

Where does my code go?

Recipe: add a new API call

Recipe: add a mutation

Recipe: add a page

Recipe: add a UI component

Style rules that will fail your build

Before you push

Contribution workflow

​Before you start

​Where does my code go?

​Recipe: add a new API call

​Recipe: add a mutation

​Recipe: add a page

​Recipe: add a UI component

​Style rules that will fail your build

​Before you push

Contribution workflow

Before you start

Where does my code go?

Recipe: add a new API call

Recipe: add a mutation

Recipe: add a page

Recipe: add a UI component

Style rules that will fail your build

Before you push