DOCSEARCHbyAlgolia
Submit Docs

AutoTMS NextJS Coding Convention

website·Indexed 29 days ago

https://tms-convention.vercel.app/

Coding conventions and checklists for the AutoTMS team, focusing on Next.js App Router, TypeScript, React, and styling. Covers architecture layers, Prisma client singleton patterns, SWR custom hooks, Jotai state management, and UI standards including responsive design and test-addressable UI.

Tokens
18.2K
Snippets
121
Records
157
Agent score
74%

What's inside AutoTMS Coding Convention

  1. Overview of NextJS Coding Convention for AutoTMS

    The NextJS Coding Convention serves as a comprehensive guide and checklist for the AutoTMS team to ensure code consistency and quality. Its primary objectives are to:

    • Standardize code style for improved readability, reviewability, and maintainability.
    • Implement best practices across Next.js, React, TypeScript, Strapi/Prisma, and styling.
    • Provide a pre-completion checklist covering business logic, Server Actions, UI, and Git.
    • Accelerate the onboarding process for new team members.

  3. General UI and Styling Conventions for TMS Convention

    The project follows specific UI coding standards to maintain consistency and performance:

    • Avoid using inline styles within components.
    • Avoid defining inline functions inside components.
    • Adhere to Master Screen rules for list views (including search, URL search, table alignment, required inputs, and flashing prevention).
    • Implement Responsive design and Internationalization (i18n) using translation files (e.g., vi.json) and standardized navigation.

  4. Apply Service Layer architecture to Server Actions

    Server Actions act as the entry point layer and must not call Prisma directly (except for prisma.$transaction). All database access logic must reside in the Service layer (/src/services).

    The responsibilities of an Action are:

    1. Receive input.
    2. Perform preliminary validation.
    3. Call one or more Services (or open a transaction).
    4. Return a standardized response format.

  5. Implement Frontend Testable UI Core Principles

    To ensure frontend code is test-addressable, deterministic, and automation-friendly, developers must adhere to these core principles:

    • Use stable selectors (do not depend on CSS or layout).
    • Ensure predictable rendering and clear UI state.
    • Build test hooks directly into components.
    • Avoid flaky asynchronous behavior.
    • Prioritize an accessibility-first structure.

  6. Implement the Next.js App Router architectural layer pattern

    To ensure maintainability and testability, follow a one-way data flow: UI → Actions → Services → Prisma/DB. The architecture is divided into specific layers with strict dependency rules to prevent circular dependencies and logic leakage.
    [UI / Route] → [Actions] → [Services] → [Prisma / DB]
                    ↓
                [Lib] (helper, handler, auth...)

  7. Synchronize Strapi and Prisma schemas

    When using Strapi (CMS) with Prisma, the schemas must align with business requirements. Ensure that all fields, types, relationship directions, and cardinality are consistent across both. Fields marked as required in Strapi must be defined as non-null in Prisma, while optional fields in Strapi should use the optional operator (?) in Prisma.

  8. Handle default parameters and avoid mutating arguments

    Use default parameters instead of mutating parameters inside the function body. Place default parameters at the end of the parameter list and ensure they do not cause side effects. Avoid reassigning or mutating input parameters; instead, create new variables or return new objects.
    type RequestOptions = { timeout?: number };

// Correct: Default parameter at the end, no mutation
function handleThings(name: string, opts: RequestOptions = {}): void {
  const timeout = opts.timeout ?? 1000;
}

// Correct: Avoid mutating object properties
function f1(obj: { key: number }): void {
  const newKey = obj.key !== undefined ? obj.key : 1;
  // Use newKey instead of modifying obj.key
}

  10. Enforce authorization in Server Actions and APIs

    Hiding a button in the UI is not sufficient for security. Always verify authentication, organization, and user roles within the Server Action or API layer before executing any operation to prevent unauthorized direct calls.

  11. Use valid ARIA roles and avoid accessKey

    Only use valid, standard ARIA roles. Avoid abstract roles (e.g., role="range") or non-standard roles (e.g., role="datepicker"). Additionally, do not use the accessKey attribute on elements as it often conflicts with screen reader and keyboard shortcuts.
    // ✅ Good
<div role="button" />

  12. Synchronize list filters with URL query parameters

    Master list screens must support searching and filtering via URL query parameters (e.g., ?q=keyword&status=active). This ensures that filters are preserved when a user refreshes the page or shares a link. Implementation should involve reading searchParams from the page to initialize the filter/search state and updating the URL (via shallow or push) whenever a filter changes.
    // Example logic: 
// 1. Read searchParams on mount to set initial state
// 2. Update URL when filter state changes
const { searchParams } = useSearchParams();
const initialQuery = searchParams.get('q');