When Files Regenerate

Sonamu automatically regenerates related files based on file changes. This document clearly explains which files are regenerated when you change each file.

Regeneration Flow Diagram

On Entity Save

When you save an .entity.json file, the following files are regenerated.

Regenerated Files

1. {Entity}.types.ts

TypeScript types and Zod schemas per EntityLocation: api/src/application/{entity}/{entity}.types.tsGeneration condition: Only when Entity is first created (not auto-regenerated afterwards)

user.types.ts

// Base type
export type User = {
  id: number;
  email: string;
  // ...
};

// Zod schema
export const User = z.object({
  id: z.number(),
  email: z.string(),
  // ...
});

2. sonamu.generated.ts

Base types and Enums for the entire projectLocation: api/src/application/sonamu.generated.tsAlways regenerated: ✅

// All Entity Enums
export const UserRole = z.enum(["admin", "normal"]);

// Subset types
export type UserSubsetKey = "A" | "P" | "SS";
export type UserSubsetMapping = { ... };

// Model exports
export * from "./user/user.model";

3. sonamu.generated.sso.ts

Subset query functionsLocation: api/src/application/sonamu.generated.sso.tsAlways regenerated: ✅

export const userSubsetQueries = {
  A: (puri) => puri.table("users").select([...]),
  P: (puri) => puri.table("users").leftJoin(...).select([...]),
};

export const userLoaderQueries = { ... };

4. Target Copy

Above files are copied to target projectsLocations:

web/src/services/user/user.types.ts
web/src/services/sonamu.generated.ts
web/src/services/sonamu.generated.sso.ts
app/src/services/... (same)

Trigger Example

{
  "id": "User",
  "table": "users",
  "props": [
    { "name": "id", "type": "integer" },
    { "name": "email", "type": "string" }
  ],
  "subsets": {
    "A": ["id", "email"]
  },
  "enums": {
    "UserRole": {
      "admin": "Administrator",
      "normal": "Normal User"
    }
  }
}

✅ Generated: user.types.ts (first creation only)
✅ Generated: sonamu.generated.ts
✅ Generated: sonamu.generated.sso.ts
✅ Copied: web/src/services/user/user.types.ts
✅ Copied: web/src/services/sonamu.generated.ts
✅ Copied: web/src/services/sonamu.generated.sso.ts

{entity}.types.ts is only auto-generated when Entity is first created. It must be manually managed afterwards.To regenerate an existing user.types.ts:

rm api/src/application/user/user.types.ts
# Re-save Entity

On Model Save

When you save a .model.ts file, the following files are regenerated.

Regenerated Files

1. services.generated.ts

API client functions and TanStack Query hooksLocations:

web/src/services/services.generated.ts
app/src/services/services.generated.ts

Always regenerated: ✅

// Axios clients
export async function findUserById(id: number): Promise<User> { ... }

// TanStack Query hooks
export function useUserById(id: number) { ... }
export function useSaveUser() { ... }

Generation criteria: Methods with @api decorator in Model

2. sonamu.generated.http

HTTP test file for REST ClientLocation: api/sonamu.generated.httpAlways regenerated: ✅

### User.findById
GET http://localhost:3000/user/findById?id=1

### User.save
POST http://localhost:3000/user/save
Content-Type: application/json

{ "params": [...] }

3. queries.generated.ts

Query Options for SSRLocation: web/src/queries.generated.tsAlways regenerated: ✅

export const userQueries = {
  findById: (id: number) => queryOptions({
    queryKey: ["User", "findById", id],
    queryFn: () => findUserById(id),
  }),
};

4. entry-server.generated.tsx

SSR Entry Server codeLocation: web/src/entry-server.generated.tsxAlways regenerated: ✅

export async function loader({ params }) {
  const queryClient = new QueryClient();
  
  // SSR data prefetching
  if (params.userId) {
    await queryClient.prefetchQuery(
      userQueries.findById(Number(params.userId))
    );
  }
  
  return { dehydratedState: dehydrate(queryClient) };
}

Trigger Example

class UserModelClass extends BaseModelClass {
  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"] })
  async findById(id: number): Promise<User> {
    // ...
  }

  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
  async save(params: UserSaveParams[]): Promise<number[]> {
    // ...
  }
}

🔄 Invalidated:
- src/application/user/user.model.ts (with 2 APIs)

✅ Generated: services.generated.ts
✅ Generated: sonamu.generated.http
✅ Generated: queries.generated.ts
✅ Generated: entry-server.generated.tsx

✨ HMR completed in 234ms

On Types Save

When you save a .types.ts file, schema files are regenerated and copied to targets.

.types.ts files are treated as Single Source of Truth. Changes trigger schema file regeneration, same as Entity changes.

Regenerated Files

1. sonamu.generated.ts

Base types and Enums for the entire projectLocation: api/src/application/sonamu.generated.tsAlways regenerated: ✅Zod schemas defined in Types files are reflected in this file.

2. sonamu.generated.sso.ts

Subset query functionsLocation: api/src/application/sonamu.generated.sso.tsAlways regenerated: ✅Regenerated together to maintain type consistency with Types changes.

3. Target Copy

Modified Types file and regenerated files are copied to target projectsLocations:

web/src/services/{entity}/{entity}.types.ts
web/src/services/sonamu.generated.ts
web/src/services/sonamu.generated.sso.ts
app/src/services/... (same)

Always copied: ✅import transformation: sonamu → ./sonamu.shared

Trigger Example

import { z } from "zod";

// Custom type added
export const UserLoginParams = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

export type UserLoginParams = z.infer<typeof UserLoginParams>;

