Gite - Vite-like Development Server for Go

Gite is a fast, modern development server for Go web applications that provides Vite-like features including hot module replacement (HMR), asset bundling, and live reloading. Built with esbuild for lightning-fast asset processing and optimized for modern web development workflows.

Features

🔥 Hot Module Replacement (HMR) - Instant updates without page refresh
📦 Asset Bundling - Built-in esbuild integration for TypeScript/JavaScript
🎨 CSS Preprocessing - Support for Tailwind CSS and SASS
🔄 Live Reloading - Automatic browser refresh on file changes
🚀 Fast Development - Optimized for developer experience
📱 Production Ready - Build and preview modes for deployment
🔧 Configurable - Environment variables and command-line flags
🗜️ Compression - Built-in gzip compression for production

Quick Start

Installation

go get github.com/ahsanatha/gite

Basic Usage

Development Mode (default):
```
go run main.go
# or with dev flag
go run main.go dev
```
Starts the development server with hot reloading at http://localhost:5173
Build for Production:
```
go run main.go -build
```
Builds optimized assets for production
Preview Production Build:
```
go run main.go -preview
```
Serves the production build for testing

Getting Started

Create a new project with the following structure:

mkdir my-gite-app && cd my-gite-app
go mod init my-gite-app
go get github.com/ahsanatha/gite

Project Structure

your-project/
├── web/                 # Web root directory
│   ├── index.html      # Main HTML template
│   ├── entry.ts        # TypeScript entry point
│   └── styles/         # CSS/SASS files
├── dist/               # Built assets (auto-generated)
├── internal/           # Go packages (if using as library)
│   ├── build/         # Build system
│   ├── config/        # Configuration
│   └── server/        # HTTP server
├── main.go            # Application entry point
├── gite.config.json   # Optional configuration file
├── package.json       # Node.js dependencies (for CSS frameworks)
└── tailwind.config.js # Tailwind CSS configuration

Minimal Setup

Create a minimal main.go:

package main

import (
    "embed"
    "log"
    "os"
    
    "github.com/ahsanatha/gite/internal/config"
    "github.com/ahsanatha/gite/internal/server"
)

//go:embed dist
var assets embed.FS

func main() {
    cfg := config.LoadConfig()
    srv := server.New(cfg, assets)
    
    if err := srv.Start(); err != nil {
        log.Printf("Server error: %v", err)
        os.Exit(1)
    }
}

Configuration

Command Line Flags

Flag	Default	Description
`-addr`	`:5173`	Server address
`-root`	`web`	Web root directory
`-outdir`	`dist`	Output directory for built assets
`-build`	`false`	Build mode (build and exit)
`-preview`	`false`	Preview mode (serve built assets)
`-tailwind`	`false`	Enable Tailwind CSS
`-sass`	`false`	Enable SASS preprocessing

Environment Variables

Variable	Default	Description
`GITE_ADDR`	`:5173`	Server address
`GITE_ROOT`	`web`	Web root directory
`GITE_OUTDIR`	`dist`	Output directory
`GITE_API_PROXY`	`http://localhost:8081`	API proxy URL
`GITE_TAILWIND`	`false`	Enable Tailwind CSS
`GITE_SASS`	`false`	Enable SASS
`GITE_HMR`	`true`	Enable hot module replacement
`GITE_GZIP`	`true`	Enable gzip compression

Example Configuration

# Development with Tailwind CSS
GITE_TAILWIND=true go run main.go

# Custom port and API proxy
GITE_ADDR=:3000 GITE_API_PROXY=http://localhost:9000 go run main.go

# Build with SASS
GITE_SASS=true go run main.go -build

HTML Templates

Gite uses Go's html/template package. Your HTML files can access these template variables:

<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
    <!-- HMR client script (development only) -->
    {{.HMRClient}}
</head>
<body>
    <div id="app"></div>
    
    <!-- In production, use manifest for asset URLs -->
    {{if .Asset}}
        <script src="{{.Asset "entry.js"}}"></script>
    {{else}}
        <script src="/static/entry.js"></script>
    {{end}}
