create-pnpm-custom-app 1.0.0

package/README.md

@@ -0,0 +1,217 @@
+# create-pnpm-custom-app
+
+> A professional CLI to scaffold full-stack monorepo projects with Next.js, Fastify, and pnpm workspaces
+
+## Features
+
+- **Next.js 16**: Latest Next.js with App Router and React 19
+- **Fastify 5**: High-performance backend API
+- **MongoDB**: Mongoose ODM for database operations
+- **JWT Authentication**: Secure authentication out of the box
+- **i18n Ready**: Internationalization with next-intl (English/Spanish)
+- **Tailwind CSS 4**: Modern utility-first styling
+- **Swagger/OpenAPI**: Auto-generated API documentation
+- **Testing Ready**: Jest configured for both frontend and backend
+- **Monorepo**: pnpm workspaces for efficient dependency management
+- **Shared Types**: TypeScript interfaces shared between apps
+
+## Quick Start
+
+```bash
+# Using npx (recommended)
+npx create-pnpm-custom-app my-project
+
+# Or with pnpm
+pnpm create pnpm-custom-app my-project
+
+# Or install globally
+pnpm add -g create-pnpm-custom-app
+create-pnpm-custom-app my-project
+```
+
+## Project Structure
+
+```txt
+my-project/
+├── apps/
+│   ├── web/                # Next.js frontend
+│   │   ├── app/
+│   │   ├── i18n/
+│   │   ├── messages/
+│   │   └── package.json
+│   └── api/                # Fastify backend
+│       ├── src/
+│       ├── tests/
+│       └── package.json
+├── packages/
+│   └── shared/             # Shared types
+├── docs/
+├── .github/
+│   └── copilot-instructions.md
+└── package.json
+```
+
+## What's Included
+
+### Frontend (Next.js)
+
+- React 19 with Server Components
+- TypeScript strict mode
+- Tailwind CSS 4 with custom design system
+- i18n with next-intl (Spanish/English)
+- Fully responsive with mobile-first approach
+- Accessibility-first components
+
+### Backend (Fastify)
+
+- Fastify 5 with TypeScript
+- MongoDB with Mongoose
+- JWT authentication (@fastify/jwt)
+- Swagger/OpenAPI documentation
+- CORS, rate limiting, multipart support
+- Pino logger (pretty mode in dev)
+- Input validation schemas
+- Jest + Supertest for testing
+
+### Monorepo Setup
+
+- pnpm workspaces
+- Shared TypeScript types
+- Consistent linting and formatting
+- Comprehensive documentation
+- GitHub Copilot instructions
+
+## After Creating Your Project
+
+1. **Navigate to your project:**
+
+   ```bash
+   cd my-project
+   ```
+
+2. **Configure environment variables:**
+
+   ```bash
+   # Frontend
+   cp apps/web/.env.example apps/web/.env.local
+   
+   # Backend
+   cp apps/api/.env.example apps/api/.env
+   ```
+
+3. **Edit the environment files with your values:**
+   - `apps/web/.env.local` - API URL and frontend config
+   - `apps/api/.env` - MongoDB URI, JWT secret, CORS origin
+
+4. **Start development servers:**
+
+   ```bash
+   # Terminal 1: Frontend (http://localhost:3000)
+   pnpm --filter web dev
+   
+   # Terminal 2: Backend (http://localhost:3002)
+   pnpm --filter api dev
+   ```
+
+5. **Access Swagger documentation:**
+   - Open <http://localhost:3002/docs>
+
+## Available Scripts
+
+### Root Level
+
+```bash
+pnpm install       # Install all dependencies
+pnpm run dev       # Start both apps in parallel
+pnpm run build     # Build all apps
+pnpm run lint      # Lint all apps
+pnpm run test      # Run all tests
+```
+
+### Frontend
+
+```bash
+pnpm --filter web dev       # Development server
+pnpm --filter web build     # Production build
+pnpm --filter web start     # Production server
+pnpm --filter web lint      # Lint code
+```
+
+### Backend
+
+```bash
+pnpm --filter api dev           # Development server
+pnpm --filter api build         # Build TypeScript
+pnpm --filter api start         # Production server
+pnpm --filter api test          # Run tests
+pnpm --filter api test:watch    # Tests in watch mode
+pnpm --filter api lint          # Lint code
+```
+
+## Tech Stack
+
+| Category | Technologies |
+| ---------- | ------------- |
+| **Frontend** | Next.js 16, React 19, TypeScript, Tailwind CSS 4, next-intl |
+| **Backend** | Fastify 5, TypeScript, MongoDB, Mongoose, Pino |
+| **Auth** | @fastify/jwt, bcrypt |
+| **Testing** | Jest, Supertest |
+| **Tooling** | pnpm, ESLint, Prettier, TypeScript |
+| **Docs** | Swagger/OpenAPI, JSDoc |
+
+## Requirements
+
+- **Node.js** 20.0.0 or higher
+- **pnpm** 9.0.0 or higher
+- **MongoDB** (local or remote instance)
+
+## Documentation
+
+After creating your project, check:
+
+- `README.md` - Project overview and setup
+- `CONTRIBUTING.md` - Contribution guidelines
+- `.github/copilot-instructions.md` - AI coding assistant guidelines
+- `docs/` - Additional documentation
+
+## Tips
+
+### MongoDB Setup
+
+**Local MongoDB:**
+
+```bash
+# macOS (Homebrew)
+brew install mongodb-community
+brew services start mongodb-community
+
+# Your connection string:
+MONGODB_URI=mongodb://localhost:27017/your-database
+```
+
+**MongoDB Atlas (Cloud):**
+
+1. Sign up at <https://www.mongodb.com/cloud/atlas>
+2. Create a cluster
+3. Get your connection string
+4. Add to `.env`: `MONGODB_URI=mongodb+srv://...`
+
+### Customization
+
+- **Colors**: Edit `apps/web/app/globals.css`
+- **i18n**: Add/edit translations in `apps/web/messages/`
+- **API Routes**: Add routes in `apps/api/src/routes/`
+- **Models**: Create models in `apps/api/src/models/`
+- **Components**: Add to `apps/web/app/components/`
+
+## License
+
+MIT
+
+## Author
+
+Created by Pelayo Trives
+
+---
+
+**Happy coding!**

