☁️ Air - Live reload for Go apps

English |Giản thể trung văn|Phồn thể trung văn

Motivation

When I started developing websites in Go and usingginframework, it was a pity that gin lacked a live-reloading function. So I searched around and triedfresh,it seems not much flexible, so I intended to rewrite it better. Finally, Air's born. In addition, great thanks topilu,no fresh, no air:)

Air is yet another live-reloading command line utility for developing Go applications. Runairin your project root directory, leave it alone, and focus on your code.

Note: This tool has nothing to do with hot-deploy for production.

Features

• Colorful log output
• Customize build or any command
• Support excluding subdirectories
• Allow watching new directories after Air started
• Better building process

Overwrite specify configuration from arguments

Support air config fields as arguments:

If you want to config build command and run command, you can use like the following command without the config file:

air --build.cmd"go build -o bin/api cmd/run.go"--build.bin"./bin/api"

Use a comma to separate items for arguments that take a list as input:

air --build.cmd"go build -o bin/api cmd/run.go"--build.bin"./bin/api"--build.exclude_dir"templates,build"

Installation

Viago install(Recommended)

With go 1.23 or higher:

go install github.com/air-verse/air@latest

Via install.sh

#binary will be $(go env GOPATH)/bin/air
curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh|sh -s -- -b$(go env GOPATH)/bin

#or install it into./bin/
curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh|sh -s

air -v

Viagoblin.run

#binary will be /usr/local/bin/air
curl -sSfL https://goblin.run/github.com/air-verse/air|sh

#to put to a custom path
curl -sSfL https://goblin.run/github.com/air-verse/air|PREFIX=/tmp sh

Docker/Podman

Please pull this Docker imagecosmtrek/air.

docker/podman run -it --rm \
-w"<PROJECT>"\
-e"air_wd=<PROJECT>"\
-v$(pwd):<PROJECT>\
-p<PORT>:<APP SERVER PORT>\
cosmtrek/air
-c<CONF>

Docker/Podman.${SHELL}rc

if you want to use air continuously like a normal app, you can create a function in your ${SHELL}rc (Bash, Zsh, etc…)

air() {
podman/docker run -it --rm \
-w"$PWD"-v"$PWD":"$PWD"\
-p"$AIR_PORT":"$AIR_PORT"\
docker.io/cosmtrek/air"$@"
}

<PROJECT>is your project path in container, eg: /go/example if you want to enter the container, Please add --entrypoint=bash.

For example

One of my project runs in Docker:

docker run -it --rm \
-w"/go/src/github.com/cosmtrek/hub"\
-v$(pwd):/go/src/github.com/cosmtrek/hub \
-p 9090:9090 \
cosmtrek/air

Another example:

cd/go/src/github.com/cosmtrek/hub
AIR_PORT=8080 air -c"config.toml"

this will replace$PWDwith the current directory,$AIR_PORTis the port where to publish and$@is to accept arguments of the application itself for example -c

Usage

For less typing, you could addalias air='~/.air'to your.bashrcor.zshrc.

First enter into your project

cd/path/to/your_project

The simplest usage is run

#firstly find `.air.toml` in current directory, if not found, use defaults
air -c.air.toml

You can initialize the.air.tomlconfiguration file to the current directory with the default settings running the following command.

air init

After this, you can just run theaircommand without additional arguments, and it will use the.air.tomlfile for configuration.

air

For modifying the configuration refer to theair_example.tomlfile.

Runtime arguments

You can pass arguments for running the built binary by adding them after the air command.

#Will run./tmp/main bench
air bench

#Will run./tmp/main server --port 8080
air server --port 8080

You can separate the arguments passed for the air command and the built binary with--argument.

#Will run./tmp/main -h
air -- -h

#Will run air with custom config and pass -h argument to the built binary
air -c.air.toml -- -h

Docker Compose

services:
my-project-with-air:
image:cosmtrek/air
#working_dir value has to be the same of mapped volume
working_dir:/project-package
ports:
-<any>:<any>
environment:
-ENV_A=${ENV_A}
-ENV_B=${ENV_B}
-ENV_C=${ENV_C}
volumes:
-./project-relative-path/:/project-package/

Debug

air -dprints all logs.

Installation and Usage for Docker users who don't want to use air image

Dockerfile

#Choose whatever you want, version >= 1.16
FROMgolang:1.23-alpine

WORKDIR/app

RUNgo install github.com/air-verse/air@latest

COPYgo.mod go.sum./
RUNgo mod download

CMD["air","-c",".air.toml"]

docker-compose.yaml

version:"3.8"
services:
web:
build:
context:.
#Correct the path to your Dockerfile
dockerfile:Dockerfile
ports:
-8080:3000
#Important to bind/mount your codebase dir to /app dir for live reload
volumes:
-./:/app

Q&A

"command not found: air" or "No such file or directory"

exportGOPATH=$HOME/xxxxx
exportPATH=$PATH:$GOROOT/bin:$GOPATH/bin
exportPATH=$PATH:$(go env GOPATH)/bin<---- Confirm this lineinyou profile!!!

Error under wsl when ' is included in the bin

Should use\to escape the `' in the bin. related issue:#305

Question: how to do hot compile only and do not run anything?

#365

[build]
cmd="/usr/bin/true"

How to Reload the Browser Automatically on Static File Changes

Refer to issue#512for additional details.

• Ensure your static files ininclude_dir,include_ext,orinclude_file.
• Ensure your HTML has a</body>tag
• Activate the proxy by configuring the following config:

[proxy]
enabled=true
proxy_port= <air proxy port>
app_port= <your server port>

Development

Please note that it requires Go 1.16+ since I usego modto manage dependencies.

#Fork this project

#Clone it
mkdir -p$GOPATH/src/github.com/cosmtrek
cd$GOPATH/src/github.com/cosmtrek
git clone [email protected]:<YOUR USERNAME>/air.git

#Install dependencies
cdair
make ci

#Explore it and happy hacking!
make install

Pull requests are welcome.

Release

#Checkout to master
git checkout master

#Add the version that needs to be released
git tag v1.xx.x

#Push to remote
git push origin v1.xx.x

#The CI will process and release a new version. Wait about 5 min, and you can fetch the latest version

Star History

Sponsor

Give huge thanks to lots of supporters. I've always been remembering your kindness.

License

GNU General Public License v3.0