🎨 Ẹwà UI

Spatialnode's shared React component library

Requirements • Getting Started • Structure • Testing • Publishing • Contributing

---

Spatialnode's React component library is a set of shared, reusable UI components built with React, Radix UI, and Tailwind CSS. It's distributed as @spatialnode/ewa-ui on npm.

Requirements

• Node.js >=20
• pnpm 10.27.0 (managed via packageManager in package.json — use Corepack to pick it up automatically)

corepack enable

Getting Started

1. Clone the repository

   git clone git@github.com:Spatialnode/ewa-ui.git
   cd ewa-ui

2. Install dependencies

   pnpm install

3. Start Storybook to develop and preview components in isolation

   pnpm storybook

   Storybook runs at http://localhost:6006.

Project Structure

ewa-ui/
├── .storybook/          # Storybook configuration
├── src/
│   ├── components/
│   │   ├── ui/           # Base/primitive components
│   │   └── custom/       # Composed/higher-level components
│   ├── stories/          # Storybook stories and example assets
│   ├── lib/              # Shared utilities (e.g. `cn` helper)
│   └── index.ts          # Public package entry point / exports
├── dist/                 # Build output (generated, not committed)
├── tsdown.config.ts      # Build configuration (tsdown)
├── vitest.config.ts      # Test configuration
└── tsconfig.json         # TypeScript configuration

New components should be added under src/components/ui (primitives) or src/components/custom (composed components), then re-exported from src/index.ts to be included in the published package.

Available Scripts

Script	Description
pnpm build	Bundles the library to dist/ using tsdown
pnpm test	Runs the test suite once (Vitest)
pnpm test:watch	Runs the test suite in watch mode
pnpm typecheck	Type-checks the project without emitting output
pnpm storybook	Starts Storybook in dev mode on port 6006
pnpm build-storybook	Builds a static Storybook site to storybook-static/

Development Workflow

1. Create a branch off main:

   git checkout -b feat/component-name

2. Build your component under src/components/ui or src/components/custom, using class-variance-authority and the shared cn utility (src/lib/utils.ts) for variant/class handling, consistent with existing components (see src/components/ui/button.tsx).

3. Add a Storybook story alongside the component (*.stories.tsx) and verify it renders correctly via pnpm storybook.

4. Export the component from src/index.ts.

5. Add/update tests, run type checking, and confirm everything passes locally before opening a PR:

   pnpm typecheck
   pnpm test

6. Open a pull request against main for review.

Testing

Tests run via Vitest, with browser-mode component tests powered by Playwright and the Storybook addon.

pnpm test         # run once
pnpm test:watch   # watch mode

Building

pnpm build

This runs tsdown, which bundles src/index.ts into ESM and CJS output with type declarations in dist/, and validates the package output with publint.

Publishing

Ewa UI is published to npm under the @spatialnode organization as @spatialnode/ewa-ui. Releases are triggered from GitHub, not published manually from a local machine.

1. Bump version in package.json (merge that change to main first, following the normal PR workflow).
2. On GitHub, create a new Release with tag vX.Y.Z matching the package.json version (e.g. v0.1.0), targeting main.
3. Publishing the release triggers .github/workflows/release.yml, which runs typecheck, tests, and pnpm build, verifies the tag matches package.json, then runs npm publish --access public --provenance.

This requires an NPM_TOKEN repo secret (an npm automation token for an account in the spatialnode org — automation tokens bypass 2FA for CI) configured under repo Settings → Secrets and variables → Actions.

Contributing

• Follow the existing code style and component patterns (Radix primitives, cva for variants, Tailwind for styling).
• Every component change should include a corresponding Storybook story.
• Run pnpm typecheck and pnpm test before pushing.
• Keep pull requests focused and scoped to a single component or change.