examples

Buffkit Examples

This directory contains a complete example application demonstrating all Buffkit features.

Quick Start

# From the buffkit root directory
make run

# Or directly
cd examples
go run main.go

The application will start at http://localhost:3000

Features Demonstrated

This example application shows how to use:

1. Authentication

• Login form at /login
• Protected routes under /protected/*
• Test credentials: test@example.com / password
• Session-based authentication with encrypted cookies

2. Server-Sent Events (SSE)

• Real-time updates at /sse-demo
• Broadcasting messages to all connected clients
• Automatic reconnection and heartbeats

3. Server-Side Components

• Component showcase at /components
• Examples of all built-in components:
  • <bk-button> - Styled buttons with variants
  • <bk-card> - Card containers with slots
  • <bk-dropdown> - Dropdown menus
  • <bk-alert> - Alert messages
  • <bk-form> - Forms with CSRF protection
  • <bk-input> - Form inputs with labels

4. Mail Preview (Development)

• View sent emails at /__mail/preview
• Only available when DevMode is true

5. Security Features

• Automatic security headers on all responses
• CSRF protection on forms
• Content Security Policy configured

Project Structure

examples/
├── main.go           # Application setup and handlers
└── templates/        # Template files (currently using inline HTML)
    └── .keep         # Placeholder for embed.FS

Configuration

The example uses an in-memory SQLite database and includes these configurations:

• DevMode: Enabled for development features
• AuthSecret: Test secret (change in production!)
• RedisURL: Optional - jobs work without it
• SMTPAddr: Optional - emails are logged if not configured
• Dialect: SQLite for simplicity

Running with Services

For the full experience with Redis and mail catching:

# Start Redis and MailHog
make docker-services

# Then run the app
make run

• Redis will be available at localhost:6379
• MailHog SMTP at localhost:1025
• MailHog UI at http://localhost:8025

API Endpoints

Public Routes

• GET / - Home page
• GET /about - About page
• GET /components - Component showcase
• GET /sse-demo - SSE demonstration
• POST /broadcast - Send SSE broadcast
• GET /login - Login form
• POST /login - Process login
• POST /logout - Logout

Protected Routes

• GET /protected/dashboard - User dashboard (requires login)
• GET /protected/profile - User profile (requires login)

API Routes

• GET /api/status - System status JSON

System Routes

• GET /events - SSE endpoint
• GET /__mail/preview - Mail preview (dev only)

Customization

This example is designed to be modified. Try:

1. Adding New Components: Register custom components in the app setup
2. Creating New Protected Routes: Use buffkit.RequireLogin middleware
3. Broadcasting Custom Events: Use kit.Broker.Broadcast()
4. Sending Emails: Use kit.Mail.Send()
5. Enqueueing Jobs: Use kit.Jobs.Enqueue()

Testing Authentication

1. Navigate to any protected route (e.g., /protected/dashboard)
2. You'll be redirected to /login
3. Enter test credentials: test@example.com / password
4. After login, you'll be redirected back
5. Click logout to end the session

Testing SSE

1. Open /sse-demo in multiple browser tabs
2. Send a broadcast message from one tab
3. All tabs receive the update instantly
4. Check browser console for SSE events

Troubleshooting

App won't start

• Check port 3000 is not in use
• Ensure Go 1.21+ is installed

Login doesn't work

• The test user is created in memory on startup
• Check the console for any database errors

SSE not connecting

• Check browser console for errors
• Ensure /events endpoint is accessible
• Some proxies may interfere with SSE

Components not rendering

• View page source to see if <bk-*> tags are present
• Check console for expansion errors

Production Considerations

This example is for demonstration. For production:

1. Use a real database (PostgreSQL, MySQL)
2. Set a secure AuthSecret from environment
3. Configure proper SMTP settings
4. Set up Redis for job processing
5. Disable DevMode
6. Use proper templates instead of inline HTML
7. Add rate limiting and monitoring
8. Configure proper CSP headers

Learning Resources

• See HOW_IT_WORKS.md for architecture details
• Check individual package documentation for API details
• Review PLAN.md for the design philosophy