Skip to content

v1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@jaycmpb jaycmpb released this 29 Oct 16:55
v1.0.0
60fa621

Initial Release - Convex Starter with Hono HTTP API and OpenAPI Docs

This is the initial release of a production-ready Convex starter project that combines Convex's real-time database with Hono's lightweight HTTP framework.

Features

  • Hono HTTP Framework: Fast, lightweight web framework for RESTful API endpoints.
  • OpenAPI Documentation: Auto-generated API documentation with Scalar UI integration.
  • Complete Example API: Full-featured counters API demonstrating CRUD operations.
  • Error Handling: Comprehensive error handling system with ErrorCodes.
  • PostHog Integration: Automatic error logging and monitoring.
  • Request Validation: Zod-based schema validation for all endpoints.
  • Type Safety: Fully type-safe Convex functions (queries, mutations, actions).
  • Project Structure: Organized codebase following Convex best practices.

Example API Endpoints

The included counters API demonstrates:

  • GET /api/counters - List All Counters
  • GET /api/counters/:name - Get Counter by Name
  • POST /api/counters - Create a New Counter
  • POST /api/counters/:id/increment - Increment a Counter
  • POST /api/counters/:id/decrement - Decrement a Counter
  • POST /api/counters/:id/reset - Reset a Counter to Zero
  • DELETE /api/counters/:id - Delete a Counter

All endpoints include:

  • OpenAPI documentation via describeRoute.
  • Request validation via Zod schemas.
  • Consistent error handling with ErrorCodes.
  • Automatic PostHog error logging for unexpected errors.
  • Type-safe responses.

Quick Start

  1. Install dependencies:

    bun install

  2. Set up environment variables (see .env.example):

    cp .env.example .env.local

  3. Start the development server:

    bun convex dev

  4. Access API documentation:

    • Scalar UI: http://localhost:3000/api/scalar
    • OpenAPI Spec: http://localhost:3000/api/openapi

Project Structure

convex/
├── src/
│   ├── _shared/           # Shared Utilities
│   │   ├── errorCodes.ts  # Error Handling and Logging
│   │   └── http.ts        # HTTP Response Schemas
│   ├── example/           # Example Feature
│   │   ├── mutations.ts   # Database Mutations
│   │   ├── queries.ts     # Database Queries
│   │   └── http.ts        # HTTP Endpoints
│   └── internal/          # Internal Functions
│       └── logging/       # Error Logging to PostHog
├── schema.ts              # Database Schema
└── http.ts                # Main HTTP Router

Environment Variables

Variable Required Description
CONVEX_DEPLOYMENT Yes Your Convex Deployment URL
POSTHOG_API_KEY No PostHog API key for Error Logging
POSTHOG_ENDPOINT No PostHog Endpoint (defaults to US)

Documentation

  • See README.md for complete setup and usage instructions.
  • API documentation available at /api/scalar when running.
  • All endpoints are fully documented with OpenAPI schemas.

Error Handling

The project implements a comprehensive error handling system:

  • Expected Errors: Use ErrorCodes directly for business logic errors (no logging).
  • Unexpected Errors: Use logAndReturnError() for errors that should be logged to PostHog.
  • All errors follow a consistent response format.
  • Automatic background logging for unexpected errors.

Contributing

This starter project follows Convex best practices and includes:

  • Consistent code structure and naming conventions.
  • Type-safe error handling.
  • Comprehensive JSDoc comments.
  • OpenAPI documentation for all endpoints.

License

See LICENSE file for details.

Assets 2
Loading