create-pnpm-custom-app 1.0.0

package/templates/apps/api/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@{{PROJECT_NAME}}/api",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "NODE_ENV=test node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "NODE_ENV=test node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+    "test:coverage": "NODE_ENV=test node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.1",
+    "@fastify/jwt": "^9.0.1",
+    "@fastify/multipart": "^9.0.1",
+    "@fastify/rate-limit": "^10.1.1",
+    "@fastify/swagger": "^9.3.0",
+    "@fastify/swagger-ui": "^5.0.1",
+    "@{{PROJECT_NAME}}/shared": "workspace:*",
+    "bcrypt": "^5.1.1",
+    "dotenv": "^16.4.7",
+    "fastify": "^5.2.0",
+    "mongoose": "^8.9.3",
+    "pino": "^9.5.0",
+    "pino-pretty": "^13.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@jest/globals": "^29.7.0",
+    "@types/bcrypt": "^5.0.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.5",
+    "@types/supertest": "^6.0.2",
+    "eslint": "^9.18.0",
+    "jest": "^29.7.0",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.21.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/templates/apps/api/src/app.ts

@@ -0,0 +1,121 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import cors from '@fastify/cors';
+import jwt from '@fastify/jwt';
+import rateLimit from '@fastify/rate-limit';
+import multipart from '@fastify/multipart';
+import swagger from '@fastify/swagger';
+import swaggerUi from '@fastify/swagger-ui';
+import routes from './routes/routes.js';
+import config from './config/config.js';
+import { getLoggerConfig } from './config/logger.js';
+
+/**
+ * Registers CORS middleware
+ */
+function registerCors(app: FastifyInstance) {
+  app.register(cors, {
+    origin: config.corsOrigin,
+    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+    credentials: true,
+  });
+}
+
+/**
+ * Registers JWT authentication plugin
+ */
+function registerJWT(app: FastifyInstance) {
+  if (!config.jwtSecret) {
+    throw new Error(
+      'JWT_SECRET is not defined. Please copy apps/api/.env.example to apps/api/.env and set JWT_SECRET'
+    );
+  }
+  
+  app.register(jwt, {
+    secret: config.jwtSecret,
+    sign: {
+      expiresIn: '24h',
+    },
+  });
+}
+
+/**
+ * Registers rate limiting plugin
+ */
+function registerRateLimit(app: FastifyInstance) {
+  if (config.env === 'test') {
+    return;
+  }
+  
+  app.register(rateLimit, {
+    global: false,
+  });
+}
+
+/**
+ * Registers Swagger documentation
+ */
+async function registerSwagger(app: FastifyInstance) {
+  await app.register(swagger, {
+    openapi: {
+      openapi: '3.0.0',
+      info: {
+        title: '{{PROJECT_NAME}} API',
+        description: 'API documentation for {{PROJECT_NAME}}',
+        version: '1.0.0',
+      },
+      servers: [
+        {
+          url: `http://localhost:${config.port}`,
+          description: 'Development server',
+        },
+      ],
+      tags: [
+        { name: 'Health', description: 'Health check endpoints' },
+      ],
+    },
+  });
+
+  await app.register(swaggerUi, {
+    routePrefix: '/docs',
+    uiConfig: {
+      docExpansion: 'list',
+      deepLinking: true,
+    },
+    staticCSP: true,
+  });
+}
+
+/**
+ * Registers file upload support
+ */
+function registerMultipart(app: FastifyInstance) {
+  app.register(multipart, {
+    limits: {
+      fileSize: 10 * 1024 * 1024, // 10MB
+    },
+  });
+}
+
+/**
+ * Builds and configures the Fastify application
+ * 
+ * @returns Configured Fastify instance
+ */
+export async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify({
+    logger: getLoggerConfig(),
+  });
+
+  // Register plugins
+  registerCors(app);
+  registerJWT(app);
+  registerRateLimit(app);
+  registerMultipart(app);
+  await registerSwagger(app);
+
+  // Register routes
+  await app.register(routes);
+
+  return app;
+}

package/templates/apps/api/src/config/config.ts

