Frontend Architecture

Phoenix uses a filename-based routing system. Any file that ends with .route.tsx will be accessible as a page, with the URL path derived from the file name.

Path Resolution Rules

1. Remove the .route.tsx suffix
2. Replace all . characters with /
3. Remove any segment of the file name that begins with an _

Route Naming Examples

The _site segment groups routes that share a common layout or upstream data, but is removed from the resulting URL path.

Route files can function as layouts for nested routes by including an <Outlet /> component. Nested pages render inside their parent layout at the Outlet position.

// _sample.route.tsx (layout)
export default function MyLayout() {
  return (
    <div>
      <h3>This is my layout</h3>
      <Outlet />
    </div>
  );
}

// _sample.nested.route.tsx (nested page)
export default function Page() {
  return <p>Hello!</p>;
}

Accessing /nested renders the _sample layout first, then renders the nested page contents in place of the <Outlet />.

Loaders are server-side data loading functions executed before a page renders. They return data used to server-render the page and deliver a pre-populated HTML response to the end user.

export async function loader(args: LoaderFunctionArgs) {
  const api = await getApi(args.request);
  const myData = await api.GetSomeData();
  return json(myData);
}

export async function loader(args: LoaderFunctionArgs) {
  const api = await getApi(args.request);
  const hasRole = await api.CheckRole("Store Admin");
  if (!hasRole) {
    return redirect("/login");
  }
  return json(myData);
}

For API requests from React components (rather than loaders), use the useApi() hook. This returns an API object similar to the legacy cvApi from CEF.

export const MyComponent = () => {
  const api = useApi();

  useEffect(() => {
    api.GetSomeData().then(r => setSomeState(r));
  }, []);
};

Auto-generated Files

When to Use useApi vs. Loaders

The CV Grid is a data grid component for paginated data, supporting both client-side and server-side data sources. It requires the data array, a total count, a unique row key, and column definitions.

Core Props

<CVGrid
  source={myArrayOfItems}
  totalCount={myArrayOfItems.length}
  rowKey={i => i.Id}
  columns={[
    { title: "Id", content: x => x.Id },
    { title: "Name", content: x =>
      <p>{x.FirstName} {x.LastName}</p> },
    { title: "Details", className: "w-0",
      content: x => <Button>Click Here</Button> }
  ]}
/>

Filters

Specify filters on a CV Grid by providing an array of filter definitions. Supported filter types:

<CVGrid
  ...
  filters={[
    { title: "ID", type: "number", key: "Id" },
    { title: "Date", type: "daterange", key: "CreatedDate" }
  ]}
/>

Column Classes

Columns support three class properties, merged via the cn() utility:

Extension points let submodules open themselves to customization from other submodules or the client project, without being directly edited or overridden.

Creating an Extension Point

import ExtensionPoint from "@core/components/PipelineComponents/ExtensionPoint";

export default function MyComponent() {
  return (
    <div>
      <h1>My Component</h1>
      <ExtensionPoint name="mycomponent.content" />
    </div>
  );
}

Registering an Extension

Create a .ext.tsx file and call registerExtension(). All .ext.tsx files are automatically loaded via glob pattern in root.tsx.

import { registerExtension } from
  "@core/components/PipelineComponents/ExtensionProvider";

const MyWidget = () => {
  return <div>Hello from my widget!</div>;
};

registerExtension("mycomponent.content", MyWidget, "MyWidget");

Sort Order Constants

Control rendering order by specifying a sort order as the fifth argument to registerExtension(). Lower values render first.

import { registerExtension, EXTENSION_SORT_ORDER }
  from "@core/components/PipelineComponents/ExtensionProvider";

// Using constants (recommended)
registerExtension(
  "admin.dashboard", HighPriorityWidget,
  "HighPriority", false, EXTENSION_SORT_ORDER.HIGH
);

// Using direct numbers (fine-grained control)
registerExtension(
  "admin.dashboard", CustomWidget,
  "Custom", false, 250
);

// Default order (1000) — omit sort order
registerExtension(
  "admin.dashboard", NormalWidget, "Normal"
);

Passing Props to Extensions

Extension points can pass arbitrary props to their registered extensions:

// In the host component
<ExtensionPoint
  name="dashboard.products.$id.Form"
  form={form}
/>

// In the extension
interface DashboardProductIdFormProps {
  form: UseFormReturn<any, any, undefined>;
}

export const ConditionSelector =
  ({ form }: DashboardProductIdFormProps) => {
    // ... use the form object ...
  };

registerExtension(
  "dashboard.products.$id.Form",
  ConditionSelector, "ConditionSelector"
);

Extension Point Rendering Flow

Phoenix supports overriding files from plugins. To override a plugin file, create the same file under /overrides/ instead of /plugins/. The compiler handles the replacement automatically.

Override Resolution

Phoenix uses Tailwind CSS (instead of Bootstrap). Tailwind provides utility-first CSS with powerful features like exact values (p-[4px]) and responsive prefixes.

Media Breakpoints

Apply classes conditionally at specific breakpoints using prefixes. For example, md:px-4 is equivalent to Bootstrap's px-md-4.

Theme Editor Values

The theme editor sets colors as Tailwind variables, available as standard color utilities:

Color Scale

Colors range from -50 (lightest) to -950 (darkest) in increments of 100, matching Tailwind's default color variable structure.

Borders & Radii

The cn() Function

Use the cn() function to merge Tailwind classes cleanly. Classes are combined left to right, with later values overriding earlier ones.

const MyComponent = ({ className }: MyProps) => {
  return (
    <div className={cn("p-4 my-base-classes", className)}>
      Hello!
    </div>
  );
};

<div className={cn("border", someCondition && "bg-danger-500")}>

The theme editor provides a visual interface for customizing site appearance. Styles are defined as Tailwind variables and applied through a set of critical files.

Key Files

Adding Styles for a Themed Element

Follow these four steps to add theme editor support for a new element:

const MiniMenuButton = ({ className }: Props) => {
  const themeClasses = useElementTheme("MiniMenuButton");

  return (
    <button
      className={cn(
        "px-3 py-2 rounded-base border",
        themeClasses,
        className
      )}
    >
      ...
    </button>
  );
};

Adding a New Style Property

Follow these five steps to add a new CSS property (e.g. maxHeight) to the theme editor: