Constructs.sh

Next.js + Supabase + shadcn

by curator

Full-stack development with Next.js App Router, Supabase, shadcn/ui, and Tailwind. PWA patterns included.

Key Principles

  • Code Quality & Style

    • Write concise, maintainable, and strongly typed code with accurate TypeScript implementations.
    • Embrace functional, declarative programming. Avoid OOP and classes.
    • Limit files to a maximum of 150 lines; refactor into smaller modules if exceeded.
    • Prefer iteration and modularization over duplication.
    • Use descriptive, semantic variable names with auxiliary verbs (e.g., isLoading, hasError).
    • Use lowercase with dashes for directories and files (e.g., components/auth-wizard).
    • Favor named exports for components.
    • Adopt RORO (Receive an Object, Return an Object) for function parameters/returns.
    • Always attain to use DRY (Don't Repeat Yourself) principles.
    • Conduct regular code reviews and frequent refactoring sessions to ensure consistency and quality.
    • Check and improve Web Vitals (LCP, CLS, FID) to maintain performance and user experience.

  • Create 'Build Notes':

    • You must create a 'Build Notes' file for each task group to track the progress of the task group we work on.
    • Clarity & Brevity: Keep notes concise, direct, and focused on the task at hand.
    • Logical Naming: Use a consistent naming convention that ties each notes file to a specific task and date.
    • Incremental Updates: Update notes as plans evolve or tasks are completed. Append rather than overwrite.
    • Traceability: Ensure that each decision or change in approach is recorded and easy to follow.

  • Review 'Project Contexts':

    • You must review the projectContext.md as we need to ensure that the project context is up to date and accurate.
    • Stability: Treat context files as stable references, not daily scratchpads.
    • Selective Updates: Update context files only when there are significant, approved changes to requirements or project scope.
    • Accessibility: Make context files easily understandable and organized so future developers can quickly grasp the project’s core guidance.

  • Stack and Framework Conventions

    • Target Next.js 15+ and leverage the App Router, React Server Components (RSC), and SSR capabilities.
    • Use Zustand for state management in client components when necessary.
    • Maintain proper Shadcn UI management using npx shadcn@latest add for new components.
    • Follow a mobile-first approach and responsive design patterns.
    • Emphasize server-side logic, minimizing the usage of use client and other client-only APIs.
    • Structure project as Progressive Web App (PWA) with offline capabilities, app-like experience, and installability across devices.

  • Monorepo & Tooling

    • If using a monorepo structure, place shared code in a packages/ directory and app-specific code in app/.
    • Use Taskfile.yml commands for development, testing, and deployment tasks.
    • Keep environment variables and sensitive data outside of code and access them through .env files or similar configuration.

Below is a structured guideline to provide to the AI development agent, incorporating key principles and detailed rules for maintaining the /ProjectDocs/Build_Notes/ and /ProjectDocs/contexts/ directories.

Rules for Build Notes Files

  1. Location & Naming:

    • Store all notes files in /ProjectDocs/Build_Notes/.
    • Use a logical, descriptive naming convention, e.g., build-title_phase-#_task-group-name.md.
    • Use the <build-title> to describe the build task.
    • Use the <phase-#> to apply the Phase # to the build task.
    • Use the <task-group-name> to describe the task group name.
    • Example: supabase-schema-standardization_phase-1_preparation-and-code-analysis.md
      • supabase-schema-standardization is the build title
      • phase-1 is the phase number
      • preparation-and-code-analysis is the task group name

  2. Content Structure:

    • Begin with a brief Task Objective that summarizes what you aim to achieve.
    • Provide Current State Assessment: a short description of the current state of the project pertaining to the build tasks.
    • Provide Future State Goal: a short description of the future state of the project pertaining to the build tasks.
    • Follow with a Implementation Plan: a numbered list of steps containing checklist tasks to achieve the future state.
    • Update the Implementation Plan as tasks are completed and line out not applicable tasks. NEVER DELETE TASKS FROM THE PLAN.
    • If the plan changes or evolves, add new steps or tasks, rather than overwriting previous content.

  3. When to Update:

    • At Task Start: Create or open the task-specific notes file and record the initial plan before coding.
    • During Task Execution: Add updates when plans change, difficulties arise, or new insights emerge.
    • At Task Completion: Append a summary of what was done and verify it aligns with the original objective.

  4. Style & Tone:

    • Keep notes succinct, on-topic, and free of unrelated commentary.
    • Maintain a logical sequence so that future readers can understand the decision-making process without confusion.

  5. Completion of Build Notes:

    • Once the build notes are complete, move the file to the /ProjectDocs/Build_Notes/completed/ directory.
    • If build notes are deprecated and no longer needed, move the file to the /ProjectDocs/Build_Notes/archived/ directory.

Rules for Context Files

  1. Master Project Context (projectContext.md):

    • Located in /ProjectDocs/contexts/.
    • Provides the overarching project scope, requirements, and design principles.
    • Only update this file if there are major changes to the project’s fundamental direction or scope.

  2. Additional Context Files:

    • Supplementary files (e.g., uiContext.md, featureAContext.md) may be created for more detailed specifications on certain functionalities, designs, or areas of the application.
    • Keep these files stable. Update them only when new, approved changes need to be documented.
    • Reference these files frequently to ensure development aligns with established guidelines.

  3. Change Management:

    • Record any changes to context files within the corresponding build notes file for that task.
    • Maintain a clear rationale for context changes to preserve transparency and alignment with the core project goals.

Project Structure

Adopt a clear, modular directory structure: