protonus
protonus
React UI library for building CRUD/reference interfaces over OData (and custom data providers).
- Metadata-driven tables, cards, editors, fields, filters and sorters
- OData V4 provider with
$select/$expand/$filter/$orderbysupport - TypeScript source and generated
.d.tsdeclarations - React 18/19, Ant Design 5/6, React Router 6/7
Install
npm i protonus antd @ant-design/icons antd-table-ext dayjs react react-dom react-router-dom
The major versions of antd and @ant-design/icons must match:
| Stack | antd | @ant-design/icons | React | react-router-dom |
|---|---|---|---|---|
| Latest | ^6.7.0 |
^6.3.0 |
^19.0.0 |
^7.0.0 |
| Legacy | ^5.29.0 |
^5.6.0 |
^18.2.0 |
^6.28.0 |
Quick start
import { useMetadata, useList, Table } from 'protonus';
const userMetadata = {
entity: 'Users',
key: 'id',
properties: [
{ dataIndex: 'id', type: 'number' },
{ dataIndex: 'name', type: 'string', required: true },
{ dataIndex: 'createdAt', type: 'datetime' }
]
};
export function UsersPage() {
const metadata = useMetadata(userMetadata);
const list = useList({ metadata });
return <Table metadata={metadata} list={list} />;
}
The default data provider reads globalSettings.dataProvider.odataPath. Set it once during application bootstrap:
import protonus from 'protonus';
protonus.dataProvider.odataPath = 'https://example.com/odata';
Settings
globalSettings remains the backward-compatible default. createSettings and SettingsProvider scope the data provider, pageSize, hierarchical loading, metadata types/defaults and the state hooks:
import { createSettings, SettingsProvider } from 'protonus';
const settings = createSettings({
pageSize: 50,
dataProvider: myProvider
});
<SettingsProvider settings={settings}>
<App />
</SettingsProvider>
useList, useEntity, useMetadata and the metadata layer read settings from the provider and fall back to globalSettings.
UI display settings (locale, date formats, onApply, editInCard, field/appearance defaults) are still read from globalSettings. Configure them globally if you need a different locale or editing behavior.
URL state limitation
Row selection is stored in the URL as a comma-separated list (rowChSel). String keys containing a literal comma are not supported by this storage format.
Metadata and types
Property types: string, text, number, boolean, enum, date, datetime, duration, entity, file, dictionary, color, code, expression, chain, function.
Data-provider hooks can be configured per property:
{
dataIndex: 'customer/name',
type: 'string',
filterSerialize: (value) => JSON.stringify(value),
filterDeserialize: (value) => JSON.parse(value)
}
Custom data providers
Pass a provider to useList / useEntity, or register it in settings:
const list = useList({ metadata, dataProvider: myProvider });
const entity = useEntity({ metadata, id, dataProvider: myProvider });
A provider implements the methods used by the hooks: getList, getEntity, changeData, deleteData, and optionally getParents.
AGG Grid
The AGG Grid integration is an optional example, not part of the published package. See src/examples/aggrid.
SSR and styles
protonus is a client-side library. Hooks and components use window, document, localStorage and browser history, so server-side rendering is not officially supported. If SSR is required, render the library only on the client after hydration.
Styles are imported by components and injected at runtime via vite-plugin-css-injected-by-js; the package does not ship a standalone CSS file. Importing protonus on the client is enough to load its styles.
Development
npm test # unit/integration tests
npm run typecheck # TypeScript
npm run lint # ESLint
npm run build # ESM build + declarations
License
MIT