Skip to main content
Build a dashboard that connects to a local Oxygen backend to display monthly metrics in real-time. Goal: Demonstrate the simplest possible Oxygen SDK integration pattern - querying time-series data (month + value).

Design System

Use this clean, professional design system inspired by modern SaaS dashboards:

Colors

Typography

Components

Layout

Charts

  • Use line charts with 2px stroke width
  • Primary line: coral color (#FF7A59)
  • Secondary/average lines: gray (#9CA3AF), dashed
  • Grid lines: very light gray (#F3F4F6)
  • Axis labels: small, gray text (0.75rem, #6B7280)
  • Chart dots: filled circles matching line color

Key Principles

  1. Clean & Professional: Minimal decoration, focus on data
  2. Generous Whitespace: Don’t crowd elements
  3. Subtle Shadows: Use sparingly (0 1px 3px rgba(0,0,0,0.05))
  4. Consistent Spacing: Use 0.5rem increments (8px, 16px, 24px, 32px)
  5. Clear Hierarchy: Bold headings, medium labels, regular body text
  6. Accessible Colors: Ensure sufficient contrast for text

1. Install Dependencies

Packages:
  • @oxy-hq/sdk (version 0.3.0+) - Oxygen SDK for data access
  • recharts - For charts
  • date-fns - For date formatting (optional)

2. Configure Vite

Update vite.config.ts:

3. Configure OxyProvider in App.tsx

Wrap your app with OxyProvider to enable SDK access:
Key features:
  • Uses loadingFallback and errorFallback props for graceful SDK loading
  • Global error handler for unhandled promise rejections
  • Error boundary for React errors

4. Add Error Boundary Component

Create src/components/ErrorBoundary.tsx:

5. Add Error Handling to main.tsx

Update src/main.tsx to catch mount errors:

6. Create Oxygen Integration File

Create src/integrations/oxy/oxy-integration.ts:
Key features:
  • BigInt-safe JSON serializer for logging
  • Handles epoch date objects with BigInt support
  • Checks multiple columns for numeric values
  • Handles various data type formats (BigInt, objects, strings)

7. Create Connection Error Component

Create src/components/ConnectionError.tsx:

8. Create Main Page Component

Create src/pages/Index.tsx:

9. Optional: Add Line Chart

Enhance with a chart visualization:

10. Optional: Add Summary Metrics

Show current month target, total targets, and period:
Note: Don’t forget to import the icons at the top of your file:

Key Takeaways

  1. OxyProvider with Fallbacks: Use loadingFallback and errorFallback props for graceful loading
  2. BigInt-Safe Logging: Handle BigInt values from DuckDB properly
  3. Epoch Date Handling: Convert DuckDB epoch objects to readable dates
  4. Robust Value Parsing: Check multiple columns and data types for values
  5. Error Boundaries: Catch and display errors gracefully
  6. Global Error Handler: Catch unhandled promise rejections
  7. Show Real Errors: Don’t hide connection problems with fake data
This is the foundation - once you understand this pattern, you can build more complex dashboards!