package/bin/cli.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import prompts from 'prompts';
+import chalk from 'chalk';
+import ora from 'ora';
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const program = new Command();
+
+program
+  .name('create-pnpm-custom-app')
+  .description('Scaffold a professional full-stack monorepo with Next.js, Fastify, and pnpm workspaces')
+  .version('1.0.0')
+  .argument('[project-name]', 'Name of the project')
+  .parse(process.argv);
+
+const args = program.args;
+
+async function main() {
+  console.log(chalk.bold.cyan('\n🚀 Create PNPM Custom App\n'));
+
+  let projectName = args[0];
+  let githubUser = '';
+
+  if (!projectName) {
+    const response = await prompts({
+      type: 'text',
+      name: 'projectName',
+      message: 'What is your project name?',
+      initial: 'my-app',
+      validate: (value) => (value.length > 0 ? true : 'Project name is required'),
+    });
+
+    if (!response.projectName) {
+      console.log(chalk.red('\n❌ Project creation cancelled.'));
+      process.exit(1);
+    }
+
+    projectName = response.projectName;
+  }
+
+  // Ask for GitHub username
+  const githubResponse = await prompts({
+    type: 'text',
+    name: 'githubUser',
+    message: 'What is your GitHub username? (optional, used only for repository links)',
+    initial: projectName,
+    validate: (value) => true, // Optional field
+  });
+
+  githubUser = githubResponse.githubUser || projectName;
+
+  const projectPath = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(projectPath)) {
+    console.log(chalk.red(`\n❌ Directory "${projectName}" already exists.`));
+    process.exit(1);
+  }
+
+  console.log(chalk.gray(`\n📁 Creating project at: ${projectPath}\n`));
+
+  const spinner = ora('Creating project structure...').start();
+
+  try {
+    // Create project directory
+    fs.mkdirSync(projectPath, { recursive: true });
+
+    // Copy all templates
+    const templatesDir = path.join(__dirname, '../templates');
+    fs.copySync(templatesDir, projectPath);
+
+    // Rename gitignore files (npm publish removes .gitignore)
+    const gitignoreRootPath = path.join(projectPath, 'gitignore-root');
+    if (fs.existsSync(gitignoreRootPath)) {
+      fs.renameSync(gitignoreRootPath, path.join(projectPath, '.gitignore'));
+    }
+
+    const webGitignorePath = path.join(projectPath, 'apps/web/gitignore');
+    if (fs.existsSync(webGitignorePath)) {
+      fs.renameSync(webGitignorePath, path.join(projectPath, 'apps/web/.gitignore'));
+    }
+
+    const apiGitignorePath = path.join(projectPath, 'apps/api/gitignore');
+    if (fs.existsSync(apiGitignorePath)) {
+      fs.renameSync(apiGitignorePath, path.join(projectPath, 'apps/api/.gitignore'));
+    }
+
+    // Replace project name in package.json files
+    const packageJsonPaths = [
+      path.join(projectPath, 'package.json'),
+      path.join(projectPath, 'apps/web/package.json'),
+      path.join(projectPath, 'apps/api/package.json'),
+      path.join(projectPath, 'packages/shared/package.json'),
+    ];
+
+    packageJsonPaths.forEach((pkgPath) => {
+      if (fs.existsSync(pkgPath)) {
+        const content = fs.readFileSync(pkgPath, 'utf-8');
+        const updated = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+        fs.writeFileSync(pkgPath, updated);
+      }
+    });
+
+    // Replace project name in all other files (tsx, ts, md, json, etc.)
+    const filesToReplace = [
+      path.join(projectPath, 'README.md'),
+      path.join(projectPath, 'CONTRIBUTING.md'),
+      path.join(projectPath, 'apps/web/app/layout.tsx'),
+      path.join(projectPath, 'apps/web/app/manifest.json'),
+      path.join(projectPath, 'apps/web/app/components/layout/Nav.component.tsx'),
+      path.join(projectPath, 'apps/web/app/components/layout/Footer.component.tsx'),
+      path.join(projectPath, 'apps/web/app/[locale]/(routes)/page.tsx'),
+      path.join(projectPath, 'apps/web/app/opengraph-image.tsx'),
+      path.join(projectPath, 'apps/web/app/twitter-image.tsx'),
+      path.join(projectPath, 'apps/web/app/apple-icon.tsx'),
+      path.join(projectPath, 'apps/web/app/icon.tsx'),
+      path.join(projectPath, 'apps/web/messages/en.json'),
+      path.join(projectPath, 'apps/web/messages/es.json'),
+      path.join(projectPath, 'apps/api/src/app.ts'),
+      path.join(projectPath, 'packages/shared/src/index.ts'),
+      path.join(projectPath, '.github/copilot-instructions.md'),
+    ];
+
+    filesToReplace.forEach((filePath) => {
+      if (fs.existsSync(filePath)) {
+        let content = fs.readFileSync(filePath, 'utf-8');
+        content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+        content = content.replace(/\{\{GITHUB_USER\}\}/g, githubUser);
+        fs.writeFileSync(filePath, content);
+      }
+    });
+
+    spinner.succeed(chalk.green('Project structure created!'));
+
+    // Install dependencies
+    spinner.start('Installing dependencies with pnpm... This may take a few minutes.');
+    
+    try {
+      execSync('pnpm install', { cwd: projectPath, stdio: 'ignore' });
+      spinner.succeed(chalk.green('Dependencies installed successfully!'));
+    } catch (error) {
+      spinner.warn(chalk.yellow('Could not install dependencies automatically.'));
+      console.log(chalk.gray('  Run `pnpm install` manually inside the project.'));
+    }
+
+    // Success message
+    console.log(chalk.bold.green(`\n✅ Project "${projectName}" created successfully!\n`));
+    console.log(chalk.cyan('📦 Project structure:'));
+    console.log(chalk.gray('  ├── apps/'));
+    console.log(chalk.gray('  │   ├── web/        (Next.js 16 + TypeScript + Tailwind 4)'));
+    console.log(chalk.gray('  │   └── api/        (Fastify + MongoDB + TypeScript)'));
+    console.log(chalk.gray('  ├── packages/'));
+    console.log(chalk.gray('  │   └── shared/     (Shared types and interfaces)'));
+    console.log(chalk.gray('  └── docs/           (Project documentation)\n'));
+
+    console.log(chalk.cyan('🚀 Next steps:'));
+    console.log(chalk.white(`  1. cd ${projectName}`));
+    console.log(chalk.white('  2. Copy .env.example files and configure:'));
+    console.log(chalk.gray('     - apps/web/.env.local'));
+    console.log(chalk.gray('     - apps/api/.env'));
+    console.log(chalk.white('  3. Start development:'));
+    console.log(chalk.gray('     - Frontend: pnpm --filter web dev'));
+    console.log(chalk.gray('     - Backend:  pnpm --filter api dev'));
+    console.log(chalk.white('  4. Read the README.md for more information\n'));
+
+    console.log(chalk.bold.magenta('Happy coding! 🎉\n'));
+
+  } catch (error) {
+    spinner.fail(chalk.red('Failed to create project'));
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error(chalk.red('An error occurred:'), error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-pnpm-custom-app",
+  "version": "1.0.0",
+  "description": "A professional CLI to scaffold full-stack monorepo projects with Next.js, Fastify, and pnpm workspaces",
+  "type": "module",
+  "bin": {
+    "create-pnpm-custom-app": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"Run: npx create-pnpm-custom-app my-project\" && exit 0"
+  },
+  "keywords": [
+    "cli",
+    "scaffold",
+    "boilerplate",
+    "monorepo",
+    "pnpm",
+    "nextjs",
+    "fastify",
+    "typescript",
+    "tailwind"
+  ],
+  "author": "Pelayo Trives",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.1.1",
+    "prompts": "^2.4.2"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ]
+}

