Skip to main content

Configuration

@xond/api can be customized through configuration files. This allows you to control code generation behavior, skip certain models, and customize field mappings.

Configuration File Location​

Create a configuration file at:

src/config/customConfig.ts

This file should export a customConfig object that merges with the default configuration.

Default Configuration​

The default configuration includes:

export const defaultConfig = {
  skipTables: [],
  defaultDisplayFields: ["name", "code", "title"],
  defaultDisplayField: "name",
  prismaTsTypeMap: {
    String: "string",
    Int: "number",
    Float: "number",
    Decimal: "number",
    Boolean: "boolean",
    DateTime: "Date",
    Json: "any",
  },
  // ... more defaults
};

Custom Configuration Example​

// src/config/customConfig.ts
export const customConfig = {
  // Skip these models from frontend generation
  skipTables: ["_Migration", "AuditLog", "SystemConfig"],

  // Default fields to display in lists
  defaultDisplayFields: ["name", "code", "description"],

  // Primary display field
  defaultDisplayField: "name",

  // Code field (for lookup fields)
  defaultCodeField: "code",

  // Name field (for display)
  defaultNameField: "name",

  // Description field
  defaultDescriptionField: "description",

  // Default page size for pagination
  defaultPageSize: 20,

  // Fields to skip in forms
  skipFields: ["id", "createdAt", "updatedAt", "deletedAt"],
};

Configuration Options​

skipTables​

Array of model variable names to skip during frontend model generation.

skipTables: ["_Migration", "AuditLog"]

These models will still generate backend services, but not frontend models.

defaultDisplayFields​

Fields that should be displayed by default in list views.

defaultDisplayFields: ["name", "code", "title"]

defaultDisplayField​

The primary field to use for display purposes.

defaultDisplayField: "name"

defaultCodeField​

The field that contains a unique code identifier.

defaultCodeField: "code"

defaultNameField​

The field that contains a human-readable name.

defaultNameField: "name"

defaultDescriptionField​

The field that contains a description.

defaultDescriptionField: "description"

defaultPageSize​

Default number of items per page in paginated results.

defaultPageSize: 20

skipFields​

Fields to exclude from form generation.

skipFields: ["id", "createdAt", "updatedAt", "deletedAt"]

Model Overrides​

You can customize how models are parsed by providing an override function:

// src/config/customConfig.ts
import { Model } from "@xond/api/core/parseSchema";

export const overrideModel = (models: Model[]): Model[] => {
  return models.map((model) => {
    // Customize specific models
    if (model.name === "User") {
      // Add custom fields
      model.fields.push({
        name: "fullName",
        type: "String",
        isRequired: false,
        // ... more field properties
      });
    }

    // Modify all models
    model.fields = model.fields.filter(
      (field) => !field.name.startsWith("_")
    );

    return model;
  });
};

Environment Variables​

Configuration can also be influenced by environment variables:

DATABASE_URL​

Required. Database connection string.

DATABASE_URL=postgresql://user:password@localhost:5432/mydb

NODE_ENV​

Should be set to development or dev for local development.

NODE_ENV=development

DEFAULT_SYSTEM_USER_ID​

Optional. UUID for system user in audit logs.

DEFAULT_SYSTEM_USER_ID=00000000-0000-0000-0000-000000000000

File Paths​

The generator looks for files in these locations:

  • Structure SQL: prisma/structure.sql
  • Update Scripts: prisma/update-struct-*.sql
  • Dummy Data: prisma/dummy.xlsx
  • Prisma Schema: prisma/schema.prisma
  • Custom Config: src/config/customConfig.ts

UI Path Configuration​

If you have a separate UI application in your monorepo, configure the relative path:

The generator automatically detects UI apps by looking for:

  • apps/*-ui/ directories
  • Or you can configure it in customConfig.ts

Validation​

The configuration is validated when you run xond-api generate. Invalid configurations will show errors:

❌ Error loading config: [error message]

Best Practices​

  1. Version Control Config – Commit customConfig.ts to version control
  2. Document Customizations – Add comments explaining why you skip certain models
  3. Test After Changes – Regenerate code after changing configuration
  4. Use TypeScript – Leverage TypeScript for type safety in your config

Example: Complete Configuration​

// src/config/customConfig.ts
import { Model } from "@xond/api/core/parseSchema";

export const customConfig = {
  skipTables: ["_Migration", "AuditLog"],
  defaultDisplayFields: ["name", "code"],
  defaultDisplayField: "name",
  defaultCodeField: "code",
  defaultNameField: "name",
  defaultDescriptionField: "description",
  defaultPageSize: 25,
  skipFields: ["id", "createdAt", "updatedAt"],
};

export const overrideModel = (models: Model[]): Model[] => {
  // Customize models before generation
  return models;
};