HomeAPIBlog

wheels generate frontend

Generate frontend code including JavaScript, CSS, and interactive components.

⚠️ Note: This command is currently marked as disabled in the codebase. The documentation below represents the intended functionality when the command is restored.

Synopsis

wheels generate frontend [type] [name] [options]
wheels g frontend [type] [name] [options]

Description

The wheels generate frontend command creates frontend assets including JavaScript modules, CSS stylesheets, and interactive components. It supports various frontend frameworks and patterns while integrating seamlessly with Wheels views.

Current Status

This command is temporarily disabled. Use manual approaches:

# Create frontend files manually in:
# /public/javascripts/
# /public/stylesheets/
# /views/components/

Arguments (When Enabled)

Argument
Description
Default

type

Type of frontend asset (component, module, style)

Required

name

Name of the asset

Required

Options (When Enabled)

Option
Description
Default

--framework

Frontend framework (vanilla, alpine, vue, htmx)

vanilla

--style

CSS framework (none, bootstrap, tailwind)

none

--bundler

Use bundler (webpack, vite, none)

none

--typescript

Generate TypeScript files

false

--test

Generate test files

true

--force

Overwrite existing files

false

--help

Show help information

Intended Functionality

Generate Component

wheels generate frontend component productCard --framework=alpine

Would generate:

/public/javascripts/components/productCard.js:

// Product Card Component
document.addEventListener('alpine:init', () => {
    Alpine.data('productCard', (initialData = {}) => ({
        // State
        product: initialData.product || {},
        isLoading: false,
        isFavorite: false,
        
        // Computed
        get formattedPrice() {
            return new Intl.NumberFormat('en-US', {
                style: 'currency',
                currency: 'USD'
            }).format(this.product.price || 0);
        },
        
        // Methods
        async toggleFavorite() {
            this.isLoading = true;
            try {
                const response = await fetch(`/api/products/${this.product.id}/favorite`, {
                    method: this.isFavorite ? 'DELETE' : 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                        'X-CSRF-Token': this.getCsrfToken()
                    }
                });
                
                if (response.ok) {
                    this.isFavorite = !this.isFavorite;
                    this.$dispatch('favorite-changed', {
                        productId: this.product.id,
                        isFavorite: this.isFavorite
                    });
                }
            } catch (error) {
                console.error('Failed to toggle favorite:', error);
                this.$dispatch('notification', {
                    type: 'error',
                    message: 'Failed to update favorite status'
                });
            } finally {
                this.isLoading = false;
            }
        },
        
        async addToCart() {
            this.isLoading = true;
            try {
                const response = await fetch('/api/cart/items', {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                        'X-CSRF-Token': this.getCsrfToken()
                    },
                    body: JSON.stringify({
                        productId: this.product.id,
                        quantity: 1
                    })
                });
                
                if (response.ok) {
                    this.$dispatch('cart-updated');
                    this.$dispatch('notification', {
                        type: 'success',
                        message: 'Added to cart'
                    });
                }
            } catch (error) {
                console.error('Failed to add to cart:', error);
            } finally {
                this.isLoading = false;
            }
        },
        
        getCsrfToken() {
            return document.querySelector('meta[name="csrf-token"]')?.content || '';
        }
    }));
});

/public/stylesheets/components/productCard.css:

/* Product Card Styles */
.product-card {
    @apply bg-white rounded-lg shadow-md overflow-hidden transition-transform hover:scale-105;
}

.product-card__image {
    @apply w-full h-48 object-cover;
}

.product-card__content {
    @apply p-4;
}

.product-card__title {
    @apply text-lg font-semibold text-gray-800 mb-2;
}

.product-card__price {
    @apply text-xl font-bold text-blue-600 mb-3;
}

.product-card__actions {
    @apply flex justify-between items-center;
}

.product-card__button {
    @apply px-4 py-2 rounded font-medium transition-colors;
}

.product-card__button--primary {
    @apply bg-blue-500 text-white hover:bg-blue-600;
}

.product-card__button--secondary {
    @apply bg-gray-200 text-gray-700 hover:bg-gray-300;
}

.product-card__button:disabled {
    @apply opacity-50 cursor-not-allowed;
}

/views/components/_productCard.cfm:

