create-pnpm-custom-app 1.0.0

package/templates/apps/api/src/tests/health.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeAll, afterAll } from '@jest/globals';
+import { buildApp } from '../app.js';
+// import { connectMongo, disconnectMongo } from '../db/mongo.js';
+import type { FastifyInstance } from 'fastify';
+
+/**
+ * Example Test Suite
+ * 
+ * This file demonstrates how to write tests for your API endpoints.
+ * 
+ * @remarks
+ * Testing best practices:
+ * - Use descriptive test names
+ * - Test both success and error cases
+ * - Mock external dependencies
+ * - Clean up test data after each test
+ * - Use beforeAll/afterAll for setup/teardown
+ * 
+ * @example
+ * ```typescript
+ * describe('User API', () => {
+ *   let app: FastifyInstance;
+ * 
+ *   beforeAll(async () => {
+ *     await connectMongo(process.env.MONGODB_URI_TEST!);
+ *     app = await buildApp();
+ *   });
+ * 
+ *   afterAll(async () => {
+ *     await app.close();
+ *     await disconnectMongo();
+ *   });
+ * 
+ *   it('should create a new user', async () => {
+ *     const response = await app.inject({
+ *       method: 'POST',
+ *       url: '/users',
+ *       payload: {
+ *         email: 'test@example.com',
+ *         password: 'password123',
+ *         name: 'Test User',
+ *       },
+ *     });
+ * 
+ *     expect(response.statusCode).toBe(201);
+ *     expect(response.json()).toMatchObject({
+ *       email: 'test@example.com',
+ *       name: 'Test User',
+ *     });
+ *   });
+ * 
+ *   it('should return 400 for invalid email', async () => {
+ *     const response = await app.inject({
+ *       method: 'POST',
+ *       url: '/users',
+ *       payload: {
+ *         email: 'invalid-email',
+ *         password: 'password123',
+ *       },
+ *     });
+ * 
+ *     expect(response.statusCode).toBe(400);
+ *   });
+ * });
+ * ```
+ */
+
+describe('Health Check API', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await buildApp();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('should return health status', async () => {
+    const response = await app.inject({
+      method: 'GET',
+      url: '/health',
+    });
+
+    expect(response.statusCode).toBe(200);
+    const body = response.json();
+    expect(body).toHaveProperty('status', 'ok');
+    expect(body).toHaveProperty('timestamp');
+  });
+});

package/templates/apps/api/src/tests/helpers/test-helpers.ts

