elseware-ui

A TypeScript-first React component library for web and React Native applications. The package provides shared component contracts, platform-specific implementations, Tailwind/NativeWind styling, and conditional exports for browser and mobile bundlers.

Features

• Web and React Native entry points with platform-specific declarations
• React 18 and 19 support
• React Native and NativeWind components
• Tailwind CSS design tokens and a reusable preset
• Tree-shakable ESM builds for modern web and Metro bundlers
• Storybook 10 component development and production builds
• TypeScript 7 web/native validation
• Oxlint, Prettier, Knip, lint-staged, and Husky quality gates

Installation

Install the library and the peer dependencies required by your target.

Web

npm install elseware-ui react react-dom formik yup tailwindcss

Import the browser API and compiled styles:

import { Button } from "elseware-ui";
import "elseware-ui/styles.css";

React Native

npm install elseware-ui react react-native formik yup nativewind tailwindcss react-native-reanimated react-native-worklets

Metro-compatible bundlers select the react-native condition from the root export. The native entry can also be imported explicitly:

import { Button, Input } from "elseware-ui/native";

Configure NativeWind and Reanimated in the consuming application according to their platform setup requirements.

The native API currently includes only:

• Button
• Checkbox
• DateSelector
• Form and FormResponse
• Input, InputFile, InputLabel, and InputResponse
• Select
• Tags
• TextArea

Other components and every composition are currently web-only. Importing the explicit elseware-ui/native entry is the deterministic option when a tool does not enable the react-native export condition.

Package exports

The root export selects the native build when the bundler enables the react-native condition and otherwise selects the web build.

{
  ".": {
    "react-native": {
      "types": "./dist/index.native.d.ts",
      "import": "./dist/index.native.mjs",
      "default": "./dist/index.native.mjs"
    },
    "types": "./dist/index.d.ts",
    "import": "./dist/index.mjs",
    "default": "./dist/index.mjs"
  },
  "./native": {
    "types": "./dist/index.native.d.ts",
    "import": "./dist/index.native.mjs",
    "default": "./dist/index.native.mjs"
  },
  "./tailwind": "./tailwind.preset.js",
  "./styles.css": "./dist/index.css"
}

Tailwind preset

Add the package preset and include the distributed component sources or compiled application usage in your Tailwind content configuration as appropriate for your application:

const elsewarePreset = require("elseware-ui/tailwind");

module.exports = {
  presets: [elsewarePreset],
  content: ["./src/**/*.{js,jsx,ts,tsx}"],
};

Development

npm install
npm run dev

The main quality commands are:

npm run typecheck          # Type-check workspace, web, and native graphs
npm run lint               # Run Oxlint with warnings denied
npm run format:check       # Verify Prettier formatting
npm run deadcode           # Check files and dependency reachability
npm run build              # Build JS, CSS, and TS7 declarations
npm run build:storybook    # Build the production Storybook
npm run validate           # Run the complete quality pipeline

npm install initializes Husky for repository contributors. The pre-commit hook runs lint-staged; it can also be invoked directly with npm run precommit.

Component structure

Shared behavior and types live in base modules. Browser and native renderers live in web and native modules, with .native barrels forming the mobile public graph. Platform-neutral modules must not import DOM-only utilities.

Only add a native implementation when it is intentionally supported. Use native/Component.native.tsx, export it from the component's index.native.ts, and then add its index.native.ts entry to the native data-entry boundary with a direct wildcard export. Do not forward web implementations through the native graph.

Web component styles stay beside their owning component and are imported by that component's web implementation or local barrel. Do not register component styles in a root CSS manifest. The build follows the web module graph and extracts those imports into the public elseware-ui/styles.css bundle. Only design-system-wide foundations belong in src/styles.

Use type-only imports for TypeScript types and keep imports grouped as external, internal, data, and types where those groups are useful.

Source naming and export rules are documented in docs/Architecture.md. Leaf barrels use explicit runtime exports and export type; aggregate barrels use direct wildcard exports for their immediate child boundaries. Implementation code must not import explicit index files.

Publishing

Pull requests targeting main run the complete validation suite and verify that the package version has not already been published. A successful merge to main runs the same checks and publishes through GitHub's OIDC trusted publishing; no long-lived npm token is stored in GitHub. Because this source repository is private, the workflow disables npm provenance, which npm only accepts for public source repositories.

Before enabling the workflow, configure npm's trusted publisher for the elseware-ui package with the GitHub organization/repository and the workflow filename .github/workflows/publish.yml. Create the npm-production GitHub environment and restrict it to the main branch. Keep the package version in package.json and package-lock.json synchronized; bump it in the release PR:

npm version patch --no-git-tag-version

The workflow deliberately fails before publishing if that exact version is already present in the npm registry. If this repository is later made public, remove --provenance=false from the publish workflow to enable signed npm provenance attestations.

For a local release preview, use:

npm run validate
npm publish --dry-run --access public --provenance=false --ignore-scripts

The release command runs the full validation pipeline before publishing publicly.