Skip to main content

Source: ocean/docs/HIDDEN_FEATURES.md | ✏️ Edit on GitHub

Hidden Features & Patterns in Ocean

This document reveals powerful features and patterns that already exist in Ocean but might not be immediately obvious.

🎯 Data Fetching & Mutations​

useMutationWithToast​

Automatically handles loading states, success/error toasts, and cache invalidation:

const mutation = useMutationWithToast({
  mutationFn: async (data) => apiClient.updateProfile(data),
  successMessage: 'Profile updated successfully',
  errorMessage: 'Failed to update profile',
  invalidateQueries: [['profile', userId]],
})

useGraphQLQuery​

Type-safe GraphQL queries with automatic error handling:

const { data, isLoading } = useGraphQLQuery(GET_USER_QUERY, { userId }, { enabled: !!userId })

withRetry​

Built-in retry logic for resilient API calls:

const result = await withRetry(() => apiClient.fetchData(), { maxAttempts: 3, delayMs: 1000 })

🔐 Authentication Patterns​

Multi-Tab Synchronization​

Auth state automatically syncs across browser tabs - no setup needed!

JWT Monitoring​

The <JWTMonitor /> component tracks token expiry in real-time:

  • Shows countdown to expiry
  • Automatic refresh attempts
  • Visual indicators for token health

Race Condition Protection​

Auth context handles concurrent auth operations safely - no manual coordination needed.

🎨 UI Utilities​

useIsMobile Hook​

Responsive behavior without media queries:

const isMobile = useIsMobile()
return isMobile ? <MobileView /> : <DesktopView />

Theme-Aware Assets​

Dynamic logos based on current theme:

const logo = getThemedLogo(theme, systemPreference)
const logomark = getThemedLogomark(theme, systemPreference)

Loading Skeletons​

Pre-built loading states:

if (isLoading) return <DashboardLoadingSkeleton />
if (isAuthLoading) return <AuthLoadingSkeleton />

🚨 Error Handling​

Error Boundaries​

Three types for different contexts:

// Wrap components with specific error handling
export default withErrorBoundary(MyComponent, {
  fallback: <CustomErrorUI />,
  onError: (error) => console.error(error),
})

Manual Error Triggering​

const { showBoundary } = useErrorBoundary()
// Trigger error boundary programmatically
showBoundary(new Error('Something went wrong'))

Structured Error Classes​

throw new ApiError('Failed to fetch', { statusCode: 404 })
throw new AuthError('Session expired')
throw new NetworkError('Connection lost')

🛠️ Development Tools​

Debug Commands​

# Debug user creation flow
pnpm debug:user "test@email.com" "Org Name"

# Check production health
pnpm health:check

# Monitor secret rotation
pnpm security:check

# Test performance regression
pnpm perf:check

One-Command Setup​

# Complete environment setup in <5 minutes
pnpm setup:ocean

Error Boundary Testing​

In development, use <ErrorBoundaryTest /> to test error states.

📊 Performance Features​

GraphQL Operation Tracking​

All GraphQL operations are automatically tracked for performance:

  • Operation duration
  • Success/failure rates
  • Automatic Sentry integration

Bundle Size Monitoring​

# Check for bundle size regressions
pnpm perf:check

🎯 Form Patterns​

TanStack Form with Valibot​

Type-safe forms with automatic validation:

const form = useForm({
  defaultValues: { email: '' },
  onSubmit: async ({ value }) => {
    await mutation.mutateAsync(value)
  },
  validators: {
    onChange: profileUpdateSchema,
  },
})

Pre-built Validation Schemas​

Check /src/schemas/ for reusable validation:

  • loginSchema
  • signupSchema
  • profileUpdateSchema
  • organizationSchema

🔄 State Management​

Organization Context​

Automatically manages organization switching:

const { currentOrganization, switchOrganization } = useOrganization()

PostHog Integration​

Feature flags and analytics ready to use:

const { isFeatureEnabled } = usePostHog()
if (isFeatureEnabled('new-feature')) {
  // Show new feature
}

🎪 Hidden UI Features​

Container Queries (Tailwind v4)​

Components can respond to their container size:

<div className="@container">
  <div className="grid @sm:grid-cols-2 @lg:grid-cols-3">
    {/* Responsive to container, not viewport! */}
  </div>
</div>

Dynamic Breadcrumbs​

Breadcrumbs automatically update based on route - no manual management needed.

Collapsible Sidebar​

The sidebar remembers its state and syncs across page reloads.

💡 Pro Tips​

  1. Always use useMutationWithToast instead of raw mutations
  2. Leverage error boundaries instead of try-catch in components
  3. Use useIsMobile for responsive logic instead of CSS-only
  4. Check /scripts/ folder for automation tools
  5. Use pnpm validate before commits - it catches many issues
  6. Explore /docs/adr/ for architecture decisions and rationale

🚀 Advanced Patterns​

Provisioning Service​

New user setup is fully automated:

  1. Creates Supabase profile
  2. Provisions Neon database
  3. Sets up Stripe customer
  4. All with automatic rollback on failure

Health Monitoring​

Production health endpoints track:

  • Database connections
  • External service availability
  • Queue sizes
  • Error rates

Security Monitoring​

Automatic monitoring for:

  • Secret rotation schedules
  • API key usage
  • Authentication anomalies

Most of these features work out-of-the-box without additional configuration. The Ocean platform is more powerful than it appears on the surface!