stackkit 0.2.7 → 0.2.9

package/templates/express/package.json

@@ -6,27 +6,33 @@
   "scripts": {
     "dev": "tsx watch src/server.ts",
     "build": "tsc",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
+    "lint": "eslint ./src/**/*",
+    "lint:fix": "eslint ./src/**/* --fix",
     "start": "node dist/server.js"
   },
   "dependencies": {
+    "cookie-parser": "^1.4.7",
     "cors": "^2.8.5",
     "dotenv": "^17.2.3",
     "express": "^5.2.1",
     "helmet": "^8.1.0",
+    "http-status": "^2.1.0",
     "morgan": "^1.10.1",
-    "express-rate-limit": "^6.10.0"
+    "express-rate-limit": "^6.10.0",
+    "qs": "^6.14.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/cookie-parser": "^1.4.10",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/morgan": "^1.9.10",
     "@types/node": "^25.0.8",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
+    "@types/qs": "^6.14.0",
     "eslint": "^9.39.2",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0"
   }
 }

package/templates/express/src/app.ts

@@ -1,20 +1,28 @@
+import cookieParser from "cookie-parser";
 import express, { Application, Request, Response } from "express";
+import helmet from "helmet";
+import qs from "qs";
 import { cors } from "./config/cors";
-import { helmet } from "./config/helmet";
 import { logger } from "./config/logger";
 import { limiter } from "./config/rate-limit";
 import { apiRoutes } from "./routes";
-import { errorHandler } from "./shared/middlewares/error.middleware";
+import { globalErrorHandler } from "./shared/middlewares/error.middleware";
 import { notFound } from "./shared/middlewares/not-found.middleware";
 
 // app initialization
 const app: Application = express();
-app.use(express.json());
 
-app.use(helmet);
+// app settings
+app.set("query parser", (str: string) => qs.parse(str));
+
+// middlewares
+app.use(express.json());
+app.use(helmet());
 app.use(logger);
 app.use(cors);
 app.use(limiter);
