pushpak1300 Larasonic .cursorrules file for Vue (stars: 209)

// =========================================
// TABLE OF CONTENTS
// =========================================
// 1. General Philosophy
// 2. Vue 3 (Composition API) Conventions
// 3. PHP (Laravel) Conventions
// 4. Tailwind CSS Conventions
// 5. Inertia & Frontend Integration
// 6. Project Structure
// 7. Testing & Quality Assurance
// 8. Performance & Optimization
// 9. Security & Accessibility
// 10. Documentation & Comments
// 11. Additional Tooling & Workflow

// =========================================
// 1. GENERAL PHILOSOPHY
// =========================================
// - You are a highly skilled Laravel, Vue, Inertia, and Tailwind app developer.
// - Your task: Help create a new Starter Kit app and code structure.
// - Always follow best practices, coding standards, and established conventions.
// - Never suggest the use of TypeScript features.
// - Ensure consistency, maintainability, and clarity in all code.
// - Prefer simplicity and readability over "clever" or overly abstract solutions.
// - Keep all code strictly typed in PHP (declare(strict_types=1)) and strongly typed props in Vue.

// =========================================
// 2. VUE 3 (COMPOSITION API) CONVENTIONS
// =========================================
const VueDevelopmentConventions = {
    'principles': [
        'Favor readability, maintainability, and consistency.',
        'Follow the Composition API and `<script setup>` conventions.',
        'Emphasize component reusability, modularity, and clarity.',
    ],

    'projectStructure': [
        'Organize components by feature or domain, not just by type.',
        'Use PascalCase for filenames (e.g., `UserCard.vue`).',
        'Maintain separate directories for `components`, `layouts`, `pages`, `mixins`, and `utils`.',
    ],

    'template': [
        'Use kebab-case for attribute names in templates.',
        'Self-close empty elements (e.g., `<img />`).',
        'Always use `v-for` with a `key` prop.',
        'Keep templates under 100 lines—split into smaller components if needed.',
        'Avoid `v-html` with untrusted content; sanitize beforehand.',
    ],

    'script': [
        'Use `<script setup>` and Composition API exclusively.',
        'Define props with types, default values, and validation.',
        'Order component options: `name`, `components`, `props`, `data`, `computed`, `methods`, `watch`.',
        'Use camelCase for props and methods internally.',
        'Prefix emitted events with the component name (e.g., `user:created`).',
    ],

    'style': [
        'Use scoped styles for component-specific CSS.',
        'Place `<style>` blocks at the bottom of the `.vue` file.',
        'Use BEM naming conventions for classes.',
        'Organize CSS logically: layout first, typography second, utilities last.',
        'Leverage CSS variables for theming where possible.',
    ],

    'propsAndEvents': [
        'Use camelCase for prop names in JS and kebab-case in templates.',
        'Validate all props with types and default values.',
        'Use `emit` with explicit, descriptive event names.',
        'Use `v-model` with a custom prop instead of `.sync` modifiers.',
    ],

    'stateManagement': [
        'Use Pinia or Vuex for global state management as needed.',
        'Limit component-level state to local UI logic.',
        'Keep store modules feature-focused and small.',
    ],

    'componentDesign': [
        'Favor single-responsibility components.',
        'Use `Base`-prefixed components for common UI elements (e.g., `BaseButton`).',
        'Utilize `slots` for flexible content.',
        'Avoid tightly coupling components; use props and events for communication.',
    ],

    'namingConventions': [
        'PascalCase for component names (e.g., `UserCard`).',
        'CamelCase for props and events in JS, kebab-case in templates.',
        'Use semantic, descriptive names for components and props.',
    ],

    'testing': [
        'Use `vue-test-utils` and related tools for unit tests.',
        'Focus on testing component behavior and outputs over implementation details.',
        'Aim for 100% test coverage on critical components and logic.',
    ],

    'performanceOptimization': [
        'Use lazy loading for large components.',
        'Leverage `v-once` for static content.',
        'Use `keep-alive` for caching dynamic components.',
        'Avoid inline functions in templates; use computed properties or methods.',
        'Use pagination or computed properties to optimize large loops.',
    ],

    'accessibility': [
        'Use semantic HTML and proper ARIA attributes.',
        'Ensure keyboard navigability and focus management.',
        'Follow color contrast guidelines for UI elements.',
    ],

    'documentationAndComments': [
        'Comment non-obvious logic and complex computed properties.',
        'Document props, events, and slots in block comments above the component definition.',
    ],

    'bestPractices': [
        'Always use Composition API over Options API.',
        'Never mutate props directly; use computed properties or local copies.',
        'Use `defineExpose` judiciously for composables.',
        'Keep components small, focused, and composable.',
        'Adhere to linting rules (`eslint-plugin-vue`, Prettier).',
    ],
};

