Syncer - 🌲 Sonamu

Syncer is Sonamu’s automatic generation system. It detects file changes, automatically generates necessary code, and synchronizes to target projects (web, app, etc.).

What is Syncer?

File Change Detection

Track Entity, Model, Types file changesEfficient checksum-based detection

Auto Code Generation

Generate types, schemas, API clientsTemplate-based generation

HMR Support

Real-time reflection during developmentFile invalidation and reload

Multi-Target Sync

Sync to web, app, and other projectsAutomatic file copying

Syncer Operation Flow

Watched File Patterns

File patterns that Syncer tracks for changes:

File Type	Pattern	Purpose
Entity	`src/application/*/.entity.json`	Data structure definition
Types	`src/application/*/.types.ts`	Type definitions
Model	`src/application/*/.model.ts`	Business logic
Frame	`src/application/*/.frame.ts`	Frame logic
Functions	`src/application/*/.functions.ts`	Utility functions
Generated	`src/application/sonamu.generated.ts`	Generated base file
Config	`src/sonamu.config.ts`	Sonamu configuration
Workflow	`src/application/*/.workflow.ts`	Workflow definitions
i18n	`src/i18n/**/!(sd.generated).ts`	i18n source files
i18nGenerated	`src/i18n/**/sd.generated.ts`	i18n generated files

File patterns: Managed in file-patterns.ts, change detection via checksum

Manual Synchronization

You can manually sync without the development server.

# Full sync
pnpm sonamu sync

# Sync only changed files
pnpm sonamu sync --check

Execution result:

🔄 Syncing files...
✅ Generated: sonamu.generated.ts
✅ Generated: sonamu.generated.sso.ts
✅ Copied: web/src/services/user/user.types.ts
✅ Copied: web/src/services/sonamu.generated.ts
✅ Generated: services.generated.ts
✅ Generated: sonamu.generated.http
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  All files are synced!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Automatic Synchronization (HMR)

During development server runtime, file changes are automatically detected and synchronized.

# Start development server
pnpm dev

# File changes are auto-synced
# - user.entity.json change → Type regeneration
# - user.model.ts change → API client regeneration

HMR log example:

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

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

✨ HMR completed in 234ms

Syncer Events

Syncer emits events as an EventEmitter.

import { Sonamu } from "sonamu";

// Subscribe to HMR completed event
Sonamu.syncer.eventEmitter.on("onHMRCompleted", () => {
  console.log("✅ HMR completed!");
  // Perform additional tasks...
});

Event types:

Event	When Triggered	Use Case
`onHMRCompleted`	HMR completion	Trigger follow-up tasks

Syncer Actions

Different actions execute based on file change type.

1. Entity Change (`handleTruthSourceChanges`)

Regenerates schemas when Entity file changes. Trigger: *.entity.json file change Actions:

Reload EntityManager
Generate *.types.ts for new Entity
Generate schema files:
- sonamu.generated.ts
- sonamu.generated.sso.ts
Copy files to targets

// Syncer internal logic
async handleTruthSourceChanges(diffGroups, diffTypes) {
  await EntityManager.reload();
  
  // Generate new Entity type file
  if (entity.parentId === undefined && !(await exists(typeFilePath))) {
    await generateTemplate("init_types", { entityId });
  }
  
  // Generate schemas
  await SyncerActions.actionGenerateSchemas();
}

2. Types/Functions/Generated Change

Copies type files to targets when they change. Trigger: *.types.ts, *.functions.ts, *.generated.ts change Actions:

Collect changed file list
Copy to each target (web, app)
Transform sonamu import to ./sonamu.shared

// Import transformation on copy
// Before (api)
import { BaseModelClass } from "sonamu";

// After (web/app)
import { BaseModelClass } from "./sonamu.shared";

sonamu.shared.ts: Since web/app don’t have the sonamu package, common utilities are provided via a shared file.

3. Model/Frame Change

Regenerates API clients when Model file changes. Trigger: *.model.ts, *.frame.ts change Actions:

Reload Model, Types, APIs
Generate API client (services.generated.ts)
Generate HTTP test file (sonamu.generated.http)
Regenerate SSR files (queries.generated.ts, entry-server.generated.tsx)

async handleImplementationChanges(diffGroups) {
  // Reload modules
  await this.autoloadModels();
  await this.autoloadTypes();
  await this.autoloadApis();
  
  // Generate services
  await SyncerActions.actionGenerateServices(params);
  await SyncerActions.actionGenerateHttps();
  
  // Regenerate SSR files
  await SyncerActions.actionGenerateSsr();
}

4. Config Change

Synchronizes environment variables when config file changes. Trigger: sonamu.config.ts change Actions:

Create/update .sonamu.env file
Copy to each target

web/.sonamu.env

API_HOST=localhost
API_PORT=3000

5. Workflow Change

Reloads when workflow file changes. Trigger: *.workflow.ts change Actions: Reload and sync workflows

6. i18n Change

Regenerates SD file when i18n file changes. Trigger: src/i18n/**/!(sd.generated).ts change Actions:

Copy Locale files to targets
Generate sd.generated.ts (api, web, app)

7. SSR Config Change

Immediately reloads when SSR route config files change. Trigger: src/ssr/**/*.ts change Actions:

Invalidate changed file (HMR)
Reload all SSR routes (autoloadSSRRoutes)
Emit HMR completed event

SSR config changes are not part of checksum-based sync. The watcher detects them directly and processes them through a separate path.

Checksum-Based Change Detection

