DOCSEARCHbyAlgolia
Submit Docs

Owl Admin

repository·master·Indexed 20 days ago

https://github.com/slowlyo/owl-admin

A rapid backend development framework built on Laravel and the amis JSON-based UI engine. It enables the creation of complex administrative interfaces using declarative JSON configurations to minimize frontend development effort. Key features include built-in user and role management, a code generator, over 150 encapsulated amis components, and a decoupled frontend-backend architecture. It also provides specialized development resources and agent skills for AI editors like Cursor, Claude Code, and Trae.

Tokens
28.1K
Snippets
71
Records
111
Agent score
69%

What's inside owl-admin

  1. Overview of Owl Admin

    master

    Owl Admin is a fast and flexible backend framework built on top of Laravel and amis. It allows developers to build complex administrative pages using JSON-based configurations via amis, significantly reducing frontend development workload.

    Key features include:

    • Built-in Admin Functions: User management, role management, permission management, and menu management.
    • Code Generator: Supports saving generation records, importing/exporting records, and generating full functionality without manual code changes.
    • Amis Integration: Over 150 encapsulated amis components for rapid UI building.
    • Dynamic API Templates: Support for CRUD, options, settings, state switching, and aggregate statistics.
    • Decoupled Architecture: A frontend-backend separation that allows for custom frontend development if amis components are insufficient.

  2. Use Owl Admin DevTools Generator for code generation and dynamic APIs

    master

    The owl-admin-devtools-generator skill is designed for tasks involving Owl Admin's development tools. Use this skill when working with:

    • Code Generation: Generating CRUD code, using Support/CodeGenerator, or managing code generator logic.
    • Dynamic APIs: Creating or modifying dynamic API templates in app/ApiTemplates or Support/Apis.
    • Relationship Management: Configuring model relationships and connections.
    • Visual Pages: Managing low-code visual pages or complex controller/iframe-based pages.
    • DevTools: Interacting with Controllers/DevTools or general developer utilities.

    When performing these tasks, prioritize reusing built-in templates (List, Detail, Create, Update, Delete, Options, Settings, Status Toggle, Aggregated Statistics) and ensure new API templates implement the AdminBaseApi and AdminApiInterface contracts.

  3. Develop Owl Admin extensions and modules

    master

    When building for Owl Admin, follow these core development principles:

    • Module Creation: Always prioritize using php artisan admin-module:init ModuleName for new modules.
    • Extension Lifecycle: Extensions should follow the lifecycle of the Owl Admin Extend\ServiceProvider.
    • Isolation: Ensure that routes, configurations, language files, and menus are isolated within their respective modules or extensions.
    • Menu & Permissions: When modifying menus and permissions, verify the URL, component type, and parent-child relationships.
    • Safety: Avoid performing destructive operations like database clearing, full deletions, or git operations during development tasks.

  4. Development principles for Owl Admin extensions

    master

    When extending Owl Admin via the DevTools or Code Generator, follow these principles to ensure stability and compatibility:

    Dynamic APIs

    • Template Reuse: Prioritize reusing built-in templates (List, Detail, Create, Update, Delete, Options, Settings, Status Toggle, Aggregated Statistics).
    • Contract Adherence: New API templates must implement AdminBaseApi and AdminApiInterface. Do not bypass these interfaces.

    Pages and UI

    • Low-Code First: Use the built-in Page Management for low-code pages. For complex logic, transition to a dedicated Controller or an iframe-based page.

    Code Generation

    • CRUD Readiness: Before generating CRUD, verify the database table structure, primary keys, timestamps, soft deletes, and menu information.
    • Lifecycle Coverage: Changes to the code generator must be tested across the preview, generation, and cleanup paths, as well as import/export record paths.

    Relationship Management

    • Consistency: When modifying relationship management, confirm model namespaces, connections, field options, and the resulting model methods.

    Performance

    • Avoid I/O in Loops: Do not perform database schema queries or file I/O operations inside loops.

  5. Implement conditional queries and model relations

    master

    Conditional Queries

    Use the ConditionBuilderScopeTrait and the ConditionBuilder component to implement complex conditional search logic.

    Model Relations

    To display related model data in the UI:

    1. Ensure the Service layer performs the necessary eager loading for the association.
    2. Use the relation.field syntax in the component field configuration to access the related data.

  6. Initialize and run the owl-admin project

    master

    To set up the project environment, install dependencies using pnpm. You can then run the project in development mode or build it for production using the provided scripts.

    # Install dependencies
