Getting Started

Werkbank is a type-safe, performance-oriented UI component library for React applications. It provides a set of accessible, WAI-ARIA compliant components optimized for Parcel and Vanilla Extract.

Prerequisites

Ensure the development environment meets the following requirements:

• Node.js: Version 18 or higher.
• npm: Package manager for dependency installation.
• TypeScript: Version 5.0 or higher.
• Secure Context: A secure context (HTTPS or localhost) is required for certain browser APIs.

Architecture Overview

Werkbank utilizes a specific stack to optimize for build size and type safety:

• Parcel: A zero-configuration bundler.
• Vanilla Extract: A zero-runtime CSS-in-JS library that generates static CSS files at build time.
• Valibot: A schema validation library used for data integrity and bundle size optimization.

1. Initialize the Project

Use the create-parcel scaffolding tool to set up a new React application configured for Parcel.

npm create parcel react-client my-werkbank-app
cd my-werkbank-app
Copy

2. Install Dependencies

Install the required core packages and development tools.

npm install werkbank valibot
npm install --save-dev @vanilla-extract/parcel-transformer @vanilla-extract/css typescript
Copy

3. Configure Parcel

Global configuration is managed via package.json and .parcelrc.

package.json

Configure the Parcel resolver to respect package exports.

{
  "name": "my-werkbank-app",
  "@parcel/resolver-default": {
    "packageExports": true
  }
}
Copy

.parcelrc

Configure the Vanilla Extract transformer to process TypeScript style definitions (.css.ts) before other transformations.

{
  "extends": "@parcel/config-default",
  "transformers": {
    "*.css.ts": ["@vanilla-extract/parcel-transformer", "..."],
    "*.css.js": ["@vanilla-extract/parcel-transformer", "..."]
  }
}
Copy

4. Create the Application Entry Point

Update the main application file to apply the theme and render a component.

src/App.tsx

Import the following:

• defaultTheme: The pre-configured theme class from Werkbank.
• cx: A type-safe utility for concatenating class names.
• reset.css: The CSS reset for browser consistency.

import React from 'react';
import { Button } from 'werkbank/component/button';
import { defaultTheme } from 'werkbank/style/theme';
import { cx } from 'werkbank/utils';
import 'werkbank/style/reset.css';
import * as styles from './index.css';

export const App = () => (
  <div className={cx(defaultTheme, styles.container)}>
    <h1>Werkbank Initialization</h1>
    <p>System operational.</p>
    <Button
      type="button"
      onClick={() => alert('Action triggered')}
    >
      Execute
    </Button>
  </div>
);
Copy

Tree Shaking and Module Resolution

Werkbank supports deep imports (e.g., werkbank/component/button). This practice allows the bundler to include only the necessary code, minimizing the final bundle size.

Licensing

Werkbank is licensed under MPL-2.0.

Additional Resources

• Routing: Configuration for client-side routing.
• Forms: Implementation of data collection and validation.
• RPC: Integration with backend services using Remote Procedure Calls.