Skip to main content
The Teak web app is a modern, full-featured Next.js application that serves as the primary interface for managing your personal knowledge hub.

​
Overview

Built with Next.js 16 and React 19, the web app provides a responsive, real-time interface for collecting, organizing, and rediscovering your ideas and inspirations.

Technology Stack

  • Next.js 16.1.6 (App Router)
  • React 19.2.4
  • Convex for real-time backend
  • Better Auth for authentication

UI Framework

  • Tailwind CSS 4
  • shadcn/ui components
  • Ant Design components
  • Lucide React icons

​
Key Features

​
Real-Time Synchronization

The web app uses Convex for real-time data synchronization, ensuring your cards are always up-to-date across all devices. 
import { useQuery } from "@teak/convex";
import { api } from "@teak/convex";

// Real-time cached queries via ConvexQueryCacheProvider
const cards = useQuery(api.cards.list);

​
Card Management

1

Create Cards

Add cards through multiple methods:
  • Direct text input
  • URL saving with automatic metadata extraction
  • File uploads (images, videos, audio, documents)
  • Drag-and-drop interface
2

Organize

Use tags, favorites, and AI-powered categorization to keep your knowledge organized.
3

Search & Rediscover

Powerful search with AI-generated summaries and metadata to quickly find what you need.

​
Advanced Capabilities

  • EXIF data extraction
  • Color palette detection
  • Image optimization with @cf-wasm/photon
  • Thumbnail generation
  • Video uploads and previews
  • Audio file support
  • Document handling
  • Automatic media transcription

​
Installation & Setup

​
Prerequisites

  • Node.js 18+ or Bun
  • A Convex account for the backend
  • Better Auth configured

​
Development

# Install dependencies
bun install

# Start web app + Convex backend
bun run dev

# Or start web app only
bun run dev:web

​
Environment Configuration

Create a .env.local file in the web app directory: 
NEXT_PUBLIC_CONVEX_URL=your_convex_deployment_url
BETTER_AUTH_SECRET=your_auth_secret
BETTER_AUTH_URL=http://localhost:3000

# Optional: Analytics
NEXT_PUBLIC_VERCEL_ANALYTICS_ID=your_analytics_id

# Optional: Sentry
SENTRY_DSN=your_sentry_dsn

​
Platform-Specific Features

​
Desktop Auth Integration

The web app includes a special authentication flow for the Tauri desktop app: 
// apps/web/src/app/desktop/auth/complete/page.tsx
// Handles OAuth callback for desktop app

​
Command Palette

Keyboard-first navigation using cmdk:

Keyboard Shortcuts

  • Cmd/Ctrl + K - Open command palette
  • Quick navigation to cards, settings, and actions
  • Fast card creation and search

​
Masonry Grid Layout

Responsive masonry grid for displaying cards of varying sizes and types:
  • Optimized for performance with virtualization
  • Drag-and-drop reordering
  • Responsive breakpoints

​
Global Drag & Drop

Drag files directly from your desktop to create cards: 
import { useGlobalDragDrop } from "@/hooks/use-global-drag-drop";

// Enable global drag-and-drop anywhere in the app
useGlobalDragDrop();

​
Technology Details

​
React Compiler

The web app uses the experimental React Compiler for optimized performance: 
{
  "devDependencies": {
    "babel-plugin-react-compiler": "^1.0.0"
  }
}

​
Image Optimization

Utilizes Cloudflare’s WebAssembly Photon library for client-side image processing:
  • Fast client-side resizing
  • Color palette extraction
  • EXIF data preservation

​
Analytics

Integrated with Vercel Analytics for performance monitoring and user insights.

​
Error Tracking

Sentry integration for comprehensive error tracking and monitoring: 
import * as Sentry from "@sentry/nextjs";

​
Architecture

​
App Router Structure

app/
├── (auth)/           # Authentication pages
│   ├── login/
│   ├── register/
│   └── forgot-password/
├── (settings)/       # Settings pages
│   ├── settings/
│   └── admin/
├── desktop/          # Desktop app integration
│   └── auth/
└── page.tsx          # Main cards view

​
Component Organization

  • UI Components: shadcn/ui components in components/ui/
  • Card Components: CardModal, CardItem, AddCardForm
  • Layout Components: MasonryGrid, DragOverlay
  • Search: SearchBar with real-time filtering

​
Hooks

  • useCardActions - Card CRUD operations
  • useCardModal - Card detail modal state
  • useGlobalDragDrop - Global drag-and-drop handling

​
Deployment

The web app is optimized for deployment on Vercel:
1

Connect Repository

Connect your GitHub repository to Vercel
2

Configure Environment

Add environment variables in the Vercel dashboard
3

Deploy

Vercel automatically builds and deploys on push to main
The web app requires a deployed Convex backend. Deploy Convex first, then configure the web app with the Convex deployment URL.

​
Learn More

Backend

Learn about the Convex backend architecture

Architecture

Understand the system architecture

Next.js

Official Next.js documentation

Convex

Official Convex documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us