xTweak - Modern Phoenix LiveView Component Library

A production-ready Phoenix LiveView component library ported from Nuxt UI, featuring 113 components with Alpine.js interactivity and UnoCSS atomic styling. Built on Elixir umbrella architecture with Ash Framework integration.

🤖 AI Development Setup

This project is optimized for AI-assisted development.

For Humans (Peter):

• 🎯 dev_docs/README.md – Documentation index (start here!)
• 📖 dev_docs/COMPLETE_WORKFLOW_GUIDE.md – Complete guide for working with Claude Code

For Claude Code (Automatic):

• Claude reads CLAUDE.md automatically - you just use slash commands or direct prompts

🏗️ Architecture

xTweak is built as an Elixir umbrella application with three independent apps:

• xtweak_core - Business logic with Ash Framework (User authentication, Newsletter)
• xtweak_web - Phoenix LiveView web interface with UnoCSS styling
• xtweak_ui - Reusable UI component library for Phoenix applications

🚀 Quick Start

Prerequisites

• Elixir 1.19.1+ (upgraded October 2025)
• Erlang/OTP 28.1+ (upgraded October 2025)/p
• PostgreSQL 14+ (tested with 16)
• Bun 1.0+ (for asset compilation)

Version Management Options:

• Use Devbox (recommended): devbox shell at project root
• OR install manually: See required versions above

Using xTweak as a Template

xTweak is designed to be cloned and renamed for new projects. Use the standalone rename script:

# 1. Clone the template
git clone <your_repository_url> my-new-project
cd my-new-project

# 2. Initialize fresh git history
rm -rf .git && git init

# 3. Rename the project (interactive, runs before installing deps)
elixir scripts/rename_project.exs

# 4. Install dependencies
mix deps.get

# 5. Follow the post-rename steps

Development Setup (If Not Renaming)

1. Clone the repository:

   git clone <your_repository_url>
   cd xtweak

2. Install dependencies:

   mix deps.get
   cd apps/xtweak_web/assets && bun install && cd ../../..
   cd apps/xtweak_ui/assets && bun install && cd ../../..

3. Setup database:

   mix ash.setup

4. Start the development server:

   mix phx.server

Visit localhost:4000 to see the application.

Testing

Run the test suite:

# Run all tests
mix test

# Run specific app tests
mix test apps/xtweak_core/test
mix test apps/xtweak_web/test

Code Quality

# Format code
mix format

# Run static analysis
mix credo --strict

# Type checking
mix dialyzer

📦 What's Included

Current Status (Phase 0 Baseline)

• Infrastructure: Elixir umbrella with Phoenix + Ash Framework + UnoCSS
• Theme System: OKLCH-based theming with dark/light mode, CSS variables
• Template Resources: User and Newsletter resources (for reference/testing)
• Component Templates: 5-stage workflow (plan, implement, validate, document, release)
• AI Development: 37 agents, 15 patterns, 13 slash commands for AI-assisted development

Components: 0 ported yet (Phase 0 baseline) - 113 Nuxt UI components mapped for porting

Next Phase: Phase 0.25 (Showcase Infrastructure) - Build Nuxt UI documentation clone

Tech Stack

• Elixir 1.19.1+ with OTP 28.1+ - Functional programming language
• Phoenix 1.8+ with LiveView 1.1+ - Real-time web applications
• Ash Framework 3.7+ - Resource-based application framework
• UnoCSS 0.65+ - Atomic CSS engine with Tailwind-compatible utilities
• Alpine.js 3.14+ - Lightweight JavaScript framework for interactivity
• PostgreSQL 14+ - Primary database (for Ash resources)

🗄️ Database Schema

The project includes reference Ash resources for testing/template purposes:

# Generate and run migrations
mix ash_postgres.generate_migrations
mix ash.setup

Template resources (for reference/testing):

• users - User resource with authentication (Ash template)
• newsletter_subscriptions - Newsletter resource (Ash template)

These are minimal examples to demonstrate Ash Framework integration. They can be removed or customized as needed.

📁 Project Structure

