Quickstart

This gets a working import flow onto your page. You need access to the published packages and a self-hosted (or pilot) engine endpoint with a signed license key.

0. Try it first — no install, no signup

The playground runs the real widget in your browser: upload a messy file (or use the preloaded samples) and walk upload → match → review → apply in under a minute. If the flow fits, everything below is the same widget pointed at your schema.

Package access

Packages publish to GitHub Packages (npm.pkg.github.com, scope @capitality-io) — a plain npm install against the public registry will not find them. Access comes with any plan, including Free/Dev (pricing): write to [email protected] for a registry token.

Your license key is separate and self-serve: create one in your account — see Your Mildport account.

1. Install the package

Point npm’s @capitality-io scope at GitHub Packages once, using the token from onboarding:

.npmrc

@capitality-io:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${MILDPORT_NPM_TOKEN}

npm install @capitality-io/mildport-widget

Non-Angular hosts: one build-tool step

Under the hood the widget is an Angular library, and like every Angular package it ships partially-compiled code that the consuming build links. Angular CLI and Analog projects do this out of the box — skip ahead. In any other Vite project, add the linker once:

npm install -D @analogjs/vite-plugin-angular @angular/compiler-cli @angular/compiler @angular/build "typescript@~5.9.0"

vite.config.ts

import angular from '@analogjs/vite-plugin-angular';
import { defineConfig } from 'vite';

export default defineConfig({ plugins: [angular()] });

The plugin reads tsconfig.app.json by default (set its tsconfig option if yours is named differently). Without the linker, the build or first render fails with JIT compilation failed errors.

2. Define the custom element

main.ts

import { defineImportSuiteElement } from '@capitality-io/mildport-widget';

await defineImportSuiteElement('mildport-import');

3. Drop it in and point it at your schema

The recommended default is a server-managed target catalog: the schema lives in Mildport’s no-code editor (drafted from your API spec if you like), versioned with rollback, and schema changes publish without a host release. The embed stays three attributes:

<mildport-import
  api-base-url="https://imports.your-infra.example"
  license-key="SIGNED_TENANT_KEY"
  catalog-key="crm"
></mildport-import>

wire-it-up.ts

const el = document.querySelector('mildport-import')!;
el.addEventListener('import-applied', e => sync(e.detail));

Alternative: schema-as-code

Prefer the schema versioned and type-checked with your app — or need fields computed per user at runtime? Pass targets from host code instead of catalog-key (derive them from Zod schemas with @capitality-io/mildport-zod):

wire-it-up.ts

import { mountImportFlow } from '@capitality-io/mildport-widget';

const el = document.querySelector('mildport-import')!;

mountImportFlow(el, {
  id: 'my-import',
  version: 'v1',
  targets: [
    {
      id: 'contact',
      label: 'Contact',
      fields: [
        { key: 'contact.email', label: 'Email', columnType: 'email', required: true },
        { key: 'contact.name', label: 'Name' },
      ],
    },
  ],
  input: { acceptedFormats: ['spreadsheet', 'text', 'pdf'] },
  delivery: { mode: 'browser' },
});

el.addEventListener('import-applied', e => sync(e.detail));

No engine yet? Add the offline attribute and drop api-base-url/license-key — the whole flow (parse, match, review, apply) runs in the browser with the bundled deterministic matcher, so you can wire and demo the integration before any backend exists:

<mildport-import offline></mildport-import>

In browser delivery the rows reach your code through the resultsHook — the third argument of mountImportFlow — just before apply (import-applied’s detail carries the summary: recordId, action, rowCount):

mountImportFlow(el, flowInput, {
  resultsHook: ({ rows, mapping }) => sync(rows),
});

That’s the whole integration surface: attributes in, DOM events out. No SDK lock-in, no iframe.

Next

• Your first import — catalog, embed, review, signed webhook.
• Target catalogs — manage the schema in the no-code editor, draft it from an API spec, version and roll back.
• Configure the widget — targets, attributes, apply modes.
• Events & apply — the lifecycle events and how rows reach your app.
• Theming — match the widget to your design system.