<div class="product-card" 
     x-data="productCard({
         product: #SerializeJSON({
             id: arguments.product.id,
             name: arguments.product.name,
             price: arguments.product.price,
             image: arguments.product.imageUrl
         })#
     })">
    
    <img :src="product.image" 
         :alt="product.name" 
         class="product-card__image">
    
    <div class="product-card__content">
        <h3 class="product-card__title" x-text="product.name"></h3>
        <p class="product-card__price" x-text="formattedPrice"></p>
        
        <div class="product-card__actions">
            <button @click="addToCart" 
                    :disabled="isLoading"
                    class="product-card__button product-card__button--primary">
                <span x-show="!isLoading">Add to Cart</span>
                <span x-show="isLoading">Adding...</span>
            </button>
            
            <button @click="toggleFavorite" 
                    :disabled="isLoading"
                    class="product-card__button product-card__button--secondary">
                <span x-show="!isFavorite">♡</span>
                <span x-show="isFavorite">♥</span>
            </button>
        </div>
    </div>
</div>

Generate JavaScript Module

wheels generate frontend module api --typescript

Would generate /public/javascripts/modules/api.ts:

// API Module
interface RequestOptions extends RequestInit {
    params?: Record<string, any>;
}

interface ApiResponse<T = any> {
    data: T;
    meta?: Record<string, any>;
    errors?: Array<{
        field: string;
        message: string;
    }>;
}

class ApiClient {
    private baseUrl: string;
    private defaultHeaders: Record<string, string>;
    
    constructor(baseUrl: string = '/api') {
        this.baseUrl = baseUrl;
        this.defaultHeaders = {
            'Content-Type': 'application/json',
            'X-Requested-With': 'XMLHttpRequest'
        };
        
        // Add CSRF token if available
        const csrfToken = document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content;
        if (csrfToken) {
            this.defaultHeaders['X-CSRF-Token'] = csrfToken;
        }
    }
    
    async request<T = any>(
        endpoint: string,
        options: RequestOptions = {}
    ): Promise<ApiResponse<T>> {
        const { params, ...fetchOptions } = options;
        
        // Build URL with params
        const url = new URL(this.baseUrl + endpoint, window.location.origin);
        if (params) {
            Object.entries(params).forEach(([key, value]) => {
                if (value !== undefined && value !== null) {
                    url.searchParams.append(key, String(value));
                }
            });
        }
        
        // Merge headers
        const headers = {
            ...this.defaultHeaders,
            ...fetchOptions.headers
        };
        
        try {
            const response = await fetch(url.toString(), {
                ...fetchOptions,
                headers
            });
            
            if (!response.ok) {
                throw new ApiError(response.status, await response.text());
            }
            
            const data = await response.json();
            return data;
            
        } catch (error) {
            if (error instanceof ApiError) {
                throw error;
            }
            throw new ApiError(0, 'Network error');
        }
    }
    
    get<T = any>(endpoint: string, params?: Record<string, any>): Promise<ApiResponse<T>> {
        return this.request<T>(endpoint, { method: 'GET', params });
    }
    
    post<T = any>(endpoint: string, data?: any): Promise<ApiResponse<T>> {
        return this.request<T>(endpoint, {
            method: 'POST',
            body: JSON.stringify(data)
        });
    }
    
    put<T = any>(endpoint: string, data?: any): Promise<ApiResponse<T>> {
        return this.request<T>(endpoint, {
            method: 'PUT',
            body: JSON.stringify(data)
        });
    }
    
    delete<T = any>(endpoint: string): Promise<ApiResponse<T>> {
        return this.request<T>(endpoint, { method: 'DELETE' });
    }
}

class ApiError extends Error {
    constructor(public status: number, message: string) {
        super(message);
        this.name = 'ApiError';
    }
}

// Export singleton instance
export const api = new ApiClient();

// Export types
export type { ApiResponse, RequestOptions };
export { ApiClient, ApiError };

Generate HTMX Component

wheels generate frontend component searchForm --framework=htmx

Would generate:

/views/components/_searchForm.cfm:

<form hx-get="/products/search" 
      hx-trigger="submit, keyup changed delay:500ms from:input[name='q']"
      hx-target="##search-results"
      hx-indicator="##search-spinner"
      class="search-form">
    
    <div class="search-form__input-group">
        <input type="search" 
               name="q" 
               value="#params.q ?: ''#"
               placeholder="Search products..."
               class="search-form__input">
        
        <button type="submit" class="search-form__button">
            Search
        </button>
    </div>
    
    <div class="search-form__filters">
        <select name="category" 
                hx-get="/products/search"
                hx-trigger="change"
                hx-target="##search-results"
                hx-include="[name='q']"
                class="search-form__select">
            <option value="">All Categories</option>
            <cfloop query="categories">
                <option value="#categories.id#" 
                        <cfif params.category == categories.id>selected</cfif>>
                    #categories.name#
                </option>
            </cfloop>
        </select>
        
        <select name="sort" 
                hx-get="/products/search"
                hx-trigger="change"
                hx-target="##search-results"
                hx-include="[name='q'],[name='category']"
                class="search-form__select">
            <option value="relevance">Relevance</option>
            <option value="price-asc">Price: Low to High</option>
            <option value="price-desc">Price: High to Low</option>
            <option value="name">Name</option>
        </select>
    </div>
