go-embedded-spa

Go Embedded SPA

Overview

Go Embedded SPA is a technique that embeds frontend SPA (Single Page Application) static resources (React/Vue/TSX) into Go binary files using Go 1.16+ embed package, achieving single-binary full-stack deployment.

Core Benefits

Benefit	Description
🎯 Single File Deploy	One binary contains both frontend and backend, no nginx needed
🌍 Cross-Platform	GOOS/GOARCH easily compiles for Linux/Mac/Windows
📦 Zero Dependencies	Target machine needs no Node.js/npm, uses Go standard library only
🚀 Container Friendly	Dockerfile only needs COPY + ENTRYPOINT
🔒 Resource Security	Static resources compiled into binary, tamper-proof
⚡ Fast Startup	No disk I/O for loading static files

Project Structure

project/
├── go.mod
├── Makefile
├── site/                    # Frontend project
│   ├── embed.go             # Go embed directive
│   ├── src/                 # React/Vue source
│   ├── dist/                # Build output (embedded)
│   ├── package.json
│   ├── vite.config.ts
│   └── index.html
├── pkg/
│   └── siteserver/          # Static file server
│       └── siteserver.go
└── cmd/
    └── app/
        └── main.go

Implementation Steps

Step 1: Create embed.go

Create site/embed.go to declare embed directive. See references/embed.md for complete code.

Key points:

• Use //go:embed all:dist to embed all files including hidden files
• Use fs.Sub() to remove dist/ prefix

Step 2: Create Static File Server

Create pkg/siteserver/siteserver.go. See references/siteserver.md for complete implementation using Go standard net/http.

Core logic:

1. Pre-load index.html for SPA fallback
2. Create http.FileServer from embed.FS
3. Detect static resources by file extension
4. Return index.html for SPA routes (no file extension)

Step 3: Application Integration

package main

import (
    "log"
    "net/http"
    
    "your-project/pkg/siteserver"
    "your-project/site"
)

func main() {
    mux := http.NewServeMux()
    
    // 1. Register API routes FIRST
    mux.HandleFunc("/apis/v1/health", healthHandler)
    mux.HandleFunc("/apis/v1/data", dataHandler)
    
    // 2. Wrap with static file server (as fallback)
    handler := siteserver.WrapHandler(mux, site.DistDirFS)
    
    log.Println("Server starting on :8080")
    log.Fatal(http.ListenAndServe(":8080", handler))
}