@@ -0,0 +1,38 @@
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+interface Config {
+  env: string;
+  port: number;
+  mongoUri: string;
+  corsOrigin: string;
+  bcryptRounds: number;
+  jwtSecret?: string;
+}
+
+const env = process.env.NODE_ENV ?? 'development';
+
+/**
+ * Application configuration loaded from environment variables
+ * 
+ * @remarks
+ * Required environment variables:
+ * - MONGODB_URI: MongoDB connection string
+ * - JWT_SECRET: Secret for JWT token signing
+ * 
+ * Optional environment variables:
+ * - PORT: Server port (default: 3002)
+ * - CORS_ORIGIN: Allowed CORS origin (default: *)
+ * - BCRYPT_ROUNDS: Bcrypt hashing rounds (default: 10, 4 in test)
+ */
+const config: Config = {
+  env,
+  port: Number(process.env.PORT) || 3002,
+  mongoUri: process.env.MONGODB_URI || '',
+  corsOrigin: process.env.CORS_ORIGIN || '*',
+  bcryptRounds: Number(process.env.BCRYPT_ROUNDS || (env === 'test' ? 4 : 10)),
+  jwtSecret: process.env.JWT_SECRET,
+};
+
+export default config;

package/templates/apps/api/src/config/logger.ts

@@ -0,0 +1,57 @@
+import config from './config.js';
+import pino from 'pino';
+
+/**
+ * Returns logger configuration based on environment
+ * 
+ * @returns Logger config or false to disable logging in test
+ * 
+ * @remarks
+ * - Test/E2E: Logging disabled
+ * - Production: Structured JSON logs at 'info' level
+ * - Development: Pretty-printed colored logs at 'debug' level
+ */
+export function getLoggerConfig(): false | object {
+  if (config.env === 'test' || process.env.E2E_MODE === 'true') {
+    return false;
+  }
+
+  if (config.env === 'production') {
+    return {
+      level: 'info',
+      serializers: {
+        req: (req: { method: string; url: string }) => ({
+          method: req.method,
+          url: req.url,
+        }),
+        res: (res: { statusCode: number }) => ({
+          statusCode: res.statusCode,
+        }),
+      },
+    };
+  }
+
+  return {
+    level: 'debug',
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true,
+        translateTime: 'HH:MM:ss',
+        ignore: 'pid,hostname,reqId',
+      },
+    },
+  };
+}
+
+/**
+ * Application-wide logger instance using Pino
+ * 
+ * @example
+ * ```typescript
+ * logger.info({ userId: '123' }, 'User logged in');
+ * logger.error({ error }, 'Failed to process request');
+ * logger.debug({ data }, 'Processing data');
+ * ```
+ */
+export const logger = pino(getLoggerConfig() || { level: 'silent' });

package/templates/apps/api/src/db/mongo.ts

@@ -0,0 +1,30 @@
+import mongoose from 'mongoose';
+
+/**
+ * Establishes connection to MongoDB
+ * 
+ * @param uri - MongoDB connection URI
+ * @returns Mongoose connection object
+ * @throws Error if connection fails
+ * 
+ * @example
+ * ```typescript
+ * await connectMongo('mongodb://localhost:27017/mydb');
+ * ```
+ */
+export async function connectMongo(uri: string) {
+  mongoose.set('strictQuery', true);
+  await mongoose.connect(uri);
+  return mongoose.connection;
+}
+
+/**
+ * Disconnects from MongoDB
+ * 
+ * @remarks
+ * Call this when shutting down the application or when database
+ * connection is no longer needed.
+ */
+export async function disconnectMongo() {
+  await mongoose.disconnect();
+}

package/templates/apps/api/src/index.ts

@@ -0,0 +1,40 @@
+import { buildApp } from './app.js';
+import { connectMongo } from './db/mongo.js';
+import config from './config/config.js';
+
+/**
+ * Starts the API server
+ * 
+ * - Connects to MongoDB
+ * - Starts the Fastify server on configured port
+ * - Logs server URL when ready
+ */
+async function start() {
+  const app = await buildApp();
+  
+  try {
+    if (!config.mongoUri) {
+      app.log.error(
+        'MONGODB_URI is not defined. Please copy apps/api/.env.example to apps/api/.env and set MONGODB_URI'
+      );
+      process.exit(1);
+    }
+
+    await connectMongo(config.mongoUri);
+    app.log.info('MongoDB connected successfully');
+
+    await app.listen({ port: config.port, host: '0.0.0.0' });
+    app.log.info(`🚀 API server listening on http://localhost:${config.port}`);
+    app.log.info(`📚 API documentation available at http://localhost:${config.port}/docs`);
+  } catch (error) {
+    app.log.error(error);
+    process.exit(1);
+  }
+}
+
+// Only start server if not in test environment
+if (config.env !== 'test') {
+  start();
+}
+
+export { buildApp };

package/templates/apps/api/src/middlewares/middleware.ts