</form>

<div id="search-spinner" class="htmx-indicator">
    <div class="spinner"></div>
</div>

<div id="search-results">
    <!--- Results will be loaded here --->
</div>

Generate Vue Component

wheels generate frontend component todoList --framework=vue

Would generate /public/javascripts/components/TodoList.vue:

<template>
  <div class="todo-list">
    <h2>{{ title }}</h2>
    
    <form @submit.prevent="addTodo" class="todo-form">
      <input
        v-model="newTodo"
        type="text"
        placeholder="Add a new todo..."
        class="todo-form__input"
      >
      <button type="submit" class="todo-form__button">
        Add
      </button>
    </form>
    
    <ul class="todo-items">
      <li
        v-for="todo in filteredTodos"
        :key="todo.id"
        class="todo-item"
        :class="{ 'todo-item--completed': todo.completed }"
      >
        <input
          type="checkbox"
          v-model="todo.completed"
          @change="updateTodo(todo)"
        >
        <span class="todo-item__text">{{ todo.text }}</span>
        <button
          @click="deleteTodo(todo.id)"
          class="todo-item__delete"
        >
          ×
        </button>
      </li>
    </ul>
    
    <div class="todo-filters">
      <button
        v-for="filter in filters"
        :key="filter"
        @click="currentFilter = filter"
        :class="{ active: currentFilter === filter }"
        class="todo-filter"
      >
        {{ filter }}
      </button>
    </div>
  </div>
</template>

<script>
import { ref, computed, onMounted } from 'vue';
import { api } from '../modules/api';

export default {
  name: 'TodoList',
  props: {
    title: {
      type: String,
      default: 'Todo List'
    }
  },
  setup() {
    const todos = ref([]);
    const newTodo = ref('');
    const currentFilter = ref('all');
    const filters = ['all', 'active', 'completed'];
    
    const filteredTodos = computed(() => {
      switch (currentFilter.value) {
        case 'active':
          return todos.value.filter(todo => !todo.completed);
        case 'completed':
          return todos.value.filter(todo => todo.completed);
        default:
          return todos.value;
      }
    });
    
    const loadTodos = async () => {
      try {
        const response = await api.get('/todos');
        todos.value = response.data;
      } catch (error) {
        console.error('Failed to load todos:', error);
      }
    };
    
    const addTodo = async () => {
      if (!newTodo.value.trim()) return;
      
      try {
        const response = await api.post('/todos', {
          text: newTodo.value,
          completed: false
        });
        todos.value.push(response.data);
        newTodo.value = '';
      } catch (error) {
        console.error('Failed to add todo:', error);
      }
    };
    
    const updateTodo = async (todo) => {
      try {
        await api.put(`/todos/${todo.id}`, {
          completed: todo.completed
        });
      } catch (error) {
        console.error('Failed to update todo:', error);
        todo.completed = !todo.completed;
      }
    };
    
    const deleteTodo = async (id) => {
      try {
        await api.delete(`/todos/${id}`);
        todos.value = todos.value.filter(todo => todo.id !== id);
      } catch (error) {
        console.error('Failed to delete todo:', error);
      }
    };
    
    onMounted(loadTodos);
    
    return {
      todos,
      newTodo,
      currentFilter,
      filters,
      filteredTodos,
      addTodo,
      updateTodo,
      deleteTodo
    };
  }
};
</script>

<style scoped>
.todo-list {
  max-width: 500px;
  margin: 0 auto;
}

.todo-form {
  display: flex;
  margin-bottom: 1rem;
}

.todo-form__input {
  flex: 1;
  padding: 0.5rem;
  border: 1px solid #ddd;
  border-radius: 4px 0 0 4px;
}

.todo-form__button {
  padding: 0.5rem 1rem;
  background: #007bff;
  color: white;
  border: none;
  border-radius: 0 4px 4px 0;
  cursor: pointer;
}

.todo-items {
  list-style: none;
  padding: 0;
}

.todo-item {
  display: flex;
  align-items: center;
  padding: 0.5rem;
  border-bottom: 1px solid #eee;
}

.todo-item--completed .todo-item__text {
  text-decoration: line-through;
  opacity: 0.6;
}

