express-project-init 0.0.0-stage → 1.1.0

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "express-project-init",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Create production-ready Express.js API projects with JavaScript or TypeScript using clean, reusable starter templates.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "express-project-init": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "clean": "node -e \"const fs=require('node:fs'); for (const p of ['dist','tsconfig.tsbuildinfo']) fs.rmSync(p,{recursive:true,force:true})\"",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run clean && npm run build",
+    "start": "node dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raunak-ray/ExpressKit.git"
+  },
+  "homepage": "https://github.com/raunak-ray/ExpressKit#readme",
+  "bugs": {
+    "url": "https://github.com/raunak-ray/ExpressKit/issues"
+  },
+  "keywords": [
+    "express",
+    "expressjs",
+    "express-generator",
+    "express-cli",
+    "nodejs",
+    "api-generator",
+    "backend",
+    "project-scaffolding",
+    "boilerplate",
+    "starter-template",
+    "typescript",
+    "javascript"
+  ],
+  "author": "Raunak Ray",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
+}

package/templates/format/biome/both/biome.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  }
+}

package/templates/format/biome/both/package.json

@@ -0,0 +1,12 @@
+{
+  "scripts": {
+    "lint": "biome lint",
+    "lint:fix": "biome lint --write",
+    "format": "biome format --write",
+    "format:check": "biome format",
+    "check": "biome check"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4"
+  }
+}

package/templates/format/biome/format/biome.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": false
+  }
+}

package/templates/format/biome/format/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "format": "biome format --write",
+    "format:check": "biome format"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4"
+  }
+}

package/templates/format/prettier/.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+coverage

package/templates/format/prettier/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "tabWidth": 2
+}

package/templates/format/prettier/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "devDependencies": {
+    "prettier": "^3.9.10"
+  }
+}

package/templates/javascript/base/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "my-api",
+  "version": "1.0.0",
+  "description": "Express API generated by ExpressKit",
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch src/server.js",
+    "start": "node src/server.js"
+  },
+  "dependencies": {
+    "express": "^5.1.0"
+  }
+}

package/templates/javascript/base/src/app.js

@@ -0,0 +1,22 @@
+import express from "express";
+import { getTimeStamp } from "./utils/helpers.js";
+import { successResponse } from "./utils/responseHelpers.js";
+
+const app = express();
+
+app.use(express.json());
+
+// Health check
+app.get("/health", (_req, res) =>
+  successResponse(res, {
+    statusCode: 200,
+    message: "API is up and running",
+    data: {
+      status: "ok",
+      uptime: Math.round(process.uptime()),
+      timestamp: getTimeStamp(),
+    },
+  }),
+);
+
+export default app;

package/templates/javascript/base/src/server.js

@@ -0,0 +1,8 @@
+import app from "./app.js";
+
+const PORT = process.env.PORT || 3000;
+
+app.listen(PORT, () => {
+  console.log(`API running on http://localhost:${PORT}`);
+  console.log(`Health check: http://localhost:${PORT}/health`);
+});

package/templates/javascript/base/src/utils/helpers.js

@@ -0,0 +1,3 @@
+export function getTimeStamp() {
+  return new Date().toISOString();
+}

package/templates/javascript/base/src/utils/responseHelpers.js

@@ -0,0 +1,19 @@
+export function successResponse(res, { statusCode = 200, message, data }) {
+  return res.status(statusCode).json({
+    success: true,
+    message,
+    data,
+  });
+}
+
+export function errorResponse(
+  res,
+  { statusCode = 500, message, code = "INTERNAL_ERROR", fields },
+) {
+  return res.status(statusCode).json({
+    success: false,
+    message,
+    code,
+    fields,
+  });
+}

package/templates/javascript/error-handler/src/app.js

@@ -0,0 +1,28 @@
+import express from "express";
+import errorMiddleware from "./middleware/error.middleware.js";
+import notFoundMiddleware from "./middleware/notFound.middleware.js";
+import { getTimeStamp } from "./utils/helpers.js";
+import { successResponse } from "./utils/responseHelpers.js";
+
+const app = express();
+
+app.use(express.json());
+
+// Health check
+app.get("/health", (_req, res) =>
+  successResponse(res, {
+    statusCode: 200,
+    message: "API is up and running",
+    data: {
+      status: "ok",
+      uptime: Math.round(process.uptime()),
+      timestamp: getTimeStamp(),
+    },
+  }),
+);
+
+// Unknown routes → 404, then every error gets formatted in one place.
+app.use(notFoundMiddleware);
+app.use(errorMiddleware);
+
+export default app;

package/templates/javascript/error-handler/src/middleware/error.middleware.js

