Development & Contribution Guide

This guide provides instructions for setting up your development environment, building, testing, and contributing to the Better UI project.

Getting Started

To get started with Better UI development, follow these steps:

1. Clone the repository:

2. Install dependencies:
   This command will install all necessary project dependencies, including development tools and peer dependencies.

Development Commands

Better UI uses npm scripts to streamline development workflows:

• npm run dev: Starts the Next.js development server for the demo application. This allows you to test changes to the library and the demo in real-time.
• npm run build:lib: Compiles the core Better UI library (src/) into CommonJS (.js) and ES Modules (.mjs) formats. It also generates TypeScript declaration files (.d.ts) and cleans the dist directory before building. This command uses tsup.
• npm run build:next: Builds the Next.js demo application located in the app/ directory for production.
• npm run build: A comprehensive build command that first runs npm run build:lib and then npm run build:next, preparing the entire project (library and demo) for deployment.
• npm run type-check: Runs the TypeScript compiler to check for type errors across the project without emitting any JavaScript files. This is crucial for maintaining type safety.
• npm run lint: Executes ESLint to enforce code style, catch potential bugs, and ensure consistency across the codebase.
• npm run test: Runs unit and integration tests using Jest.

Project Structure

The Better UI codebase is organized as follows:

src/
  tool.tsx          # Core tool() API definition and logic
  react/
    useTool.ts      # React hooks for integrating tools into components
  index.ts          # Main entry point for the Better UI library exports

app/
  demo/             # The main demonstration page for Better UI
  api/chat/         # API route for chat integration with AI models
  api/tools/        # API route for executing tools server-side

lib/
  tools.tsx         # Contains example tool definitions used by the demo app

docs/
  API_V2.md         # Detailed API documentation (not included in this context)

The src/ directory contains the core, distributable library code. The app/ directory houses the Next.js demo application, showcasing how to use the library. lib/ is used for shared example tool definitions.

Testing

Better UI employs Jest for testing, with a specific configuration to handle different test environments:

• jest.config.js: This configuration file defines two test "projects":
  • node: For server-side logic tests (**/__tests__/**/*.test.ts), running in a Node.js environment. This is ideal for testing the core Tool class and its server-side handlers.
  • react: For client-side React component and hook tests (**/__tests__/**/*.react.test.tsx), running in a jsdom environment. It includes a setup file (src/__tests__/setup.ts) to configure @testing-library/jest-dom for DOM-related matchers.
• src/__tests__: This directory contains all test files:
  • tool.test.ts: Focuses on the core Tool class functionality, server-side execution, input/output validation, and caching.
  • react.react.test.tsx: Contains tests for the useTool and useTools React hooks, ensuring they integrate correctly with React's lifecycle and state management.
  • setup.ts: Provides global setup for the React test environment, importing custom Jest matchers.

To run all tests, use npm run test.

Build Process

The library build process leverages tsup, a fast and simple TypeScript bundler, as configured in package.json's build:lib script:

• It targets src/index.ts as the entry point.
• Outputs both CommonJS (.js) and ES Module (.mjs) formats, ensuring broad compatibility.
• Generates accurate TypeScript declaration files (.d.ts) for excellent type-checking support in consuming projects.
• Uses tsconfig.lib.json for specific library compilation settings.
• The dist directory is cleaned before each build to ensure a fresh output.

Contribution Guidelines

We welcome contributions to Better UI! To ensure a smooth process, please follow these guidelines:

1. Fork the Repository: Start by forking the lantos1618/better-ui repository to your GitHub account.
2. Create a Branch: For any new feature or bug fix, create a dedicated branch from main. Use a descriptive name (e.g., feat/add-new-tool, fix/bug-in-cache).
3. Code Style: Adhere to the existing code style. The npm run lint command will help identify any deviations.
4. Tests: All new features must be accompanied by relevant unit or integration tests. Bug fixes should include a test that reproduces the bug and then verifies the fix. Ensure all existing tests pass by running npm run test.
5. Type Safety: Maintain type safety throughout the codebase. Run npm run type-check to catch any TypeScript errors.
6. Descriptive Commits: Write clear, concise commit messages that explain the purpose of each change.
7. Pull Requests (PRs):
   • Submit your PR to the main branch of the original repository.
   • Provide a clear and detailed description of your changes, explaining the problem it solves or the feature it introduces.
   • Reference any relevant issues.
   • Ensure your branch is up-to-date with the main branch before submitting.
8. License: By contributing, you agree that your contributions will be licensed under the project's MIT License.

Thank you for helping make Better UI even better!