.todo-item__delete {
  margin-left: auto;
  background: none;
  border: none;
  color: #dc3545;
  font-size: 1.5rem;
  cursor: pointer;
}

.todo-filters {
  display: flex;
  gap: 0.5rem;
  margin-top: 1rem;
}

.todo-filter {
  padding: 0.25rem 0.75rem;
  border: 1px solid #ddd;
  background: white;
  cursor: pointer;
  border-radius: 4px;
}

.todo-filter.active {
  background: #007bff;
  color: white;
  border-color: #007bff;
}
</style>

Workaround Implementation

Until the command is fixed, create frontend assets manually:

1. Directory Structure

/public/
├── javascripts/
│   ├── app.js
│   ├── components/
│   ├── modules/
│   └── vendor/
├── stylesheets/
│   ├── app.css
│   ├── components/
│   └── vendor/
└── images/

2. Basic App Structure

/public/javascripts/app.js:

// Main application JavaScript
(function() {
    'use strict';
    
    // Initialize on DOM ready
    document.addEventListener('DOMContentLoaded', function() {
        initializeComponents();
        setupEventListeners();
        loadDynamicContent();
    });
    
    function initializeComponents() {
        // Initialize all components
        document.querySelectorAll('[data-component]').forEach(element => {
            const componentName = element.dataset.component;
            if (window.components && window.components[componentName]) {
                new window.components[componentName](element);
            }
        });
    }
    
    function setupEventListeners() {
        // Global event delegation
        document.addEventListener('click', handleClick);
        document.addEventListener('submit', handleSubmit);
    }
    
    function handleClick(event) {
        // Handle data-action clicks
        const action = event.target.closest('[data-action]');
        if (action) {
            event.preventDefault();
            const actionName = action.dataset.action;
            // Handle action
        }
    }
    
    function handleSubmit(event) {
        // Handle AJAX forms
        const form = event.target;
        if (form.dataset.remote === 'true') {
            event.preventDefault();
            submitFormAjax(form);
        }
    }
    
    function submitFormAjax(form) {
        const formData = new FormData(form);
        
        fetch(form.action, {
            method: form.method,
            body: formData,
            headers: {
                'X-Requested-With': 'XMLHttpRequest'
            }
        })
        .then(response => response.json())
        .then(data => {
            // Handle response
        })
        .catch(error => {
            console.error('Form submission error:', error);
        });
    }
    
    function loadDynamicContent() {
        // Load content marked for lazy loading
        const lazyElements = document.querySelectorAll('[data-lazy-load]');
        
        const observer = new IntersectionObserver((entries) => {
            entries.forEach(entry => {
                if (entry.isIntersecting) {
                    loadContent(entry.target);
                    observer.unobserve(entry.target);
                }
            });
        });
        
        lazyElements.forEach(el => observer.observe(el));
    }
    
    function loadContent(element) {
        const url = element.dataset.lazyLoad;
        fetch(url)
            .then(response => response.text())
            .then(html => {
                element.innerHTML = html;
                initializeComponents();
            });
    }
    
})();

3. CSS Structure

/public/stylesheets/app.css:

/* Base styles */
:root {
    --primary-color: #007bff;
    --secondary-color: #6c757d;
    --success-color: #28a745;
    --danger-color: #dc3545;
    --warning-color: #ffc107;
    --info-color: #17a2b8;
    --light-color: #f8f9fa;
    --dark-color: #343a40;
}

/* Layout */
.container {
    max-width: 1200px;
    margin: 0 auto;
    padding: 0 1rem;
}

/* Components */
@import 'components/buttons.css';
@import 'components/forms.css';
@import 'components/cards.css';
@import 'components/modals.css';

/* Utilities */
.hidden {
    display: none !important;
}

.loading {
    opacity: 0.6;
    pointer-events: none;
}

/* Animations */
@keyframes fadeIn {
    from { opacity: 0; }
    to { opacity: 1; }
}

.fade-in {
    animation: fadeIn 0.3s ease-in;
}

Best Practices

  1. Organize by feature: Group related files together

  2. Use modules: Keep code modular and reusable

  3. Follow conventions: Consistent naming and structure

  4. Progressive enhancement: Work without JavaScript

  5. Optimize performance: Minimize and bundle assets

  6. Test components: Unit and integration tests

  7. Document APIs: Clear component documentation

  8. Handle errors: Graceful error handling

  9. Accessibility: ARIA labels and keyboard support

  10. Security: Validate inputs, use CSRF tokens

See Also

Previouswheels generate api-resourceNextwheels generate test

Last updated

Was this helpful?