@adlas/create-app 1.0.45 → 1.0.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adlas/create-app",
-  "version": "1.0.45",
+  "version": "1.0.46",
   "description": "Adlas project initializer with Figma and Swagger integration",
   "type": "module",
   "main": "./dist/cli.js",

package/templates/docs/PROJECT_DOCUMENTATION.md

@@ -0,0 +1,452 @@
+# @adlas/create-app - Complete Project Documentation
+
+## Project Overview
+
+**Package Name**: `@adlas/create-app`
+**Current Version**: `1.0.41`
+**NPM Registry**: https://www.npmjs.com/package/@adlas/create-app
+**Type**: CLI Tool for scaffolding Next.js projects with HeroUI, Tailwind CSS 4, and TypeScript
+
+## Project Purpose
+
+This is a CLI tool that generates production-ready Next.js 15 projects with:
+- **HeroUI v2** (React UI component library)
+- **Tailwind CSS v4** (Latest version with new @theme syntax)
+- **TypeScript** (Strict mode enabled)
+- **Next.js 15** with App Router
+- **Internationalization** (next-intl)
+- **React Query** (TanStack Query v5)
+- **Form Management** (React Hook Form + Zod)
+- **PWA Support** (Always enabled)
+- **ESLint + Prettier** (With strict formatting rules)
+
+## Project Structure
+
+```
+cli-tool/
+├── src/
+│   └── commands/
+│       ├── init.ts          # Main project scaffolding command
+│       ├── figma.ts         # Figma integration (not actively used)
+│       └── swagger.ts       # Swagger integration (not actively used)
+├── templates/
+│   ├── boilerplate/         # Template files copied to new projects
+│   │   ├── assets/          # SVG icons
+│   │   ├── components/      # Reusable UI components
+│   │   │   ├── icons/       # Generated icon components
+│   │   │   └── ui/          # HeroUI wrapper components
+│   │   ├── config/          # App configuration
+│   │   ├── libs/            # Library configurations
+│   │   ├── locales/         # Translation files
+│   │   ├── providers.tsx    # React providers wrapper
+│   │   ├── styles/          # Global styles and theme
+│   │   │   ├── globals.css  # Tailwind CSS 4 with custom breakpoints
+│   │   │   └── hero.ts      # HeroUI theme configuration
+│   │   ├── types/           # TypeScript type definitions
+│   │   ├── utils/           # Helper functions
+│   │   └── validations/     # Zod schemas and validation logic
+│   ├── configs/             # Configuration files
+│   │   ├── .gitignore
+│   │   ├── eslint.config.mjs
+│   │   ├── next.config.ts
+│   │   ├── tsconfig.json
+│   │   └── ... (other config files)
+│   └── docs/                # Documentation (CURRENTLY EMPTY)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Key Technical Decisions
+
+### 1. Font Configuration
+**Default Font**: `ibx` (IBM Plex Sans)
+- Configured in `templates/boilerplate/styles/globals.css`
+- CSS Variable: `--font-sans: var(--font-ibx), system-ui, sans-serif`
+
+### 2. Responsive Breakpoints (Mobile-First)
+Custom breakpoints based on real device sizes:
+
+```css
+/* Mobile */
+--breakpoint-4xs: 320px;   /* iPhone SE */
+--breakpoint-3xs: 375px;   /* iPhone 13 mini */
+--breakpoint-2xs: 390px;   /* iPhone 13/14/16, 14/15 Pro, 16 Pro */
+--breakpoint-xs: 440px;    /* iPhone 14/16 Plus, 14/15 Pro Max, 16 Pro Max */
+
+/* Tablet */
+--breakpoint-sm: 744px;    /* iPad mini 8.3" */
+--breakpoint-md: 834px;    /* iPad Pro 11" */
+--breakpoint-lg: 1024px;   /* iPad Pro 12.9" - REFERENCE POINT */
+
+/* Desktop */
+--breakpoint-xl: 1280px;   /* MacBook Air, TV, Android Expanded */
+--breakpoint-2xl: 1440px;  /* Desktop, Surface Pro 8, Wireframes */
+--breakpoint-3xl: 1512px;  /* MacBook Pro 14" */
+--breakpoint-4xl: 1728px;  /* MacBook Pro 16" */
+```
+
+**Important**: `lg` (1024px) is the reference breakpoint.
+
+### 3. HeroUI Theme Configuration
+Located in `templates/boilerplate/styles/hero.ts`:
+
+```typescript
+export default heroui(); // Minimal config, uses HeroUI defaults
+```
+
+**Note**: The theme file was recently simplified. If you need custom colors, refer to the berndorf project at `/Users/amir/Desktop/Projects/adlas/berndorf/src/styles/hero.ts` for a complete example with all color definitions.
+
+### 4. Dependencies Management
+**Critical Change**: Automatic `pnpm install` is **DISABLED**.
+
+**Why**: To prevent long installation times and allow users to review dependencies first.
+
+**Implementation**:
+- In `src/commands/init.ts` line 214, `--skip-install` flag is added to `pnpm create next-app` command
+- The `installDependencies()` function call has been removed from the initialization flow
+- Users must manually run `pnpm install` after project creation
+- No `node_modules` folder is created during project initialization
+
+### 5. Ignored Files
+Added to `.gitignore`:
+- `pnpm-lock.yaml`
+- `pnpm-workspace.yaml`
+
+**Reason**: These files should not be in version control for CLI-generated projects.
+
+### 6. ESLint Configuration
+**Issue**: `eslint-plugin-tailwindcss` has compatibility issues with Tailwind CSS v4 and HeroUI custom classes.
+
+**Solution**: The plugin is included but configured properly with settings pointing to `globals.css`.
+
+**Reference Project**: `/Users/amir/Desktop/Projects/adlas/berndorf` - This project has a working eslint config that we copied.
+
+### 7. Removed Features
+- **Figma Integration Prompt**: Removed from init wizard
+- **Swagger Integration Prompt**: Removed from init wizard
+
+These features are still in the codebase but not exposed to users during project creation.
+
+## Important File Locations
+
+### Critical Boilerplate Files
+1. **`templates/boilerplate/styles/globals.css`**
+   - Tailwind CSS 4 configuration
+   - Custom breakpoints
+   - HeroUI integration
+   - Toast styles (Sonner)
+
+2. **`templates/boilerplate/styles/hero.ts`**
+   - HeroUI theme configuration
+   - Currently minimal setup
+
+3. **`templates/configs/eslint.config.mjs`**
+   - ESLint configuration
+   - Includes tailwindcss plugin
+   - Import sorting rules
+
+4. **`src/commands/init.ts`**
+   - Main scaffolding logic
+   - Dependency versions (line 453-505)
+   - Project generation flow
+
+### Key Package Versions
+```json
+{
+  "@heroui/react": "^2.8.5",
+  "@internationalized/date": "3.10.1",  // IMPORTANT: Must be exactly 3.10.1
+  "next": "15.5.4",
+  "react": "19.2.0",
+  "tailwindcss": "4.1.17",
+  "eslint-plugin-tailwindcss": "^4.0.0-beta.0"
+}
+```
+
+**Critical**: `@internationalized/date` must be `3.10.1` to match HeroUI's internal version and avoid type conflicts.
+
+## Development Workflow
+
+### Building the CLI
+```bash
+cd /Users/amir/Desktop/Projects/cli-tool
+pnpm build
+```
+
+### Testing Locally
+```bash
+# Build first
+pnpm build
+
+# Test in a new directory
+cd /Users/amir/Desktop
+npx /Users/amir/Desktop/Projects/cli-tool init test-project
+```
+
+### Publishing to NPM
+
+**Prerequisites**:
+1. Git working directory must be clean
+2. You must be logged into npm (`npm whoami` to check)
+
+**Commands**:
+```bash
+# Option 1: Automatic version bump + build + publish
+pnpm release          # Bumps patch version (1.0.32 → 1.0.33)
+
+# Option 2: Manual version control
+pnpm release:minor    # Bumps minor version (1.0.32 → 1.1.0)
+pnpm release:major    # Bumps major version (1.0.32 → 2.0.0)
+
+# Option 3: Force publish without version bump
+pnpm publish:force    # Use with caution
+```
+
+**Publishing Flow**:
+1. Commit all changes: `git add . && git commit -m "your message"`
+2. Run `pnpm release`
+3. Script automatically:
+   - Bumps version in package.json
+   - Builds the project
+   - Publishes to npm
+   - Creates a git tag
+
+## Common Issues and Solutions
+
+### Issue 1: TypeScript Errors with DatePicker
+**Error**: Type mismatch with `@internationalized/date`
+
+**Solution**:
+- Ensure version is exactly `3.10.1` in `src/commands/init.ts` line 459
+- Run `pnpm add @internationalized/date@3.10.1` in generated project
+
+### Issue 2: ESLint Errors with Tailwind Classes
+**Error**: `Cannot apply unknown utility class 'bg-background'`
+
+**Solution**:
+- This was fixed by defining minimal HeroUI theme
+- If it happens again, check that `hero.ts` exports `heroui()` properly
+- Verify `eslint.config.mjs` has correct Tailwind settings
+
+### Issue 3: Lint Errors in Generated Projects
+**Status**: RESOLVED in v1.0.41
+
+**Previous Issue**: Generated projects had lint errors:
+- `next.config.ts`: Missing spacing between import groups
+- `src/types/next-pwa.d.ts`: Using `import` instead of `import type`
+
+**Solution**:
+- Fixed in `src/commands/init.ts` line 300: Added extra newline after `import type { NextConfig } from 'next';`
+- Fixed in `src/commands/init.ts` line 576: Changed to `import type { NextConfig } from 'next';`
+- All generated projects now pass `pnpm lint` and `pnpm check:types` without errors
+
+## Reference Projects
+
+### Berndorf Project
+**Location**: `/Users/amir/Desktop/Projects/adlas/berndorf`
+
+**Why it matters**:
+- Has working HeroUI theme with all colors defined
+- Has working eslint-plugin-tailwindcss configuration
+- Used as reference for:
+  - `hero.ts` color definitions
+  - ESLint configuration
+  - Tailwind CSS setup
+
+**Key files to reference**:
+- `/Users/amir/Desktop/Projects/adlas/berndorf/src/styles/hero.ts` - Complete color palette
+- `/Users/amir/Desktop/Projects/adlas/berndorf/eslint.config.mjs` - Working ESLint config
+
+## Testing Checklist
+
+Before publishing a new version, test these commands in a generated project:
+
+```bash
+# 1. Create new project
+npx @adlas/create-app@latest init test-project
+cd test-project
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Run type check (should pass with 0 errors)
+pnpm check:types
+
+# 4. Run linter (may have errors, should be fixable)
+pnpm lint
+
+# 5. Fix lint errors
+pnpm lint --fix
+
+# 6. Verify lint passes
+pnpm lint
+
+# 7. Start dev server (should work without errors)
+pnpm dev
+
+# 8. Build project (should complete successfully)
+pnpm build
+```
+
+## Project History (Recent Changes)
+
+### v1.0.41 (Latest)
+- **CRITICAL FIX**: Fixed import spacing in generated `next.config.ts`
+- **CRITICAL FIX**: Fixed `import type` usage in generated `next-pwa.d.ts`
+- Generated projects now pass `pnpm lint` and `pnpm check:types` without errors
+- Modified `generateNextConfig()` function to add proper spacing after 'next' import
+- Modified `createTypeDeclarations()` function to use `import type` instead of `import`
+
+### v1.0.40
+- Added `check:types` script to package.json template
+- Script: `"check:types": "tsc --noEmit --pretty"`
+
+### v1.0.39
+- Fixed import spacing in next.config.ts template
+- Removed extra spacing between next-intl/plugin and next-pwa imports
+
+### v1.0.38
+- Resolved remaining lint errors in boilerplate files
+- Fixed import spacing in next.config.ts
+- Fixed Tailwind class ordering in Navbar component
+- Ensured import type is used correctly in next-pwa.d.ts
+
+### v1.0.37
+- Fixed Tailwind class ordering in Navbar component (text-xl font-bold)
+
+### v1.0.36
+- Removed duplicate types folder copy to resolve TypeScript compilation error
+
+### v1.0.35
+- Fixed package.json dependencies alphabetical ordering
+- Added layout components (Navbar, Footer) to boilerplate copy
+
+### v1.0.33
+- Fixed package.json dependencies sorting
+- Added layout components to boilerplate
+
+### v1.0.32
+- Fixed lint errors in boilerplate files
+- Added `next-pwa.d.ts` type definitions
+- Applied lint fixes to DatePicker, queryClient, and other files
+
+### v1.0.28-31
+- Removed Figma and Swagger prompts from init wizard
+- Disabled automatic `pnpm install` with `--skip-install` flag
+- Added pnpm-lock.yaml and pnpm-workspace.yaml to gitignore
+- Updated eslint.config.mjs with Tailwind plugin configuration
+- Changed default font to `ibx`
+- Changed hero.ts to minimal configuration `heroui()`
+
+## Environment Setup
+
+### Required Software
+- **Node.js**: >= 18.0.0
+- **pnpm**: Latest version recommended
+- **npm**: For publishing (comes with Node.js)
+- **Git**: For version control
+
+### NPM Authentication
+```bash
+# Check if logged in
+npm whoami
+
+# Login if needed
+npm login
+
+# Verify access to @adlas scope
+npm access list packages @adlas
+```
+
+## File Modifications Not in Git
+
+The following files are modified during the build/publish process and may not match what's in the repository:
+
+1. **package.json** - Version number changes with each release
+2. **dist/** - Generated TypeScript output (gitignored)
+3. **node_modules/** - Dependencies (gitignored)
+
+## Critical Notes for Future Sessions
+
+1. **Never revert hero.ts to complex configuration** unless specifically needed. The minimal `heroui()` export is intentional.
+
+2. **Don't remove eslint-plugin-tailwindcss** even if it seems unused. It's required for Tailwind class ordering.
+
+3. **Always test with a fresh project** before publishing. The boilerplate may have lint errors that only appear after generation.
+
+4. **Reference berndorf project** for working examples of HeroUI + Tailwind CSS v4 + ESLint configuration.
+
+5. **pnpm-lock.yaml should NOT be in generated projects** - it's in gitignore for a reason.
+
+6. **Font is ibx, not inter** - Check globals.css if font-related issues arise.
+
+7. **@internationalized/date version is critical** - Must be 3.10.1 to avoid type errors.
+
+8. **Breakpoint reference is 1024px (lg)** - All other breakpoints are relative to this.
+
+## Useful Commands Reference
+
+```bash
+# Build the CLI
+pnpm build
+
+# Publish new version
+pnpm release
+
+# Test locally without publishing
+pnpm link
+cd /some/test/directory
+npx @adlas/create-app init my-test
+
+# Clear npm cache (if users report old version)
+npm cache clean --force
+
+# Check what's included in published package
+npm pack --dry-run
+```
+
+## Contact & Repository
+
+- **NPM Package**: https://www.npmjs.com/package/@adlas/create-app
+- **Repository**: https://github.com/adlas/create-app (configured in package.json)
+- **License**: UNLICENSED (private/proprietary)
+
+## Final Notes
+
+This project is a **production CLI tool** that generates real projects for end users. Any changes should be:
+1. Tested thoroughly
+2. Documented
+3. Version controlled
+4. Published with appropriate version bumps
+
+The quality of generated projects reflects directly on the CLI tool, so maintain high standards for code quality, linting, and TypeScript safety.
+
+## Key Fixes Summary
+
+### Lint and Type Checking (v1.0.36 - v1.0.41)
+This series of releases focused on ensuring generated projects pass all quality checks:
+
+1. **Import Spacing**: ESLint rule `perfectionist/sort-imports` requires proper spacing between import groups
+   - Fixed by adding `\n\n` after the first import in `generateNextConfig()`
+
+2. **Type Imports**: ESLint rule `ts/consistent-type-imports` requires `import type` for type-only imports
+   - Fixed in `createTypeDeclarations()` for next-pwa.d.ts generation
+
+3. **Tailwind Class Ordering**: ESLint rule `tailwindcss/classnames-order` enforces specific class order
+   - Fixed in Navbar component template
+
+4. **Duplicate File Copy**: TypeScript compilation error from duplicate variable names
+   - Removed duplicate types folder copy in copyBoilerplate function
+
+5. **Missing Components**: Layout components weren't being copied to generated projects
+   - Added layout folder copy to copyBoilerplate function
+
+6. **Package.json Ordering**: Dependencies must be alphabetically sorted
+   - Fixed dependency ordering in init.ts
+
+**Result**: Generated projects now pass `pnpm lint` and `pnpm check:types` without any errors.
+
+---
+
+**Last Updated**: December 23, 2025 (v1.0.41)
+**Documentation Created For**: Claude AI continuation in different account