Enterprise Web Code

Enterprise Web Development

Build bulletproof, enterprise-ready web applications that embody Kaizen (continuous improvement) and Monozukuri (meticulous craftsmanship) principles. This skill guides development of clean, efficient, performant Next.js 16 and React code that is simple, elegant, and built to last.

Core Philosophy

Kaizen (改善): Continuous improvement through incremental refinement Monozukuri (ものづくり): The art of making things with meticulous attention to quality and craftsmanship

These principles translate to web code that is:

• Clean: Self-documenting, readable, and maintainable
• Efficient: Optimized bundles and minimal runtime overhead
• Fast: Performance-first architecture with sub-second load times
• Simple: Complexity only where justified
• Elegant: Beautiful solutions that feel inevitable

Web Development Workflow

1. Understand Requirements Deeply

Before writing code:

• Clarify user experience and functionality goals
• Identify edge cases and error scenarios
• Consider responsive design and accessibility (WCAG 2.1)
• Understand performance budgets and SEO requirements
• Plan for internationalization if needed

2. Design Before Implementation

Plan the architecture:

• Choose appropriate Next.js rendering strategy (SSR, SSG, ISR, CSR)
• Design component hierarchy and data flow
• Plan API routes and data fetching patterns
• Consider state management needs (Server Components, Context, Zustand)
• Plan for type safety with TypeScript

3. Write Code with Craftsmanship

Simplicity First

• Prefer Server Components over Client Components
• Use native Web APIs when possible
• Avoid premature abstraction
• Keep components focused and composable
• YAGNI (You Aren't Gonna Need It)

Clean Code Standards

• Meaningful, descriptive names (components, functions, variables)
• Components should have single responsibility
• Keep components under 200 lines
• Extract complex logic into custom hooks
• Use early returns to reduce nesting
• Comments explain WHY, not WHAT

TypeScript Best Practices

• Use strict mode ("strict": true)
• Avoid any - use unknown or proper types
• Define interfaces for component props
• Use type inference where obvious
• Leverage discriminated unions for state
• Use Zod for runtime validation

Error Handling

• Use Error Boundaries for React errors
• Implement proper error pages (error.tsx, not-found.tsx)
• Validate user inputs on client AND server
• Provide actionable error messages
• Log errors with proper context
• Handle loading and error states

Security Mindset

• Sanitize user inputs (prevent XSS)
• Use CSRF tokens for mutations
• Implement proper authentication (NextAuth.js)
• Validate all API inputs with Zod
• Use environment variables for secrets
• Set proper security headers
• Implement rate limiting

4. Optimize for Web Performance

Next.js 16 Optimization

• Use Server Components by default
• Implement streaming with Suspense
• Optimize images with next/image
• Use dynamic imports for code splitting
• Implement Partial Prerendering (PPR)
• Leverage Turbopack for fast builds

React Performance

• Minimize client-side JavaScript
• Use React.memo for expensive components
• Implement virtual scrolling for long lists
• Debounce/throttle event handlers
• Avoid inline function definitions in JSX
• Use useCallback and useMemo judiciously

Bundle Optimization

• Tree-shake unused code
• Use dynamic imports for large dependencies
• Analyze bundle with @next/bundle-analyzer
• Remove unused dependencies
• Use barrel exports carefully (they prevent tree-shaking)

Asset Optimization

• Optimize images (WebP, AVIF formats)
• Lazy load images below the fold
• Use SVG for icons
• Implement font optimization (next/font)
• Minimize CSS with CSS modules or Tailwind

Caching Strategy

• Configure proper Cache-Control headers
• Use Next.js caching (fetch cache, unstable_cache)
• Implement stale-while-revalidate
• Use CDN for static assets
• Consider Redis for server-side caching

5. Ensure Robustness

Comprehensive Testing

• Unit tests for utility functions (Vitest)
• Component tests with React Testing Library
• E2E tests for critical flows (Playwright)
• Visual regression tests (Percy/Chromatic)
• API route tests

Accessibility (A11y)

• Semantic HTML elements
• ARIA labels where needed
• Keyboard navigation support
• Screen reader testing
• Color contrast compliance (WCAG AA)
• Focus management

Progressive Enhancement

• Core functionality works without JS
• Graceful degradation
• Loading states for all async operations
• Optimistic UI updates
• Error recovery strategies

Monitoring and Observability

• Implement error tracking (Sentry)
• Add performance monitoring (Vercel Analytics)
• Log important user actions
• Track Core Web Vitals
• Set up alerts for errors and performance

6. Refine Through Kaizen

Continuously improve:

• Review and refactor components
• Eliminate duplicate code
• Improve component composition
• Update dependencies regularly
• Address technical debt incrementally
• Monitor performance metrics

Code Quality Standards

File and Folder Structure

app/
├── (auth)/                 # Route groups
│   ├── login/
│   └── register/
├── (marketing)/
│   ├── page.tsx
│   └── layout.tsx
├── api/                    # API routes
│   └── users/
│       └── route.ts
├── dashboard/
│   ├── page.tsx
│   ├── loading.tsx
│   └── error.tsx
├── layout.tsx              # Root layout
└── globals.css

components/
├── ui/                     # Reusable UI components
│   ├── button.tsx
│   ├── card.tsx
│   └── input.tsx
└── features/               # Feature-specific components
    ├── auth/
    └── dashboard/

lib/
├── db.ts                   # Database client
├── auth.ts                 # Auth utilities
├── utils.ts                # Helper functions
└── validations.ts          # Zod schemas

hooks/                      # Custom React hooks
├── use-user.ts
└── use-debounce.ts

types/                      # TypeScript types
└── index.ts

Naming Conventions

Components: PascalCase (UserProfile.tsx, NavigationBar.tsx) Files: kebab-case for non-components (api-client.ts, use-auth.ts) Functions: camelCase (fetchUser, calculateTotal, handleSubmit) Constants: UPPER_SNAKE_CASE (API_URL, MAX_RETRIES) Types/Interfaces: PascalCase (User, ApiResponse, ButtonProps) Props interfaces: ComponentNameProps (ButtonProps, CardProps)

Component Patterns

// GOOD: Server Component (default)
export default async function UserProfile({ userId }: { userId: string }) {
  const user = await db.user.findUnique({ where: { id: userId } });
  
  return (
    <div>
      <h1>{user.name}</h1>
      <UserPosts userId={userId} />
    </div>
  );
}

// GOOD: Client Component (when needed)
'use client';

import { useState } from 'react';

interface CounterProps {
  initialCount?: number;
}

export function Counter({ initialCount = 0 }: CounterProps) {
  const [count, setCount] = useState(initialCount);
  
  return (
    <button => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

// GOOD: Async Server Component with Suspense
export default function Page() {
  return (
    <Suspense fallback={<UserSkeleton />}>
      <UserProfile userId="123" />
    </Suspense>
  );
}

TypeScript Patterns

// Define prop types
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'danger';
  isLoading?: boolean;
  children: React.ReactNode;
}

// Use discriminated unions for state
type FetchState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: string };

// Zod for validation
import { z } from 'zod';

const userSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  age: z.number().min(18).max(120),
});