xtweak/
├── apps/
│   ├── xtweak_core/           # Business logic & Ash resources
│   │   ├── lib/xtweak/core/   # User, Newsletter resources
│   │   └── test/              # Resource tests
│   ├── xtweak_web/            # Phoenix web interface
│   │   ├── lib/xtweak_web_web/
│   │   │   ├── controllers/   # Page controller
│   │   │   ├── components/    # LiveView components
│   │   │   └── live/          # LiveView modules (if needed)
│   │   └── assets/            # CSS/JS assets
│   └── xtweak_ui/             # UI component library
│       └── lib/xtweak_ui/     # Reusable Phoenix components
├── config/                    # Application configuration
├── dev_docs/                # Human-readable documentation
├── prd/                       # Product roadmap and sprint plans
└── .claude/                   # AI coding assistance setup

🔧 Configuration

Environment Variables

The template is pre-configured for development. For production, set:

DATABASE_URL=your_database_url
SECRET_KEY_BASE=your_secret_key
PHX_HOST=your_domain.com

🛠️ Customization

Adding New Resources

1. Create new Ash resource:

   # Navigate to core app
   cd apps/xtweak_core
   
   # Add new resource file
   # lib/xtweak/core/your_resource.ex

2. Add to domain:

   # lib/xtweak/core.ex
   resources do
     resource(XTweak.Core.User)
     resource(XTweak.Core.Newsletter)
     resource(XTweak.Core.YourResource)  # Add here
   end

3. Generate migrations:

   mix ash_postgres.generate_migrations
   mix ash.setup

Using UI Components

Import the component library in your LiveViews:

defmodule YourAppWeb.YourLive do
  use YourAppWeb, :live_view
  use XTweakUI.Components

  def render(assigns) do
    ~H"""
    <.card>
      <:header>Welcome</:header>
      <:body>
        <.button variant="primary">Get Started</.button>
      </:body>
    </.card>
    """
  end
end

📋 Available Mix Commands

# Development
mix setup                 # Set up the project
mix phx.server           # Start Phoenix server

# Database (Ash commands)
mix ash.setup            # Setup database with Ash
mix ash_postgres.generate_migrations  # Generate migrations

# Testing
mix test                 # Run all tests
mix test --cover        # Run with coverage

# Code Quality
mix format              # Format code
mix credo --strict      # Static analysis
mix dialyzer           # Type checking

# Assets
mix assets.build        # Build assets for development
mix assets.deploy       # Build assets for production

🤖 AI Development Ready

This template is pre-configured for AI-assisted development with Claude Code:

MCP Server Integration

• Ash AI (mcp__ash_ai__*) - Ash Framework assistance, resource listings, generators
• TideWave (mcp__tidewave__*) - Elixir development tools, project evaluation, docs
• Context7 (mcp__context7__*) - Library documentation (Cytoscape, UnoCSS, etc.)
• Playwright (mcp__playwright__*) - Browser automation for UI verification

Pattern-Based Development

• Comprehensive pattern library in .claude/patterns/
• Specialized agents for different tasks (see .claude/README.md)
• Enforced quality gates and verification workflows
• See CLAUDE.md for complete guidelines

🎨 Theming & Styling

The project uses UnoCSS (atomic CSS engine) with OKLCH color space and CSS variable-based theming:

• UnoCSS - Tailwind-compatible atomic CSS with instant compilation
• OKLCH colors - Perceptually uniform color space for consistent theming
• Dark/light mode - Automatic theme switching with CSS variables
• Alpine.js - Client-side interactivity (color mode toggle, dropdowns, etc.)
• Responsive design - Mobile-first utilities

Theme system: See apps/xtweak_ui/lib/xtweak_ui/theme.ex and prd/06-theming-strategy.md

📄 License

This project template is licensed under the MIT License.

🤝 Getting Help

• Check the dev_docs/ directory for human-readable documentation
• Review the prd/ directory for product roadmap and sprint plans
• Review existing code patterns in each app
• Use the AI coding assistance tools pre-configured in the project

---

Ready to build something amazing? 🚀

This template gives you a clean, minimal starting point with modern Elixir best practices. Customize it to fit your project's needs!