Entity Reference

Define entities with defineEntity().

import { defineEntity } from '@flexkit/studio';
 
export const customers = defineEntity({
  name: 'customer',
  plural: 'customers',
  display: 'name',
  menu: {
    label: 'Customers',
    group: 'sales',
  },
  attributes: [
    {
      name: 'name',
      label: 'Name',
      scope: 'global',
      dataType: 'string',
      inputType: 'text',
      defaultValue: '',
    },
  ],
});

Entity Shape

• name: string singular identifier (example: customer).
• plural: string plural collection name (example: customers).
• display?: string attribute name shown in relationship previews, search hits, and edit-drawer titles. Must match an attribute name. Falls back to the first attribute when omitted. The effective display attribute cannot be space-bound.
• menu?: { hidden: true; label?: string } | { label?: string; group?: string; icon?: JSX.Element }
• groups?: FieldGroup[] form tabs. Distinct from menu.group (sidebar section). See Field Groups.
• attributes: Attribute[] list of field definitions.

Naming Guidelines

• Use singular name values for entity types (product, not products).
• Use alphanumeric or underscore names for compatibility.
• Keep names stable: changing names impacts queries, references, and migrations.
• Avoid reserved/system-like names for fields and entities when possible.

Menu Behavior

• menu.label controls sidebar label.
• menu.group maps to project menuGroups.name.
• menu.hidden: true excludes entity from menu while keeping it in schema.

Field Groups

• groups organizes the edit form into tabs. It does not change storage.
• Assign attributes with group: 'seo' or group: ['seo', 'media'].
• Studio always adds an All fields tab. Hide it with { name: 'all', hidden: true } in groups. Attributes with no visible tab are omitted from the form and validation.

Entity Design Tips

• Keep entity boundaries business-centric (Catalog, CRM, ERP, etc.).
• Set display to one attribute name for predictable relationship labels.
• Normalize shared concepts into separate entities (currency, country, tag, supplier).
• Model cross-entity workflows via relationships, not duplicated text fields.

Permission spaces

Use spaces: ['catalog'] to restrict a supported entity or global/local attribute to members of a deployed space. Membership in any listed space is sufficient. The effective display attribute cannot be space-bound, and relationship-scoped attributes cannot declare spaces. See permission spaces for deployment and assignment.