pnpm install

# Run in development mode
pnpm run dev

# Build for production
pnpm run build

  7. Install Owl Admin

    master

    To install Owl Admin in a Laravel project, follow these steps in order:

    1. Install the package via Composer.
    2. Publish the framework resources.
    3. Run the installation command.
    4. Run the diagnostic tool to verify the installation.

    If you are using an AI-powered editor (like Cursor or Trae) and want to optimize the project for AI assistance, run the admin:ai-install command after the standard installation.

    composer require slowlyo/owl-admin
php artisan admin:publish
php artisan admin:install
php artisan admin:doctor

# For AI editor optimization
php artisan admin:ai-install

  8. Install AI Editor development resources

    master

    To optimize development using AI-powered editors like Codex, Cursor, Claude Code, or Trae, you can install specialized development materials. Running php artisan admin:ai-install generates a .agents directory containing:

    • .agents/skills: Agent Skills for tools like Codex and Cursor.
    • .agents/adapters: Rule adaptation files for Claude Code, Cursor, and Trae.
    • .agents/README.md: Instructions for using these files.

    These resources cover business logic development, amis pages, multi-module extensions, code generation, and more, designed to reduce noise for AI agents.

    # Install the AI resources
php artisan admin:ai-install

# To overwrite existing .agents files, use:
php artisan admin:ai-install --force

  9. Set up AI Agent Skills and Rules for Claude Code

    master

    To integrate Owl Admin with Claude Code, you need to copy the project rules to CLAUDE.md and migrate the agent skills into the .claude/skills directory.

    # Copy project rules
cp .agents/adapters/CLAUDE.md CLAUDE.md

# Copy Agent Skills
mkdir -p .claude/skills
cp -R .agents/skills/* .claude/skills/

  10. Best practices for using AI with Owl Admin

    master

    When using AI coding assistants (like Cursor, Claude, or Trae) with Owl Admin, follow these guidelines to ensure accuracy and prevent errors:

    1. Context Initialization: Always start by having the AI read config/admin.php, app/Admin, and routes/admin.php to understand the project structure.
    2. Rendering Preference: When creating pages, prioritize using Owl Admin's backend amis renderers.
    3. Extension/Module Management: Use Owl Admin's built-in commands for any tasks involving extensions or modules.
    4. Avoid Compilation Errors: Do not instruct the AI to compile vendor/slowlyo/owl-admin/admin-views.
    5. Environment: Always launch your AI editor from the Laravel project root.

  11. Develop Owl Admin pages using amis

    master

    Owl Admin uses amis schemas to drive backend pages, including CRUD operations, forms, tables, detail views, filters, and toolbar actions.

    Implementation Principles

    • Schema Generation: Prioritize using the amis() helper and Owl Admin Renderer classes to generate schemas.
    • CRUD Structure: For CRUD pages, reuse the standard AdminController structure consisting of list(), form(), and detail() methods.
    • Logic Separation: Keep data querying, saving, and validation within Service classes or native Laravel capabilities. Do not embed complex business logic directly into the page schema.
    • Component Usage: Refer to specific documentation themes for components (Pages, Forms, Buttons, Data Display, Layout, Conditional Display, and Data Linkage). Extra components like Iconify, WangEditor, and Watermark should be used via the Renderer pattern.
    • Iframe Pages: Use the CLI to generate the skeleton for iframe pages.
    • Frontend: Do not attempt to compile admin-views unless you specifically need to modify the framework's core frontend source code.
    // Example principle: Use AdminController structure for CRUD
class UserController extends AdminController
{
    public function list()
    {
        // Return amis schema for list view
    }

    public function form()
    {
        // Return amis schema for form/create/edit
    }

    public function detail()
    {
        // Return amis schema for detail view
    }
}