SUPERKIT

Build high-performance apps swiftly with minimal team resources in Go programming language. SUPERKIT is a full-stack web framework that provides a set of tools and libraries to help you build web applications quickly and efficiently. SUPERKIT is built on top of the Go programming language and is designed to be simple and easy to use.

The project (for now) is in the experimental phase.

Table of content

• SUPERKIT
  • Table of content
• Installation
• Getting started
  • Application structure
    • assets
    • conf
    • db
    • events
    • handlers
    • types
    • views
  • Development server
  • Hot reloading the browser
• Migrations
  • Create a new migration
  • Migrate the database
  • Reset the database
  • Seeds
• Creating views with Templ
• Validations
• Testing
  • Testing handlers
• Create a production release

Installation

To create a new SUPERKIT project, you can run the following command:

# Create your SUPERKIT project in a single command:
go run github.com/anthdm/superkit@master [yourprojectname]

# You can now navigate to your project:
cd [myprojectname]

# Run npm install to install both tailwindcss and esbuild locally.
npm install

# If you run into dependency issues you can run:
go clean -modcache && go get -u ./...  

# If you have the authentication plugin enabled you need to migrate your database.
make db-up 

Getting started

Application structure

The SUPERKIT project structure is designed to be simple and easy to understand. The project structure is as follows:

├── bootstrap
│   ├── app
│     ├──  assets
│     ├──  conf
│     ├──  db
│       ├── migrations 
│     ├──  events
│     ├──  handlers
│     ├──  types
│     ├──  views
│       ├── components
│       ├── errors
│       ├── landing
│       ├── layouts
│   ├── cmd
│     ├── app
│     ├── scripts
│       ├── seed
│   ├── plugins
│     ├── auth
│   ├── public
│     ├── assets
│   ├── env.local
│   ├── go.mod
│   ├── go.sum
│   ├── Makefile
│   ├── package-lock.json
│   ├── package.json
│   ├── tailwind.config.js
├── db
├── event 
├── kit
│   ├── middleware
├── validate
├── view
├── go.mod
├── install.go
├── README.md

assets

Assets are stored in the assets directory. This directory contains all your CSS and JavaScript files. The assets directory is structured as follows:

assets
├── css
│   ├── app.css
├── js
│   ├── app.js

conf

Configuration. First, config.yml is read, then environment variables overwrite the yaml config if they match. The config structure is in the config.go. The env-required: true tag obliges you to specify a value (either in yaml, or in environment variables).

Reading the config from yaml contradicts the ideology of 12 factors, but in practice, it is more convenient than reading the entire config from ENV. It is assumed that default values are in yaml, and security-sensitive variables are defined in ENV.

db

The db directory contains all your database related files. The db directory is structured as follows:

db
├── migrations
│   ├── 20210919123456_create_users_table.sql
├── seeds
│   ├── seed.go

events

The events directory contains all your event related files. These files are used to define custom events and event handlers for the project. The events directory is structured as follows:

events
├── event.go

handlers

The handlers directory contains the main handlers or controllers for the project. These handlers handle incoming requests, perform necessary actions, and return appropriate responses. They encapsulate the business logic and interact with other components of the project, such as services and data repositories.

It is important to note that the project structure described here may not include all the directories and files present in the actual project. The provided overview focuses on the key directories relevant to understanding the structure and organization of the project.

types

The types directory contains all your type related files. For example, you can define your models, structs, and interfaces in this directory. The types directory is structured as follows:

types
├── user.go
├── auth.go

views

The views directory contains all your view related files. These files are used to render HTML templates for the project. The views directory is structured as follows:

views
├── home.go
├── about.go

Development server

You can run the development server with the following command:

make dev 

Hot reloading the browser

Hot reloading is configured by default when running your application in development.

NOTE: on windows or on in my case (WSL2) you might need to run make watch-assets in another terminal to watch for CSS and JS file changes.

Migrations

Create a new migration

make db-mig-create add_users_table

The command will create a new migration SQL file located at app/db/migrations/add_users_table.sql

Migrate the database

make db-up

Reset the database

make db-reset

Seeds

make db-seed

This command will run the seed file located at cmd/scripts/seed/main.go

Creating views with Templ

superkit uses Templ as its templating engine. Templ allows you to create type safe view components that renders fragments of HTML. In-depth information about Templ can be found here: Templ documentation

Validations

todo

Testing

Testing handlers

Create a production release

superkit will compile your whole application including its assets into a single binary. To build your application for production you can run the following command:

make build

This will create a binary file located at /bin/app_prod.

Make sure you also set the correct application environment variable in your .env file.

SUPERKIT_ENV = production