@@ -0,0 +1,75 @@
+import { FastifyRequest, FastifyReply } from 'fastify';
+
+/**
+ * Example Middleware
+ * 
+ * Middlewares (preHandlers in Fastify) run before route handlers.
+ * They can modify requests, perform authentication, logging, etc.
+ * 
+ * @remarks
+ * Common middleware uses:
+ * - Authentication/Authorization
+ * - Request validation
+ * - Logging
+ * - Rate limiting
+ * - Request transformation
+ * 
+ * @example
+ * ```typescript
+ * // Authentication Middleware
+ * export async function authenticate(
+ *   request: FastifyRequest,
+ *   reply: FastifyReply
+ * ) {
+ *   try {
+ *     await request.jwtVerify();
+ *   } catch (err) {
+ *     reply.status(401).send({ error: 'Unauthorized' });
+ *   }
+ * }
+ * 
+ * // Admin Check Middleware
+ * export async function requireAdmin(
+ *   request: FastifyRequest,
+ *   reply: FastifyReply
+ * ) {
+ *   if (request.user?.role !== 'admin') {
+ *     reply.status(403).send({ error: 'Forbidden: Admin access required' });
+ *   }
+ * }
+ * ```
+ * 
+ * Usage in routes:
+ * ```typescript
+ * app.get('/admin/users', {
+ *   preHandler: [authenticate, requireAdmin],
+ *   handler: async (request, reply) => {
+ *     // Only authenticated admins reach here
+ *   },
+ * });
+ * ```
+ * 
+ * Or register globally:
+ * ```typescript
+ * app.addHook('preHandler', authenticate);
+ * ```
+ */
+
+export async function exampleMiddleware(
+  request: FastifyRequest,
+  _reply: FastifyReply
+) {
+  // Example: Log all requests
+  request.log.info(`${request.method} ${request.url}`);
+}
+
+export async function authenticate(
+  request: FastifyRequest,
+  reply: FastifyReply
+) {
+  try {
+    await request.jwtVerify();
+  } catch {
+    reply.status(401).send({ error: 'Unauthorized' });
+  }
+}

package/templates/apps/api/src/models/example.model.ts

