go-web-starter-kit/pages/index.md

Go Web Starter Kit

This is a fairly complete web development starter kit in Go. It tries to be as simple as possible without leaving out modern features like reactive UIs and database migrations. A primary thing that's included is working authentication, since that's the main thing holding people back when they first start, and also the easiest to get wrong.

In fact, if you look at how I do it in this first version it is WRONG so do not use this in production yet until I can make it correct. Just use it to learn for now.

The Stack

Currently I'm using the following components in a tastefully crafted stack similar to a Crepe Cake:

• goose -- This manages the database migrations.
• sqlx -- This is the database driver.
• squirrel -- This is the SQL query generator.
• Fiber -- This is the main web API and does most everything you need.
• tailwind -- This makes your sites perty and is easy to use, but I reject the @apply slander and use @apply to give you nice things.
• Alpine.js -- This gives you just enough reactivity to not be annoyed, but not so much that you hate the web.
• ssgod -- A static site generator I wrote that only does static site generation.
• chromedp -- This does your automated testing for you.

I then add a few little "sweetener" APIs on top of this for simple things like, making the tests nicer or making it easier to quickly return a page from a view.

Isn't Fiber Banned?!

First off, nobody has the right to "ban" a project. If you're hanging out in the Go discord and you've seen Fiber on some ban list then whoever did that is a fucking asshole. Just ignore that bullshit and use the best tech you can.

Second, if you're only supposed to use the Go standard library then why is there a whole fucking document on the official go website explaining how to use Gin to make an API?. It seems like whoever is claiming that you are only allowed to use the Go standard library is in disagreement with the actual fucking Go project.

Finally, you don't have to do what you're told, especially when the person telling you what to do is some random asshole hiding in a chat room being a random asshole. Use what you want, and Fiber is in that sweet spot of being a nice API that isn't slow dogshit like Gin.

Getting Started

First, install a couple tools that'll be used everywhere, and that have huge dependencies you don't actually need in your project:

go install golang.org/x/pkgsite/cmd/pkgsite@latest
go install github.com/pressly/goose/v3/cmd/goose@latest

You can get use this project working by doing this:

git clone https://lcthw.dev/go/go-web-starter-kit.git my-project
cd my-project

Then on Linux/OSX you want to delete the .git with this:

rm -rf .git
mv LICENSE LICENSE.old # it's MIT

And on Windows you use the ever more clear and totally easier:

rm -recurse -force .git
mv LICENSE LICENSE.old # it's MIT

Once you have that you can make it your own:

git init .
go mod tidy
cp config_example.toml config.toml
make migrate_up
sqlite3 db.sqlite3 ".read tools/pragmas.sql"
make build
make dev

This gets the site running and ready for development. You only need to do this once.. After this, when you're ready to work just do:

make dev

Configuration

There's 3 basic moving parts to the whole system: webapp.exe, ssgod, tailwind, and ozai.

You can configure the webapp.exe using the config.toml which you copied over from config_example.toml. The options are fairly self-explanatory.

You can configure ssgod using the ssgod.toml file. You'll notice that there's two layouts with this setup, one for webapp.exe and another for ssgod. You can just point ssgod at your views/layouts/main.html file if you want, but it seems people want two different layouts for their static site vs. "the app."

You can configure tailwind using the static/input_style.css and editing the Makefile to have it run how you want. I use the @apply heavily because I'm a programmer and no programmer would ever tell someone they should sprinkle repetitive bullshit all over their HTML. Resist the authority. Use @apply.

Finally, you can configure other processes to run with Ozai in the .ozai.json file. Why so many different formats? I'm still learning which is best to use and while I like TOML I think I may go with .json files to reduce dependencies. You tell me though.

Ozai Autorestarts

Ozai is a simpler tool that doesn't do auto restart. Instead it will create a little webserver at http://127.0.0.1:9999 with endpoints you can hit with curl to force a restart. Look in the .ozai.json file to see what's configured. This makes it easy to simple add a curl call in your build process and kick everything over. Look in the Makefile for how I do this.

This works better than the way Air does it for a few reasons:

1. You can run your build like normal in your own IDE or build tool and see your errors directly. When you use other autobuild tools they have the errors so you can't access them.
2. You get an immediate restart after your build succeeds, rather than waiting for an external tool to detect you made changes, run the build, and then restart your browser.
3. You avoid the "auto reload deadlock" where you run a build, the server is shutdown, but you hit refresh too soon, so now your browser waits for an error, then you have to refresh again. Way easier to just not use any of that.
4. No more silent failures hiding inside your terminal that you can't see. Just manually restart it.

For more, checkout the Ozai Project.

Tour of Directories

The directories are organized in a way that separates "App Stuff" from "Content Stuff".

