Satellite Apps

​

What a satellite is

​

Two shapes of ownership

• Forms tables live in the Postgres private schema (getPrivateFormsClient(supabase) => supabase.schema('private')), so every read needs the admin client. An anon/RLS client cannot reach them at all, which means proxying to web buys nothing.
• The public form-filling surface at /f/<shareCode> is served to anonymous respondents. See the public-API note under API proxying below.

​

Cache Components: connection(), not dynamic

Workspace not found: personal
[WorkspaceHelper] Failed to fetch workspace
Error: During prerendering, fetch() rejects when the prerender is complete

• Add await connection() as the first statement of any authed page or layout that touches Supabase, getPermissions, getWorkspace, or the app session. A dynamic layout does not make its child pages dynamic — each page needs its own call.
• cacheComponents also prerenders GET route handlers. A Supabase-backed GET route with no dynamic signal is statically generated and its response is baked in at build time. Add await connection() there too; every API route should report ƒ (Dynamic) in the build output.
• Where it fits, prefer the true PPR shape: a static shell with the dynamic part inside <Suspense> and await connection() inside the suspended component. apps/meet/[planId] is the reference.
• Unit tests call pages and handlers outside a request scope, where connection() throws. Stub it in the app’s vitest setup while keeping every other export:

vi.mock('next/server', async (importOriginal) => ({
  ...(await importOriginal<typeof import('next/server')>()),
  connection: vi.fn().mockResolvedValue(undefined),
}));

​

Auth: resolve the actor from the app session

// satellite page
const actor = await getSatelliteAppSessionUser('contacts');
const user = actor?.id
  ? await getWorkspaceUserLinkForUser(wsId, actor.id)
  : null;

​

Personal workspace aliases in APIs

​

The actorless-call trap

Workspace not found: personal
Error: During prerendering, fetch() rejects when the prerender is complete
digest: 'HANGING_PROMISE_REJECTION'

export async function getContactsWorkspace(id: string) {
  const user = await getSatelliteAppSessionUser('contacts');
  if (!user?.id) return null;
  return getWorkspace(id, { useAdmin: true, user });
}

export async function getContactsWorkspacePermissions(wsId: string) {
  const user = await getSatelliteAppSessionUser('contacts');
  if (!user?.id) return null;
  return getPermissions({ user, wsId });
}

​

One actor for the workspace shell

​

Reserved route placeholders

​

API proxying — and the catch-all trap

​

The proxied web route must accept app sessions

// Workspace routes
const access = await resolveWorkspaceRouteAccess(req, wsId, [
  'manage_workspace_members',
]);
if (!access.ok) return access.response;

// Or, for withSessionAuth routes
export const GET = withSessionAuth(handler, {
  allowAppSessionAuth: CURRENT_USER_APP_SESSION_AUTH,
});

grep -rL "resolveWorkspaceRouteAccess\|allowAppSessionAuth" \
  "apps/web/src/app/api/workspaces/[wsId]/members"

​

Public (anonymous) API routes on a satellite

const isPublicSharedFormApi = isPublicSharedFormApiRequest(request);
const shouldRefreshAppSession =
  !isLocalAuthApi &&
  (!isPublicSharedFormApi || hasApiSessionCredentials(request));

[WorkspaceHelper] Failed to fetch workspace: { workspaceId: 'v1', … }

​

Translations

​

Moving a feature from web to a satellite

• Relative-sibling imports (../../x) — invisible to a @/ grep.
• Dynamic imports — await import('@/…') has no from clause.
• Side-effect imports — import '@/lib/dayjs-setup' has no from clause.
• npm deps of the extracted file must be added to the target package.
• vi.mock paths silently break: a test mocking @/lib/x stops intercepting once the extracted module imports the package copy directly, so the real module runs unmocked.

​

Debugging a satellite in production

bun add -g vercel
vercel ls contacts --scope tuturuuu
vercel logs <deployment-url> --scope tuturuuu --json