+app.use(cookieParser());
+app.use(express.urlencoded({ extended: true }));
 
 // trust proxy when behind proxies (load balancers)
 if (process.env.NODE_ENV === "production") {
@@ -33,12 +41,12 @@ app.get("/", (_req: Request, res: Response) => {
 });
 
 // API routes
-app.use("/api", apiRoutes);
+app.use("/api/v1", apiRoutes);
 
 // unhandled routes
 app.use(notFound);
 
 // Global error handler
-app.use(errorHandler);
+app.use(globalErrorHandler);
 
-export default app;
+export { app };

package/templates/express/src/config/cors.ts

@@ -1,12 +1,13 @@
 import createCors from "cors";
-import { env } from "./env";
+import { envVars } from "./env";
 
-const origin = env.isProduction
-  ? process.env.CORS_ORIGIN
-    ? process.env.CORS_ORIGIN.split(",").map((s) => s.trim())
-    : false
-  : true;
+const origin = [envVars.FRONTEND_URL as string, "http://localhost:3000"];
 
-const cors = createCors({ origin });
+const cors = createCors({
+  origin,
+  credentials: true,
+  methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+  allowedHeaders: ["Content-Type", "Authorization"],
+});
 
 export { cors };

package/templates/express/src/config/env.ts

@@ -1,12 +1,33 @@
 import dotenv from "dotenv";
+import status from "http-status";
 import path from "path";
+import { AppError } from "../shared/errors/app-error";
 
 dotenv.config({ path: path.join(process.cwd(), ".env") });
 
-const env = {
-  port: Number(process.env.PORT) || 3000,
-  node_env: process.env.NODE_ENV || "development",
-  isProduction: (process.env.NODE_ENV || "development") === "production",
+interface EnvConfig {
+  NODE_ENV: string;
+  PORT: string;
+  FRONTEND_URL?: string;
+}
+
+const loadEnvVars = (): EnvConfig => {
+  const requiredEnvVars = ["NODE_ENV", "PORT", "FRONTEND_URL"];
+
+  requiredEnvVars.forEach((varName) => {
+    if (!process.env[varName]) {
+      throw new AppError(
+        status.INTERNAL_SERVER_ERROR,
+        `Environment variable ${varName} is required but not set in .env file.`,
+      );
+    }
+  });
+
+  return {
+    NODE_ENV: process.env.NODE_ENV as string,
+    PORT: process.env.PORT as string,
+    FRONTEND_URL: process.env.FRONTEND_URL as string,
+  };
 };
 
-export { env };
+export const envVars = loadEnvVars();

package/templates/express/src/config/logger.ts

@@ -1,6 +1,6 @@
 import morgan from "morgan";
-import { env } from "./env";
+import { envVars } from "./env";
 
-const logger = env.isProduction ? morgan("combined") : morgan("dev");
+const logger = envVars.NODE_ENV === "production" ? morgan("combined") : morgan("dev");
 
 export { logger };

package/templates/express/src/config/rate-limit.ts

@@ -1,9 +1,9 @@
 import rateLimit from "express-rate-limit";
-import { env } from "./env";
+import { envVars } from "./env";
 
 const limiter = rateLimit({
   windowMs: 15 * 60 * 1000, // 15 minutes
-  max: env.isProduction ? 100 : 1000, // limit each IP
+  max: envVars.NODE_ENV === "production" ? 100 : 1000, // limit each IP
   standardHeaders: true,
   legacyHeaders: false,
 });

package/templates/express/src/modules/health/health.controller.ts

@@ -1,17 +1,19 @@
-import { NextFunction, Request, Response } from "express";
+import { Request, Response } from "express";
+import { catchAsync } from "../../shared/utils/catch-async";
+import { sendResponse } from "../../shared/utils/send-response";
 
-const health = async (_req: Request, res: Response, next: NextFunction) => {
-  try {
-    res.status(200).json({
-      success: true,
-      message: "API is healthy!",
+const health = catchAsync(async (_req: Request, res: Response) => {
+
+  sendResponse(res, {
+    status: 200,
+    success: true,
+    message: "Health test route is working!",
+    data: {
       timestamp: new Date().toISOString(),
       version: "1.0.0",
-    });
-  } catch (error) {
-    next(error);
-  }
-};
+    },
+  });
+});
 
 export const healthController = {
   health,

package/templates/express/src/routes/index.ts

@@ -2,11 +2,6 @@ import { Router } from "express";
 import { healthRoutes } from "../modules/health/health.route";
 const router = Router();
 
-// versioned API
-const v1 = Router();
-
-v1.use("/health", healthRoutes);
-
-router.use("/v1", v1);
+router.use("/health", healthRoutes);
 
 export const apiRoutes = router;

package/templates/express/src/server.ts

@@ -1,14 +1,14 @@
-import app from "./app";
-import { env } from "./config/env";
+import { app } from "./app";
+import { envVars } from "./config/env";
 
-async function startServer() {
-  const port = env.port;
-  app.listen(port, () => {
-    console.log(`Server is running on http://localhost:${port}`);
-  });
-}
+const bootstrap = async () => {
+  try {
+    app.listen(envVars.PORT, () => {
+      console.log(`Server is running on http://localhost:${envVars.PORT}`);
+    });
+  } catch (error) {
+    console.error("Failed to start server:", error);
+  }
+};
 
-startServer().catch((err) => {
-  console.error("Failed to start server:", err);
-  process.exit(1);
-});
+bootstrap();

package/templates/express/src/shared/errors/app-error.ts

@@ -0,0 +1,16 @@
+class AppError extends Error {
+  public statusCode: number;
+
+  constructor(statusCode: number, message: string, stack = "") {
+    super(message);
+    this.statusCode = statusCode;
+
+    if (stack) {
+      this.stack = stack;
+    } else {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+export { AppError };

package/templates/express/src/shared/middlewares/error.middleware.ts

@@ -1,18 +1,160 @@
-import { NextFunction, Request, Response } from "express";
-import { env } from "../../config/env";
+import { ErrorRequestHandler } from "express";
+import status from "http-status";
+import { envVars } from "../../config/env";
+import ApiError from "../errors/api-error";
+import { AppError } from "../errors/app-error";
 
-export const errorHandler = (err: any, _req: Request, res: Response, _: NextFunction) => {
-  const statusCode = err.status || 500;
-  const errorMessage = err?.message || "Internal server error!";
+type ErrorSource = {
+  path: string;
+  message: string;
+};
 
-  const payload: any = {
-    success: false,
-    message: errorMessage,
-  };
+type ErrorResponse = {
+  success: false;
+  message: string;
+  errorSources: ErrorSource[];
+  stack?: string;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === "object" && value !== null;
+};
+
+const toErrorSource = (value: unknown): ErrorSource | null => {
+  if (!isRecord(value)) return null;
+
+  const message = typeof value.message === "string" ? value.message : "Unknown error";
+  const path =
+    typeof value.path === "string"
+      ? value.path
+      : typeof value.field === "string"
+        ? value.field
+        : "";
+
+  return { path, message };
+};
+
+const getStatusCode = (value: unknown): number | null => {
+  if (!isRecord(value)) return null;
+
+  const statusCodeCandidate =
+    typeof value.statusCode === "number"
+      ? value.statusCode
+      : typeof value.status === "number"
+        ? value.status
+        : null;
 
-  if (!env.isProduction) {
-    payload.errors = err?.stack || err;
+  if (
+    typeof statusCodeCandidate === "number" &&
+    Number.isInteger(statusCodeCandidate) &&
+    statusCodeCandidate >= 400 &&
+    statusCodeCandidate <= 599
+  ) {
+    return statusCodeCandidate;
   }
 
-  res.status(statusCode).json(payload);
+  return null;
 };
+
+const isJsonParseError = (value: unknown): value is SyntaxError => {
+  if (!(value instanceof SyntaxError)) return false;
+  if (!isRecord(value)) return false;
+
+  return "body" in value;
+};
+
+const isZodLikeError = (
+  value: unknown,
+): value is {
+  issues: Array<{ path: Array<string | number>; message: string }>;
+  stack?: string;
+} => {
+  if (!isRecord(value)) return false;
+  if (!Array.isArray(value.issues)) return false;
+
+  return value.issues.every((issue) => {
+    if (!isRecord(issue)) return false;
+    if (!Array.isArray(issue.path)) return false;
+    if (typeof issue.message !== "string") return false;
+
+    return issue.path.every(
+      (segment) => typeof segment === "string" || typeof segment === "number",
+    );
+  });
+};
+
+const errorHandler: ErrorRequestHandler = (err, _req, res) => {
+  const isDevelopment = envVars.NODE_ENV === "development";
+
+  if (isDevelopment) {
+    console.error("Global Error Handler:", err);
+  }
+
+  let errorSources: ErrorSource[] = [];
+  let statusCode: number = status.INTERNAL_SERVER_ERROR;
+  let message = "Internal Server Error";
+  let stack: string | undefined;
+
+  if (isZodLikeError(err)) {
+    statusCode = status.BAD_REQUEST;
+    message = "Validation Error";
+    errorSources = err.issues.map((issue) => ({
+      path: issue.path.join("."),
+      message: issue.message,
+    }));
+    stack = err.stack;
+  } else if (err instanceof AppError || err instanceof ApiError) {
+    statusCode = err.statusCode;
+    message = err.message;
+    stack = err.stack;
+    errorSources = [{ path: "", message: err.message }];
+  } else if (isJsonParseError(err)) {
+    statusCode = status.BAD_REQUEST;
+    message = "Invalid JSON payload";
+    stack = err.stack;
+    errorSources = [{ path: "body", message }];
+  } else if (err instanceof Error) {
+    statusCode = getStatusCode(err) ?? status.INTERNAL_SERVER_ERROR;
+    message = err.message || message;
+    stack = err.stack;
+    errorSources = [{ path: "", message }];
+  } else if (isRecord(err)) {
+    statusCode = getStatusCode(err) ?? status.INTERNAL_SERVER_ERROR;
+
+    if (typeof err.message === "string" && err.message.length > 0) {
+      message = err.message;
+    }
+
+    const sources: ErrorSource[] = [];
+    if (Array.isArray(err.errorSources)) {
+      err.errorSources.forEach((source) => {
+        const normalized = toErrorSource(source);
+        if (normalized) {
+          sources.push(normalized);
+        }
+      });
+    }
+
+    if (Array.isArray(err.errors)) {
+      err.errors.forEach((source) => {
+        const normalized = toErrorSource(source);
+        if (normalized) {
+          sources.push(normalized);
+        }
+      });
+    }
+
+    errorSources = sources.length > 0 ? sources : [{ path: "", message: String(message) }];
+  }
+
+  const errorResponse: ErrorResponse = {
+    success: false,
+    message,
+    errorSources,
+    stack: isDevelopment ? stack : undefined,
+  };
+
+  res.status(statusCode).json(errorResponse);
+};
+
+export const globalErrorHandler = errorHandler;

package/templates/express/src/shared/middlewares/not-found.middleware.ts

@@ -1,7 +1,8 @@
 import { Request, Response } from "express";
+import status from "http-status";
 
 export function notFound(req: Request, res: Response) {
-  res.status(404).json({
+  res.status(status.NOT_FOUND).json({
     message: `Can't find ${req.originalUrl} on this server!`,
     path: req.originalUrl,
     date: Date(),

package/templates/express/src/shared/utils/catch-async.ts

@@ -0,0 +1,11 @@
+import { NextFunction, Request, RequestHandler, Response } from "express";
+
+export const catchAsync = (fn: RequestHandler) => {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await fn(req, res, next);
+    } catch (error: unknown) {
+      next(error);
+    }
+  };
+};

package/templates/express/src/shared/utils/pagination.ts

@@ -1,4 +1,9 @@
-export function getPagination(query: any) {
+type PaginationQuery = {
+  page?: string | number;
+  limit?: string | number;
+};
+
+export function getPagination(query: PaginationQuery) {
   const page = Math.max(1, parseInt(String(query.page || "1"), 10) || 1);
   const limit = Math.min(100, parseInt(String(query.limit || "10"), 10) || 10);
   const skip = (page - 1) * limit;

package/templates/express/src/shared/utils/send-response.ts

@@ -0,0 +1,25 @@
+import { Response } from "express";
+
+interface IResponseData<T> {
+  status: number;
+  success: boolean;
+  message: string;
+  data?: T;
+  meta?: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+export const sendResponse = <T>(res: Response, responseData: IResponseData<T>) => {
+  const { status, success, message, data, meta } = responseData;
+
+  res.status(status).json({
+    success,
+    message,
+    data,
+    meta,
+  });
+};

package/templates/nextjs/lib/env.ts

@@ -1,8 +1,19 @@
-export const env = {
-  app: {
-    url: process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000",
-  },
-
-  isDev: process.env.NODE_ENV === "development",
-  isProd: process.env.NODE_ENV === "production",
-} as const;
+interface EnvVars {
+  APP_URL: string;
+}
+
+const loadEnvVars = (): EnvVars => {
+  const requiredEnvVars = [""];
+
+  requiredEnvVars.forEach((varName) => {
+    if (!process.env[varName]) {
+      throw new Error(`Environment variable ${varName} is required but not defined.`);
+    }
+  });
+
+  return {
+    APP_URL: process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000",
+  };
+};
+
+export const envVars = loadEnvVars();

package/modules/auth/better-auth/files/shared/lib/email/email-service.ts

@@ -1,33 +0,0 @@
-import nodemailer from "nodemailer";
-
-// Create email transporter
-const transporter = nodemailer.createTransport({
-  host: process.env.EMAIL_HOST,
-  port: parseInt(process.env.EMAIL_PORT || "587"),
-  secure: process.env.EMAIL_PORT === "465",
-  auth: {
-    user: process.env.EMAIL_USER,
-    pass: process.env.EMAIL_PASS,
-  },
-});
-
-// Send email function
-export const sendEmail = async ({ to, subject, text, html }: {
-  to: string;
-  subject: string;
-  text?: string;
-  html?: string;
-}) => {
-  try {
-    await transporter.sendMail({
-      from: process.env.EMAIL_FROM,
-      to,
-      subject,
-      text,
-      html,
-    });
-  } catch (error) {
-    console.error("Email sending failed:", error);
-    throw error;
-  }
-};

package/modules/auth/better-auth/files/shared/lib/email/email-templates.ts

@@ -1,89 +0,0 @@
-export const getVerificationEmailTemplate = (user: { name?: string; email: string }, url: string) => {
-  const html = `
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Verify Your Email</title>
-  <style>
-    body { font-family: Arial, sans-serif; line-height: 1.6; color: #000; max-width: 600px; margin: 0 auto; padding: 20px; background-color: #fff; }
-    .header { padding: 20px; text-align: center; border-bottom: 1px solid #000; }
-    .content { padding: 20px; }
-    .button { display: inline-block; background-color: #fff; color: #000; padding: 10px 20px; text-decoration: none; border: 1px solid #000; border-radius: 5px; margin: 20px 0; }
-    .footer { font-size: 12px; color: #000; text-align: center; margin-top: 20px; border-top: 1px solid #000; padding-top: 20px; }
-  </style>
-</head>
-<body>
-  <div class="header">
-    <h1>Verify Your Email Address</h1>
-  </div>
-  <div class="content">
-    <p>Hi ${user.name || user.email},</p>
-    <p>Thank you for signing up. Please verify your email address to complete your registration.</p>
-    <a href="${url}" class="button">Verify Email</a>
-    <p>If the button doesn't work, copy and paste this link: <a href="${url}">${url}</a></p>
-    <p>This link expires in 24 hours.</p>
-  </div>
-  <div class="footer">
-    <p>If you didn't create an account, ignore this email.</p>
-  </div>
-</body>
-</html>
-  `;
-
-  const text = `Hi ${user.name || user.email},
-
-Thank you for signing up. Please verify your email address by clicking this link: ${url}
-
-This link expires in 24 hours.
-
-If you didn't create an account, ignore this email.`;
-
-  return { html, text };
-};
-
-export const getPasswordResetEmailTemplate = (user: { name?: string; email: string }, url: string) => {
-  const html = `
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Reset Your Password</title>
-  <style>
-    body { font-family: Arial, sans-serif; line-height: 1.6; color: #000; max-width: 600px; margin: 0 auto; padding: 20px; background-color: #fff; }
-    .header { padding: 20px; text-align: center; border-bottom: 1px solid #000; }
-    .content { padding: 20px; }
-    .button { display: inline-block; background-color: #fff; color: #000; padding: 10px 20px; text-decoration: none; border: 1px solid #000; border-radius: 5px; margin: 20px 0; }
-    .footer { font-size: 12px; color: #000; text-align: center; margin-top: 20px; border-top: 1px solid #000; padding-top: 20px; }
-  </style>
-</head>
-<body>
-  <div class="header">
-    <h1>Reset Your Password</h1>
-  </div>
-  <div class="content">
-    <p>Hi ${user.name || user.email},</p>
-    <p>You requested a password reset. Click the link below to reset your password.</p>
-    <a href="${url}" class="button">Reset Password</a>
-    <p>If the button doesn't work, copy and paste this link: <a href="${url}">${url}</a></p>
-    <p>This link expires in 1 hour.</p>
-  </div>
-  <div class="footer">
-    <p>If you didn't request this, ignore this email.</p>
-  </div>
-</body>
-</html>
-  `;
-
-  const text = `Hi ${user.name || user.email},
-
-You requested a password reset. Click this link to reset your password: ${url}
-
-This link expires in 1 hour.
-
-If you didn't request this, ignore this email.`;
-
-  return { html, text };
-};