@@ -0,0 +1,36 @@
+import { AppError, BadRequestError } from "../utils/AppError.js";
+import { getTimeStamp } from "../utils/helpers.js";
+import { errorResponse } from "../utils/responseHelpers.js";
+
+// Express error handler — needs all 4 params, that's how Express recognizes it.
+export default function errorMiddleware(error, req, res, _next) {
+  const timeStamp = getTimeStamp();
+
+  // Expected errors — log them and send their details
+  if (error instanceof AppError) {
+    console.log(
+      `[${timeStamp}] [ERROR] ${req.method} ${req.originalUrl} - ${error.message}`,
+    );
+
+    return errorResponse(res, {
+      statusCode: error.statusCode,
+      message: error.message,
+      code: error.code,
+      fields: error instanceof BadRequestError ? error.fields : undefined, // fields only for bad requests
+    });
+  }
+
+  // Not an AppError — build a message if it's an Error, otherwise fall back
+  const message =
+    error instanceof Error ? error.message : "Internal server error";
+
+  console.error(
+    `[${timeStamp}] [ERROR] ${req.method} ${req.originalUrl} - ${message}`,
+    error,
+  );
+
+  return errorResponse(res, {
+    statusCode: 500,
+    message,
+  });
+}

package/templates/javascript/error-handler/src/middleware/notFound.middleware.js

@@ -0,0 +1,5 @@
+import { NotFoundError } from "../utils/AppError.js";
+
+export default function notFoundMiddleware(_req, _res, next) {
+  next(new NotFoundError("Route not found"));
+}

package/templates/javascript/error-handler/src/utils/AppError.js

@@ -0,0 +1,30 @@
+export class AppError extends Error {
+  constructor(message, { code = "INTERNAL_ERROR", statusCode = 500 } = {}) {
+    super(message);
+
+    this.name = this.constructor.name;
+    this.code = code; // machine-readable code, e.g. "BAD_REQUEST"
+    this.statusCode = statusCode; // HTTP status to send back
+  }
+}
+
+export class BadRequestError extends AppError {
+  // fields: validation errors, e.g. [{ field: "email", message: "required" }]
+  constructor(message = "Bad request", fields = []) {
+    super(message, { code: "BAD_REQUEST", statusCode: 400 });
+
+    this.fields = fields;
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = "Unauthorized") {
+    super(message, { code: "UNAUTHORIZED", statusCode: 401 });
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = "Not found") {
+    super(message, { code: "NOT_FOUND", statusCode: 404 });
+  }
+}

package/templates/lint/biome/biome.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.6.4/schema.json",
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": false
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  }
+}

package/templates/lint/biome/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "lint": "biome lint",
+    "lint:fix": "biome lint --write"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4"
+  }
+}

package/templates/lint/eslint/eslint.config.js

@@ -0,0 +1,36 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+let prettier = [];
+try {
+  const prettierConfig = await import("eslint-config-prettier");
+  prettier = [prettierConfig.default];
+} catch (error) {
+  // eslint-config-prettier is optional, used when Prettier is also configured
+  void error;
+}
+
+export default tseslint.config(
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          varsIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
+  ...prettier,
+);

package/templates/lint/eslint/package.json

@@ -0,0 +1,12 @@
+{
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "eslint": "^9.20.0",
+    "globals": "^16.0.0",
+    "typescript-eslint": "^8.24.0"
+  }
+}

package/templates/lint/oxlint/.oxlintrc.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn", "oxc"],
+  "categories": {
+    "correctness": "error"
+  },
+  "rules": {},
+  "env": {
+    "builtin": true,
+    "node": true
+  },
+  "ignorePatterns": ["node_modules", "dist"]
+}

package/templates/lint/oxlint/package.json

@@ -0,0 +1,9 @@
+{
+  "scripts": {
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix"
+  },
+  "devDependencies": {
+    "oxlint": "^1.90.0"
+  }
+}

package/templates/typescript/base/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "my-api",
+  "version": "1.0.0",
+  "description": "Express API generated by ExpressKit",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "tsx src/server.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "express": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^26.6.5",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/typescript/base/src/app.ts

@@ -0,0 +1,22 @@
+import express, { type Request, type Response } from "express";
+import { getTimeStamp } from "./utils/helpers";
+import { successResponse } from "./utils/responseHelpers";
+
+const app = express();
+
+app.use(express.json());
+
+// Health check
+app.get("/health", (_req: Request, res: Response) =>
+  successResponse(res, {
+    statusCode: 200,
+    message: "API is up and running",
+    data: {
+      status: "ok",
+      uptime: Math.round(process.uptime()),
+      timestamp: getTimeStamp(),
+    },
+  }),
+);
+
+export default app;

package/templates/typescript/base/src/server.ts

@@ -0,0 +1,8 @@
+import app from "./app";
+
+const PORT = Number(process.env.PORT) || 3000;
+
+app.listen(PORT, () => {
+  console.log(`API running on http://localhost:${PORT}`);
+  console.log(`Health check: http://localhost:${PORT}/health`);
+});

package/templates/typescript/base/src/utils/helpers.ts

@@ -0,0 +1,3 @@
+export function getTimeStamp(): string {
+  return new Date().toISOString();
+}

package/templates/typescript/base/src/utils/responseHelpers.ts

