Frontend on Palmyra

1. Project setup

Mon, 01 Jan 0001 00:00:00 +0000

1. Project setup#

Prerequisites#

Node.js 18+
Backend from the backend tutorial running on http://localhost:8080 with context path /api

Scaffold#

npm create vite@latest your-web -- --template react-ts
cd your-web

Dependencies#

The clinic sample composes the stack out of React 19 + Mantine 8 + the Palmyra UI libraries + a handful of utilities. Minimum viable install:

# React + Mantine
npm install react@19 react-dom@19 @mantine/core@8 @mantine/hooks@8 @mantine/dates@8

# Routing + transport + toasts
npm install react-router-dom@7 axios react-toastify lucide-react

# Palmyra frontend libraries
npm install @palmyralabs/palmyra-wire @palmyralabs/rt-forms \
            @palmyralabs/rt-forms-mantine @palmyralabs/template-tribble

# Dev
npm install -D vite @vitejs/plugin-react typescript vite-tsconfig-paths \
              tailwindcss @tailwindcss/vite

Vite config#

Proxy /api to the backend so the Palmyra store can use relative paths.

2. Store factory

Mon, 01 Jan 0001 00:00:00 +0000

2. Store factory#

There is no hand-rolled axios module per entity. All IO flows through a single PalmyraStoreFactory that serves two kinds of stores:

Grid store — paginated list reads (sort, search, filters, offset/limit).
Form store — single-record read / create / update / delete.

Pages don’t import URLs directly; they import an endpoint path from a central config and hand it to a template.

Configure the factory#

// src/wire/StoreFactory.ts
import { PalmyraStoreFactory } from '@palmyralabs/palmyra-wire';
import { toast } from 'react-toastify';

// Map HTTP failures to user-visible feedback. 401 kicks the session flow;
// 403 shows a permission-denied toast without tearing down the app.
let lastServerDownAt = 0;
const errorHandler = () => ({
  onError: (status: number, _err: unknown) => {
    switch (status) {
      case 401: {
        // tell any listener to clear local state, then redirect
        window.dispatchEvent(new CustomEvent('session:expired'));
        window.location.assign('/login');
        return;
      }
      case 403:
        toast.error("You don't have permission for this action.");
        return;
      case 500:
      case 502:
      case 503: {
        const now = Date.now();
        if (now - lastServerDownAt > 5000) {     // 5 s cooldown
          toast.error('Server is unreachable. Please retry.');
          lastServerDownAt = now;
        }
        return;
      }
    }
  }
});

const AppStoreFactory = new PalmyraStoreFactory({
  baseUrl: '/api/palmyra',
  errorHandlerFactory: errorHandler
});

export const useFormstore = (endPoint: string, options: any = {}, idKey?: string) =>
  AppStoreFactory.getFormStore(options, endPoint, idKey);

export const useGridstore = (endPoint: string, options: any = {}, idKey?: string) =>
  AppStoreFactory.getGridStore(options, endPoint, idKey);

export default AppStoreFactory;

baseUrl: '/api/palmyra' matches the context path your backend publishes under (see backend step 1). Every endPoint you pass to the hooks is appended to this base.

3. Grid pages

Mon, 01 Jan 0001 00:00:00 +0000

3. Grid pages#

Pages are thin. The clinic sample uses SummaryGrid from @palmyralabs/template-tribble — it bundles server-side pagination, sort, search, row selection, and toolbar actions, driven by a column-definition array from @palmyralabs/rt-forms.

Column definitions#

Columns are data, not JSX. Keep them near the page that uses them.

// src/pages/masterdata/manufacturer/columns.ts
import type { ColumnDefinition } from '@palmyralabs/rt-forms';

export const manufacturerColumns: ColumnDefinition[] = [
  { attribute: 'name',          name: 'name',          label: 'Name',    searchable: true, sortable: true },
  { attribute: 'contactMobile', name: 'contactMobile', label: 'Mobile' },
  { attribute: 'contactEmail',  name: 'contactEmail',  label: 'Email' },
  { attribute: 'rating',        name: 'rating',        label: 'Rating', type: 'number', sortable: true },
  { attribute: 'address',       name: 'address',       label: 'Address' },
];

Declarative fields like searchable / sortable compile into the query parameters the Palmyra backend expects — no custom wiring per column.

4. Forms and ACL

Mon, 01 Jan 0001 00:00:00 +0000

4. Forms and ACL#

Forms use @palmyralabs/rt-forms for state/validation and @palmyralabs/rt-forms-mantine for the Mantine-styled input widgets. You do not wire Mantine’s useForm directly — the Palmyra form layer takes care of binding, validation, submit, and store integration.

Dialog create form#

The clinic sample uses a DialogNewForm template that renders a modal, collects attributes into a FieldGroupContainer, and POSTs to endPoint on submit.

// src/pages/masterdata/manufacturer/ManufacturerNewForm.tsx
import { DialogNewForm } from '@palmyralabs/template-tribble';
import { FieldGroupContainer } from '@palmyralabs/rt-forms';
import { TextField, TextArea, CurrencyField }
  from '@palmyralabs/rt-forms-mantine';

import { ServiceEndpoint } from '@/config/ServiceEndpoints';
import { MobileRegex, fieldMsg } from '@/config/validation';

export default function ManufacturerNewForm(props: {
  open: boolean;
  onClose: () => void;
  onRefresh: () => void;
  pageName: string;
  title: string;
}) {
  const apiEndPoint = ServiceEndpoint.masterData.manufacturer.restApi;

  return (
    <DialogNewForm
      size="lg"
      endPoint={apiEndPoint}
      open={props.open}
      onClose={props.onClose}
      onRefresh={props.onRefresh}
      pageName={props.pageName}
      title={props.title}
    >
      <FieldGroupContainer columns={2}>
        <TextField
          attribute="name"
          label="Name"
          autoFocus required
          invalidMessage={fieldMsg.mandatory}
        />
        <TextField
          attribute="contactMobile"
          label="Mobile"
          validRule="number"
          regExp={{ regex: MobileRegex, errorMessage: 'Invalid phone number' }}
        />
        <TextField
          attribute="contactEmail"
          label="Email"
          validRule="email"
        />
        <CurrencyField
          attribute="rating"
          label="Rating"
          min={0} max={5} defaultValue={0}
        />
        <TextArea
          attribute="address"
          label="Address"
          colspan={2}
        />
      </FieldGroupContainer>
    </DialogNewForm>
  );
}

The attribute prop on each field is the POJO attribute name declared in @PalmyraField. That’s the only cross-stack coupling — rename the Java field and the JSON key, and this form changes in one place.