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

0. Create a new repository from the template.

1. Clone the repository.

2. Run the setup script:

make setup

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

3. Configure the environment variables in the .env and client/.env.local file.

4. 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:

1. Ensure Terraform CLI is installed locally.

2. 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.

3. Navigate to the Terraform directory:

cd ci/terraform-ec2

4. Initialize Terraform:

terraform init

5. Apply the Terraform configuration:

terraform apply

6. 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

1. 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

2. Push to main or dev branch to trigger the CI/CD pipeline.

3. 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