The shared package: one definition, four outputs

D3 was "the same type exists four times". A Blog is a Go struct, a database column list, a TypeScript interface and a validation schema, and nothing makes them agree except the person who remembers to change all four.

This chapter is about the place where three of those four stop being separate things, and about the one command that keeps them that way.

What is in it

packages/shared/
├── package.json
├── types/          TypeScript interfaces, one file per model
├── schemas/        Zod schemas, one file per model
├── constants/      API routes and shared constants
├── themes.ts       the palette both frontends read
└── brand.config.ts the product name, logo and copy

It is a workspace package rather than a published one, so there is no build step and no version to bump. The frontends import it by subpath:

"exports": {
  "./schemas":   "./schemas/index.ts",
  "./types":     "./types/index.ts",
  "./constants": "./constants/index.ts",
  "./brand":     "./brand.config.ts",
  "./themes":    "./themes.ts"
}

import { CreateBlogSchema } from "@repo/shared/schemas"
import type { Blog } from "@repo/shared/types"

Everything that renders imports from here: the web app, the admin panel, and the desktop and mobile clients if the project has them. One definition, four consumers.

A generated pair, in full

Given this model:

type Blog struct {
    ID          string     `json:"id"          gorm:"primaryKey"`
    Title       string     `json:"title"       binding:"required"`
    Slug        string     `json:"slug"`
    Content     string     `json:"content"     gorm:"type:text"`
    Image       *string    `json:"image"`
    Published   bool       `json:"published"`
    PublishedAt *time.Time `json:"published_at"`
    CreatedAt   time.Time  `json:"created_at"`
    UpdatedAt   time.Time  `json:"updated_at"`
}

you get types/blog.ts:

export interface Blog {
  id: string;
  title: string;
  slug: string;
  content: string;
  image: string | null;
  published: boolean;
  published_at: string | null;
  created_at: string;
  updated_at: string;
}

and schemas/blog.ts, which is three schemas rather than one:

export const BlogSchema = z.object({
  id: z.string(),
  title: z.string(),
  slug: z.string(),
  content: z.string(),
  image: z.string().nullable(),
  published: z.boolean(),
  published_at: z.string().nullable(),
  created_at: z.string(),
  updated_at: z.string(),
});

export const CreateBlogSchema = z.object({
  title: z.string().min(1, "Title is required"),
  content: z.string().optional(),
  image: z.string().optional(),
  published: z.boolean().optional(),
});

export const UpdateBlogSchema = CreateBlogSchema.partial();

Why three, and what each one is for

• BlogSchema
• The row as the API returns it. Every field, including the ones the server assigns
• CreateBlogSchema
• What a POST accepts. No id, no timestamps, andrequired where the Go binding tag said so
• UpdateBlogSchema
• The create schema, .partial(). A PATCH sends the fields that changed and nothing else

id, created_at, updated_at and deleted_at are dropped from the create schema automatically. They are assigned by the server, so a form that offers them is a form that can lie.

nullable against optional, which is not pedantry

image is z.string().nullable() in the row schema and z.string() .optional() in the create schema, and the difference is the difference between two states that look the same in a form:

• nullable: the server will send "image": null. The key is there, the value is empty.
• optional: the client may leave the key out entirely, and the server applies its default.

A Go pointer field (*string, *time.Time) becomes nullable, because a pointer is how Go says "this may be absent". A non-required field becomes optional on create. Get these the wrong way round by hand and you get a form that refuses to submit because a column the user cannot see is null.

grit sync, and exactly what it does

grit sync

It parses every file in apps/api/internal/models/ with Go's own parser, not a regular expression, and for each struct it writes:

• types/<name>.ts
• The interface, overwritten
• schemas/<name>.ts
• The three schemas, overwritten
• the admin resource
• New fields added to the generated section only

The name is kebab-cased from the struct: BlogPost becomes blog-post.ts.

User is skipped. It has hand-written schemas covering login, registration, password reset and profile updates, which are not derivable from the struct, and regenerating them would throw away work the framework cannot reproduce.

The mapping, for the types you will actually hit:

• Go
• TypeScript
• Zod
• string
• string
• z.string()
• int, int64
• number
• z.number().int()
• uint
• number
• z.number().int().nonnegative()
• float64
• number
• z.number()
• bool
• boolean
• z.boolean()
• time.Time
• string
• z.string()
• *time.Time
• string | null
• z.string().nullable()

Times cross as strings, because JSON has no date type. Chapter nineteen covers the format; the thing to hold onto here is that the TypeScript type saysstring and means RFC 3339, and the parsing is the frontend's job.

// schemas/blog-form.ts, which sync does not touch
export const BlogFormSchema = CreateBlogSchema.extend({
  slug: z.string().regex(/^[a-z0-9-]+$/, "lowercase and dashes"),
}).refine((v) => !v.published || v.content.length > 0, {
  message: "a published post needs content",
  path: ["content"],
})

The admin resource is updated, not overwritten

The third thing sync touches is the admin resource definition, and it is treated differently because it is yours.

The generated file carries markers around the section the generator owns. New model fields are added inside those markers, to the columns and the form. Anything you customised, a renamed label, a render function, a reordered column, sits outside them and survives.

So the usual loop after changing a model is two commands:

grit migrate
grit sync

and the admin has the new field in the table and the form without you opening the file.

Where the chain stops, honestly

sync keeps three things in step: the type, the schema, and the admin resource. It does not update the generated mobile forms or the desktopcolumns, because those have no marker scheme yet.

It says so rather than pretending:

⚠ 2 field(s) never reached apps/mobile:
  reading_notes, verified_at

That warning exists because the failure without it is miserable to diagnose: a correct API, a correct type, a correct admin screen, and a mobile create form frozen at the three fields the resource was generated with. The field is in the response and absent from the form, and nothing is broken enough to show an error.

Using it on the frontend

The schemas are not decoration. They are the validation layer of every generated form:

const form = useForm<CreateBlogInput>({
  resolver: zodResolver(CreateBlogSchema),
})

The inferred input type comes from the same schema:

export type CreateBlogInput = z.infer<typeof CreateBlogSchema>;

so renaming a field in the Go model and running grit sync makes the editor underline every place the old name is used, before anything runs. That is the actual payoff of D3: not that the four definitions exist in one place, but that disagreeing with them is a compile error rather than a support ticket.

The error codes travel the same way. types/errors.ts is generated from the Go error catalogue, so a frontend can match on a code rather than on a message:

if (apiErrorCode(err) === "EMAIL_EXISTS") {
  form.setError("email", { message: "That email is taken" })
}

Constants, themes and brand

Three smaller files, each solving a small duplication that gets annoying at the third app:

• constants/ holds the API route paths, so a URL typo is a type error rather than a 404 at runtime.
• themes.ts holds the palette, read by the admin, the web app and the desktop client, so a theme change lands everywhere at once.
• brand.config.ts holds the product name, logo and marketing copy, which is why a generated project shows your name rather than Grit's.

grit generate resource Reading \
  --fields "label:string, value:float, taken_at:datetime"
grit migrate

Verified bool `json:"verified"`

Assignment

Commit your work with the message Shared Package - Assignment One, exactly as written, so the leaderboard can score it.