R2WC — React to Web Component bundler

Build and ship self-contained Web Components with @dev/r2wc-component and @dev/r2wc-vite.

Packages

This is a monorepo. Two packages are published to the internal npm registry (https://npm.finapi.ghe.com/):

| Package | Role | |---|---| | @dev/r2wc-vite | Vite preset (defineR2WCConfig, getR2WCConfig) for downstream builds. | | @dev/r2wc-component | Browser runtime: R2WC, Styled, plugins, etc. |

Get started

Downstream applications bring their own Vite project and consume the two packages directly:

import { defineConfig } from 'vite';
import { defineR2WCConfig } from '@dev/r2wc-vite';

export default defineConfig((env) => defineR2WCConfig(env));

See MIGRATION.md for the concrete package.json, config, and source changes used for web-form-ui_2.1 and finapi-widget-library.

Migrating from Direflow

See MIGRATION.md — full step-by-step for downstream consumers moving off direflow-component / direflow-scripts (including the @mbenko/* fork).

Local development

npm install           # root + all packages
npm run build:all     # build the published packages via tsc
npm test              # vitest run (unit tests)
npm run e2e           # playwright test (browser e2e against built bundle)

End-to-end tests — Playwright

Specs live in e2e/specs/; the host fixture app is at e2e/fixture/. Playwright's webServer runs the fixture's own scripts before tests, which:

1. builds the fixture via vite build → e2e/fixture/build/r2wc-bundle.js
2. copies the bundle into e2e/fixture/public/r2wc-bundle.js
3. serves public/ on port 5173

Then the specs exercise the real built bundle in Chromium. Playwright's CSS locators pierce open shadow roots, so no plugin is needed:

await expect(page.locator('basic-test .app .header-title')).toHaveText('Test Setup');

Useful commands:

npm run e2e            # headless run
npm run e2e:ui         # Playwright UI mode
npm run e2e:debug      # step through with Inspector

First-time setup also needs the Chromium binary: npx playwright install chromium.

CI / publishing — Jenkins

The pipeline lives in Jenkinsfile. It loads the internal finapi-build-library@develop shared library and runs four stages on every branch:

1. Initialize — tag the version, terminate outdated jobs.
2. Build — npm run build:all across the two publishable packages.
3. Test — npm test (Vitest).
4. Release NPM — npm run publish:all. Each package's publishConfig.registry pins the target to https://npm.finapi.ghe.com/.
5. Upload Collaterals — pushes README.md, MIGRATION.md, and devops/ to Artifactory under /io/finapi/r2wc.

Branch behavior:

• develop → snapshot release (prerelease).
• main → versioned release.

Slack notifications fire on unsuccessful, fixed, and success for those two branches only — #proj-widget-library.

Why publishConfig matters

Every package.json here declares:

"publishConfig": {
  "registry": "https://npm.finapi.ghe.com/"
}

This pins npm publish to the internal registry regardless of the developer's local .npmrc. Without it, an accidental npm publish from a workstation could push to the public registry. The Jenkins build also relies on this so it doesn't need a registry flag.

Adding a new publishable package

1. Create packages/<new-name>/ with a package.json that includes:

   "name": "@dev/<new-name>",
   "publishConfig": { "registry": "https://npm.finapi.ghe.com/" },
   "engines": { "node": ">=20" }

2. Ensure it has a build script and files field listing the publishable artifacts.
3. Root build:all and publish:all already target the workspace packages — no Jenkinsfile change is needed.