Scaffolding Tab - 🌲 Sonamu

In the Scaffolding tab, you can auto-generate Model and test code based on Entities. It provides the CLI pnpm scaffold command through a visual interface.

Scaffolding Tab Structure

The Scaffolding tab consists of two main areas:

Left Sidebar: Entity list and selection checkboxes
Right Content: Code generation options (Model Class, Model Test, View)

Available Code Types

Code Type	Description	Status	CLI Command
Model Class	Model class for Entity	✅ Available	`pnpm scaffold model`
Model Test	Model test file	✅ Available	`pnpm scaffold model_test`
View List	List View component	🚧 In Development	-
View Form	Form View component	🚧 In Development	-

View component generation is currently under development. You can generate React components through other Sonamu UI features.

Generating Model Class

1. Select Entity

Select the Entity to generate a Model for from the left Entity list. Single selection:

☑ User
□ Post
□ Comment

Multiple selection:

☑ User
☑ Post
☑ Comment

2. Select Generation Option

Check the ☑ Model Class checkbox.

3. Run Generate

Click the [Generate] button to create the following file:

Generated Code

src/application/user/user.model.ts

import {
  api,
  asArray,
  BadRequestException,
  BaseModelClass,
  exhaustive,
  NotFoundException,
  type ListResult,
} from "sonamu";

import { SD } from "../../i18n/sd.generated";
import { UserSubsetKey, UserSubsetMapping } from "../sonamu.generated";
import { userLoaderQueries, userSubsetQueries } from "../sonamu.generated.sso";
import { UserListParams, UserSaveParams } from "./user.types";

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  // findById / findOne / findMany / save / del are generated with @api decorators
}

export const UserModel = new UserModelClass();

Auto-generated features:

✅ TypeScript type definitions
✅ Entity connection
✅ BaseModel inheritance
✅ Basic CRUD methods

Generating Model Test

1. Select Entity

Select Entity same as for Model.

2. Select Generation Option

Check the ☑ Model Test checkbox.

Generate Model and Test together: You can select both Model Class and Model Test to generate them at once.

3. Run Generate

Click the [Generate] button to create the following file:

Generated Code

src/application/user/user.model.test.ts

import { bootstrap, test } from "sonamu/test";
import { describe, expect, vi } from "vitest";

bootstrap(vi);
describe.skip("UserModelTest", () => {
  test("Query", async () => {
    expect(true).toBe(true);
  });
});

The generated test starts as describe.skip. Remove .skip once you have written real assertions.

What is generated:

✅ A bootstrap(vi) call (Sonamu init + per-test transaction wrapping)
✅ An empty describe.skip block — you write the actual cases

Batch Generation

Generate for All Entities

Click [Select All] button
Select generation options
Click [Generate]

Result:

✓ user.model.ts created
✓ user.model.test.ts created
✓ post.model.ts created
✓ post.model.test.ts created
✓ comment.model.ts created
✓ comment.model.test.ts created

6 files generated successfully!

Select Specific Entities Only

For all Entities during initial project setup:

☑ User
☑ Post
☑ Comment
☑ Category
☑ Tag

[Generate] → 10 files generated

For new Entity only when adding:

□ User (already generated)
□ Post (already generated)
☑ Product (new)

[Generate] → 2 files generated

Checking Generation Results

Success Message

✅ Code Generation Complete

Generated files:
  ✓ src/application/user/user.model.ts
  ✓ src/application/user/user.model.test.ts
  ✓ src/application/post/post.model.ts
  ✓ src/application/post/post.model.test.ts

Total: 4 files

File Conflict

When trying to generate files that already exist, a confirmation modal appears:

⚠️ Files Already Exist

The following files will be overwritten:
  • src/application/user/user.model.ts
  • src/application/user/user.model.test.ts

[Cancel] [Backup & Overwrite] [Overwrite]

Options:

