Grit Desktop — Complete LLM Reference

1What is Grit Desktop?

Grit Desktop builds native desktop applications using Go + Wails + React. One command (grit new-desktop myapp) scaffolds a complete project that compiles to a single native binary. No browser, no Electron, no separate runtime.

The scaffolded project includes JWT authentication, blog and contact CRUD resources, PDF and Excel data export, a custom frameless title bar, dark theme with shadcn/ui components, toast notifications, and GORM Studio for database browsing — all out of the box.

2Why Wails (not Electron or Tauri)?

Grit chose Wails because Go is already the backend language for Grit web projects. Using Wails means developers write Go for both web and desktop — no Rust learning curve (Tauri), and none of Electron's bloat.

3Architecture

Unlike Grit web projects (which use Gin HTTP server), desktop projects have no HTTP server. Wails bridges Go and JavaScript directly. The React frontend calls Go functions through generated TypeScript bindings.

Call Flow

React Component
  --> Wails TypeScript Binding (auto-generated)
    --> Go App Method (on the App struct)
      --> GORM Service (business logic + queries)
        --> SQLite Database

4Project Structure

Desktop projects are a single directory (not a monorepo). Go code lives at the root and in internal/, while the React frontend lives in frontend/.

myapp/
├── main.go                  # Wails entry point — creates app, binds methods
├── app.go                   # App struct with all bound methods + constructor
├── types.go                 # Input structs for bound methods
├── wails.json               # Wails project configuration
├── go.mod                   # Go module definition
├── go.sum                   # Go dependency checksums
│
├── internal/
│   ├── config/
│   │   └── config.go        # App configuration (reads .env)
│   ├── db/
│   │   └── db.go            # GORM database setup (SQLite) + AutoMigrate
│   ├── models/
│   │   ├── user.go          # User model (auth)
│   │   ├── blog.go          # Blog post model (scaffolded example)
│   │   └── contact.go       # Contact model (scaffolded example)
│   └── service/
│       ├── auth.go          # Authentication service (register, login, JWT)
│       ├── blog.go          # Blog CRUD service
│       └── contact.go       # Contact CRUD service
│
├── frontend/
│   ├── src/
│   │   ├── main.tsx          # React entry point (TanStack Router)
│   │   ├── routes/           # File-based routes (TanStack Router)
│   │   │   ├── __root.tsx    # Root route
│   │   │   ├── _layout.tsx   # Auth guard + sidebar layout
│   │   │   └── _layout/      # Protected page routes
│   │   ├── components/       # Shared UI: sidebar, title-bar, data-table, etc.
│   │   │   └── sidebar.tsx   # App sidebar with navigation
│   │   ├── hooks/            # TanStack Query hooks for Wails bindings
│   │   └── lib/              # Utilities
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.js
│
├── build/
│   ├── appicon.png           # App icon (1024x1024 — auto-converted per platform)
│   └── bin/                  # Build output directory
│
└── cmd/
    └── studio/
        └── main.go           # GORM Studio server (port 8080)

5All CLI Commands

Every desktop-relevant command. The CLI auto-detects desktop projects by checking for wails.json.

6Resource Generation — Complete Reference

The same grit generate resource command works for both web and desktop projects. The CLI auto-detects the project type by checking for wails.json.

Syntax

Supported Field Types

Slug Field Syntax

The slug type uses a special syntax to specify the source field:

This adds a uniqueIndex and a GORM BeforeCreate hook that auto-generates the slug from the title. Slug fields are excluded from forms and input structs.

Files Created Per Resource

Example: Generate a Product Resource

package models

import (
    "gorm.io/gorm"
)

type Product struct {
    gorm.Model
    Name      string  `gorm:"not null" json:"name"`
    Price     float64 `json:"price"`
    Stock     int     `json:"stock"`
    Published bool    `gorm:"default:false" json:"published"`
}

type ProductInput struct {
    Name      string  `json:"name"`
    Price     float64 `json:"price"`
    Stock     int     `json:"stock"`
    Published bool    `json:"published"`
}