// =========================================
// 3. PHP (LARAVEL) CONVENTIONS
// =========================================
const PhpCodingGuidelines = [
    'Use `declare(strict_types=1)` in all PHP files.',
    'Always specify property, parameter, and return types.',
    'Prefer final classes and private methods by default, unless otherwise needed.',
    'Leverage Laravel’s built-in features rather than reinventing the wheel.',
    'Avoid “magic” and use explicit, descriptive methods and properties.',
    'Use composition over inheritance.',
    'Use ClassName::class constants instead of hardcoded class names.',
    'Provide descriptive exceptions and minimal but clear comments.',
];

const LaravelDevelopmentConventions = [
    'Focus on consistency, security, and performance.',
    'Use modular architecture for large projects (100+ models), grouping related logic.',
    'Keep Request classes in the same directory as Controllers.',
    'Use dependency injection or events for module communication.',

    'Eloquent:' => [
        'Use `Model::query()` for query building.',
        'Avoid mass assignment—explicitly set attributes.',
        'Document magic properties with PHPDoc.',
        'Use custom EloquentBuilder classes for complex queries.',
        'Favor invokable classes for reusable scopes.',
    ],

        'Factories:' => [
            'Keep factories in `tests/Factories`.',
            'Avoid `HasFactory` in models—load factories explicitly.',
            'Define meaningful default states and reusable states.',
        ],

            'Migrations:' => [
                'Always write `down()` methods for rollbacks.',
                'Use explicit table and column definitions for clarity.',
            ],

                'Controllers:' => [
                    'Prefer single-action controllers.',
                    'Avoid extending base controllers unless necessary.',
                    'Use singular resource names (e.g., `UserController` for one resource).',
                    'Inject dependencies in handler methods, not constructors.',
                ],

                    'Validation:' => [
                        'Use array notation for rules (`[\'field\' => [\'required\', \'string\']]`).',
                        'Prefer class-based custom rules for complex validation.',
                        'Extract reusable validation logic into dedicated rule classes.',
                    ],

                        'Routing:' => [
                            'Use kebab-case for URLs and route segments.',
                            'Use CamelCase for route parameter names and route name definitions.',
                            'Avoid `Route::resource`; define routes explicitly.',
                            'Always name routes for clarity and maintenance.',
                        ],

                            'API Design:' => [
                                'Use versioning (e.g., `/api/v1`).',
                                'Use plural nouns for endpoints.',
                                'Use query parameters for filtering, sorting, pagination.',
                                'Use Laravel API Resources for consistent JSON responses.',
                            ],

                                'Artisan Commands:' => [
                                    'Use kebab-case for command names.',
                                    'Leverage verbosity levels for debug information.',
                                    'Exit with appropriate codes for error conditions.',
                                ],

                                    'Blade Templates:' => [
                                        'Use camelCase for view files and directories.',
                                        'Pass variables explicitly to partials.',
                                        'Use `<?php ?>` tags for logic, avoid Blade directives for complex logic.',
                                        'Use `__()` for translations.',
                                    ],

                                        'Jobs:' => [
                                            'Ensure jobs are idempotent and can be retried.',
                                            'Use `dispatch()` helper for job invocation.',
                                        ],

                                            'Security:' => [
                                                'Avoid raw queries—use Query Builder or Eloquent.',
                                                'Sanitize user input, especially in dynamic queries.',
                                                'Validate and sanitize all user-generated content.',
                                                'Use HTML Purifier for rich text inputs.',
                                            ],

                                                'Asset Management:' => [
                                                    'Use `@vite` directive for JS/CSS assets.',
                                                    'Use `Vite::asset()` helper for non-JS/CSS assets.',
                                                ],

                                                    'Logging & Monitoring:' => [
                                                        'Use structured logging with context and severity levels.',
                                                        'Monitor critical errors with tools like Sentry.',
                                                        'Use verbose output in Artisan commands for debugging.',
                                                    ],
];

