Go + TypeScript/JavaScript Boilerplate

This is a comprehensive boilerplate project that combines a Go backend with a TypeScript/JavaScript frontend, featuring a wide range of technologies and features for building robust and scalable applications.

Technologies and Features

Backend:

Go language
Labstack Echo framework
Gorm ORM (supports SQLite, PostgreSQL, MySQL)
Swagger for API documentation
Automated GitHub releases with GoReleaser

Frontend:

TypeScript/JavaScript
Next.js 14
Shadcn UI + Tailwind CSS for UI
Clerk for authentication
Ionic Capacitor for iOS and Android native app export
Wails for macOS, Windows, and Linux native app export
Orval for generating types and API clients from Swagger specs

CI/CD:

GitHub Actions for testing, code build checks, automated releases
Codacy for code quality analysis
CodeQL for security scans

Infrastructure:

Fully dockerized builds with Dockerfiles and Docker Compose
Terraform for automated EC2 instance creation and deployment

Getting Started

Prerequisites

Go (latest stable version)
Node.js (latest LTS version)
Tmux (for running both backend and frontend together) (Optional)

Local Development

Create a new repository from the template.
Clone the repository.
Run the setup script:

make setup

This command will install all dependencies and create environment variable files.

Configure the environment variables in the .env and client/.env.local file.
Start the development:

make run

This command will start both the backend and frontend using Tmux for the development environment. You can also run them separately:

# Start the backend
make run-server

# Start the frontend
make run-client

Alternatively, you can use the following commands:

# Start the backend
go run . start

# Start the frontend
cd client && yarn dev

You can also run go run . help for an overview of available commands and options from the CLI.

Swagger and Orval API Documentation

make docs-gen

This command will generate the Swagger and Orval API types, documentations and client.

View the Swagger UI at http://localhost:8000/api/swagger/index.html.

Deployment

Binary Distribution

You can bundle the frontend and backend into a single binary for deployment, run:

make builder

Docker Image

To build the Docker image, run:

make docker-run

AWS EC2 Deployment with Terraform

To deploy the application to AWS EC2 using Terraform:

Ensure Terraform CLI is installed locally.
Make sure you have an AWS key pair named midgard in the us-east-1 region, and download the private key (midgard.pem) to the project's root directory.
Navigate to the Terraform directory:

cd ci/terraform-ec2

Initialize Terraform:

terraform init

Apply the Terraform configuration:

terraform apply

Destroy the Terraform configuration:

terraform destroy

IOS and Android Native App Export

Before exporting the iOS and Android native apps, make sure you have installed XCode (for IOS) and Android Studio (for Android).

To export the IOS and Android native apps, follow these steps:

# change directory to the client directory
cd client

# Add the native platforms
npx cap add ios
npx cap add android

# build the web app
yarn export

# sync the capacitor
npx cap sync

# open the native apps in xcode and android to build
npx cap open ios
npx cap open android

macOS, Linux, and Windows Native App Export

Before exporting the macOS, Linux, and Windows native apps, make sure you have installed the Wails and it's required dependencies based on your platform. Also you need XCode for the MacOS native app.

To export the macOS, Linux, and Windows native apps, follow these steps:

# change directory to the scripts/build-wails directory
cd scripts/build-wails

# You need to Run the sh scripts based your platform and release types
# For example if you want to build the universal macOS native app, you need to run:
sudo sh ./scripts/build-wails/build-macos.sh

CI/CD

Configure GitHub Actions for CI/CD

Add these envs to your repo secrets:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY= # Publishable key
CLERK_SECRET_KEY= # Secret key
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/

GO_RELEASER_GITHUB_TOKEN= # GitHub token

Push to main or dev branch to trigger the CI/CD pipeline.
Run make release version=v0.0.1 to create a release. NOTE: the version argument needs to be a valid semantic version.

Limitations

Server-side rendering (SSR) is not supported in Next.js, as the frontend needs to be statically exported to run with native apps.
The Wails app cannot be run in development mode; it needs to be built before running. Check the scripts/build-wails directory for various platform build scripts for Wails.

Roadmap

Improve folder structure and organization.
Address current limitations.
Add Ory Kratos and Keto for authentication and authorization.
Integrate Grafana Labs tools for monitoring, load testing, and logging.
Add Terraform support for other cloud platforms.
Add Kubernetes support.
Implement tests.
And more!

Contributing

Contributions are welcome! Please follow the guidelines in the contributing guide for details on how to contribute.

License

This project is licensed under the BSD 3-Clause License

Changelog

Check the release notes here

nexentra/midgard