code-style

oaknational's avatarfrom oaknational

Oak AI project TypeScript coding conventions including naming patterns (kebab-case files, PascalCase components, camelCase functions), component structure, error handling with cause, state management patterns, and tRPC implementation. Use when writing, reviewing, or refactoring code.

⭐29stars🔀3forks📁View on GitHub🕐Updated Dec 18, 2025
[Code Review]

When & Why to Use This Skill

This Claude skill acts as an automated guardian for the Oak AI project's TypeScript ecosystem, enforcing rigorous coding conventions and architectural standards. It streamlines the development lifecycle by providing real-time guidance on naming patterns (kebab-case, PascalCase, camelCase), modular component structures, and advanced error handling. By integrating specific patterns for tRPC, Zustand, and testing, it ensures high-quality, maintainable, and consistent code across the entire engineering team.

Use Cases

  • Automated Code Review: Analyze pull requests to ensure all new TypeScript code adheres to the project's specific naming conventions and modular architecture requirements.
  • Standardized Feature Scaffolding: Generate boilerplate for React components and tRPC routers that automatically include 'use client' directives and proper file organization.
  • Codebase Refactoring: Systematically update legacy code to implement modern error handling patterns using the 'cause' property and transition to functional, declarative programming styles.
  • Developer Onboarding: Serve as an interactive documentation tool for new engineers to quickly learn and apply the project's unique state management and testing patterns.
namecode-style
descriptionOak AI project TypeScript coding conventions including naming patterns (kebab-case files, PascalCase components, camelCase functions), component structure, error handling with cause, state management patterns, and tRPC implementation. Use when writing, reviewing, or refactoring code.

Code Style Guide

General Principles

  • TypeScript: Strict types with noUncheckedIndexedAccess. Prefer explicit return types.
  • Imports: Sorted: React → Third-party → Project → Relative
  • Formatting: 2-space indents, 80 char width, double quotes, trailing commas
  • Function style: Functional, declarative programming. Avoid classes.
  • Organization: Modular architecture with clear separation of concerns

Naming Conventions

  • Files/Directories: kebab-case (lowercase with dashes)
  • Components: PascalCase
  • Variables/Functions: camelCase
  • Types/Interfaces: PascalCase
  • Constants: UPPER_CASE for true constants, camelCase for config objects
  • Hooks: Always prefix with "use" (e.g., useAnalytics)

Component Structure

  • Component Pattern: Functional components with hooks
  • Client Components: Add "use client" directive at the top of file
  • File Organization:
    • Exported component first
    • Sub-components next
    • Helper functions
    • Type definitions at the end

State Management

  • Global State: Zustand stores organized by domain
  • Local State: React hooks (useState, useReducer)
  • Remote State: tRPC queries and mutations with TanStack Query

Error Handling

  • Promise Handling: Always await promises or use .catch() (enforced by no-floating-promises)
  • Error Patterns:
    • Early returns with guard clauses
    • Structured error types
    • User-friendly error messages
    • Proper logging
  • Error Cause: When rethrowing errors, use the cause option for better error context:
    throw new Error("High-level error message", { cause: originalError });

tRPC Implementation

  • Router Organization: By domain/feature
  • Procedure Types: Query for read, Mutation for write operations
  • Error Handling: Consistent error responses
  • Middleware: Authentication, rate limiting, etc.

Testing Patterns

  • Unit Tests: Jest for utilities and hooks
  • Component Tests: React Testing Library
  • E2E Tests: Playwright
  • Mocking: Mock external dependencies appropriately