---
title: "Code Style"
description: "Code Style documentation for Ring Platform"
locale: "en"
---
# Code Style Guide

TypeScript, React, and Next.js conventions for Ring Platform development.

## 📚 Documentation code blocks (MDX)

Ring docs use **one server-side Shiki pass** — no client re-highlighting.

| Authoring | Pipeline |
|-----------|----------|
| Fenced ` ```lang ` blocks | `rehypeCodeFenceToMdx` → async `` → `highlightCodeToHtml` |
| JSX `{\`…\`}` | Same server path; wrap body in `{\`…\`}` when it contains `{` braces |
| Inline `` `code` `` | `` (no Shiki) |

Themes: **nord** (light) + **tokyo-night** (dark). Copy UI is client-only (`CodeBlockShell`).

Do **not** use raw `` for examples — use fences or ``. Legacy `EnhanceSyntax` / `EnhanceCodeBlocks` / `@shikijs/rehype` were removed in v1.6.2.

## 📝 TypeScript Best Practices

### Type Definitions
// Use interfaces for object shapes

{`interface Entity {
  id: string
  name: string
  type: EntityType
  createdAt: Date
}

// Use type aliases for unions and primitives
type EntityType = 'technology' | 'healthcare' | 'finance'
type Status = 'active' | 'inactive'`}

### Strict Type Safety
// Enable strict mode in tsconfig.json

{`{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  }
}`}

## ⚛️ React Component Patterns

### Component Structure
// components/EntityCard.tsx

{`import { type FC } from 'react'

interface EntityCardProps {
  entity: Entity
  onEdit?: (id: string) => void
  className?: string
}

export const EntityCard: FC = ({ 
  entity, 
  onEdit, 
  className = '' 
}) => {
  return (
    
      {entity.name}
      {entity.type}
      {onEdit && (
         onEdit(entity.id)}>
          Edit
        
      )}
    
  )
}`}

### Custom Hooks
// hooks/useEntity.ts

{`import { useState, useEffect } from 'react'

export function useEntity(id: string) {
  const [entity, setEntity] = useState(null)
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)

  useEffect(() => {
    fetchEntity(id)
      .then(setEntity)
      .catch(err => setError(err.message))
      .finally(() => setLoading(false))
  }, [id])

  return { entity, loading, error }
}`}

## 🔥 Next.js Patterns

### Server Components
// app/[locale]/(protected)/entities/page.tsx

{`import { auth } from '@/auth'
import { getEntities } from '@/lib/entities'

export default async function EntitiesPage() {
  const session = await auth()
  
  if (!session) {
    redirect('/login')
  }

  const entities = await getEntities(session.user.id)

  return (
    
      Your Entities
      
    
  )
}`}

### Server Actions
// actions/create-entity.ts

{`'use server'

import { auth } from '@/auth'
import { redirect } from 'next/navigation'

export async function createEntity(formData: FormData) {
  const session = await auth()
  
  if (!session) {
    redirect('/login')
  }

  const name = formData.get('name') as string
  const type = formData.get('type') as EntityType

  // Validation
  if (!name || !type) {
    return { error: 'Name and type are required' }
  }

  try {
    const entity = await saveEntity({ name, type, userId: session.user.id })
    redirect(`/entities/${entity.id}`)
  } catch (error) {
    return { error: 'Failed to create entity' }
  }
}`}

## 🎨 Styling Guidelines

### Tailwind CSS Conventions
// Use consistent spacing scale

{`const spacing = {
  xs: 'p-2',    // 8px
  sm: 'p-4',    // 16px
  md: 'p-6',    // 24px
  lg: 'p-8',    // 32px
  xl: 'p-12'    // 48px
}

// Component with consistent styling
export const Card = ({ children, size = 'md' }) => (
  
    {children}
  
)`}

### CSS Custom Properties
/* globals.css */

{`:root {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  --color-success: #10b981;
  --color-error: #ef4444;
  --color-warning: #f59e0b;
}`}

## 🧹 Code Organization

### File Structure
```
src/
├── app/                    # Next.js App Router
├── components/            # Reusable UI components
├── lib/                   # Utility functions and configs
├── hooks/                 # Custom React hooks
├── types/                 # TypeScript type definitions
├── actions/               # Server actions
└── styles/                # Global styles
```

### Import Organization
// 1. React imports

{`import { useState, useEffect } from 'react'

// 2. Third-party imports
import { NextPage } from 'next'
import { toast } from 'sonner'

// 3. Internal imports (absolute paths)
import { Button } from '@/components/ui/Button'
import { useEntity } from '@/hooks/useEntity'
import { type Entity } from '@/types/entity'

// 4. Relative imports
import './EntityCard.css'`}

## 📋 ESLint Configuration

// .eslintrc.js

{`module.exports = {
  extends: [
    'next/core-web-vitals',
    '@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    '@typescript-eslint/no-unused-vars': 'error',
    '@typescript-eslint/prefer-const': 'error',
    'react-hooks/exhaustive-deps': 'warn',
    'prefer-const': 'error',
    'no-var': 'error'
  }
}`}

---

Complete code style documentation is being expanded.