Migrate from OutSystems

Read. Rebuild. Run independently.

Use the OutSystems model as your specification, then give its interface, logic, and platform services a new home.

Start with the stack your team runs.

// Browser: create once after the host element exists.
const grid = createGrid<Customer>(host, options);
const response = await fetch('/api/customers');
if (!response.ok) throw new Error('Load failed');
const { rows } = await response.json();
grid.setData(rows);
// Call grid.destroy() when the view is removed.

Extract enough context to reproduce the screen.

1. Choose one bounded screen

   Start with a list and detail flow such as BluKavantUi_Pro_Showcase.ProShowcases.McpCustomerDemo. Record the source environment, module, screen, timestamp and SDK version. Note the user roles and each action a person can take. Save the module before extraction.

2. Connect both MCPs

   Keep your existing OutSystems MCP connection and add BluKavantUI MCP. Approve the editor connection through Service Studio when required. The assistant coordinates the two servers; neither server needs to call the other. Keep session credentials outside generated application source.

3. Discover the available read tools

   Ask the MCP client for its tools first. Our connected editor exposed listApps, getScreen, getServerAction, runQuery and getSerializedObjectByNameAndType. Tool names, argument schemas and access vary by installed integration; use the returned schema, not an assumed endpoint or fixed local port.

4. Follow the dependencies

   Read the layout, referenced Blocks and producer versions; screen inputs and local state; load queries, joins, filters and pagination; client events; server actions; entity attributes, identifiers and relationships; validation; role checks; transactions and external API dependencies. A screenshot alone does not capture these rules.

5. Fetch the equivalent web contracts

   For each BluKavant control, read blukavantui_get_component with platform: "web" and fetch its example. Compare against the native contract. Carry over meaning, then use the web factory’s exact signatures. Preserve required theme/component styles and dispose instances when views unmount.

   BluKavantUI MCP tool argumentsCopy code

   // blukavantui_get_component
   { "name": "Grid", "platform": "web", "section": "all" }
   
   // blukavantui_get_example
   { "name": "Grid", "platform": "web" }
   
   // Repeat for Drawer, Button and other controls used by the screen.

6. Save a migration manifest

   Keep the extracted models, source timestamps/hashes, component versions, field mappings and unresolved dependencies with the project. Label cached snapshots and failed reads. Extracting entity definitions does not export the entity’s records or the user directory.

OutSystems → external app: the complete mapping

In the customer example, only Name, Seats and Revenue are editable. Active, Joined and LastActivity remain read-only even though a shared source action can support other fields. Treat identifiers as strings when JavaScript number precision could lose information. Represent timestamps with an explicit timezone policy; keep date-only values distinct. The complete example stores money in integer cents.

One API. One TypeScript entry. A real grid.

This first example is deliberately small: Express returns three synthetic customers, Vite builds the browser code, and the Grid displays the response. It has no OutSystems connections and no authentication or writes. Use Node.js 24 or newer.

# Unzip blukavant-express-grid-1.0.0.zip, then:
cd blukavant-express-grid
npm ci
npm run build
npm start
# Open http://127.0.0.1:3377/

npm ci installs the locked dependencies. npm run build type-checks the code and bundles the frontend into dist/. npm start runs Express, which serves that directory and /api/customers from the same origin. This earlier v1.0.0 example retains the combined SDK 0.9.0 in vendor/; other packages come from npm. For new projects, use Community Basic Grid or install the licensed Pro Grid alongside Community, as shown in Getting started.

import express from 'express';
import { fileURLToPath } from 'node:url';
import type { Customer } from './customer.ts';

const app = express();
const rows: Customer[] = [
  { Id: '1', Name: 'Atlas Labs', Seats: 12, Revenue: 2400 },
  { Id: '2', Name: 'Northstar', Seats: 24, Revenue: 4800 },
  { Id: '3', Name: 'Harbor Systems', Seats: 8, Revenue: 1600 },
];

app.get('/api/customers', (_request, response) => response.json({ rows }));
app.get('/api/health', (_request, response) => response.json({ status: 'ok', outsystemsRequired: false }));
app.use(express.static(fileURLToPath(new URL('./dist', import.meta.url))));
const port = Number(process.env.PORT || 3377);
app.listen(port, '127.0.0.1', () => console.log(`Open http://127.0.0.1:${port}/`));

export interface Customer {
  Id: string;
  Name: string;
  Seats: number;
  Revenue: number;
}

import '@blukavantui/web/theme.css';
import '@blukavantui/web/grid.css';
import { createGrid } from '@blukavantui/web/grid';
import type { Customer } from '../customer.ts';
import './style.css';

const host = document.querySelector<HTMLElement>('#customers')!;
const status = document.querySelector<HTMLElement>('#status')!;
const grid = createGrid<Customer>(host, {
  RowKeyField: 'Id',
  Mode: 'Client',
  Rows: [],
  Columns: [
    { Field: 'Name', Header: 'Customer', Flex: 2, MinWidth: 180, IsSortable: true, IsFilterable: true },
    { Field: 'Seats', Header: 'Seats', Type: 'Number', MinWidth: 100, IsSortable: true },
    { Field: 'Revenue', Header: 'Revenue', Type: 'Currency', MinWidth: 140, IsSortable: true },
  ],
  Config: { Height: '400px', IsReadOnly: true, ShowEditToolbar: false, EnablePagination: true, PageSize: 10, CurrencyCode: 'USD' },
});

try {
  const response = await fetch('/api/customers');
  if (!response.ok) throw new Error('Customers could not be loaded.');
  const data: { rows: Customer[] } = await response.json();
  grid.setData(data.rows);
  status.textContent = `${data.rows.length} sample customers loaded from Express.`;
} catch (error) {
  status.textContent = error instanceof Error ? error.message : 'Could not load customers.';
}
// In a framework, call destroy() in its component unmount hook.
if (import.meta.hot) import.meta.hot.dispose(() => grid.destroy());

