Templates Overview

Vinoflare offers 9 carefully crafted templates to match different project requirements. Each template comes with TypeScript, testing, linting, and best practices configured out of the box.

Template Comparison

Full-Stack Templates

Full-stack templates include a React frontend with TanStack Router, Vite, and Tailwind CSS. They differ in their API client approach and feature set.

API-Only Templates

API-only templates provide a Hono REST API server without a frontend. Perfect for microservices or when you have a separate frontend.

API Client Comparison

Orval (OpenAPI)

Orval generates typed API clients from OpenAPI schemas. Best for:

• Standards-based development - OpenAPI/Swagger specification
• API documentation - Auto-generated docs from schema
• Cross-team collaboration - Share schemas between teams
• Code generation - Hooks and types generated automatically

// Auto-generated hooks with full type safety
const { data, error, isLoading } = useGetTodos();
const createTodo = useCreateTodo();
 
// Mutation with optimistic updates
createTodo.mutate({ title: "New Todo" });

Hono RPC

Hono RPC provides end-to-end type inference without code generation. Best for:

• Rapid development - No code generation step needed
• Type inference - Types flow from backend to frontend
• Smaller bundle size - No generated code
• Simpler setup - Less configuration required

// Direct type inference from backend
const todos = await client.api.todos.$get();
const newTodo = await client.api.todos.$post({ 
  json: { title: "New Todo" } 
});

Feature Details

Database (Cloudflare D1)

Templates with database include:

• Drizzle ORM for type-safe database queries
• Migration system for schema changes
• Local D1 database for development
• Seed data for quick starts

Authentication (Better Auth)

Templates with auth include:

• Discord OAuth pre-configured
• Session management with secure cookies
• Protected routes on frontend and backend
• User profiles and management

Frontend Stack

All full-stack templates include:

• React 19 with Server Components support
• TanStack Router for type-safe routing
• TanStack Query for data fetching
• Tailwind CSS for styling
• Vite for lightning-fast HMR

Choosing the Right Template

Decision Tree

1. Do you need a frontend?

   • ✅ Yes → Continue to step 2
   • ❌ No → Choose an API-only template

2. Do you need user data persistence?

   • ✅ Yes → Continue to step 3
   • ❌ No → Choose a template without database

3. Do you need user authentication?

   • ✅ Yes → Choose a template with auth
   • ❌ No → Choose a template without auth

4. Which API client approach do you prefer?

   • 📋 Standards-based with documentation → Choose Orval
   • ⚡ Fast development with type inference → Choose RPC

Common Scenarios

Building a SaaS application → Full Stack with Orval or RPC (with auth & database)

Creating a public tool or documentation site → Full Stack without auth (with database)

Building a static site with API calls → Full Stack without database

Creating a microservice → API only (choose features based on needs)

Building a webhook handler → API only without database

Quick Start Commands

# Full-stack with everything (Orval)
npm create vinoflare@latest my-app
 
# Full-stack with everything (RPC)
npm create vinoflare@latest my-app --rpc
 
# Full-stack without auth
npm create vinoflare@latest my-app --no-auth
 
# Full-stack without database
npm create vinoflare@latest my-app --no-db
 
# API only
npm create vinoflare@latest my-api --type=api-only
 
# API without auth
npm create vinoflare@latest my-api --type=api-only --no-auth
 
# API without database
npm create vinoflare@latest my-api --type=api-only --no-db

Next Steps

• Explore individual template documentation:
  • Orval Templates
  • RPC Templates
  • API Templates
• Read the Quick Start Guide
• Learn about Development Workflow