✅ Generated: sonamu.generated.ts
✅ Generated: sonamu.generated.sso.ts
✅ Copied: web/src/services/user/user.types.ts
✅ Copied: web/src/services/sonamu.generated.ts
✅ Copied: web/src/services/sonamu.generated.sso.ts

On Config Save

When you save sonamu.config.ts, environment variables are synchronized.

Regenerated Files

.sonamu.env

Environment variable file containing API server infoLocations:

web/.sonamu.env
app/.sonamu.env

Always regenerated: ✅

API_HOST=localhost
API_PORT=3000

Trigger Example

export default {
  server: {
    listen: {
      host: "0.0.0.0",  // changed
      port: 4000,       // changed
    },
  },
};

✅ Updated: web/.sonamu.env
✅ Updated: app/.sonamu.env

On i18n File Save

When you save src/i18n/**/*.ts, SD files are regenerated.

Regenerated Files

1. Locale File Copy

i18n files are copied to targetsLocations:

web/src/i18n/{locale}.ts
app/src/i18n/{locale}.ts

2. sd.generated.ts

Sonamu Dictionary file generationLocations:

api/src/sd.generated.ts
web/src/sd.generated.ts
app/src/sd.generated.ts

Always regenerated: ✅

export const SD = {
  User: "User",
  user: {
    id: "ID",
    email: "Email",
  },
} as const;

Regeneration Matrix

A table showing file changes and regeneration relationships at a glance.

Changed File	.types.ts	sonamu.generated.ts	sonamu.generated.sso.ts	services.generated.ts	sonamu.generated.http	queries.generated.ts	entry-server.generated.tsx	.sonamu.env	sd.generated.ts
.entity.json	✅ (first creation)	✅	✅	-	-	-	-	-	-
.model.ts	-	-	-	✅	✅	✅	✅	-	-
.types.ts	copy	✅	✅	-	-	-	-	-	-
sonamu.config.ts	-	-	-	-	-	-	-	✅	-
i18n/.ts	-	-	-	-	-	-	-	-	✅

Legend:

✅ = Always regenerated
✅ (first creation) = Only on first creation
copy = Copied to targets
- = Not regenerated

Preventing Regeneration

Modifying generated files will be overwritten on next regeneration.

❌ Wrong Way

Directly modifying services.generated.ts

// ❌ Don't do this!
export async function findUserById(id: number): Promise<User> {
  // Custom logic added
  console.log("Finding user:", id);
  
  const { data } = await axios.get("/user/findById", { params: { id } });
  return data;
}
// → Gets overwritten on Model change 💥

✅ Right Way

Create Separate File
Use Types File
Handle in Model

services/user/user.custom.ts

import { findUserById } from "../services.generated";

// Create wrapper function
export async function findUserByIdWithLog(id: number) {
  console.log("Finding user:", id);
  return findUserById(id);
}

Advantage: Doesn’t touch generated files

api/src/application/user/user.types.ts

// Add custom types beyond Entity base types
export const UserLoginParams = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

// This file is not regenerated!

Advantage: Managed together with Types

api/src/application/user/user.model.ts

@api({ httpMethod: "GET" })
async findByIdWithLog(id: number): Promise<User> {
  this.logger.info("Finding user:", id);
  return this.findById("A", id);
}

Advantage: Automatically exposed as API

Forcing Regeneration

How to force regeneration when files aren’t being regenerated.

Checksum Reset

# Delete checksum file
rm sonamu.lock

# Full re-sync
pnpm sonamu sync

Specific File Regeneration

# Re-save Entity file (in Sonamu UI)
# Or modify and save file content

# Re-save Model file
# → services.generated.ts etc. auto-regenerated

Force Overwrite

import { Sonamu } from "sonamu";

// Force regeneration with overwrite option
await Sonamu.syncer.generateTemplate(
  "services",
  {},
  { overwrite: true }  // Overwrite existing file
);

Regeneration Optimization

Tips to reduce regeneration time.

Change Only Necessary Files

If not changing Model APIs, modifying Entity or Types is sufficient

Types/Entity change → Schema regeneration
Model change → Services and HTTP file regeneration

Remove Unnecessary Targets

Remove unused targets from sonamu.config.ts

export default {
  sync: {
    targets: ["web"],  // Remove app
  },
};

Minimize @api Decorators

Add @api only to necessary methods

Internal methods don’t need @api
Fewer APIs = faster regeneration

HMR Optimization

Use Node.js v22+ and SSD

{
  "engines": {
    "node": ">=22.0.0"
  }
}

Next Steps

Customizing Generated Code

Safely customize generated code

Syncer

Deep understanding of Syncer system

Templates

Create custom templates

Testing

Test generated code

​Regeneration Flow Diagram

​On Entity Save

​Regenerated Files

​Trigger Example

​On Model Save

​Regenerated Files

​Trigger Example

​On Types Save

​Regenerated Files

​Trigger Example

​On Config Save

​Regenerated Files

​Trigger Example

​On i18n File Save

​Regenerated Files

​Regeneration Matrix

​Preventing Regeneration

​❌ Wrong Way

​✅ Right Way

​Forcing Regeneration

​Checksum Reset

​Specific File Regeneration

​Force Overwrite

​Regeneration Optimization

​Next Steps

Customizing Generated Code

Syncer

Templates

Testing

Regeneration Flow Diagram

On Entity Save

Regenerated Files

Trigger Example

On Model Save

Regenerated Files

Trigger Example

On Types Save

Regenerated Files

Trigger Example

On Config Save

Regenerated Files

Trigger Example

On i18n File Save

Regenerated Files

Regeneration Matrix

Preventing Regeneration

❌ Wrong Way

✅ Right Way

Forcing Regeneration

Checksum Reset

Specific File Regeneration

Force Overwrite

Regeneration Optimization

Next Steps