@@ -0,0 +1,89 @@
+import mongoose, { Schema, Document } from 'mongoose';
+
+/**
+ * Example Mongoose Model
+ * 
+ * Models define the structure of documents in MongoDB collections.
+ * They provide an interface for database operations.
+ * 
+ * @remarks
+ * Model best practices:
+ * - Define TypeScript interfaces for type safety
+ * - Use Mongoose Schema for MongoDB structure
+ * - Add indexes for frequently queried fields
+ * - Include timestamps for audit trail
+ * - Add schema validation
+ * 
+ * @example
+ * ```typescript
+ * // User Model Example
+ * import mongoose, { Schema, Document } from 'mongoose';
+ * 
+ * export interface IUser extends Document {
+ *   email: string;
+ *   password: string;
+ *   name: string;
+ *   role: 'user' | 'admin';
+ *   createdAt: Date;
+ *   updatedAt: Date;
+ * }
+ * 
+ * const UserSchema = new Schema<IUser>(
+ *   {
+ *     email: {
+ *       type: String,
+ *       required: true,
+ *       unique: true,
+ *       lowercase: true,
+ *       trim: true,
+ *     },
+ *     password: {
+ *       type: String,
+ *       required: true,
+ *     },
+ *     name: {
+ *       type: String,
+ *       required: true,
+ *       trim: true,
+ *     },
+ *     role: {
+ *       type: String,
+ *       enum: ['user', 'admin'],
+ *       default: 'user',
+ *     },
+ *   },
+ *   {
+ *     timestamps: true, // Adds createdAt and updatedAt
+ *   }
+ * );
+ * 
+ * // Add indexes
+ * UserSchema.index({ email: 1 });
+ * 
+ * export const User = mongoose.model<IUser>('User', UserSchema);
+ * ```
+ */
+
+export interface IExample extends Document {
+  name: string;
+  description?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const ExampleSchema = new Schema<IExample>(
+  {
+    name: {
+      type: String,
+      required: true,
+    },
+    description: {
+      type: String,
+    },
+  },
+  {
+    timestamps: true,
+  }
+);
+
+export const Example = mongoose.model<IExample>('Example', ExampleSchema);

package/templates/apps/api/src/routes/routes.ts

@@ -0,0 +1,54 @@
+import { FastifyInstance } from 'fastify';
+
+/**
+ * Registers all API routes
+ * 
+ * @param app - Fastify instance
+ * 
+ * @remarks
+ * This function registers all route modules.
+ * Add your route registrations here as you create new endpoints.
+ * 
+ * @example
+ * ```typescript
+ * // Register a new route module
+ * await app.register(userRoutes, { prefix: '/users' });
+ * ```
+ */
+export default async function routes(app: FastifyInstance) {
+  // Health check endpoint
+  app.get('/health', {
+    schema: {
+      tags: ['Health'],
+      description: 'Health check endpoint',
+      response: {
+        200: {
+          description: 'Server is healthy',
+          type: 'object',
+          properties: {
+            status: { type: 'string' },
+            timestamp: { type: 'string' },
+          },
+        },
+      },
+    },
+    handler: async () => {
+      return {
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+      };
+    },
+  });
+
+  // Example protected route (uncomment when you have auth middleware)
+  // app.get('/protected', {
+  //   preHandler: [app.authenticate], // JWT verification middleware
+  //   handler: async (request) => {
+  //     return { message: 'You are authenticated!', user: request.user };
+  //   },
+  // });
+
+  // Register your route modules here:
+  // await app.register(authRoutes, { prefix: '/auth' });
+  // await app.register(userRoutes, { prefix: '/users' });
+}

package/templates/apps/api/src/schemas/swagger.schema.ts

@@ -0,0 +1,58 @@
+/**
+ * Swagger Schema Definitions
+ * 
+ * This file contains reusable schema definitions for Swagger/OpenAPI documentation.
+ * 
+ * @remarks
+ * - Define request/response schemas here
+ * - Use these schemas in your route definitions
+ * - Keep schemas organized by feature/entity
+ * 
+ * @example
+ * ```typescript
+ * export const UserSchema = {
+ *   type: 'object',
+ *   properties: {
+ *     id: { type: 'string' },
+ *     email: { type: 'string' },
+ *     name: { type: 'string' },
+ *   },
+ *   required: ['id', 'email', 'name'],
+ * };
+ * 
+ * export const CreateUserSchema = {
+ *   type: 'object',
+ *   properties: {
+ *     email: { type: 'string' },
+ *     password: { type: 'string' },
+ *     name: { type: 'string' },
+ *   },
+ *   required: ['email', 'password', 'name'],
+ * };
+ * ```
+ * 
+ * Usage in routes:
+ * ```typescript
+ * app.post('/users', {
+ *   schema: {
+ *     body: CreateUserSchema,
+ *     response: {
+ *       201: UserSchema,
+ *     },
+ *   },
+ *   handler: async (request, reply) => {
+ *     // ...
+ *   },
+ * });
+ * ```
+ */
+
+export const HealthCheckSchema = {
+  type: 'object',
+  properties: {
+    status: { type: 'string' },
+    timestamp: { type: 'string' },
+  },
+};
+
+// Add your schemas here

package/templates/apps/api/src/services/example.service.ts

@@ -0,0 +1,63 @@
+/**
+ * Example Service
+ * 
+ * Services contain business logic and interact with models/database.
+ * They are called by route handlers and keep routes thin.
+ * 
+ * @remarks
+ * Service responsibilities:
+ * - Business logic implementation
+ * - Data validation
+ * - Database operations via models
+ * - Error handling
+ * - Data transformation
+ * 
+ * @example
+ * ```typescript
+ * // User Service Example
+ * import bcrypt from 'bcrypt';
+ * import { User } from '../models/user.model.js';
+ * 
+ * export class UserService {
+ *   async createUser(email: string, password: string, name: string) {
+ *     const hashedPassword = await bcrypt.hash(password, 10);
+ *     const user = await User.create({
+ *       email,
+ *       password: hashedPassword,
+ *       name,
+ *     });
+ *     return user;
+ *   }
+ * 
+ *   async findUserByEmail(email: string) {
+ *     return User.findOne({ email });
+ *   }
+ * 
+ *   async findUserById(id: string) {
+ *     return User.findById(id);
+ *   }
+ * }
+ * 
+ * export const userService = new UserService();
+ * ```
+ * 
+ * Usage in routes:
+ * ```typescript
+ * import { userService } from '../services/user.service.js';
+ * 
+ * app.post('/users', async (request, reply) => {
+ *   const { email, password, name } = request.body;
+ *   const user = await userService.createUser(email, password, name);
+ *   reply.status(201).send(user);
+ * });
+ * ```
+ */
+
+export class ExampleService {
+  async doSomething() {
+    // Your business logic here
+    return { message: 'Example service method' };
+  }
+}
+
+export const exampleService = new ExampleService();