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

$3

``bash
npm install @fractl/ui-builder
`

$3

`bash


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
`

$3

Set your GitHub token:

`bash
export GITHUB_TOKEN=your_github_token_here
`

Or create a .env file:

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

📖 Usage

$3

#### Build Complete Application

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

#### Generate Schema Only

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

#### Build React App Only

`bash
agentlang-build-ui build-app
`

$3

`javascript
import { buildApp, AgentLangBuilder } from '@fractl/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

$3

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

$3

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

$3

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

📁 Project Structure

`
@fractl/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

$3

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

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

$3

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

$3

#### GitHub Authentication Failed

`bash
Error: GitHub token is required
`

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

#### Repository Not Found

`bash
Error: Repository not found
`

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

#### Build Failed

`bash
Error: React app build failed
`

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

#### Output Directory Not Empty

`bash
Error: Output directory is not empty
`

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

$3

Enable verbose logging:

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

🧪 Development

$3

`bash


Clone the repository

git clone https://github.com/fractl-dev/ui-builder.git
cd ui-builder

Install dependencies

npm install

Build the CLI

npm run build:cli

Test locally

npm run dev
`

$3

`bash


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

$3

`bash


Build a simple app


agentlang-build-ui build \
--repo my-org/my-data-model \
--output ./my-app
`

$3

`bash


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
`

$3

`yaml


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/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/ui - React UI components
- Fractl Studio - Development environment

---

Built with ❤️ by the Fractl Team