Skip to content

iyashjayesh/goscaf

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

20 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

πŸš€ goscaf

Enterprise-grade Go project scaffolder

Go Version License: MIT CI Go Report Card GoDoc Visitors

Think create-react-app, but for Go services.


What is goscaf?

goscaf generates opinionated, production-quality Go project boilerplate via an interactive CLI. Stop copy-pasting skeleton code between projects. Start with:

  • Graceful shutdown with OS signal handling
  • Structured JSON logging (slog, zerolog, or zap)
  • Your choice of HTTP framework (gin, fiber, chi, echo, gorilla/mux)
  • Your choice of Database driver (postgres, mysql, sqlite, mongo, gorm)
  • Viper-powered config with .env support
  • Optional infra clients: Redis, Kafka, NATS
  • Multi-stage distroless Dockerfile + docker-compose
  • Makefile, GitHub Actions CI, golangci-lint - ready to go on day one

Install

Go install

go install github.com/iyashjayesh/goscaf@latest

Homebrew (coming soon)

brew install goscaf-dev/tap/goscaf

From source

git clone https://github.com/iyashjayesh/goscaf.git
cd goscaf
make install

Usage

Interactive mode

goscaf init my-api

Sample prompt flow:

? Module name: (github.com/your-org/my-api)
? Go version: (1.25.0)
? HTTP framework: gin
? Structured logger: slog (stdlib)
? Add Viper for config & env management? (Y/n)
? Add Redis client (go-redis)? (y/N)
? Add Kafka client (franz-go)? (y/N)
? Add NATS client? (y/N)
? Database driver: (none)
? Add Dockerfile + docker-compose? (Y/n)
? Add Makefile? (Y/n)
? Add GitHub Actions CI? (Y/n)
? Add golangci-lint config? (Y/n)
? Add Swagger/OpenAPI scaffold? (y/N)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Scaffolding project: my-api
  Module:    github.com/your-org/my-api
  Go:        1.25.0
  Framework: gin
  Logger:    slog
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  βœ“ cmd/main.go
  βœ“ go.mod
  βœ“ .gitignore
  βœ“ .env.example
  βœ“ internal/config/config.go
  βœ“ internal/handler/handler.go
  βœ“ internal/server/server.go
  βœ“ Dockerfile
  βœ“ docker-compose.yml
  βœ“ Makefile
  βœ“ .github/workflows/ci.yml
  βœ“ .golangci.yml
  β†’ Running go mod tidy...
  βœ“ go mod tidy

  βœ” Project created successfully!

  Next steps:
    cd my-api
    cp .env.example .env
    make docker-up
    make run

Non-interactive / CI mode

goscaf init my-api --defaults
goscaf init my-api --framework fiber --logger zap --redis --kafka --docker

Flags

Flag Default Description
--module "" Go module path
--go-version 1.25.0 Go version (1.23, 1.24, 1.25)
--framework gin HTTP framework (gin|fiber|chi|echo|gorilla|none)
--logger slog Structured logger (slog|zerolog|zap)
--viper true Add Viper for config & env management
--redis false Add Redis client (go-redis/v9)
--kafka false Add Kafka client (franz-go)
--nats false Add NATS client
--db none Database driver (postgres|mysql|sqlite|mongo|gorm|none)
--docker true Add Dockerfile + docker-compose
--makefile true Add Makefile
--github true Add GitHub Actions CI
--lint true Add golangci-lint config
--swagger false Add Swagger/OpenAPI scaffold
--defaults false Skip all prompts, use recommended defaults
--output . Output directory

Generated Project Structure

my-api/
β”œβ”€β”€ cmd/
β”‚   └── main.go                  # Entrypoint with graceful shutdown
β”œβ”€β”€ internal/
β”‚   β”œβ”€β”€ config/
β”‚   β”‚   └── config.go            # Viper (or stdlib) config loader
β”‚   β”œβ”€β”€ server/
β”‚   β”‚   └── server.go            # HTTP server for chosen framework
β”‚   └── handler/
β”‚       └── handler.go           # HTTP handlers
β”œβ”€β”€ pkg/
β”‚   β”œβ”€β”€ db/db.go                 # (if selected) Database connection wrapper
β”‚   β”œβ”€β”€ redis/redis.go           # (if selected) go-redis wrapper
β”‚   β”œβ”€β”€ kafka/kafka.go           # (if selected) franz-go producer+consumer
β”‚   └── nats/nats.go             # (if selected) NATS client wrapper
β”œβ”€β”€ .github/
β”‚   └── workflows/ci.yml
β”œβ”€β”€ .env.example
β”œβ”€β”€ .gitignore
β”œβ”€β”€ .golangci.yml
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ docker-compose.yml
β”œβ”€β”€ go.mod
└── Makefile

Generated Makefile Targets

Target Description
make run go run ./cmd/main.go
make build Build binary to bin/<name>
make test go test -race -cover ./...
make test-coverage Generate coverage.html report
make lint golangci-lint run ./...
make fmt gofmt -s -w . && goimports -w .
make tidy go mod tidy
make docker-up docker compose up -d
make docker-down docker compose down
make docker-logs docker compose logs -f app
make clean Remove bin/, coverage.*
make install-tools Install golangci-lint + goimports

Supported Frameworks

Flag value Import path
gin github.com/gin-gonic/gin
fiber github.com/gofiber/fiber/v2
chi github.com/go-chi/chi/v5
echo github.com/labstack/echo/v4
gorilla github.com/gorilla/mux
none stdlib net/http

Supported Databases

Flag value Driver / Library
postgres github.com/jackc/pgx/v5
mysql github.com/go-sql-driver/mysql
sqlite modernc.org/sqlite
mongo go.mongodb.org/mongo-driver
gorm gorm.io/gorm (with Postgres driver)
none No database scaffolded

Contributing

# Clone and build
git clone https://github.com/iyashjayesh/goscaf.git
cd goscaf
make build

# Run the smoke test
make smoke-test

PRs welcome! Please open an issue first for major changes.

About

goscaf generates opinionated, production-quality Go project boilerplate via an interactive CLI. Stop copy-pasting skeleton code between projects.

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Packages

 
 
 

Contributors