• admin App The code for the built-in database admin tool.
• api App Where you put your JSON API and views handlers.
• commonApp Common helper functions.
• config App The configuration for your site, which is config.toml loaded into Go structs.
• data App Your database stuff. You put your SQL models in here, and then add them to the bottom Map to make them magically show up in the /admin/table/ tool.
• migrations App When you use goose it puts the migrations in here.
• tests App Your tests go in here. I use chromedp but the chromedp API is too low level (and weird) to be useful so look in tests/tools.go for what I use.
• tools App I put my little automation tools here. I'll be adding an admin tool that will let you admin the database from the CLI, plus probably a tool to run all the things and manage them.
• views App This is where you put the App contents, not the static content. See the Dev Workflow section on how to work to make dev faster but also use static files in production when things are working.

These directories then control you static content, but are also used by the App content. For example, static/ contains the static/input_style.css which is turned into static/style.css. The static/style.css is used by everything to--you guessed it--style your whole site.

• pages Static This is the static content you want generated by ssgod. See Dev Workflow for how I use this.
• static Static This is static content like .js, images, and .css files that are only copied over by ssgod.

The following directories are considered "build junk" and you should not commit them to your git.

• public Junk This is generated by ssgod and then served by your webapp.exe. Don't edit anything in here, and instead edit in pages or static.
• tmp Junk This is made during the build/testing process.

Dev Workflow

Warning Parts of this are not optimal. I have to work on how to make this easier, parmarily how to run all the things with one command and manage them.

The first thing I do is run each of these commands in different terminals, either with tmux or just using my fingers to run multiple tabs in PowerShell:

make dev

Working on Pages

Once those are running in different terminals I mostly have everything I need to work in my editor of choice and have things autobuild. I then put my content into pages/ and manually reload after ssgod/tailwind autoruns.

Working on Views

Another way is to put your content into views, and then add this one line of code to your api/handlers.go. For example, if I want to create /mypage/ I do this:

# make the file with an editor on Windows
echo "Test" > views/mypage.html

# edit api/handlers.go
app.Get("/mypage/", Page("mypage"))

Warning On windows the above echo command creates garbage in the output because Windows is weird. Just make the file with a text editor.

Using the Tailwind Starter

I've included tailwind in this setup, since it's decent at getting things working quickly right in the HTML. The only thing I've fully rejected is the idea that "@apply is bad m'kay." No, @apply makes it so I don't rage at all the idiots who think 92 repeated CSS classes on every div is "good practice."

NOTE You can view a sample page with all of these in /examples/sample.html and you can look at the other files in examples to get an idea of what you can do. Some of these just use tailwind, others use my starter kit.

In my setup there's a static/input_style.css that is used to generate a static/style.css and it comes preconfigured with many of the things you'll need to get a page up and running. In theory you can prototype a first page with just HTML and a bit of tailwind as needed. It also uses many of the stock HTML tags like aside and mark so you can keep things nice.

I've added 4 additional layout tags for you to use:

• grid -- For stuff in a grid. Add class="grid-cols-2" from tailwind to change its layout.
• block -- A simple pre-configured vertical flex box. Put it around vertical stuff.
• bar -- A simple pre-configured horizontal flex box. Pit it around horizontal stuff.
• stack -- A simple way to stack stuff on top of other stuff. You know, like in every single 2d compositional system since the 1500s.
• shape -- A simple 2d box to use for placeholders where you'll put images. It's a lot quicker to drop a little shape than to go find an image. I think it also makes it easier to focus on the design.

Is that "Accessible"?! What about SEO?!

Yes, I actually tested all of this with NV Access and the only thing NV Access seems to have a problem with is the pre and code tags. That's because apparently those are deemed as "images" so they get ignored...which is about the dumbest fucking shit I've ever heard. I'm working on a way to fix that.

Anyone telling you that my grid, bar, block, or stack tags impact accessibility most likely has never ran NV Access one time so they're just wrong. Additionally, it's better to have these be ignored by screen readers because they're just 2D layout junk, so they're kind of irrelevant to a linear 1D screen reader.

Finally, SEO isn't impacted because Google has literally said HTML quality doesn't matter for SEO ranking. Think about it, if Google went around dictating exact HTML they would get in so much Monopoly trouble. Instead they tend to focus more on content and organization, and I believe the official quote is, "Making everyone use the same HTML would make the web boring."

However, take this with a grain of salt because the same Google people who've said this also said that backlinks didn't impact performance and many SEO experts say this is totally not true. Do your own testing, and if it impact your SEO than just change them after you get your initial design up.

Conclusion

Hopefully that gets you started in this project. I'll be improving the usability of this as I use it myself, but if you have suggestions please email me at help@learncodethehardway.com.