package/templates/.github/copilot-instructions.md

@@ -0,0 +1,184 @@
+# GitHub Copilot Instructions for [Project Name]
+
+## Project Overview
+
+[Brief description of your project]
+
+**Tech Stack:**
+- **Frontend**: Next.js 16+ (App Router), React 19+, TypeScript
+- **Backend**: Fastify API with MongoDB
+- **Monorepo**: pnpm workspace (apps/web, apps/api, packages/shared)
+- **Styling**: Tailwind CSS 4 with custom design system
+- **i18n**: next-intl (English/Spanish)
+
+---
+
+## Architecture Patterns
+
+### Component Structure (Atomic Design)
+
+- **Atoms**: `/app/components/ui/atoms/` - Basic UI elements (Button, Input, etc.)
+- **Molecules**: `/app/components/ui/molecules/` - Composite components
+- **Layout**: `/app/components/layout/` - Navigation, Footer, etc.
+
+### Component Guidelines
+
+1. **All Typography components MUST use `forwardRef`** for animation library compatibility
+2. **Interactive components MUST have `'use client'`** directive
+3. **Server components by default** - only add 'use client' when necessary
+4. Use **TypeScript strictly** - avoid `any` types, define all interfaces
+5. **Tailwind only** - no inline styles or CSS modules
+6. Use **cn()** utility for className merging
+
+---
+
+## File Naming Conventions
+
+- Components: `ComponentName.component.tsx`
+- Pages: `page.tsx` (Next.js App Router)
+- Layouts: `layout.tsx`
+- Interfaces: `name.interface.ts`
+- Utilities: `name.ts`
+
+---
+
+## Code Style
+
+### TypeScript
+
+```typescript
+// Prefer interfaces over types
+interface ButtonProps {
+  variant?: "primary" | "secondary";
+  children: React.ReactNode;
+}
+
+// Use Record for variant mappings
+const variantClasses: Record<string, string> = {
+  primary: "bg-primary",
+  secondary: "bg-secondary",
+};
+```
+
+### React Patterns
+
+```typescript
+// Use forwardRef for components that need refs
+export const Component = forwardRef<HTMLDivElement, Props>(
+  ({ children, className, ...props }, ref) => (
+    <div ref={ref} className={cn("base-class", className)} {...props}>
+      {children}
+    </div>
+  )
+);
+Component.displayName = "Component";
+
+// Use 'use client' for interactive components
+("use client");
+import { useState } from "react";
+```
+
+### Tailwind CSS
+
+- Use responsive prefixes: `sm:`, `md:`, `lg:`
+- Dark mode support with theme provider
+- Custom colors: Use design tokens (bg-primary, text-muted-foreground, etc.)
+- Spacing: Use Tailwind scale (p-4, gap-6, etc.)
+
+---
+
+## Translations (next-intl)
+
+- Files: `/messages/en.json` and `/messages/es.json`
+- Usage: `const t = useTranslations('namespace');`
+- Structure: Nested keys `{ "auth": { "login": { "title": "Sign in" } } }`
+- Always add both English and Spanish translations
+
+---
+
+## API Integration
+
+- Services in `/lib/` (e.g., auth.ts, api.ts)
+- Use `fetch` with proper error handling
+- Handle errors with toast notifications
+- Types from `@{{PROJECT_NAME}}/shared` package
+
+---
+
+## State Management
+
+- Use React hooks for local state
+- Global state: Context API or state management library of choice
+- Keep state management simple and predictable
+
+---
+
+## Performance
+
+- Use `loading.tsx` for loading states
+- Implement proper error boundaries
+- Lazy load heavy components when possible
+- Optimize images with Next.js Image component
+
+---
+
+## Common Mistakes to Avoid
+
+❌ DON'T use inline styles - only Tailwind classes
+❌ DON'T forget 'use client' on interactive components
+❌ DON'T use `any` type
+❌ DON'T mix Spanish and English in same file
+❌ DON'T create CSS modules - Tailwind only
+
+---
+
+## When Making Changes
+
+1. Read existing file structure first
+2. Follow established patterns
+3. Update translations if adding new text
+4. Run `pnpm run lint` to verify
+5. Run `pnpm run build` for final verification
+6. Check for TypeScript errors
+7. Ensure mobile responsiveness
+
+---
+
+## Priority Order for Edits
+
+1. Fix TypeScript errors
+2. Fix build errors
+3. Add missing 'use client' directives
+4. Improve accessibility
+5. Optimize performance
+6. Enhance UX
+
+---
+
+## Documentation & Communication
+
+- **All code comments and JSDoc must be in English**
+- Code itself (variable names, function names) in English
+- Translation files (en.json, es.json) in their respective languages
+- Add JSDoc comments for all functions/components:
+  - Description of purpose
+  - `@param` for each parameter
+  - `@returns` for return value
+  - `@example` for complex usage
+
+---
+
+## Backend API Guidelines
+
+- When creating new API routes, update Swagger documentation
+- Follow existing Swagger schema patterns
+- Include request/response examples
+- Document all query parameters, headers, and body fields
+
+---
+
+## Other Notes
+
+- ALWAYS prioritize accessibility (a11y)
+- AVOID using emojis in code comments or documentation
+- Update this file when project standards or patterns change

package/templates/.nvmrc

@@ -0,0 +1 @@
+v20.18.1

package/templates/.vscode/settings.json

@@ -0,0 +1,51 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "files.associations": {
+    "*.css": "tailwindcss"
+  },
+  "tailwindCSS.experimental.classRegex": [
+    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
+  ],
+  "editor.quickSuggestions": {
+    "strings": "on"
+  },
+  "files.exclude": {
+    "**/.git": true,
+    "**/.DS_Store": true,
+    "**/node_modules": true,
+    "**/.next": true,
+    "**/dist": true,
+    "**/build": true
+  },
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/.next": true,
+    "**/dist": true,
+    "**/build": true,
+    "**/pnpm-lock.yaml": true
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact",
+    "typescript",
+    "typescriptreact"
+  ]
+}