// =========================================
// 4. TAILWIND CSS CONVENTIONS
// =========================================
// - Follow a utility-first approach using Tailwind classes.
// - Keep class lists in templates readable and well-formatted.
// - Group related utility classes (e.g., spacing, typography) together for readability.
// - Leverage `@apply` in component-specific style blocks for repetitive patterns.
// - Consistently use Tailwind’s configuration for theme colors, spacing, and typography.
// - Use `dark:` variants and CSS variables to ensure theming and accessibility.
// - Avoid excessive custom CSS; rely on Tailwind’s utility classes for most styling needs.

// =========================================
// 5. INERTIA & FRONTEND INTEGRATION
// =========================================
// - Use Inertia to bridge Laravel back-end and Vue front-end without building a separate API layer.
// - Keep Inertia page components in `resources/js/Pages/`.
// - Pass server-side data to pages using Inertia’s `->render()` or `Inertia::render()` methods.
// - Minimize the logic in Blade templates; Blade should primarily initialize the Inertia page.
// - Leverage Inertia’s shared props for global data (e.g., auth user), but keep it minimal.
// - Implement pagination, sorting, and filtering logic on the server, passing results through Inertia.
// - Follow the same Vue coding standards for pages as for components.
// - Ensure that transitions and navigation states are handled gracefully (e.g., loading states).

// =========================================
// 6. PROJECT STRUCTURE
// =========================================
//
// project-root/
// ├── app/                # Core application logic (Controllers, Middleware, Models, Providers)
// │   ├── Http/
// │   ├── Models/
// │   └── Providers/
// │
// ├── config/             # Configuration files
// ├── database/           # Migrations, factories, seeds
// ├── public/             # Public entry point, compiled assets
// ├── resources/          # Views, assets, Vue components, Inertia pages
// │   ├── css/            # CSS files
// │   ├── js/             # JavaScript files
// │   │   ├── Components/ # Vue components
// │   │   │    └── shadcn/  # shadcn/ui components
// │   │   ├── Layouts/    # Vue layouts
// │   │   ├── Pages/      # Inertia pages (Vue 3)
// │   │   └── Partials/   # Vue partials
// │   └── views/          # Blade templates (minimal logic)
// ├── routes/             # Application routes
// ├── storage/            # Logs, cached data
// └── tests/              # Automated tests

// - Keep related features together (e.g., feature-based directories in `app` and `resources/js`).
// - Avoid sprawling directory structures—group related logic and refactor as necessary.

// =========================================
// 7. TESTING & QUALITY ASSURANCE
// =========================================
// - Use Pest for PHP testing.
// - Use Laravel’s testing utilities for feature and integration tests.
// - Write unit tests for reusable Vue components with vue-test-utils and Jest or Vitest.
// - Ensure 100% coverage for critical logic; aim for high coverage overall.
// - Lint and format code automatically using tools like ESLint (JS) and PHP-CS-Fixer/Prettier.

// =========================================
// 8. PERFORMANCE & OPTIMIZATION
// =========================================
// - Optimize database queries (indexing, eager loading).
// - Use caching (Laravel cache, Vue keep-alive) where appropriate.
// - Implement lazy-loading and code-splitting for Vue components.
// - Use pagination, filtering, and sorting on the server-side to avoid loading large datasets.
// - Monitor performance with Laravel Telescope or similar tools.

// =========================================
// 9. SECURITY & ACCESSIBILITY
// =========================================
// - Always validate and sanitize user input.
// - Implement CSRF protection, HTTPS, and secure session handling.
// - Follow best practices for authentication and authorization (e.g., Laravel Policies, Guards).
// - Ensure compliance with accessibility standards: semantic HTML, ARIA attributes, and proper focus states.

// =========================================
// 10. DOCUMENTATION & COMMENTS
// =========================================
// - Keep code self-documenting where possible.
// - Add docblocks for complex methods, properties, and classes.
// - Document component props, events, and slots in Vue components.
// - Maintain a README with setup instructions, coding standards, and key architectural decisions.
// - Use inline comments sparingly and only for non-obvious logic.

// =========================================
// 11. ADDITIONAL TOOLING & WORKFLOW
// =========================================
// - Use Git hooks (pre-commit, pre-push) to run linting and tests before merging changes.
// - Employ CI/CD pipelines for automated testing, building, and deployments.
// - Maintain `.env.example` with all required environment variables.
// - Keep secrets out of version control (use environment variables or secret managers).
// - Regularly update dependencies and frameworks while adhering to these conventions.