Syncer stores file checksums for efficient change detection.

sonamu.lock

[
  { "path": "src/application/user/user.entity.json", "checksum": "a7f4b3e2c1d5..." },
  { "path": "src/application/user/user.types.ts", "checksum": "c3d1e4f5a6b7..." },
  { "path": "src/application/user/user.model.ts", "checksum": "e5f6a7b8c9d0..." }
]

How it works:

Calculate SHA-1 hash of file content
Compare with stored checksum
Consider changed if different
Update checksum after sync

Advantages:

Fast change detection (no file content comparison needed)
Accurate change tracking (unaffected by timestamp)
Handle multiple file changes simultaneously

Syncer API

Syncer can be used programmatically.

Manual Synchronization

import { Sonamu } from "sonamu";

// Full sync
await Sonamu.syncer.sync();

// Sync specific file
await Sonamu.syncer.syncFromWatcher(
  "change",
  "/path/to/user.entity.json"
);

Template Generation

// Create Entity
await Sonamu.syncer.createEntity({
  entityId: "User",
  table: "users",
  props: [
    { name: "id", type: "integer" },
    { name: "email", type: "string" },
  ],
  subsets: {
    A: ["id", "email"],
  },
  enums: {},
  indexes: [],
});

// Generate template
await Sonamu.syncer.generateTemplate(
  "model",
  { entityId: "User" },
  { overwrite: false }
);

// Render custom template
const files = await Sonamu.syncer.renderTemplate(
  "view_list",
  { entityId: "User" }
);

Module Loading

// Load types
await Sonamu.syncer.autoloadTypes();
console.log(Sonamu.syncer.types);

// Load Models
await Sonamu.syncer.autoloadModels();
console.log(Sonamu.syncer.models);

// Load APIs
await Sonamu.syncer.autoloadApis();
console.log(Sonamu.syncer.apis);

// Load Workflows
await Sonamu.syncer.autoloadWorkflows();
console.log(Sonamu.syncer.workflows);

Syncer Configuration

You can configure Syncer behavior in sonamu.config.ts.

api/src/sonamu.config.ts

export default {
  sync: {
    // Target projects for synchronization
    targets: ["web", "app"],
  },
  
  // API server settings (used for environment variable generation)
  server: {
    baseUrl: "http://localhost:3000",
    listen: {
      host: "localhost",
      port: 3000,
    },
  },
};

Development Workflow

Typical development flow using Syncer:

Start Development Server

pnpm dev

Syncer watches for file changes.

Define Entity

Define Entity in Sonamu UI or modify .entity.json file.Auto-executed:

Generate *.types.ts
Update sonamu.generated.ts
Update sonamu.generated.sso.ts
Copy files to targets

Write Model

Write business logic in Model and add @api decorator.Auto-executed:

Update services.generated.ts
Update sonamu.generated.http
Update SSR files

Frontend Development

Develop UI using generated API clients and Types.

import { useUsers } from "@/services/services.generated";
import type { User } from "@/services/user/user.types";

function UserList() {
  const { data } = useUsers();
  // ...
}

Real-time Reflection

Modifying Model or Entity reflects immediately via HMR.Check changes without browser refresh!

Troubleshooting

When Syncer Doesn’t Work

Files Not Being Generated

Check:

Confirm development server is running
Verify file matches watched patterns
Delete checksum file and retry

rm sonamu.lock
pnpm sonamu sync

Files Not Being Copied to Targets

Check:

Verify sync.targets in sonamu.config.ts
Confirm target directory exists
Create src/services/ directory in target

mkdir -p web/src/services
mkdir -p app/src/services

Slow HMR

Optimization methods:

Use latest Node.js version (v22+)
Use SSD (HDD is slow)
Exclude unnecessary files
Separate TypeScript projects (monorepo)

Import Errors

Cause: sonamu import not transformed to ./sonamu.sharedSolution:

# Force re-sync
pnpm sonamu sync --force

Next Steps

When Files Regenerate

Detailed guide on file regeneration timing

Customizing Generated Code

How to customize generated code

Templates

Create custom templates

HMR System

Deep understanding of HMR system

​What is Syncer?

File Change Detection

Auto Code Generation

HMR Support

Multi-Target Sync

​Syncer Operation Flow

​Watched File Patterns

​Manual Synchronization

​Automatic Synchronization (HMR)

​Syncer Events

​Syncer Actions

​1. Entity Change (handleTruthSourceChanges)

​2. Types/Functions/Generated Change

​3. Model/Frame Change

​4. Config Change

​5. Workflow Change

​6. i18n Change

​7. SSR Config Change

​Checksum-Based Change Detection

​Syncer API

​Manual Synchronization

​Template Generation

​Module Loading

​Syncer Configuration

​Development Workflow

​Troubleshooting

​When Syncer Doesn’t Work

​Next Steps

When Files Regenerate

Customizing Generated Code

Templates

HMR System

What is Syncer?

Syncer Operation Flow

Watched File Patterns

Manual Synchronization

Automatic Synchronization (HMR)

Syncer Events

Syncer Actions

1. Entity Change (`handleTruthSourceChanges`)

2. Types/Functions/Generated Change

3. Model/Frame Change

4. Config Change

5. Workflow Change

6. i18n Change

7. SSR Config Change

Checksum-Based Change Detection

Syncer API

Manual Synchronization

Template Generation

Module Loading

Syncer Configuration

Development Workflow

Troubleshooting

When Syncer Doesn’t Work

Next Steps