@@ -0,0 +1,40 @@
+/**
+ * Test Helpers
+ * 
+ * Utility functions to help with testing.
+ * 
+ * @example
+ * ```typescript
+ * // Create test data
+ * export function createTestUser(overrides = {}) {
+ *   return {
+ *     email: 'test@example.com',
+ *     password: 'password123',
+ *     name: 'Test User',
+ *     role: 'user',
+ *     ...overrides,
+ *   };
+ * }
+ * 
+ * // Generate JWT token for testing
+ * export function generateTestToken(userId: string, app: FastifyInstance) {
+ *   return app.jwt.sign({ id: userId });
+ * }
+ * 
+ * // Clean up test database
+ * export async function clearDatabase() {
+ *   const collections = mongoose.connection.collections;
+ *   for (const key in collections) {
+ *     await collections[key].deleteMany({});
+ *   }
+ * }
+ * ```
+ */
+
+export function generateRandomEmail(): string {
+  return `test-${Date.now()}-${Math.random().toString(36).substring(7)}@example.com`;
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/templates/apps/api/src/tests/mocks/mocks.ts

@@ -0,0 +1,29 @@
+/**
+ * Test Mocks
+ * 
+ * Mock data and functions for testing.
+ * 
+ * @example
+ * ```typescript
+ * // Mock user data
+ * export const mockUser = {
+ *   id: '507f1f77bcf86cd799439011',
+ *   email: 'test@example.com',
+ *   name: 'Test User',
+ *   role: 'user',
+ *   createdAt: new Date('2024-01-01'),
+ *   updatedAt: new Date('2024-01-01'),
+ * };
+ * 
+ * // Mock service response
+ * export const mockUserService = {
+ *   findUserById: jest.fn().mockResolvedValue(mockUser),
+ *   createUser: jest.fn().mockResolvedValue(mockUser),
+ * };
+ * ```
+ */
+
+export const mockHealthResponse = {
+  status: 'ok',
+  timestamp: '2024-01-01T00:00:00.000Z',
+};

package/templates/apps/api/src/tests/setup.ts

@@ -0,0 +1,11 @@
+/**
+ * Jest Test Setup
+ * 
+ * This file runs before any tests and sets up the test environment.
+ * It configures environment variables needed for testing.
+ */
+
+// Set test environment variables before any modules are loaded
+process.env.NODE_ENV = 'test';
+process.env.JWT_SECRET = 'test-secret-key-for-testing-only';
+process.env.MONGODB_URI = 'mongodb://localhost:27017/test-db';

package/templates/apps/api/src/types/fastify.d.ts

@@ -0,0 +1,44 @@
+import '@fastify/jwt';
+
+/**
+ * Extend Fastify types with custom properties
+ * 
+ * This file augments Fastify's type definitions to include custom properties
+ * like user authentication data from JWT.
+ * 
+ * @example
+ * ```typescript
+ * declare module '@fastify/jwt' {
+ *   interface FastifyJWT {
+ *     user: {
+ *       id: string;
+ *       email: string;
+ *       role: 'user' | 'admin';
+ *     };
+ *   }
+ * }
+ * ```
+ * 
+ * This allows TypeScript to recognize `request.user` in route handlers:
+ * ```typescript
+ * app.get('/profile', {
+ *   preHandler: [authenticate],
+ *   handler: async (request) => {
+ *     // TypeScript knows request.user has id, email, role
+ *     const userId = request.user.id;
+ *     return { userId };
+ *   },
+ * });
+ * ```
+ */
+
+declare module '@fastify/jwt' {
+  interface FastifyJWT {
+    user: {
+      id: string;
+      // Add your JWT payload properties here
+      // email?: string;
+      // role?: string;
+    };
+  }
+}

package/templates/apps/api/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/templates/apps/web/.env.example

@@ -0,0 +1,25 @@
+# ==================================================
+# API CONFIGURATION
+# ==================================================
+# URL of the backend API
+# Development: http://localhost:3002
+# Production: https://your-api-domain.com
+NEXT_PUBLIC_API_URL=http://localhost:3002
+
+# ==================================================
+# AUTHENTICATION (if using NextAuth or similar)
+# ==================================================
+# NEXTAUTH_URL=http://localhost:3000
+# NEXTAUTH_SECRET=your-secret-key-change-this
+
+# ==================================================
+# FEATURE FLAGS
+# ==================================================
+# NEXT_PUBLIC_FEATURE_ANALYTICS=false
+
+# ==================================================
+# THIRD-PARTY SERVICES
+# ==================================================
+# Add your API keys and secrets here
+# NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=
+# NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

package/templates/apps/web/.prettierignore

@@ -0,0 +1,7 @@
+node_modules
+.next
+build
+dist
+coverage
+.turbo
+pnpm-lock.yaml

package/templates/apps/web/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/templates/apps/web/app/ICONS.md

@@ -0,0 +1,42 @@
+# App Icons and Metadata
+
+This directory contains the app metadata files required by Next.js.
+
+## Required Icons
+
+Replace the default placeholder icons with your own branded images:
+
+### Social Media & SEO Images
+
+> The images shown below are NOT included with the boilerplate and must be added for a correct application experience. Maintain sizes.
+
+- **opengraph-image.png** (1200 x 630) - Open Graph image for social media sharing
+- **twitter-image.png** (1200 x 600) - Twitter/X card image
+
+### App Icons
+
+- **icon.svg** - Vector icon (already included, customize as needed)
+
+> The icons shown below are NOT included with the boilerplate and must be added for a correct application experience. Maintain sizes.
+
+- **icon.png** (512 x 512) - PNG fallback icon
+- **apple-icon.png** (180 x 180) - Apple touch icon for iOS devices
+- **favicon.ico** (48 x 48) - Browser favicon
+
+## Current Status
+
+The project includes `icon.svg` as a placeholder. You should replace it and add the missing images before deploying to production.
+
+## Generating Icons
+
+You can use tools like:
+
+- [Favicon Generator](https://realfavicongenerator.net/)
+- [PWA Asset Generator](https://github.com/elegantapp/pwa-asset-generator)
+- [Figma Export](https://www.figma.com/) for design assets
+
+## Next.js Metadata
+
+These files are automatically detected by Next.js and used in the app metadata. See:
+
+- <https://nextjs.org/docs/app/api-reference/file-conventions/metadata>

package/templates/apps/web/app/[locale]/(routes)/layout.tsx

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { Nav } from '@/app/components/layout/Nav.component';
+import { Footer } from '@/app/components/layout/Footer.component';
+
+export default function RoutesLayout({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <Nav />
+      <main className="min-h-screen">{children}</main>
+      <Footer />
+    </>
+  );
+}

package/templates/apps/web/app/[locale]/(routes)/page.tsx

@@ -0,0 +1,49 @@
+import { useTranslations } from 'next-intl';
+import Link from 'next/link';
+
+export default function HomePage() {
+  const t = useTranslations('home');
+
+  return (
+    <div className="container mx-auto px-4 py-16">
+      <div className="mx-auto max-w-3xl text-center">
+        <h1 className="text-4xl font-bold tracking-tight sm:text-5xl md:text-6xl">
+          {t('title')}
+        </h1>
+        <p className="mt-6 text-lg text-muted-foreground">{t('description')}</p>
+
+        <div className="mt-10 flex flex-col items-center gap-4 sm:flex-row sm:justify-center">
+          <a
+            href="https://github.com/{{GITHUB_USER}}/{{PROJECT_NAME}}"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex items-center justify-center rounded-md bg-primary px-6 py-3 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
+          >
+            View on GitHub
+          </a>
+        </div>
+
+        <div className="mt-16 grid gap-8 md:grid-cols-3">
+          <div className="rounded-lg border p-6">
+            <h3 className="text-lg font-semibold">Next.js 16</h3>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Latest Next.js with App Router and React Server Components
+            </p>
+          </div>
+          <div className="rounded-lg border p-6">
+            <h3 className="text-lg font-semibold">Fastify + MongoDB</h3>
+            <p className="mt-2 text-sm text-muted-foreground">
+              High-performance API with MongoDB database
+            </p>
+          </div>
+          <div className="rounded-lg border p-6">
+            <h3 className="text-lg font-semibold">pnpm Monorepo</h3>
+            <p className="mt-2 text-sm text-muted-foreground">
+              Efficient workspace management with shared packages
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/templates/apps/web/app/[locale]/[...not-found]/page.tsx

@@ -0,0 +1,8 @@
+export default function NotFoundCatchAll() {
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center p-4">
+      <h1 className="text-4xl font-bold">404</h1>
+      <p className="mt-2 text-muted-foreground">Page not found</p>
+    </div>
+  );
+}

package/templates/apps/web/app/[locale]/layout.tsx

@@ -0,0 +1,35 @@
+import React, { ReactNode } from 'react';
+import { notFound } from 'next/navigation';
+import { NextIntlClientProvider } from 'next-intl';
+import { getMessages } from 'next-intl/server';
+import { locales } from '@/i18n/config';
+
+export function generateStaticParams() {
+  return locales.map((locale) => ({ locale }));
+}
+
+export default async function LocaleLayout({
+  children,
+  params,
+}: {
+  children: ReactNode;
+  params: Promise<{ locale: string }>;
+}) {
+  // Validate locale
+  const resolvedParams = await params;
+  if (!locales.includes(resolvedParams.locale as any)) {
+    notFound();
+  }
+
+  const messages = await getMessages();
+
+  return (
+    <html lang={resolvedParams.locale}>
+      <body>
+        <NextIntlClientProvider messages={messages}>
+          {children}
+        </NextIntlClientProvider>
+      </body>
+    </html>
+  );
+}

package/templates/apps/web/app/[locale]/not-found.tsx

@@ -0,0 +1,12 @@
+import { useTranslations } from 'next-intl';
+
+export default function NotFound() {
+  const t = useTranslations();
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center p-4">
+      <h1 className="text-4xl font-bold">404</h1>
+      <p className="mt-2 text-muted-foreground">Page not found</p>
+    </div>
+  );
+}

package/templates/apps/web/app/components/layout/Footer.component.tsx

@@ -0,0 +1,30 @@
+import { useTranslations } from 'next-intl';
+import Link from 'next/link';
+
+export function Footer() {
+  const t = useTranslations('footer');
+  const currentYear = new Date().getFullYear();
+
+  return (
+    <footer className="border-t bg-background">
+      <div className="container mx-auto px-4 py-8">
+        <div className="flex flex-col items-center justify-between gap-4 md:flex-row">
+          <p className="text-sm text-muted-foreground">
+            {t('copyright', { year: currentYear })}
+          </p>
+
+          <div className="flex gap-6">
+            <a
+              href="https://github.com/{{GITHUB_USER}}/{{PROJECT_NAME}}"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-sm text-muted-foreground hover:text-foreground"
+            >
+              GitHub
+            </a>
+          </div>
+        </div>
+      </div>
+    </footer>
+  );
+}

package/templates/apps/web/app/components/layout/Nav.component.tsx

@@ -0,0 +1,34 @@
+import { useTranslations } from 'next-intl';
+import Link from 'next/link';
+
+export function Nav() {
+  const t = useTranslations('nav');
+
+  return (
+    <nav className="sticky top-0 z-50 border-b bg-background/95 backdrop-blur supports-backdrop-filter:bg-background/60">
+      <div className="container mx-auto flex h-16 items-center justify-between px-4">
+        <Link href="/" className="text-xl font-bold">
+          {{PROJECT_NAME}}
+        </Link>
+
+        <ul className="flex items-center gap-6">
+          <li>
+            <Link href="/" className="text-sm font-medium hover:text-primary">
+              {t('home')}
+            </Link>
+          </li>
+          <li>
+            <Link href="/about" className="text-sm font-medium hover:text-primary">
+              {t('about')}
+            </Link>
+          </li>
+          <li>
+            <Link href="/contact" className="text-sm font-medium hover:text-primary">
+              {t('contact')}
+            </Link>
+          </li>
+        </ul>
+      </div>
+    </nav>
+  );
+}

package/templates/apps/web/app/components/ui/README.md

@@ -0,0 +1,39 @@
+# UI Components
+
+This folder contains reusable UI components following the Atomic Design pattern.
+
+## Structure
+
+- **atoms/** - Basic building blocks (Button, Input, Typography, etc.)
+- **molecules/** - Combinations of atoms (Card, Modal, Form fields, etc.)
+
+## Guidelines
+
+1. All components should be in TypeScript
+2. Use Tailwind CSS for styling
+3. Interactive components need `'use client'` directive
+4. Add JSDoc comments for documentation
+5. Export components with `.component.tsx` suffix
+
+## Example Atom Component
+
+```tsx
+// Button.component.tsx
+interface ButtonProps {
+  variant?: 'primary' | 'secondary';
+  children: React.ReactNode;
+}
+
+export function Button({ variant = 'primary', children }: ButtonProps) {
+  const variants = {
+    primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+    secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/90',
+  };
+
+  return (
+    <button className={`rounded-md px-4 py-2 font-medium transition-colors ${variants[variant]}`}>
+      {children}
+    </button>
+  );
+}
+```

package/templates/apps/web/app/components/ui/atoms/README.md

@@ -0,0 +1,55 @@
+# UI Atoms
+
+Basic, indivisible UI components (Atomic Design pattern).
+
+## Purpose
+
+Atoms are the smallest building blocks of the UI. They cannot be broken down further without losing their meaning.
+
+## Examples
+
+- Buttons
+- Input fields
+- Labels
+- Icons
+- Badges
+
+## Component Template
+
+```tsx
+// Button.component.tsx
+import { forwardRef } from 'react';
+import { cn } from '@/lib/utils';
+
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ variant = 'primary', size = 'md', className, children, ...props }, ref) => {
+    return (
+      <button
+        ref={ref}
+        className={cn(
+          'inline-flex items-center justify-center rounded-md font-medium transition-colors',
+          {
+            'bg-primary text-primary-foreground hover:bg-primary/90': variant === 'primary',
+            'bg-secondary text-secondary-foreground hover:bg-secondary/90': variant === 'secondary',
+            'hover:bg-accent hover:text-accent-foreground': variant === 'ghost',
+            'h-8 px-3 text-sm': size === 'sm',
+            'h-10 px-4': size === 'md',
+            'h-12 px-6 text-lg': size === 'lg',
+          },
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </button>
+    );
+  }
+);
+
+Button.displayName = 'Button';
+```

package/templates/apps/web/app/components/ui/molecules/README.md

@@ -0,0 +1,51 @@
+# UI Molecules
+
+Composite UI components made of atoms (Atomic Design pattern).
+
+## Purpose
+
+Molecules are groups of atoms that work together as a unit.
+
+## Examples
+
+- Form fields (label + input + error message)
+- Search bar (input + button)
+- Card header (title + description)
+- Avatar with name
+
+## Component Template
+
+```tsx
+// FormField.component.tsx
+import { forwardRef } from 'react';
+import { cn } from '@/lib/utils';
+
+interface FormFieldProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  label: string;
+  error?: string;
+  helperText?: string;
+}
+
+export const FormField = forwardRef<HTMLInputElement, FormFieldProps>(
+  ({ label, error, helperText, className, ...props }, ref) => {
+    return (
+      <div className="space-y-2">
+        <label className="text-sm font-medium">{label}</label>
+        <input
+          ref={ref}
+          className={cn(
+            'w-full rounded-md border px-3 py-2',
+            error && 'border-destructive',
+            className
+          )}
+          {...props}
+        />
+        {error && <p className="text-sm text-destructive">{error}</p>}
+        {helperText && <p className="text-sm text-muted-foreground">{helperText}</p>}
+      </div>
+    );
+  }
+);
+
+FormField.displayName = 'FormField';
+```