generator-kodly-react-app 1.0.6 → 1.0.10

package/generators/app/templates/STRUCTURE.md

@@ -0,0 +1,661 @@
+# React App Template Structure Guide
+
+This document explains the directory structure and organization patterns used in this React application template. Understanding this structure will help you add new features, modules, and components in a consistent manner.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Root Level Files](#root-level-files)
+3. [Source Directory (`src/`)](#source-directory-src)
+4. [Module Structure](#module-structure)
+5. [Routes Structure](#routes-structure)
+6. [Components Organization](#components-organization)
+7. [Localization (i18n) Structure](#localization-i18n-structure)
+8. [Adding a New Module](#adding-a-new-module)
+9. [Naming Conventions](#naming-conventions)
+10. [File Patterns](#file-patterns)
+
+## Overview
+
+This React application follows a **feature-based modular architecture** where related functionality is grouped into self-contained modules. Each module contains its own components, layouts, hooks, contexts, and translations.
+
+```
+templates/
+├── src/                    # Source code
+│   ├── components/         # Shared/reusable components
+│   ├── lib/               # Utilities, API clients, shared logic
+│   ├── locales/           # Global translations
+│   ├── modules/           # Feature modules (feature-based organization)
+│   ├── routes/            # TanStack Router route files
+│   ├── sdk/               # Generated API client code
+│   └── types/             # TypeScript type definitions
+├── public/                # Static assets
+├── package.json           # Dependencies and scripts
+├── vite.config.js         # Vite configuration
+├── tailwind.config.js     # Tailwind CSS configuration
+└── tsconfig.json          # TypeScript configuration
+```
+
+## Root Level Files
+
+### Configuration Files
+
+- **`package.json`** - Dependencies, scripts, and project metadata
+- **`vite.config.js`** - Vite bundler configuration
+- **`tsconfig.json`** - TypeScript compiler configuration
+- **`tsconfig.app.json`** - Application-specific TypeScript config
+- **`tailwind.config.js`** - Tailwind CSS configuration
+- **`postcss.config.js`** - PostCSS configuration
+- **`openapi-ts.config.ts`** - OpenAPI TypeScript client generation config
+- **`components.json`** - shadcn/ui components configuration
+- **`.env.sandbox`** - Environment variables for sandbox mode
+
+### Template Files
+
+- **`index.html`** - HTML entry point
+- **`README.md`** - Project documentation
+- **`gitignore.template`** - Git ignore patterns (copied to `.gitignore`)
+
+## Source Directory (`src/`)
+
+### Core Application Files
+
+```
+src/
+├── main.tsx              # Application entry point
+├── app.tsx               # Root app component (wraps router with providers)
+├── router.tsx            # Router configuration
+├── routeTree.gen.ts      # Generated route tree (auto-generated)
+├── index.css             # Global styles
+├── vite-env.d.ts         # Vite type definitions
+├── openapi-client-config.ts  # OpenAPI client configuration
+└── types/
+    └── i18n.d.ts         # i18n TypeScript definitions
+```
+
+### Key Directories
+
+#### `src/components/` - Shared Components
+
+Reusable components used across multiple modules:
+
+```
+components/
+├── layout/               # Layout-related components
+│   ├── language-switcher.tsx
+│   └── theme-switcher.tsx
+├── theme/                # Theme provider components
+│   └── theme-provider.tsx
+└── ui/                   # shadcn/ui components (button, card, form, etc.)
+    ├── button.tsx
+    ├── card.tsx
+    ├── field.tsx
+    ├── form.tsx
+    ├── input.tsx
+    ├── label.tsx
+    ├── select.tsx
+    └── ...
+```
+
+**Usage Guidelines:**
+
+- Components in `components/ui/` are typically shadcn/ui components (reusable UI primitives)
+- Components in `components/layout/` are shared layout utilities
+- If a component is only used within one module, it should be in that module's `components/` directory
+
+#### `src/lib/` - Shared Libraries and Utilities
+
+Shared business logic, utilities, and API clients:
+
+```
+lib/
+├── api/
+│   └── client.ts         # API client configuration
+├── utils/
+│   ├── error-handler.ts  # Error handling utilities
+│   └── init-form-schema.ts  # Form schema initialization
+├── i18n.ts               # i18n configuration and utilities
+├── routes.ts             # Route constants (e.g., DEFAULT_LOGGED_IN_ROUTE)
+└── utils.ts              # General utility functions
+```
+
+#### `src/locales/` - Global Translations
+
+Global translations shared across all modules:
+
+```
+locales/
+├── index.ts              # Translation merging and export
+├── en/                   # English translations
+│   ├── common.json       # Common/shared strings
+│   └── theme.json        # Theme-related strings
+└── ja/                   # Japanese translations
+    ├── common.json
+    └── theme.json
+```
+
+#### `src/sdk/` - Generated API Client
+
+Auto-generated API client code (from OpenAPI specs):
+
+```
+sdk/
+├── client/               # Generated client code
+├── core/                 # Core SDK utilities
+├── schemas.gen.ts        # Generated schemas
+├── types.gen.ts          # Generated types
+└── ...
+```
+
+**Note:** This directory is typically generated and should not be manually edited.
+
+## Module Structure
+
+Modules are **feature-based** self-contained units of functionality. Each module represents a major feature or domain area.
+
+### Module Directory Structure
+
+```
+modules/
+└── {module-name}/        # e.g., auth, app, landing
+    ├── components/       # Module-specific components
+    ├── contexts/         # React contexts (if needed)
+    ├── hooks/            # Custom React hooks
+    ├── layouts/          # Layout components for this module
+    ├── locales/          # Module-specific translations
+    │   ├── {module}-en.json
+    │   └── {module}-ja.json
+    └── {module-page}.tsx # Main page components (optional)
+```
+
+### Example: Auth Module
+
+```
+modules/auth/
+├── components/
+│   ├── login-form.tsx
+│   ├── signup-form.tsx
+│   ├── forgot-password-form.tsx
+│   └── reset-password-form.tsx
+├── contexts/
+│   └── auth-context.tsx
+├── hooks/
+│   └── use-auth-hook.ts
+├── layouts/
+│   └── auth-layout.tsx
+└── locales/
+    ├── auth-en.json
+    └── auth-ja.json
+```
+
+### Example: App Module
+
+```
+modules/app/
+├── components/           # (empty, can add module-specific components)
+├── hooks/                # (empty, can add module-specific hooks)
+├── layouts/
+│   └── app-layout.tsx
+└── locales/
+    ├── app-en.json
+    └── app-ja.json
+```
+
+### Example: Landing Module
+
+```
+modules/landing/
+├── components/
+│   ├── auth-hero.tsx
+│   └── welcome-hero.tsx
+├── layouts/
+│   └── landing-page-layout.tsx
+├── locales/
+│   ├── landing-en.json
+│   └── landing-ja.json
+├── landing-page-layout.tsx
+└── landing-page.tsx
+```
+
+### Module File Types
+
+1. **Components** (`components/`)
+   - Module-specific UI components
+   - Use kebab-case: `login-form.tsx`, `user-profile-card.tsx`
+
+2. **Contexts** (`contexts/`)
+   - React Context providers for module state
+   - Use kebab-case: `auth-context.tsx`
+
+3. **Hooks** (`hooks/`)
+   - Custom React hooks for module logic
+   - Use kebab-case with `use-` prefix: `use-auth-hook.ts`
+
+4. **Layouts** (`layouts/`)
+   - Layout wrappers for module routes
+   - Use kebab-case: `auth-layout.tsx`, `app-layout.tsx`
+
+5. **Locales** (`locales/`)
+   - Translation files following pattern: `{module}-{lang}.json`
+   - Example: `auth-en.json`, `auth-ja.json`
+
+## Routes Structure
+
+Routes follow TanStack Router's file-based routing convention:
+
+```
+routes/
+├── __root.tsx            # Root route (wraps all routes)
+├── $.tsx                 # 404/fallback route
+├── _landing/             # Route group (underscore prefix)
+│   ├── route.tsx         # Parent route for landing group
+│   └── index.tsx         # Landing page route (/)
+├── app/                  # App routes (authenticated)
+│   ├── route.tsx         # Parent route with auth guard
+│   └── index.tsx         # App home page (/app)
+└── auth/                 # Auth routes (unauthenticated)
+    ├── route.tsx         # Parent route with auth layout
+    ├── login.tsx         # /auth/login
+    ├── signup.tsx        # /auth/signup
+    ├── forgot-password.tsx  # /auth/forgot-password
+    └── reset-password.tsx   # /auth/reset-password
+```
+
+### Route File Patterns
+
+1. **Parent Route** (`route.tsx`)
+   - Defines layout and guards for a route group
+   - Example: `/auth/route.tsx` wraps all `/auth/*` routes with `AuthLayout`
+
+2. **Child Routes**
+   - Individual page routes
+   - Example: `/auth/login.tsx` renders the login page component
+
+3. **Route Groups** (`_{name}/`)
+   - Underscore prefix creates a route group
+   - Example: `_landing/` groups routes without the prefix in the URL
+
+### Route Implementation Pattern
+
+```tsx
+// src/routes/{module}/route.tsx (Parent route)
+import { createFileRoute, Outlet } from '@tanstack/react-router';
+import { ModuleLayout } from '@/modules/{module}/layouts/{module}-layout';
+
+export const Route = createFileRoute('/{module}')({
+  beforeLoad: ({ context }) => {
+    // Guards, redirects, etc.
+  },
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return (
+    <ModuleLayout>
+      <Outlet />
+    </ModuleLayout>
+  );
+}
+```
+
+```tsx
+// src/routes/{module}/{page}.tsx (Child route)
+import { createFileRoute } from '@tanstack/react-router';
+import { PageComponent } from '@/modules/{module}/components/{page}-component';
+
+export const Route = createFileRoute('/{module}/{page}')({
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return <PageComponent />;
+}
+```
+
+## Components Organization
+
+### Shared vs Module-Specific Components
+
+**Shared Components** (`src/components/`):
+
+- Used across multiple modules
+- Generic, reusable UI primitives
+- Examples: `Button`, `Card`, `Input`, `Form`
+
+**Module-Specific Components** (`src/modules/{module}/components/`):
+
+- Only used within one module
+- Feature-specific logic
+- Examples: `LoginForm`, `UserProfileCard`, `DashboardWidget`
+
+### Component Naming
+
+- **File names**: kebab-case (e.g., `login-form.tsx`, `user-profile-card.tsx`)
+- **Component names**: PascalCase (e.g., `LoginForm`, `UserProfileCard`)
+- **Hooks**: kebab-case with `use-` prefix (e.g., `use-auth-hook.ts`)
+
+## Localization (i18n) Structure
+
+### Translation File Organization
+
+Translations are organized in two levels:
+
+1. **Global Translations** (`src/locales/`)
+   - Shared across all modules
+   - Languages: `en/`, `ja/`
+   - Files: `common.json`, `theme.json`
+
+2. **Module Translations** (`src/modules/{module}/locales/`)
+   - Module-specific translations
+   - Files: `{module}-en.json`, `{module}-ja.json`
+
+### Translation File Naming
+
+- Pattern: `{module}-{language}.json`
+- Examples:
+  - `auth-en.json`, `auth-ja.json`
+  - `app-en.json`, `app-ja.json`
+  - `landing-en.json`, `landing-ja.json`
+
+### Translation Merging
+
+Translations are merged in `src/locales/index.ts`:
+
+```typescript
+export const mergeTranslations = (lang: SupportedLanguages) => {
+  if (lang === 'en') {
+    return {
+      auth: { ...enAuth },
+      app: { ...enApp },
+      landing: { ...enLanding },
+      common: { ...enCommon },
+      theme: { ...enTheme },
+    };
+  }
+  // ... other languages
+};
+```
+
+### Using Translations in Components
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function MyComponent() {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t('auth.login.title')}</h1>
+      <p>{t('common.welcome')}</p>
+    </div>
+  );
+}
+```
+
+Translation keys follow the pattern: `{module}.{section}.{key}`
+
+## Adding a New Module
+
+To add a new feature module (e.g., "dashboard"), follow these steps:
+
+### 1. Create Module Directory Structure
+
+```
+src/modules/dashboard/
+├── components/
+│   └── dashboard-widget.tsx
+├── hooks/
+│   └── use-dashboard-data.ts
+├── layouts/
+│   └── dashboard-layout.tsx
+└── locales/
+    ├── dashboard-en.json
+    └── dashboard-ja.json
+```
+
+### 2. Create Translation Files
+
+**`src/modules/dashboard/locales/dashboard-en.json`**:
+
+```json
+{
+  "title": "Dashboard",
+  "welcome": "Welcome to Dashboard",
+  "widget": {
+    "title": "Widget",
+    "description": "Widget description"
+  }
+}
+```
+
+**`src/modules/dashboard/locales/dashboard-ja.json`**:
+
+```json
+{
+  "title": "ダッシュボード",
+  "welcome": "ダッシュボードへようこそ",
+  "widget": {
+    "title": "ウィジェット",
+    "description": "ウィジェットの説明"
+  }
+}
+```
+
+### 3. Update Global Locale Index
+
+Add module translations to `src/locales/index.ts`:
+
+```typescript
+import enDashboard from '@/modules/dashboard/locales/dashboard-en.json';
+import jaDashboard from '@/modules/dashboard/locales/dashboard-ja.json';
+
+export const mergeTranslations = (lang: SupportedLanguages) => {
+  if (lang === 'en') {
+    return {
+      // ... existing modules
+      dashboard: { ...enDashboard },
+    };
+  } else {
+    return {
+      // ... existing modules
+      dashboard: { ...jaDashboard },
+    };
+  }
+};
+```
+
+### 4. Create Layout Component
+
+**`src/modules/dashboard/layouts/dashboard-layout.tsx`**:
+
+```tsx
+export function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className='dashboard-container'>
+      {/* Dashboard-specific layout */}
+      {children}
+    </div>
+  );
+}
+```
+
+### 5. Create Route Files
+
+**`src/routes/dashboard/route.tsx`**:
+
+```tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router';
+import { DashboardLayout } from '@/modules/dashboard/layouts/dashboard-layout';
+
+export const Route = createFileRoute('/dashboard')({
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return (
+    <DashboardLayout>
+      <Outlet />
+    </DashboardLayout>
+  );
+}
+```
+
+**`src/routes/dashboard/index.tsx`**:
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router';
+import { DashboardPage } from '@/modules/dashboard/components/dashboard-page';
+
+export const Route = createFileRoute('/dashboard/')({
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return <DashboardPage />;
+}
+```
+
+### 6. Update Generator (if using Yeoman generator)
+
+If you're maintaining the generator, add the new module files to `generator-kodly-react-app/generators/app/index.js`:
+
+```javascript
+_writeDashboardFiles() {
+  const dashboardFiles = [
+    'src/modules/dashboard/components/dashboard-page.tsx',
+    'src/modules/dashboard/layouts/dashboard-layout.tsx',
+    'src/modules/dashboard/locales/dashboard-en.json',
+    'src/modules/dashboard/locales/dashboard-ja.json',
+    'src/routes/dashboard/route.tsx',
+    'src/routes/dashboard/index.tsx',
+  ];
+  dashboardFiles.forEach((file) => this._writeFile(file));
+}
+```
+
+## Naming Conventions
+
+### Files and Directories
+
+- **Directories**: kebab-case (e.g., `user-profile/`, `auth-flow/`)
+- **Component files**: kebab-case (e.g., `login-form.tsx`, `user-card.tsx`)
+- **Hook files**: kebab-case with `use-` prefix (e.g., `use-auth-hook.ts`)
+- **Utility files**: kebab-case (e.g., `error-handler.ts`, `api-client.ts`)
+- **Route files**: kebab-case (e.g., `login.tsx`, `user-profile.tsx`)
+
+### Code Elements
+
+- **Components**: PascalCase (e.g., `LoginForm`, `UserCard`)
+- **Hooks**: camelCase with `use` prefix (e.g., `useAuth`, `useUserData`)
+- **Functions**: camelCase (e.g., `handleSubmit`, `validateEmail`)
+- **Constants**: UPPER_SNAKE_CASE (e.g., `DEFAULT_ROUTE`, `API_BASE_URL`)
+- **Types/Interfaces**: PascalCase (e.g., `User`, `AuthContext`)
+
+### Module Names
+
+- Use singular nouns (e.g., `auth`, `user`, `dashboard`)
+- Keep names concise and descriptive
+- Avoid abbreviations unless widely understood
+
+## File Patterns
+
+### Component File Pattern
+
+```tsx
+// src/modules/{module}/components/{component-name}.tsx
+import { useTranslation } from 'react-i18next';
+
+export function ComponentName() {
+  const { t } = useTranslation();
+
+  return <div>{/* Component JSX */}</div>;
+}
+```
+
+### Hook File Pattern
+
+```tsx
+// src/modules/{module}/hooks/use-{hook-name}.ts
+import { useAtom } from 'jotai';
+
+export function useHookName() {
+  // Hook logic
+  return {
+    // Return values
+  };
+}
+```
+
+### Layout File Pattern
+
+```tsx
+// src/modules/{module}/layouts/{module}-layout.tsx
+export function ModuleLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className='module-container'>
+      {/* Layout structure */}
+      {children}
+    </div>
+  );
+}
+```
+
+### Route File Pattern
+
+```tsx
+// src/routes/{module}/{page}.tsx
+import { createFileRoute } from '@tanstack/react-router';
+import { ComponentName } from '@/modules/{module}/components/component-name';
+
+export const Route = createFileRoute('/{module}/{page}')({
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return <ComponentName />;
+}
+```
+
+### Translation File Pattern
+
+```json
+// src/modules/{module}/locales/{module}-{lang}.json
+{
+  "section": {
+    "key": "Translation value",
+    "nested": {
+      "key": "Nested translation"
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Keep modules self-contained**: Module components should primarily import from within their module or shared locations
+2. **Use shared components**: Place reusable UI components in `src/components/ui/`
+3. **Follow the translation pattern**: Always add translations for new modules and update `locales/index.ts`
+4. **Route organization**: Group related routes under a parent route with a layout
+5. **Type safety**: Use TypeScript types consistently and leverage the generated SDK types
+6. **Consistent naming**: Follow the naming conventions outlined above
+7. **Separation of concerns**: Keep business logic in hooks, UI in components, state in contexts/atoms
+
+## Summary
+
+This template follows a **feature-based modular architecture** where:
+
+- **Modules** (`src/modules/`) contain feature-specific code (components, hooks, layouts, translations)
+- **Routes** (`src/routes/`) map URL paths to components using TanStack Router
+- **Shared components** (`src/components/`) provide reusable UI primitives
+- **Library code** (`src/lib/`) contains utilities, API clients, and shared logic
+- **Translations** are organized at both global and module levels
+- Each module is **self-contained** with its own components, layouts, hooks, and translations
+
+When adding new features:
+
+1. Create a new module directory under `src/modules/`
+2. Add module-specific components, hooks, layouts, and translations
+3. Create corresponding route files in `src/routes/`
+4. Update the global locale index to include module translations
+5. Follow the established naming conventions and file patterns

package/generators/app/templates/components.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "stone",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

package/generators/app/templates/index.html

@@ -4,15 +4,23 @@
     <meta charset="UTF-8" />
     <meta
       name="viewport"
-      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
-    />
-    <meta name="theme-color" content="#000000" />
-    <meta name="description" content="<%= appNameTitleCase %> Application" />
+      content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+    <meta
+      name="theme-color"
+      content="#000000" />
+    <meta
+      name="description"
+      content="<%= appNameTitleCase %>" />
+    <link
+      rel="icon"
+      type="image/svg+xml"
+      href="/favicon.svg" />
     <title><%= appNameTitleCase %></title>
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/src/main.tsx"></script>
+    <script
+      type="module"
+      src="/src/main.tsx"></script>
   </body>
 </html>
-