Cancel: Cancel generation
Backup & Overwrite: Backup existing files as .bak then overwrite
Overwrite: Overwrite directly (caution!)

Code loss caution: Overwriting existing files may delete your business logic. Backup or avoid overwriting customized Models.

View Generation

The TemplateKey list on the Scaffolding tab includes View templates in addition to the Model ones.

TemplateKey	Output location
`view_list`	`web/src/routes/admin/{entities}/index.tsx`
`view_form`	`web/src/routes/admin/{entities}/form.tsx`
`view_search_input`	Search input component used by the list screen

The same templates are available from the CLI: pnpm scaffold view_list, pnpm scaffold view_form.

Post-Generation Workflow

1. Add Model Methods

Add business logic to the generated Model:

src/application/user/user.model.ts

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  // Find user by email
  async findByEmail(email: string): Promise<User | null> {
    return this.getPuri("r").table("users").where("email", email).first();
  }

  // Find only active users
  async findActiveUsers() {
    return this.getPuri("r").table("users").where("is_active", true).where("deleted_at", null);
  }
}

2. Add Tests

Add more tests to the generated test file:

src/application/user/user.model.test.ts

describe("User Model - Extended", () => {
  test("findByEmail", async () => {
    const user = await UserModel.findByEmail("user@example.com");
    expect(user).toBeDefined();
    expect(user?.email).toBe("user@example.com");
  });

  test("findActiveUsers", async () => {
    const users = await UserModel.findActiveUsers();
    users.forEach((user) => {
      expect(user.is_active).toBe(true);
    });
  });
});

3. Add API

Add API endpoints using the @api decorator on the Model:

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  @api({ httpMethod: "GET" })
  async findActiveUsers() {
    const { qb } = this.getSubsetQueries("A");
    qb.where("is_active", true);

    return this.executeSubsetQuery({
      subset: "A",
      qb,
      params: { num: 20, page: 1 },
    });
  }
}

Practical Tips

1. Initial Project Setup

1. Define all Entities
   ↓
2. Batch generate in Scaffolding tab
   - [Select All]
   - Model Class ☑
   - Model Test ☑
   - [Generate]
   ↓
3. Add business logic to each Model

2. Adding New Entity

1. Create Entity in Entity tab
   ↓
2. Run migration in Migration tab
   ↓
3. Generate only that Entity in Scaffolding tab
   ↓
4. Write business logic and tests

3. When Regeneration is Needed

When Entity structure changes significantly and Model needs regeneration:

# Backup existing file
cp src/application/user/user.model.ts src/application/user/user.model.ts.bak

# Regenerate in UI
[Backup & Overwrite]

# Restore custom logic from backup file

​Scaffolding Tab Structure

​Available Code Types

​Generating Model Class

​1. Select Entity

​2. Select Generation Option

​3. Run Generate

​Generated Code

​Generating Model Test

​1. Select Entity

​2. Select Generation Option

​3. Run Generate

​Generated Code

​Batch Generation

​Generate for All Entities

​Select Specific Entities Only

​Checking Generation Results

​Success Message

​File Conflict

​View Generation

​Post-Generation Workflow

​1. Add Model Methods

​2. Add Tests

​3. Add API

​Practical Tips

​1. Initial Project Setup

​2. Adding New Entity

​3. When Regeneration is Needed

​Next Steps

Model

scaffold CLI

Scaffolding Tab Structure

Available Code Types

Generating Model Class

1. Select Entity

2. Select Generation Option

3. Run Generate

Generated Code

Generating Model Test

1. Select Entity

2. Select Generation Option

3. Run Generate

Generated Code

Batch Generation

Generate for All Entities

Select Specific Entities Only

Checking Generation Results

Success Message

File Conflict

View Generation

Post-Generation Workflow

1. Add Model Methods

2. Add Tests

3. Add API

Practical Tips

1. Initial Project Setup

2. Adding New Entity

3. When Regeneration is Needed

Next Steps