Code Generation

How the Generator Works

When you run grit generate resource, the CLI goes through four stages:

Files Created (9 New Files)

For a resource named "Post", the generator creates the following 9 files. Each file is complete, ready to use, and follows Grit's conventions.

Generated Code Examples

Here is what the generator produces for grit g resource Post --fields "title:string,content:text,published:bool":

Go Model

package models

import (
    "time"
    "gorm.io/gorm"
)

// Post represents a post in the system.
type Post struct {
    ID        uint           `gorm:"primarykey" json:"id"`
    Title     string         `gorm:"size:255" json:"title" binding:"required"`
    Content   string         `gorm:"type:text" json:"content"`
    Published bool           `json:"published"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
    DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

Zod Schema

import { z } from "zod";

export const CreatePostSchema = z.object({
  title: z.string().min(1, "Required"),
  content: z.string(),
  published: z.boolean(),
});

export const UpdatePostSchema = z.object({
  title: z.string().min(1, "Required").optional(),
  content: z.string().optional(),
  published: z.boolean().optional(),
});

export type CreatePostInput = z.infer<typeof CreatePostSchema>;
export type UpdatePostInput = z.infer<typeof UpdatePostSchema>;

TypeScript Interface

export interface Post {
  id: number;
  title: string;
  content: string;
  published: boolean;
  created_at: string;
  updated_at: string;
}

Admin Resource Definition

import { defineResource } from "@/lib/resource";

export const postResource = defineResource({
  name: "Post",
  slug: "posts",
  endpoint: "/api/posts",
  icon: "FileText",
  label: { singular: "Post", plural: "Posts" },
  table: {
    columns: [
      { key: "id", label: "ID", sortable: true, width: "80px" },
      { key: "title", label: "Title", sortable: true, searchable: true },
      { key: "content", label: "Content", searchable: true },
      { key: "published", label: "Published", format: "boolean" },
      { key: "created_at", label: "Created", sortable: true, format: "relative" },
    ],
    filters: [
      { key: "published", label: "Published", type: "boolean" },
    ],
    defaultSort: { key: "created_at", direction: "desc" },
    searchable: true,
    pageSize: 20,
  },
  form: {
    fields: [
      { key: "title", label: "Title", type: "text", required: true },
      { key: "content", label: "Content", type: "textarea" },
      { key: "published", label: "Published", type: "toggle" },
    ],
  },
});

Files Modified (10 Injection Points)

In addition to creating new files, the generator injects code into existing files to wire everything together. Each injection uses a marker comment that was placed during project scaffolding.

The Marker System

Grit uses special marker comments in scaffolded files to know where to inject new code. These markers are placed during project creation and should not be removed. The generator finds each marker and inserts new code on the line before it.

How Injection Works

There are two injection modes used by the generator:

YAML Definition Format

For complex resources, use a YAML file to define the fields. This gives you more control over field properties like required, unique, and default values.

name: Invoice
fields:
  - name: number
    type: string
    required: true       # adds binding:"required" in Go, .min(1) in Zod
    unique: true         # adds gorm:"uniqueIndex"
  - name: description
    type: text           # maps to gorm:"type:text", optional by default
  - name: amount
    type: float
  - name: status
    type: string
    default: "pending"   # adds gorm:"default:pending"
  - name: quantity
    type: uint           # unsigned integer, z.number().int().nonnegative()
  - name: due_date
    type: date           # maps to *time.Time, gorm:"type:date"
  - name: paid
    type: bool
    default: "false"     # adds gorm:"default:false"

YAML Field Properties

Editing a resource after generation

Generated code is yours to edit — Grit scaffolds it once and never overwrites it. Two common follow-ups:

Add a field to an existing model

One command. It writes the column into the Go model, both Zod schemas, the TypeScript type, and the admin table and form:

grit g field Product sku:string
grit g field Invoice status:select:draft=Draft|sent=Sent|paid=Paid
grit g field Invoice paid:toggle

# the model is the source of truth, so the column lands on the next migrate
grit migrate

No migration file is written, deliberately: the Go model is what describes the schema, and GORM adds the column from it. Scalar, select and toggle types are supported.

You can still edit the Go model by hand and run grit sync, which rewrites packages/shared from your structs and inserts the field between the // grit:cols:auto and // grit:fields:auto markers so hand-edited rows survive. Worth knowing, because it is the path for anything the command will not do. Note that the create and update handlers bind explicit request structs, so a hand-added field also has to be added there before the API will accept it — which is the step grit g field does for you.

Change a sidebar icon

Every resource declares an icon — a Lucide icon name — at the top of its resource file. The generator guesses one from the resource name; change it to any icon you like:

export const productsResource = defineResource({
  name: "Product",
  slug: "products",
  icon: "Package",   // <- any Lucide icon name, e.g. "ShoppingCart", "Tag", "Boxes"
  // ...
});

The name must exist in apps/admin/lib/icons.ts (the app's icon registry). Most common icons are already there; if you pick one that isn't, add it to that file's import, the iconMap, and the re-export, and it becomes available. System links (Roles, Security, System Hub) get their icons from the sidebar component (components/chrome/CollapsibleSidebar) rather than a resource file.

Complete Field Type Mappings

Each Grit field type maps to specific types and behaviors across the entire stack. This table shows the full mapping from field type to Go, GORM, TypeScript, Zod, DataTable column format, and form field type.

Auto-Generated Search

The generator automatically builds search queries based on your field types. All string andtext fields are included in the search WHERE clause using PostgreSQL's ILIKE operator for case-insensitive matching.

// For --fields "title:string,content:text,published:bool"
// The generator produces:
query.Where("title ILIKE ? OR content ILIKE ?",
    "%"+search+"%", "%"+search+"%")

// Notice: bool and numeric fields are NOT included in text search.
// Only string and text fields participate in ILIKE search.

If a resource has no string or text fields, the generator falls back to searching by ID: id::text ILIKE ?.

Interactive Mode

When you use the -i flag, the CLI enters interactive mode where you define fields one at a time. Each field is entered as name:type. The prompt shows all valid types and provides real-time validation.

• ✓Invalid types are rejected immediately with a warning
• ✓Invalid field name formats are rejected
• ✓Each successfully added field gets a confirmation
• ✓Press Enter on an empty line to finish defining fields
• ✓At least one field is required