Packages Reference

This document is a reference for shared packages (@repo/*) and their public entrypoints.

For architectural rules (boundaries, dependency strategy, API generation flow), see Package Conventions.

Import Rules

Only import from exported entrypoints (package root or documented subpaths). Never deep-import internal files.

Root vs subpath entrypoints

• Root-only packages (import from the package root):
  • @repo/core
  • @repo/react
• Subpath-only packages (no root export):
  • @repo/ui/*
  • @repo/email/*
  • @repo/notif/*
• Mixed:
  • @repo/error — root exports (getErrorMessage, tryCatch, etc.); platform-specific modules require subpaths (@repo/error/node, @repo/error/nextjs, @repo/error/browser)
  • @repo/utils — root barrel and subpath exports; prefer subpaths for clarity and smaller import surfaces

Examples:

• ✅ import { createClient } from '@repo/core'
• ✅ import { Button } from '@repo/ui/components/button'
• ✅ import { delay } from '@repo/utils/async'
• ❌ import { delay } from '@repo/utils' (allowed by exports, but discouraged)
• ❌ import { something } from '@repo/core/src/...'

Package catalog

Core packages

@repo/core — API client & types

Generated client and types from apps/api/openapi/openapi.json.

Exports (public):

• createClient() — nested namespace API
• ApiError — error class for API failures
• export type * — all generated OpenAPI types

Auth modes (see Authentication):

Usage:

import { createClient } from '@repo/core'

// No-auth (callbacks, health checks)
const client = createClient({ baseUrl: 'http://localhost:3001' })

// JWT mode (web app—use getAuthToken, getRefreshToken, updateAuthTokens from lib/auth/auth-client)
const client = createClient({
  baseUrl: 'http://localhost:3001',
  getAuthToken,
  getRefreshToken,
  onTokensRefreshed: updateAuthTokens,
})

// API key mode (servers, CLIs)
const client = createClient({
  baseUrl: 'http://localhost:3001',
  apiKey: 'venc_xxx_secret',
})

await client.auth.magiclink.request({
  body: { email: 'me@example.com', callbackUrl: 'http://localhost:3000' },
})

@repo/react — React Query hooks

React-only helpers built on top of @repo/core.

Exports (public):

• ApiProvider
• useReactApiConfig
• useSession
• useUser
• useHealthCheck
• useMagicLink
• createReactApiConfig

Usage (minimal):

'use client'

import { createClient } from '@repo/core'
import { ApiProvider, useHealthCheck } from '@repo/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

const queryClient = new QueryClient()
const coreClient = createClient({ baseUrl: 'http://localhost:3001' })

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <ApiProvider client={coreClient}>{children}</ApiProvider>
    </QueryClientProvider>
  )
}

export function HealthStatus() {
  const { data, isLoading, error } = useHealthCheck()
  if (isLoading) return <div>Loading…</div>
  if (error) return <div>Health check failed</div>
  return <div>Server time: {data?.datetime}</div>
}

Utility packages

@repo/utils — utilities

Prefer subpath imports:

• @repo/utils/async — async helpers (delay, fetchWithTimeout, …)
• @repo/utils/web3 — chain metadata + helpers
• @repo/utils/logger/server, @repo/utils/logger/client — Pino (server) and console (client)
• @repo/utils/debug — client-only debug hooks (useDevtools, useNuqsDebug, useVconsole)

import { delay } from '@repo/utils/async'
import { logger } from '@repo/utils/logger/server'

await delay(250)
logger.info('delayed')

@repo/ui — UI components

Subpath-only exports:

• @repo/ui/components/*
• @repo/ui/lib/*
• @repo/ui/hooks/*
• @repo/ui/radix

import { Button } from '@repo/ui/components/button'
import { cn } from '@repo/ui/lib/utils'

Error reporting

@repo/error — capture interface + error utilities

Root exports for utilities; platform-specific modules use subpaths:

• @repo/error — error utilities (getErrorMessage, tryCatch, toErrorWithMessage, …)
• @repo/error/node
• @repo/error/nextjs
• @repo/error/browser
• @repo/error/react

import { captureError } from '@repo/error/node' // or /nextjs, /browser
import { getErrorMessage, tryCatch } from '@repo/error' // or @repo/error/nextjs

captureError({ error, label: 'API Call', tags: { app: 'api' } })
const message = getErrorMessage(error)

Email

@repo/email — templates

Email template library built with React Email.

Entrypoints:

• @repo/email/emails/*
• @repo/email/render (server-only)

Usage:

import { WelcomeEmail } from '@repo/email/emails/welcome'
import { render } from '@repo/email/render'

const html = await render(<WelcomeEmail fullName="John Doe" />)

Notifications

@repo/notif — env + types (no root export)

This package does not currently export a root entrypoint.

Entrypoints:

• @repo/notif/node — server env schema (Resend/email configuration)
• @repo/notif/types/* — notification type modules

import { env } from '@repo/notif/node'

env.RESEND_API_KEY

If you need to consume the notification service API from other packages/apps, the package’s exports map needs a root entrypoint (or an additional subpath) first.