type User = z.infer<typeof userSchema>;

Advanced Patterns

For complex scenarios, consult:

• references/nextjs-patterns.md: Next.js 16 specific patterns and best practices
• references/react-performance.md: React optimization techniques
• references/web-security.md: Comprehensive web security guide
• references/typescript-patterns.md: Advanced TypeScript patterns

Next.js 16 Best Practices

Server Components (Default)

• Use for data fetching
• Reduce client-side JavaScript
• Direct database access
• Better SEO

Client Components ('use client')

Only use when you need:

• Interactivity (onClick, onChange)
• State (useState, useReducer)
• Effects (useEffect)
• Browser APIs
• Event listeners

Data Fetching

// Server Component - fetch in component
async function Users() {
  const users = await fetch('https://api.example.com/users', {
    next: { revalidate: 3600 } // ISR: revalidate every hour
  });
  
  return <UserList users={users} />;
}

// Server Actions - mutations
'use server';

export async function createUser(formData: FormData) {
  const data = userSchema.parse({
    name: formData.get('name'),
    email: formData.get('email'),
  });
  
  await db.user.create({ data });
  revalidatePath('/users');
}

Streaming and Suspense

export default function Page() {
  return (
    <>
      <Header />
      <Suspense fallback={<PostsSkeleton />}>
        <Posts />
      </Suspense>
      <Suspense fallback={<CommentsSkeleton />}>
        <Comments />
      </Suspense>
    </>
  );
}

Review Checklist

Before finalizing code:

• TypeScript strict mode enabled, no any types
• Components are Server Components unless interactivity needed
• Proper loading and error states
• Images use next/image with proper sizing
• Fonts optimized with next/font
• Forms validated on client and server
• API routes protected and validated
• Security headers configured
• Accessibility tested (keyboard, screen reader)
• Performance tested (Lighthouse score >90)
• SEO metadata complete
• Error boundaries implemented
• No console.log in production code
• Tests cover critical functionality

When to Use This Skill

Apply this skill whenever:

• Building Next.js applications
• Creating React components
• Writing API routes
• Optimizing web performance
• Implementing authentication
• Setting up TypeScript projects
• User requests enterprise-grade web code
• User mentions Next.js, React, or web development

This skill transforms good web code into exceptional web applications—fast, secure, accessible, and delightful to use.