package service

import (
    "myapp/internal/models"
    "gorm.io/gorm"
)

type ProductService struct {
    DB *gorm.DB
}

type PaginatedResult struct {
    Data  interface{} `json:"data"`
    Total int64       `json:"total"`
    Page  int         `json:"page"`
    Pages int         `json:"pages"`
}

func (s *ProductService) List(page, pageSize int, search string) (*PaginatedResult, error) { ... }
func (s *ProductService) ListAll() ([]models.Product, error) { ... }
func (s *ProductService) GetByID(id uint) (*models.Product, error) { ... }
func (s *ProductService) Create(input models.ProductInput) (*models.Product, error) { ... }
func (s *ProductService) Update(id uint, input models.ProductInput) (*models.Product, error) { ... }
func (s *ProductService) Delete(id uint) error { ... }

7DataTable (List Page)

Every generated resource gets a list page with a full-featured DataTable. Here is what it includes out of the box:

Customizing Columns

Columns are defined in the list page index.tsx. You can reorder, rename, add custom formatting, or add computed columns:

const columns = [
  { accessorKey: "name", header: "Product Name" },
  {
    accessorKey: "price",
    header: "Price",
    cell: ({ row }: any) => "$" + Number(row.getValue("price")).toFixed(2),
  },
  { accessorKey: "stock", header: "Stock" },
  {
    accessorKey: "published",
    header: "Status",
    cell: ({ row }: any) =>
      row.getValue("published") ? "Published" : "Draft",
  },
];

8FormBuilder (Form Page)

Every generated resource gets a form page that handles both creating and editing records. The form fields are determined by the field types declared during generation.

Field Type to Form Input Mapping

Create vs Edit Mode

9Wails Bound Methods

Go methods on the App struct are automatically available in React. Wails generates TypeScript bindings during wails dev and wails build. React calls them as async functions.

7 Methods Generated Per Resource

// List with pagination and search
func (a *App) GetProducts(page, pageSize int, search string) (*service.PaginatedResult, error)

// Get single record by ID
func (a *App) GetProduct(id uint) (*models.Product, error)

// Create new record
func (a *App) CreateProduct(input models.ProductInput) (*models.Product, error)

// Update existing record
func (a *App) UpdateProduct(id uint, input models.ProductInput) (*models.Product, error)

// Delete record (soft delete)
func (a *App) DeleteProduct(id uint) error

// Export all records as PDF (returns raw bytes)
func (a *App) ExportProductsPDF() ([]byte, error)

// Export all records as Excel (returns raw bytes)
func (a *App) ExportProductsExcel() ([]byte, error)

Calling from React

Wails generates TypeScript bindings in frontend/wailsjs/. Import and call them as async functions:

import { GetProducts, DeleteProduct, ExportProductsPDF, ExportProductsExcel } from "../../wailsjs/go/main/App";

// In a component:
const result = await GetProducts(page, pageSize, searchQuery);
// result = { data: Product[], total: number, page: number, pages: number }

await DeleteProduct(productId);

const pdfBytes = await ExportProductsPDF();
// Save pdfBytes as a file using browser APIs

const excelBytes = await ExportProductsExcel();
// Save excelBytes as .xlsx file

10Building into Executable

Compile the entire application — Go runtime, React UI, static assets, and SQLite — into a single native binary.

This runs wails build under the hood. The React frontend is embedded via //go:embed all:frontend/dist — no separate files need to be distributed.

Build Output

Cross-Platform Builds

Windows Installer (NSIS)

Create a Windows installer with Start Menu shortcuts and uninstallation support. Requires NSIS installed:

What Gets Embedded

11Desktop vs Web — Full Comparison

Both modes share Grit conventions (GORM models, code generation, Studio), but the runtime, communication model, and distribution are fundamentally different.

12Code Markers — NEVER Delete

Desktop projects use 13 grit: markers across 6 files. The CLI injects code at these locations during grit generate resource and removes it during grit remove resource.

What line-before vs inline Means

