🔥 A next-generation CLI tool for building amazing web apps in Go using htmx & hyperscript
Tags: go, htmx, beginners, opensource
Published: 2023-09-30 11:11:57

## Introduction

Hey, my DEV friends! 👋 

It's been a while since I've been here, hasn't it? Sorry I've been missing, but there was a good reason... one of which I'm going to talk about in this article.

So, here is a new CLI tool that I have named [**gowebly**][gowebly_url] 👇

<a name="toc"></a>
### 📝 Table of contents

- [What is gowebly?](#what-is-gowebly)
- [What is the enjoyment of using it?](#what-is-the-enjoyment-of-using-it)
- [Motivation in CLI creation](#motivation-in-cli-creation)
- [Mutually beneficial cooperation](#mutually-beneficial-cooperation)

<a name="#what-is-gowebly"></a>
## What is gowebly?

It's a next-generation CLI tool that makes it easy to create amazing web applications using Go on the backend (**net/http**, **Fiber**, **Echo**, **chi**, etc.), **htmx** and **hyperscript**, and the most popular atomic/utility-first **CSS frameworks** (**Tailwind CSS**, **UnoCSS**, etc.) on the frontend.

Fully configured **Docker** files, as well, are included in your project.

{% github https://github.com/gowebly/gowebly %}

[↑ Table of contents](#toc)

<a name="#what-is-the-enjoyment-of-using-it"></a>
## What is the enjoyment of using it?

The main purpose of `gowebly` CLI is to make it easier to create a new project. And it does this very well! But it's better to see it once than to hear it a hundred times:

{% youtube https://www.youtube.com/watch?v=qazYscnLku4 %}

The first thing you need to do is to install it. This can be done via: 

- Homebrew (for GNU/Linux and Apple macOS users);
- Native Go installation (any platforms);
- Docker image (any platforms);
- Downloading a ready-made executable (any platforms).

> 💡 Note: No matter how exactly you want to install the `gowebly` CLI, it will work fine either way.

Once the `gowebly` CLI is installed on your system, the following commands are available to you: `init`, `create`, `run`, and `build`. 

Let's take a closer look at them 😊

> 💡 Note: Also, keep in mind that the documentation of the `gowebly` project has **already been** translated to: [Русский][gowebly_readme_ru_url], [中文][gowebly_readme_cn_url] and [Español][gowebly_readme_es_url]. 
>
> And the original language, of course, [English][gowebly_url].

### `init` command

Command to create a **default** config file ([`.gowebly.yml`][gowebly_default_config]) in the current folder.

<img width="720" alt="gowebly init" src="https://github.com/gowebly/gowebly/assets/11155743/679dd0e1-ecd6-4cfb-b145-c9f551ab2d9c">

Every time you make `gowebly init` command in the empty folder:

1. CLI validates the current folder;
2. CLI creates a default `.gowebly.yml` config file.

Typically, a created config file contains the following options:

```yaml
backend:
   module_name: project # (string) option can be any name of your Go module (for example, 'github.com/user/project')
   go_framework: default # (string) option can be one of the values: 'fiber', 'echo', 'chi', or 'default'
   port: 5000 # (int) option can be any port that is not taken up on your system
   timeout:
      read: 5 # (int) option can be any number of seconds, 5 is recommended
      write: 10 # (int) option can be any number of seconds, 10 is recommended

frontend:
   package_name: project # (string) option can be any name of your package.json (for example, 'project')
   css_framework: default # (string) option can be one of the values: 'tailwindcss', 'unocss', or 'default'
   runtime_environment: default # (string) option can be one of the values: 'bun', or 'default'
   htmx: latest # (string) option can be any existing version
   hyperscript: latest # (string) option can be any existing version
```

You can choose any **Go framework** for your project's backend:

| Go framework | Description                                                                 |
|--------------|-----------------------------------------------------------------------------|
| `default`    | Don't use any Go framework (only built-in [net/http][net_http_url] package) |
| `fiber`      | Use a Go backend with the [Fiber][fiber_url] web framework                  |
| `echo`       | Use a Go backend with the [Echo][echo_url] web framework                    |
| `chi`        | Use a Go backend with the [chi][chi_url] composable router                  |

In additional, you can choose versions of the **htmx**, **hyperscript**, and one of the most popular atomic/utility-first **CSS framework** to your project:

| CSS framework | Description                                                            |
|---------------|------------------------------------------------------------------------|
| `default`     | Don't use any CSS framework (only default styles for the code example) |
| `tailwindcss` | Use the [Tailwind CSS][tailwindcss_url] as a CSS framework             |
| `unocss`      | Use the [UnoCSS][unocss_url] as a CSS framework                        |

Also, you can set one of the JavaScript runtime environment for your frontend part:

| JavaScript runtime | Description                                                       |
|--------------------|-------------------------------------------------------------------|
| `default`          | Use the [Node.js][nodejs_url] as a JavaScript runtime environment |
| `bun`              | Use the [Bun][bun_url] as a JavaScript runtime environment        |

### `create` command

Command to create a new project with the **Go** backend, **htmx** & **hyperscript**, and (_optionally_) atomic/utility-first **CSS framework**.

> 💡 Note: If you don't run `init` command to create a config file (`.gowebly.yml`), the `gowebly` CLI creates a new project with a [default][gowebly_default_config] configuration.

<img width="720" alt="gowebly create" src="https://github.com/gowebly/gowebly/assets/11155743/35b15677-4991-406d-b666-dfbc40beb1ce">

Every time you make `gowebly create` command for your project:

1. CLI validates the config and applies all settings to the current project;
2. CLI prepares the backend part of your project (generates the project structure and needed utility files, runs `go mod tidy`);
3. CLI prepares the frontend part of your project (generates the needed utility files, runs `npm|bun install` and `npm|bun run build:dev` for the first time);
4. CLI downloads minimized versions of **htmx** and **hyperscript** (from official and trusted [unpkg.com][unpkg_url] CDN) to the `./static` folder and places them as separated `<script>` tags (at the bottom of the `<body>` tag) in the Go HTML template [`templates/main.html`][gowebly_main_layout].

Typically, a created project contains the following files and folders:

```console
.
├── assets
│   └── styles.css
├── static
│   ├── favicon.ico
│   ├── htmx.min.js
│   ├── hyperscript.min.js
│   └── styles.css
├── templates
│   ├── pages
│   │   └── index.html
│   └── main.html
├── .gitignore
├── go.mod
├── go.sum
├── handlers.go
├── main.go
├── package-lock.json
├── package.json
└── server.go
```

### `run` command

Command to run your project in a **development** (non-production) mode.

> 💡 Note: If you don't run `init` command to create a config file (`.gowebly.yml`), the `gowebly` CLI runs your project with a [default][gowebly_default_config] configuration.

<img width="720" alt="gowebly run" src="https://github.com/gowebly/gowebly/assets/11155743/51c05652-4601-4f8b-8722-20401d0099d1">

Every time you make `gowebly run` command for your project:

1. CLI validates the config and applies all settings to the current project;
2. CLI prepares the frontend part of your project (runs `npm|bun run build:dev`);
3. CLI prepares a development (non-production) version of the selected **CSS framework** to the `./static` folder and places it as a `<link>` tag (at the bottom of the `<head>` tag) in the Go HTML template [`templates/main.html`][gowebly_main_layout];
4. CLI starts a project's backend with settings from the default configuration (or from the `.gowebly.yml` config file) by a simple `go run` command.

### `build` command

Command to build your project for **production** and prepare Docker files for deploy.

> 💡 Note: If you don't run `init` command to create a config file (`.gowebly.yml`), the `gowebly` CLI builds your project with a [default][gowebly_default_config] configuration.

<img width="720" alt="gowebly build" src="https://github.com/gowebly/gowebly/assets/11155743/ac35b01f-0596-4d33-832e-1618709497d3">

You might add the following options:

| Option          | Description                                                                    | Required? |
|-----------------|--------------------------------------------------------------------------------|-----------|
| `--skip-docker` | Skip generation process for the Docker files (it's helpful if you've your own) | no        |

Every time you make `gowebly build` command for your project:

1. CLI validates the config and applies all settings to the current project;
2. CLI downloads minimized versions of **htmx** and **hyperscript** (from official and trusted [unpkg.com][unpkg_url] CDN) to the `./static` folder and places them as separated `<script>` tags (at the bottom of the `<body>` tag) in the Go HTML template [`templates/main.html`][gowebly_main_layout];
3. CLI prepares a production version of the selected **CSS framework** and places it as a `<link>` tag (at the bottom of the `<head>` tag) in the Go HTML template [`templates/main.html`][gowebly_main_layout];
4. If the `--skip-docker` option is not set, CLI generate a clear and well-documented Docker files (`.dockerignore`, `Dockerfile`, `docker-compose.yml`) in the root of the project folder to deploy it in isolated containers via [Portainer][portainer_url] (_recommended_), or manually, to your remote server.

[↑ Table of contents](#toc)


![gowebly logo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3xe08xv1v6wlm4lihlql.png)

<a name="#motivation-in-cli-creation"></a>
## Motivation in CLI creation

Tell me, how often have you had to start a new project from scratch and had to make painful manual configurations? 🤔 Especially, when you are just getting acquainted with a new technology or stack, where everything is new to you.

For many developers, _including me_, this process is as tedious and even depressing as possible, and doesn't carry any useful workload. It is a **very** frustrating process that can push any developer away from technology a lot.

Why not just give all that awful manual work to machines? Let them do all the hard work for us, and we will just create awesome web products and not have to think about build and deploy.

That's why I created the [gowebly CLI][gowebly_url] and [its helpers' library][gowebly_helpers_url], which helps you start an amazing web applications in **Go** using **htmx**, **hyperscript** and popular atomic/utility-first **CSS frameworks**.

I am here to save you (_and myself_) from this routine pain! ✨

> Earlier, I have already saved the world once, it was [Create Go App][cgapp_url] (yep, that's my project too). The [GitHub stars][cgapp_stars_url] statistics of this project can't lie: more than **2.2k** developers of any level and different countries start a new project through this CLI tool.

[↑ Table of contents](#toc)

<a name="#mutually-beneficial-cooperation"></a>
## Mutually beneficial cooperation

And now, I invite you to participate in this project! Let's work **together** to create the **most useful** tool for developers on the web today.

- [Issues][gowebly_issues_url]: ask questions and submit your features.
- [Pull requests][gowebly_pull_request_url]: send your improvements to the current.

Your PRs & issues are welcome! Thank you 😘

[↑ Table of contents](#toc)

<a name=""></a>
## Photos and videos by

- Vic Shóstak https://github.com/koddr

<!-- Article links -->

[gowebly_readme_ru_url]: https://github.com/gowebly/gowebly/blob/main/README_RU.md
[gowebly_readme_cn_url]: https://github.com/gowebly/gowebly/blob/main/README_CN.md
[gowebly_readme_es_url]: https://github.com/gowebly/gowebly/blob/main/README_ES.md
[gowebly_issues_url]: https://github.com/gowebly/gowebly/issues
[gowebly_pull_request_url]: https://github.com/gowebly/gowebly/pulls
[gowebly_default_config]: https://github.com/gowebly/gowebly/blob/main/internal/attachments/configs/default.yml
[gowebly_main_layout]: https://github.com/gowebly/gowebly/blob/main/internal/attachments/templates/frontend/main.html
[gowebly_helpers_url]: https://github.com/gowebly/helpers
[cgapp_url]: https://github.com/create-go-app/cli
[cgapp_stars_url]: https://github.com/create-go-app/cli/stargazers
[nodejs_url]: https://nodejs.org
[bun_url]: https://bun.sh
[docker_image_url]: https://hub.docker.com/repository/docker/gowebly/gowebly
[portainer_url]: https://docs.portainer.io
[brew_url]: https://brew.sh
[htmx_url]: https://htmx.org
[hyperscript_url]: https://hyperscript.org
[tailwindcss_url]: https://tailwindcss.com
[unocss_url]: https://unocss.dev
[unpkg_url]: https://unpkg.com
[net_http_url]: https://pkg.go.dev/net/http
[fiber_url]: https://github.com/gofiber/fiber
[echo_url]: https://github.com/labstack/echo
[chi_url]: https://github.com/go-chi/chi

<a name=""></a>
## P.S.

If you want more articles (like this) on this blog, then post a comment below and subscribe to me. Thanks! 😻

And of course, you can help me make developers' lives even better! Just connect to one of my projects as a contributor. It's easy!

My projects that need your help (and stars) 👇

- 🔥 [gowebly][gowebly_url]: A next-generation CLI tool for easily build amazing web applications with Go on the backend, using htmx & hyperscript and the most popular atomic/utility-first CSS frameworks on the frontend.
- ✨ [create-go-app][cgapp_url]: Create a new production-ready project with Go backend, frontend and deploy automation by running one CLI command.
- 🏃 [yatr][yatr_url]: Yet Another Task Runner allows you to organize and automate your routine operations that you normally do in Makefile (or else) for each project.
- 📚 [gosl][gosl_url]: The Go Snippet Library provides snippets collection for working with routine operations in your Go programs with a super user-friendly API and the most efficient performance.
- 🏄‍♂️ [csv2api][csv2api_url]: The parser reads the CSV file with the raw data, filters the records, identifies fields to be changed, and sends a request to update the data to the specified endpoint of your REST API.
- 🚴 [json2csv][json2csv_url]: The parser can read given folder with JSON files, filtering and qualifying input data with intent & stop words dictionaries and save results to CSV files by given chunk size.

<!-- Footer links -->

[gowebly_url]: https://github.com/gowebly
[cgapp_url]: https://github.com/create-go-app
[yatr_url]: https://github.com/koddr/yatr
[gosl_url]: https://github.com/koddr/gosl
[csv2api_url]: https://github.com/koddr/csv2api
[json2csv_url]: https://github.com/koddr/json2csv