# Nextjs Enterprise Init

> Initialize and structure Next.js projects for enterprise-scale development. Use when setting up a new Next.js project or restructuring an existing one to follow enterprise conventions. Creates feature-first architecture with proper separation of concerns, establishes coding standards, sets up extensibility for theming and i18n, and generates project documentation (CLAUDE.md).

- Skill: `azure12355/nextjs-enterprise-init` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add azure12355/nextjs-enterprise-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azure12355/nextjs-enterprise-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: azure12355 (https://skillmd.com/u/azure12355)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/azure12355/nextjs-enterprise-init

---


# Next.js Enterprise Project Initialization

Initialize Next.js projects with enterprise-grade architecture and conventions.

## Quick Start

To initialize a Next.js project with enterprise structure:

```bash
python3 scripts/init_nextjs_structure.py /path/to/project
```

The script will:
1. Create `src/common/` with utilities, components, hooks, services
2. Create `src/features/` with example feature module
3. Set up proper TypeScript path aliases
4. Create global styles with CSS variables for theming
5. Generate example API routes

## Architecture Overview

This skill implements a **feature-first architecture** with clear separation of concerns:

```
src/
├── app/                    # Next.js App Router (routes, layouts, pages)
├── features/               # Feature-based modules (business logic)
├── common/                 # Shared utilities and components
└── styles/                 # Global styles
```

**Key Principles:**
- **Feature-first**: Organize by business domain, not technical layers
- **Separation of concerns**: UI, logic, and data fetching are separate
- **Dependency direction**: `app/` → `features/` → `common/` (one-way)
- **Atomic components**: Build complex UIs from simple, reusable parts

## Directory Structure

For complete directory structure details, see [structure.md](references/structure.md).

### Key Directories

| Directory | Purpose |
|-----------|---------|
| `app/` | Next.js App Router - routes, layouts, pages, API routes |
| `features/` | Feature modules - self-contained business logic |
| `common/components/ui/` | Atomic UI components (Button, Input, etc.) |
| `common/hooks/` | Shared React hooks |
| `common/services/` | API services and data fetching |
| `common/utils/` | Pure utility functions |
| `common/config/` | Configuration (theme, i18n) |

## Component Conventions

### Atomic Component Pattern

Each component lives in its own directory:

```
ComponentName/
├── ComponentName.tsx       # Main component
├── ComponentName.module.css # Styles
├── ComponentName.test.tsx  # Tests
└── index.ts                # Exports
```

**Size Guidelines:**
- Atomic: ≤150 lines (Button, Input)
- Composite: 150-300 lines (composed of atomics)
- Complex: >300 lines (split into sub-components)

### Component Declaration

Always use function components with explicit types:

```tsx
import { ButtonProps } from './Button.types';
import styles from './Button.module.css';

export function Button({ variant = 'primary', children, ...props }: ButtonProps) {
  return (
    <button className={`${styles.button} ${styles[variant]}`} {...props}>
      {children}
    </button>
  );
}
```

## Hooks Conventions

### Custom Hook Pattern

```typescript
// useUserProfile.ts
export function useUserProfile(userId: string) {
  const [state, setState] = useState<AsyncState<User>>({ status: 'idle' });

  // ... implementation

  return {
    user: state.status === 'success' ? state.data : null,
    loading: state.status === 'loading',
    error: state.status === 'error' ? state.error : null,
    refetch,
  };
}
```

**Rules:**
- Prefix with `use`
- Return stable object (use useMemo if needed)
- Handle cleanup in useEffect
- Specify all dependencies

## API & Services

### API Client Pattern

Use the base `apiClient` from `common/services/apiClient.ts`:

```typescript
import { apiClient } from '@/common/services/apiClient';

export const userApi = {
  async getById(id: string): Promise<User> {
    return apiClient.get<User>(`/users/${id}`);
  },

  async update(id: string, data: UserUpdateData): Promise<User> {
    return apiClient.put<User>(`/users/${id}`, data);
  },
};
```

### State Management Strategy

| State Type | Solution | Example |
|------------|----------|---------|
| Server State | React Query | User data, API responses |
| URL State | URL params/search | ?page=2&filter=active |
| Form State | Component state | Input values, validation |
| Global UI | Context | Theme, language, auth status |

## Styling Conventions

### CSS Modules (Preferred)

```tsx
import styles from './Button.module.css';

export function Button({ variant = 'primary' }: ButtonProps) {
  return <button className={`${styles.button} ${styles[variant]}`}>...</button>;
}
```

### Theming with CSS Variables

```css
:root {
  --color-primary: #0070f3;
  --spacing-md: 1rem;
  --radius-md: 8px;
}

[data-theme='dark'] {
  --color-primary: #3291ff;
}
```

For detailed styling patterns, see [conventions.md](references/conventions.md).

## Feature Module Structure

Each feature is self-contained:

```
features/feature-name/
├── components/             # Feature-specific components
├── hooks/                  # Feature-specific hooks
├── services/               # Feature-specific API calls
├── types/                  # Feature-specific types
└── index.ts                # Public API exports
```

**Feature conventions:**
- Export only public API via `index.ts`
- Keep feature-specific code within the feature
- Use barrel exports for clean imports

## Import Conventions

Order imports consistently:

```tsx
// 1. React and Next.js
import { useState } from 'react';
import Link from 'next/link';

// 2. Third-party libraries
import { clsx } from 'clsx';

// 3. Internal imports - features
import { UserProfile } from '@/features/user-profile';

// 4. Internal imports - common
import { Button } from '@/common/components/ui/Button';
import { useDebounce } from '@/common/hooks/useDebounce';
```

## File Naming Conventions

- **Components**: PascalCase (UserProfile.tsx)
- **Hooks**: camelCase with 'use' prefix (useUserProfile.ts)
- **Utilities**: camelCase (formatDate.ts)
- **Types**: *.types.ts suffix (user.types.ts)
- **Tests**: *.test.tsx or *.spec.tsx

## Theming Extensibility

The theme system supports extension:

```typescript
import { extendTheme, lightTheme } from '@/common/config/theme';

const customTheme = extendTheme(lightTheme, {
  colors: {
    primary: '#custom-color',
  },
});
```

Theme config is in `common/config/theme.ts` - see [architecture.md](references/architecture.md) for details.

## i18n Extensibility

Add new locales by:
1. Adding locale to `i18nConfig.locales` in `common/config/i18n.ts`
2. Creating translation file in `common/locales/{locale}.json`

No code changes required for new locales.

## Error Handling

### Async Error Handling Pattern

```tsx
export function UserProfile() {
  const [state, setState] = useState<AsyncState<User>>({ status: 'idle' });

  useEffect(() => {
    const fetchUser = async () => {
      setState({ status: 'loading' });
      try {
        const user = await userApi.getById(userId);
        setState({ status: 'success', data: user });
      } catch (error) {
        setState({
          status: 'error',
          error: error instanceof Error ? error : new Error('Unknown error'),
        });
      }
    };
    fetchUser();
  }, [userId]);

  if (state.status === 'error') {
    return <ErrorMessage error={state.error} />;
  }
  // ...
}
```

## Testing Conventions

### Test Structure

```tsx
import { render, screen } from '@testing-library/react';
import { describe, it, expect, vi } from 'vitest';
import { Button } from './Button';

describe('Button', () => {
  it('renders children correctly', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });
});
```

## Security Considerations

1. **Never expose secrets** - Use environment variables
2. **Validate user input** - Client and server-side
3. **Sanitize user-generated content** - Use DOMPurify for HTML
4. **Implement rate limiting** - For API routes
5. **Use CSRF protection** - For form submissions

## CLAUDE.md

Generate `CLAUDE.md` in project root using the template from `assets/CLAUDE.md.template`.

The CLAUDE.md should contain:
- Project overview
- Architecture summary
- Development guidelines
- Project-specific rules
- Common tasks

## Using the Initialization Script

The script handles the complete setup:

```bash
# Run from project root
python3 scripts/init_nextjs_structure.py

# Or specify project path
python3 scripts/init_nextjs_structure.py /path/to/nextjs/project
```

**What it creates:**
- `src/common/` with full subdirectory structure
- `src/features/` with example feature
- `src/app/api/` with example API route
- Global CSS with theme variables
- Updated `tsconfig.json` with path aliases

## Additional References

- [structure.md](references/structure.md) - Complete directory structure
- [conventions.md](references/conventions.md) - Detailed coding standards
- [architecture.md](references/architecture.md) - Architecture principles and patterns

Load these files when you need detailed information about specific aspects of the project structure.