Quick Start

Build your first Gorbit application.

Choose an IDE

Choose a code editor or integrated development environment (IDE) for Go development. Any editor can be used, but the following options provide excellent support for Go, including syntax highlighting, code completion, debugging, and integrated tooling.

Visual Studio Code ↗JetBrains GoLand ↗Helix Editor ↗

If you're using Visual Studio Code, install the official Go extension to enable features such as IntelliSense, code navigation, formatting, testing, debugging, and automatic package management.

Go Extension for Visual Studio Code ↗
When you open your first Go project, your editor may prompt you to install additional Go tools. Accept the installation to enable the full development experience.

Create a Project

Create a new directory for your project and initialize a Go module. The module name should usually match your repository path if you plan to publish it.

Create Project Directory
If you are testing locally
If your project is going to be put on github

This creates a go.mod file, which defines your project's module path and manages its dependencies.

Project Structure
Project structure.
Project structure.
Create main.go
Run the Project
Build the Project
Project setup and ran.
Project setup and ran.
If you import external packages, run 'go mod tidy' to automatically download and manage your project's dependencies.

Install Gorbit

Gorbit can be added to any existing Go module using the Go package manager. Make sure you have initialized your project with 'go mod init' before installing the framework.

Gorbit GitHub Repository ↗
Install Gorbit

Go will automatically download Gorbit and its required dependencies, then record them in your project's go.mod and go.sum files.

Verify Installation
If you're using Go 1.17 or newer, running 'go mod tidy' after installing is recommended to download missing packages and remove unused dependencies.

Hello World

With Gorbit installed, you're ready to create your first web server. The example below starts a server on port 3000 and responds with "Hello World" when the root route is accessed.

main.go

Run the application from your project directory using the Go toolchain.

Run the Server

Once the server starts, open your browser and navigate to the address below. You should see the message "Hello World" displayed in your browser.

http://localhost:3000 ↗
The application listens on port 3000 because it was passed to gb.New(3000). You can change this to any available port if needed.

Project Structure

A well-structured project keeps your application organized, maintainable, and easy to scale. Gorbit does not enforce a specific folder layout, but the following RESTful architecture is recommended for most applications.

Recommended Project Structure

Each directory has a single responsibility. Separating your application into layers makes it easier to maintain, test, and extend as your project grows.

controllers/ Contains request handlers responsible for processing incoming HTTP requests, validating input, and generating responses. Controllers should contain minimal business logic and delegate complex operations to services.
routes/ Defines all API endpoints and maps them to controller functions. Keeping routing separate makes the application's endpoints easy to navigate and maintain.
middleware/ Stores reusable middleware such as authentication, authorization, logging, CORS, rate limiting, and request validation. Middleware executes before or after route handlers.
services/ Contains the application's business logic. Services perform operations such as authentication, file processing, AI inference, email delivery, or external API communication. Controllers should call services instead of implementing business logic directly.
db/ Handles database configuration, connection pools, transactions, queries, migrations, and helper functions. Centralizing database access keeps the rest of the application independent of the underlying database implementation.
utils/ Provides reusable helper functions such as environment variable loading, hashing, JWT utilities, validation helpers, formatting functions, and other shared utilities used across the application.
main.go The application's entry point. It initializes the server, connects to the database, registers middleware, configures routes, and starts the HTTP server.
go.mod & go.sum Manage your project's module information and dependencies. Go automatically updates these files whenever packages are added or removed.

This architecture keeps routing, request handling, business logic, database access, and utilities independent of one another, making the codebase easier to understand, test, and scale as your application evolves.