Agentlang UI Builder

🚀 Build deployable React applications from AgentLang schemas

A powerful tool that automatically generates complete, production-ready React applications from AgentLang data models. Perfect for rapid application development, prototyping, and building consistent UI frameworks.

✨ Features

• 🔗 Automatic Schema Generation: Clones GitHub repositories and generates UI schemas from AgentLang models
• ⚛️ React App Generation: Creates complete React applications with forms, dashboards, and navigation
• 🏗️ Build Pipeline: Complete build process from schema to deployable files
• 🎯 CLI Interface: Easy-to-use command-line tool for automation
• 📦 Programmatic API: Use as a library in your own applications
• 🔧 Vite Integration: Built with Vite for fast development and optimized builds

🚀 Quick Start

Installation

npm install @fractl/agentlang-ui-builder

Basic Usage

# Build a complete React app from an AgentLang repository
npx agentlang-build-ui build \
  --repo owner/repo-name \
  --output ./my-built-app \
  --token YOUR_GITHUB_TOKEN

Environment Setup

Set your GitHub token:

export GITHUB_TOKEN=your_github_token_here

Or create a .env file:

GITHUB_TOKEN=your_github_token_here
GITHUB_ORG=your_org_name
GITHUB_REPO=your_repo_name
GITHUB_USERNAME=your_username

📖 Usage

CLI Commands

Build Complete Application

agentlang-build-ui build \
  --repo owner/repo-name \
  --output ./output-directory \
  --branch main \
  --org your-org \
  --username your-username \
  --token your-token \
  --api-url https://api.example.com

Options:

• -r, --repo <repo>: GitHub repository (format: owner/repo) Required
• -o, --output <path>: Output directory for built files Required
• -b, --branch <branch>: Git branch to use (default: main)
• --org <org>: GitHub organization (defaults to repo owner)
• --username <username>: GitHub username (defaults to repo owner)
• --token <token>: GitHub personal access token
• --api-url <url>: API URL for the deployed application

Generate Schema Only

agentlang-build-ui generate-schema \
  --repo owner/repo-name \
  --branch main

Build React App Only

agentlang-build-ui build-app

Programmatic Usage

import { buildApp, AgentLangBuilder } from '@fractl/agentlang-ui-builder';

// Simple usage
await buildApp({
    repo: 'owner/repo-name',
    output: './my-app',
    branch: 'main',
});

// Advanced usage with custom options
const builder = new AgentLangBuilder();
await builder.build({
    repo: 'owner/repo-name',
    output: './my-app',
    branch: 'develop',
    org: 'custom-org',
    username: 'custom-user',
    token: 'custom-token',
    apiUrl: 'https://api.example.com',
});

🏗️ How It Works

1. Schema Generation

• Clones the specified GitHub repository
• Installs dependencies
• Uses AgentLang runtime to analyze data models
• Generates comprehensive UI schemas

2. React App Building

• Creates React components based on generated schemas
• Builds forms, dashboards, and navigation
• Optimizes for production with Vite

3. Output Generation

• Produces static HTML, CSS, and JavaScript files
• Ready for deployment to any static hosting service
• Includes all necessary assets and dependencies

📁 Project Structure

@fractl/agentlang-ui-builder/
├── src/
│   ├── cli.ts              # Command-line interface
│   ├── index.ts            # Main exports
│   └── app/                # React application
├── schema-generator/        # AgentLang schema generation
├── dist/                   # Built output
└── package.json

🔧 Configuration

GitHub Authentication

You need a GitHub Personal Access Token with the following permissions:

• repo - Access to private repositories
• read:org - Read organization information

Repository Requirements

Your AgentLang repository should contain:

• AgentLang schema files
• package.json with dependencies
• Optional ui-spec.json for custom UI configurations

📦 Output

The build process generates:

output-directory/
├── index.html              # Main HTML file
├── assets/                 # Compiled CSS and JavaScript
│   ├── index-[hash].js     # Main application bundle
│   ├── index-[hash].css    # Styles
│   └── [hash].js           # Vendor libraries
└── favicon.ico             # Application icon

🚀 Deployment

The generated files can be deployed to:

• Netlify: Drag and drop the output directory
• Vercel: Connect your repository and set build output
• GitHub Pages: Push to gh-pages branch
• AWS S3: Upload files to S3 bucket
• Any static hosting service

🔍 Troubleshooting

Common Issues

GitHub Authentication Failed

Error: GitHub token is required

Solution: Set your GITHUB_TOKEN environment variable or use --token option.

Repository Not Found

Error: Repository not found

Solution: Check repository name and ensure you have access permissions.

Build Failed

Error: React app build failed

Solution: Ensure the schema generation completed successfully and ui-schema.ts exists.

Output Directory Not Empty

Error: Output directory is not empty

Solution: Use an empty directory or clear the existing contents.

Debug Mode

Enable verbose logging:

DEBUG=* agentlang-build-ui build --repo owner/repo --output ./app

🧪 Development

Local Development

# Clone the repository
git clone https://github.com/fractl-dev/agentlang-ui-builder.git
cd agentlang-ui-builder

# Install dependencies
npm install

# Build the CLI
npm run build:cli

# Test locally
npm run dev

Building

# Build CLI and React app
npm run build:all

# Build only CLI
npm run build:cli

# Build only React app
npm run build-app

📚 Examples

Basic Example

# Build a simple app
agentlang-build-ui build \
  --repo my-org/my-data-model \
  --output ./my-app

Advanced Example

# Build with custom configuration
agentlang-build-ui build \
  --repo my-org/complex-model \
  --branch develop \
  --output ./production-app \
  --org enterprise-org \
  --username enterprise-user \
  --api-url https://api.enterprise.com

CI/CD Integration

# GitHub Actions example
name: Build AgentLang App
on:
    push:
        branches: [main]
jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3
            - uses: actions/setup-node@v3
              with:
                  node-version: '18'
            - run: npm install -g @fractl/agentlang-ui-builder
            - run: |
                  agentlang-build-ui build \
                    --repo ${{ github.repository }} \
                    --output ./dist \
                    --token ${{ secrets.GITHUB_TOKEN }}
            - uses: actions/upload-artifact@v3
              with:
                  name: built-app
                  path: ./dist

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🔗 Related Projects

• AgentLang - The core language
• @agentlang-nx/ui - React UI components
• Fractl Studio - Development environment

Built with ❤️ by the Fractl Team