Getting Started - Weber Framework

Prerequisites

Before you begin, ensure you have the following installed:

Go - Version 1.21 or higher
Node.js - Version 18 or higher
pnpm - Package manager for frontend dependencies
Make - Build automation tool

Installation

1. Clone the Repository

git clone https://github.com/umetech/weber.git
cd weber

2. Install Go Dependencies

go mod download

3. Install Frontend Dependencies

cd frontend
pnpm install

Project Setup

Configuration

Weber uses JSON configuration files for different environments. Create or modify configuration files in the config/ directory:

config/
├── dev.json      # Development configuration
├── test.json     # Test configuration
└── prod.json     # Production configuration

Example config/dev.json:

{
    "server": {
        "port": 8080,
        "host": "localhost",
        "debug": true
    },
    "database": {
        "host": "localhost",
        "port": 5432,
        "name": "weber_dev",
        "user": "weber",
        "password": "password"
    },
    "cache": {
        "enabled": true,
        "ttl": 3600
    },
    "logging": {
        "level": "debug",
        "output": "stdout"
    }
}

Development Workflow

Frontend Development

Build and watch frontend assets:

# Development build with watch mode
cd frontend
pnpm run dev

# Production build
pnpm run build

Backend Development

Run the Go server:

# Run directly
go run main.go

# Or use Make
make run

# Run with hot reload (if configured)
make dev

Using the Makefile

The Makefile provides convenient commands:

# Build the application
make build

# Run the application
make run

# Run tests
make test

# Clean build artifacts
make clean

# Build frontend
make frontend

# Full build (frontend + backend)
make all

Your First Route

1. Create a Route Handler

Create a new file backend/route/hello.go:

package route

import "weber/backend/app"

func HelloHandler(ctx *app.Context) {
    ctx.JSON(200, map[string]interface{}{
        "message": "Hello, Weber!",
    })
}

2. Register the Route

Add to backend/route/route.go:

func SetupRoutes(app *app.App) {
    // ... existing routes
    
    app.GET("/hello", HelloHandler)
}

3. Test the Route

Start the server and visit:

http://localhost:8080/hello

Your First Page

1. Create a Template

Create webroot/hello.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{.title}}</title>
</head>
<body>
    <h1>{{.title}}</h1>
    <p>{{.message}}</p>
</body>
</html>

2. Create a Handler

func HelloPageHandler(ctx *app.Context) {
    ctx.Render("hello.html", map[string]interface{}{
        "title": "Hello Page",
        "message": "Welcome to Weber!",
    })
}

3. Register the Route

app.GET("/hello-page", HelloPageHandler)

Adding a Preact Component

1. Create a Component

Create frontend/src/components/Hello.tsx:

import { h } from 'preact';
import { useState } from 'preact/hooks';

export default function Hello() {
    const [name, setName] = useState('World');
    
    return (
        <div>
            <h1>Hello, {name}!</h1>
            <input 
                type="text" 
                value={name}
                onInput={(e) => setName(e.currentTarget.value)}
            />
        </div>
    );
}

2. Register in Build System

Add to your build configuration to generate the component bundle.

3. Use in Template

<div id="hello-component"></div>
<script src="/static/js/hello.bundle.js"></script>

Directory Structure Overview

weber/
├── backend/           # Go backend code
│   ├── app/          # Core application
│   ├── route/        # Route handlers
│   ├── model/        # Data models
│   └── ...
├── frontend/          # Preact frontend
│   ├── src/          # Source files
│   │   ├── components/  # Preact components
│   │   ├── pages/       # Page-level components
│   │   └── utils/       # Utilities
│   └── build/        # Build scripts
├── webroot/          # Static files & templates
│   ├── static/       # CSS, JS, images
│   └── *.html        # HTML templates
├── config/           # Configuration files
├── main.go           # Application entry point
├── Makefile          # Build automation
└── go.mod            # Go dependencies

Common Commands

Development

# Start backend server
make run

# Watch and build frontend
cd frontend && pnpm run dev

# Run both (in separate terminals)
make dev

Building

# Build everything
make all

# Build backend only
make build

# Build frontend only
make frontend

Testing

# Run Go tests
make test
go test ./...

# Run frontend tests (if configured)
cd frontend && pnpm test

Environment Variables

Set environment variables for different configurations:

# Development
export WEBER_ENV=dev

# Production
export WEBER_ENV=prod

# Custom port
export WEBER_PORT=3000

Troubleshooting

Port Already in Use

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

Frontend Build Issues

# Clear cache and reinstall
cd frontend
rm -rf node_modules pnpm-lock.yaml
pnpm install

Go Module Issues

# Clear module cache
go clean -modcache

# Re-download dependencies
go mod download

Getting Started with Weber