@@ -0,0 +1,42 @@
+import type { Response } from "express";
+
+export type FieldError = {
+  field: string;
+  message: string;
+};
+
+type SuccessOptions<T> = {
+  statusCode?: number;
+  message: string;
+  data?: T;
+};
+
+export function successResponse<T>(
+  res: Response,
+  { statusCode = 200, message, data }: SuccessOptions<T>,
+): Response {
+  return res.status(statusCode).json({
+    success: true,
+    message,
+    data,
+  });
+}
+
+type ErrorOptions = {
+  statusCode?: number;
+  message: string;
+  code?: string;
+  fields?: FieldError[];
+};
+
+export function errorResponse(
+  res: Response,
+  { statusCode = 500, message, code = "INTERNAL_ERROR", fields }: ErrorOptions,
+): Response {
+  return res.status(statusCode).json({
+    success: false,
+    message,
+    code,
+    fields,
+  });
+}

package/templates/typescript/base/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    // Imports / modules
+    // "bundler" is THE setting that lets you import WITHOUT extensions:
+    //   import app from "./app"        (not "./app.ts")
+    "module": "esnext", // emit modern ES module syntax
+    "moduleResolution": "bundler", // resolve imports without ".ts" extensions
+    "moduleDetection": "force", // treat every file as an ES module (no CommonJS guessing)
+    "esModuleInterop": true, // allow normal default imports from CJS packages (express)
+    "verbatimModuleSyntax": true, // keep imports exactly as written; type-only imports must use "import type"
+
+    // Language level
+    "target": "esnext", // allow the newest JS features, no downleveling
+
+    // Type checking
+    "strict": true, // turn on all strict type checks
+    "noUnusedLocals": true, // error on declared-but-unused variables
+    "noUnusedParameters": true, // error on unused function parameters
+    "skipLibCheck": true, // don't type-check ".d.ts" files inside node_modules (faster)
+
+    // Runtime types
+    "types": ["node"], // auto-include ONLY Node types (no stray umbrella types)
+
+    // Output
+    "noEmit": true // tsx runs the code directly, so tsc only type-checks, never writes files
+  },
+  // Files in scope
+  "include": ["src"], // the compiler only looks at src/
+  "exclude": ["node_modules"] // never scan dependencies
+}

package/templates/typescript/error-handler/src/app.ts

@@ -0,0 +1,28 @@
+import express, { type Request, type Response } from "express";
+import errorMiddleware from "./middleware/error.middleware";
+import notFoundMiddleware from "./middleware/notFound.middleware";
+import { getTimeStamp } from "./utils/helpers";
+import { successResponse } from "./utils/responseHelpers";
+
+const app = express();
+
+app.use(express.json());
+
+// Health check
+app.get("/health", (_req: Request, res: Response) =>
+  successResponse(res, {
+    statusCode: 200,
+    message: "API is up and running",
+    data: {
+      status: "ok",
+      uptime: Math.round(process.uptime()),
+      timestamp: getTimeStamp(),
+    },
+  }),
+);
+
+// Unknown routes → 404, then every error gets formatted in one place.
+app.use(notFoundMiddleware);
+app.use(errorMiddleware);
+
+export default app;

package/templates/typescript/error-handler/src/middleware/error.middleware.ts

@@ -0,0 +1,42 @@
+import type { NextFunction, Request, Response } from "express";
+import { AppError, BadRequestError } from "../utils/AppError";
+import { getTimeStamp } from "../utils/helpers";
+import { errorResponse } from "../utils/responseHelpers";
+
+// Express error handler — needs all 4 params, that's how Express recognizes it.
+export default function errorMiddleware(
+  error: unknown,
+  req: Request,
+  res: Response,
+  _next: NextFunction,
+): Response {
+  const timeStamp = getTimeStamp();
+
+  // Expected errors — log them and send their details
+  if (error instanceof AppError) {
+    console.log(
+      `[${timeStamp}] [ERROR] ${req.method} ${req.originalUrl} - ${error.message}`,
+    );
+
+    return errorResponse(res, {
+      statusCode: error.statusCode,
+      message: error.message,
+      code: error.code,
+      fields: error instanceof BadRequestError ? error.fields : undefined, // fields only for bad requests
+    });
+  }
+
+  // Not an AppError — build a message if it's an Error, otherwise fall back
+  const message =
+    error instanceof Error ? error.message : "Internal server error";
+
+  console.error(
+    `[${timeStamp}] [ERROR] ${req.method} ${req.originalUrl} - ${message}`,
+    error,
+  );
+
+  return errorResponse(res, {
+    statusCode: 500,
+    message,
+  });
+}

package/templates/typescript/error-handler/src/middleware/notFound.middleware.ts

@@ -0,0 +1,10 @@
+import type { NextFunction, Request, Response } from "express";
+import { NotFoundError } from "../utils/AppError";
+
+export default function notFoundMiddleware(
+  _req: Request,
+  _res: Response,
+  next: NextFunction,
+): void {
+  next(new NotFoundError("Route not found"));
+}