{
  "name": "blukavant-express-grid",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24.0.0" },
  "scripts": {
    "build": "tsc --noEmit && vite build",
    "start": "node server.ts"
  },
  "dependencies": {
    "@blukavantui/web": "file:vendor/blukavantui-web-0.9.0.tgz",
    "express": "^5.1.0"
  },
  "devDependencies": {
    "@types/express": "^5.0.0",
    "@types/node": "~24.12.0",
    "typescript": "~6.0.3",
    "vite": "~8.3.4"
  }
}

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2023", "DOM"],
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "skipLibCheck": true,
    "types": ["node", "vite/client"]
  },
  "include": ["*.ts", "client/**/*.ts"]
}

<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>BluKavantUI · Express starter</title></head>
<body><main><span class="eyebrow">TypeScript + Express</span><h1>A grid in your own application.</h1><p>Three synthetic customers, served by a standalone Node.js API. Sort a column to try the grid.</p><div id="customers" aria-label="Customer grid"></div><p id="status" role="status">Loading customers…</p></main><script type="module" src="/client/main.ts"></script></body>
</html>

body { margin: 0; background: #f6f7fb; color: #1f2937; font-family: system-ui, sans-serif; }
main { max-width: 1040px; margin: 64px auto; padding: 0 24px; }
h1 { font-size: clamp(28px, 5vw, 42px); letter-spacing: -.04em; margin: 12px 0; }
p { line-height: 1.65; }
.eyebrow { text-transform: uppercase; letter-spacing: .12em; font-size: 12px; color: #5144c6; font-weight: 700; }
#customers { margin-top: 28px; min-width: 0; }
#status { font-size: 14px; }

The ZIP also includes the npm lockfile and the pinned BluKavantUI SDK in vendor/.

Node runs the server’s erasable TypeScript syntax; it does not type-check it or transform JSX. That is why the build runs tsc --noEmit separately. Vite handles browser TypeScript and CSS. See the Node.js TypeScript documentation, Express static-file guide and Vite production-build guide.

Complete customer workspace · 250 sample records

The companion app implements the more complete flow: 250 synthetic customers, search/filter/sort/pagination, an edit drawer, SQLite persistence, editor/viewer access, server validation, atomic writes, version checks and request deduplication.

Download customer workspace · v1.0.0 ↓Understand the save flow

Run the complete exampleCopy code

# Unzip blukavant-customer-workspace-1.0.0.zip, then:
cd blukavant-customer-workspace
npm ci
npm run check
npm start
# Open http://127.0.0.1:3375/
# Choose Continue as editor or Explore as viewer.

The public demo credentials are editor or viewer, password local-demo. This mode binds to loopback. The README documents APP_PASSWORD, HTTPS production cookies, database paths and the limitations of its single-account deployment mode. The example does not migrate your SSO, users or role assignments.

Save flow, validation & concurrency

The complete example separates the original record from the draft. The browser sends a request ID, the full original baseline and a full draft with only the three permitted fields changed. The server reads the current row inside a transaction, checks permission and validation, compares the expected version and baseline, then returns canonical saved rows with new versions.

POST /api/customers/save
Cookie: app-owned session
X-CSRF-Token: token from the current session

{
  "requestId": "a-new-unique-id",
  "changes": [{
    "original": { "Id": "102", "Version": 3, "...": "all original fields" },
    "draft": { "Id": "102", "Version": 3, "Name": "Northstar", "Seats": 63, "Revenue": 12500.50, "...": "unchanged fields" }
  }]
}

Use the actual Customer and request types from the download; the ellipsis above only indicates omitted fields. Expected outcomes include 401 for an absent session, 403 for forbidden access or a failed CSRF check, 422 for validation and 409 for conflicts. Keep the draft visible on failure. On success, replace the row with the server’s canonical response rather than assuming the submitted draft is the stored value.

Never trust a browser role flag, hidden field or disabled button. Enforce editable-field allowlists, numeric limits, record access and concurrency on the server. Persist idempotency outcomes in the same transaction as the writes so repeated requests cannot duplicate a change. An unknown network outcome needs reconciliation; it must not be presented as a confirmed save.

Finish the parts a screen export cannot carry.

1. Move data separately

   Use an authorized export/API or controlled migration job. Map keys and relationships, decimals, nulls, dates, binary files and external URLs. Load into a staging database first. Reconcile counts and totals, check representative records and keep a repeatable migration log. The examples on this page seed synthetic data only.

2. Replace identity and background services

   Connect your identity provider, map roles and record-level policies, and plan user provisioning or password reset. Reimplement scheduled jobs, workflows, email, files and integrations that the screen relies on. Put credentials in the deployment environment, not in frontend bundles.

3. Test the behavioral contract

   Exercise empty/loading/error states, valid/invalid edits, cancel, reload persistence, expired sessions, forbidden access, concurrent updates and retry behavior. Check keyboard navigation and your target browsers. For remote datasets, verify paging/filtering on the server, not only against a small client fixture.

4. Prepare a controlled cutover

   Choose the system of record, define a write freeze or final delta migration, rehearse the import, and document rollback before switching traffic. Avoid two independent writers without an explicit synchronization design. Configure HTTPS, a persistent database volume, backups, monitoring and your authentication provider for the external app.

5. Verify runtime independence

   Test with OutSystems services unavailable as well as the MCPs disconnected. Review browser requests, server integrations, asset URLs, identity callbacks and background jobs. A partial migration that intentionally retains an OutSystems API should be documented as hybrid.

Know what the workflow delivers.