</body>
</html>

API Proxy

Gite automatically proxies /api/* requests to your backend server:

// This will be proxied to http://localhost:8081/users
fetch('/api/users')
  .then(response => response.json())
  .then(data => console.log(data));

Hot Module Replacement

HMR is enabled by default in development mode. The HMR client automatically:

Reloads the page when HTML templates change
Hot-swaps JavaScript modules when possible
Refreshes CSS without page reload
Handles build errors gracefully

CSS Preprocessing

Tailwind CSS

Enable Tailwind CSS processing:

# Command line
go run main.go -tailwind

# Environment variable
GITE_TAILWIND=true go run main.go

Create web/styles/input.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Your custom styles */
.my-component {
  @apply bg-blue-500 text-white p-4 rounded;
}

SASS

Enable SASS preprocessing:

# Command line
go run main.go -sass

# Environment variable
GITE_SASS=true go run main.go

Create web/styles/main.scss:

$primary-color: #3b82f6;
$border-radius: 0.5rem;

.button {
  background-color: $primary-color;
  border-radius: $border-radius;
  padding: 1rem 2rem;
  
  &:hover {
    background-color: darken($primary-color, 10%);
  }
}

Production Deployment

Build assets:
```
go run main.go -build
```
Test the build:
```
go run main.go -preview
```
Deploy:
```
go build -o myapp
./myapp -preview
```

Advanced Usage

Custom Build Configuration

Extend the build system by modifying internal/build/ packages:

// Add custom esbuild plugins
builder := build.NewBuilder(build.BuildConfig{
    EntryPoints: []string{"web/entry.ts"},
    OutDir:      "dist",
    Plugins:     []api.Plugin{myCustomPlugin},
})

Custom Server Middleware

Add custom middleware in internal/server/handlers.go:

func (s *Server) setupRoutes() {
    // Add your custom middleware
    http.Handle("/custom", s.customMiddleware(s.customHandler))
    
    // Existing routes...
}

Troubleshooting

Common Issues

Port already in use:
```
GITE_ADDR=:3000 go run main.go
```
Assets not loading:
- Check that web/entry.ts exists
- Verify the web directory structure
- Run with -build flag to see build errors
HMR not working:
- Ensure you're in development mode (not -build or -preview)
- Check browser console for WebSocket connection errors
- Verify firewall settings
Template errors:
- Check HTML template syntax
- Ensure template files are in the web root
- Look for template compilation errors in logs

Debug Mode

Enable verbose logging:

GITE_DEBUG=true go run main.go

Requirements

Go: 1.24 or higher
Node.js: 16+ (optional, for CSS frameworks like Tailwind)
Modern Browser: For HMR WebSocket support

Performance

⚡ Fast Builds: Powered by esbuild for sub-second build times
🔄 Instant HMR: WebSocket-based hot module replacement
📦 Efficient Bundling: Tree-shaking and code splitting
🗜️ Optimized Output: Minification and compression for production

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details.

Architecture

Gite is built with a modular architecture:

Build System: esbuild integration with plugin support
HMR Server: WebSocket-based hot module replacement
Asset Manifest: Automatic asset versioning and mapping
Plugin Manager: Extensible plugin system for custom processing
Template Engine: Go html/template with asset injection

Roadmap

Vue.js and React component support
Advanced CSS optimization
TypeScript type checking integration
Docker containerization support
Kubernetes deployment templates

Acknowledgments

Inspired by Vite
Built with esbuild
Uses fsnotify for file watching
WebSocket implementation for real-time updates

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
internal		internal
.gitignore		.gitignore
README.md		README.md
gite.config.json		gite.config.json
go.mod		go.mod
go.sum		go.sum
main.go		main.go
package-lock.json		package-lock.json
package.json		package.json
tailwind.config.js		tailwind.config.js

ahsanatha/gite

Folders and files

Latest commit

History

Repository files navigation