Example: What Injection Looks Like

// BEFORE generation:
type App struct {
    ctx         context.Context
    authService *service.AuthService
    // grit:fields
}

// AFTER generation:
type App struct {
    ctx            context.Context
    authService    *service.AuthService
    productService *service.ProductService
    // grit:fields
}

13All 12 Injection Points — What Gets Injected

For a resource named Product, here is exactly what the CLI injects at each marker:

&models.Product{},
// grit:models

productService := &service.ProductService{DB: database}
// grit:service-init

app := NewApp(authService, productService, /* grit:app-args */)

type App struct {
    ctx            context.Context
    authService    *service.AuthService
    productService *service.ProductService
    // grit:fields
}

func NewApp(authService *service.AuthService, productService *service.ProductService, /* grit:constructor-params */) *App {
    return &App{authService: authService, productService: productService, /* grit:constructor-assign */}
}

import { createFileRoute } from "@tanstack/react-router";
// ... component imports

export const Route = createFileRoute("/_layout/products/")({
  component: ProductsListPage,
});

function ProductsListPage() {
  // ... list page with DataTable
}

import { Package } from "lucide-react";
// grit:nav-icons

{ name: "Products", href: "/products", icon: Package },
// grit:nav

14LLM Examples — Copy and Adapt

Concrete examples an AI assistant can learn from. These cover the most common workflows.

# Create the project
grit new-desktop inventory

# Navigate into project
cd inventory

# Generate resources
grit generate resource Product --fields "name:string,sku:string,price:float,stock:int,reorder_level:int,active:bool"
grit generate resource Supplier --fields "name:string,email:string,phone:string,address:text,notes:text"

# Start development
wails dev

func (s *ProductService) GetBySKU(sku string) (*models.Product, error) {
    var product models.Product
    if err := s.DB.Where("sku = ?", sku).First(&product).Error; err != nil {
        return nil, fmt.Errorf("product not found with SKU %s: %w", sku, err)
    }
    return &product, nil
}

// Custom method — add ABOVE the // grit:methods marker (not between generated code)
func (a *App) GetProductBySKU(sku string) (*models.Product, error) {
    return a.productService.GetBySKU(sku)
}

import { GetProductBySKU } from "../../wailsjs/go/main/App";

export default function ProductLookup() {
  const [sku, setSku] = useState("");
  const [product, setProduct] = useState(null);

  const handleLookup = async () => {
    try {
      const result = await GetProductBySKU(sku);
      setProduct(result);
    } catch (err) {
      toast.error("Product not found");
    }
  };

  return (
    <div>
      <input value={sku} onChange={(e) => setSku(e.target.value)} placeholder="Scan barcode..." />
      <button onClick={handleLookup}>Lookup</button>
      {product && <div>{product.name} — {product.price}</div>}
    </div>
  );
}

# Build for current platform
grit compile

# Output:
#   Windows: build/bin/inventory.exe
#   macOS:   build/bin/inventory.app
#   Linux:   build/bin/inventory

# Cross-compile for a specific platform:
wails build -platform windows/amd64
wails build -platform darwin/arm64

# Create a Windows installer:
wails build -nsis

15Golden Rules for AI Assistants — Never Break These

16Quick Build Reference

Copy-paste recipes for the most common desktop workflows.

grit new-desktop myapp
cd myapp
wails dev

grit generate resource Product --fields "name:string,price:float,stock:int,active:bool"
grit generate resource Category --fields "name:string,description:text"
grit generate resource Order --fields "customer_name:string,total:float,status:string,notes:text,completed:bool"

grit remove resource Order

grit studio
# Opens browser at http://localhost:8080/studio

grit compile
# Binary at: build/bin/myapp.exe (Windows) or build/bin/myapp (macOS/Linux)

wails build -platform windows/amd64
wails build -platform darwin/arm64
wails build -nsis  # Windows installer

17Common Mistakes LLMs Make with Desktop Projects

These are the most frequent errors AI assistants make when helping with Grit Desktop. Avoid all of them.