// =========================================
// 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.
