maxserver 0.0.15 → 0.0.16

package/README.md

@@ -11,58 +11,63 @@
 I am simplifying and improving things, that it will work for everyone plugn play.
 
 
-Ready node server setup based on **Fastify** to speedup api development.
+Ready node server setup based on **Fastify** to speed up backend development.  
+maxserver stands for **maximized simplicity** and **minimum boilerplate**.
 
 - **Auto Routes**: auto imports and registers routes and schemas
 - **Auto Docs**: auto generates docs based on schemas
-- **Preconfigures JWT auth, Cores, Helmet**
+- **Preconfigures essentials**: jwt auth, cors, helmet
 - **Auto Connect MongoDB** (optional)
 - **Dev server**
 <br><br>
 
-- Dependencies: original fastify packages + scalar/fastify-api-reference (doc generator)
-- The source is simple and short. Everyone shall be able to read, understand and modify if needed.
-
 
 ## Install
 
 ### Setup ready project
+```js
 npx maxserver [appname]
+```
 
-### Install 
+### Or install as packge
+```js
 npm install maxserver
+```
+<br>
 
 ## Setup
 ```js
 import maxserver from "maxserver";
 
-const server = await maxserver();
-await server.listen();
+const server = await maxserver({
+	port: 3000,
+	secret: "your_secret"
+});
 
-console.log("Server running at ", server.getAddress());
+await server.start();
 export default server;
-
 ```
----
+<br>
 
 ## ⚙️ Configure
-Quick configure your server by passing options to the **maxserver()** or define them in your .env file.  
-You can also pass any fastify options.
+Configs can be passed to the init call to **maxserver()** or set in your .env file.  
+If you define options in env, use all upper case letters.
+Any fastify options can be passed to maxserver() too.
+
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `PORT` | `3000` | Server port |
-| `JWT_SECRET` | *-* | Enables JWT auth (private-by-default routes) |
-| `MONGODB_URI` | *-* | Enables MongoDB auto-connect + global `db` |
-| `DOCS` | `true` | Set `false` to disable docs UI at `/docs` |
-| `STATIC_DIR` | *(optional)* | Serve static files (example: `./public`) |
-| `CORS_ORIGIN` | `*` | Allowed CORS origins |
-
----
-
-## 🗂️ Project Structure
+| `port` | `3000` | Server port |
+| `secret` | *-* | Secret used for jwt and cookies |
+| `cors` | `*` | Allowed CORS origins, default all allowed |
+| `docs` | `true` | Set `false` to disable auto generated docs` |
+| `mongodb` | *-* | MongoDB URI, if set auto-connects db |
+| `public` | `false` | Set `true` to expose the server publicly (binds to `0.0.0.0`) |
+| `static` | *-* | If set, serves this directory statically |
+<br><br>
 
-**1 route = 1 handler file + 1 schema file**
+## 🗂️ Project Structure 
+Our golden rule: **1 route = 1 handler file + 1 schema file**
 
 Example:
 
@@ -75,12 +80,11 @@ src/
 		hello.schema.js
 	...
 ```
-
----
+<br>
 
 ## 🛣️ Handlers
 
-### 1) Define method + path
+#### 1) Define method + path
 Start each route file with a comment to define the path.  
 That comment is what the route loader uses to auto-register the route.
 
@@ -88,13 +92,9 @@ That comment is what the route loader uses to auto-register the route.
 // GET /teams/:id
 ```
 
+#### 2) Export default handler
 
 
-### 2) Default export handler
-
-
-### Example
-
 ```js
 // GET /teams/:id
 
@@ -106,89 +106,75 @@ export default async function (req, res) {
 }
 ```
 
----
+<br>
+<br>
+
 
-## 🧾 Define Schemas
-Create a sibling file ending in **`.schema.js`**. 
-The schema is offcourse a jsonschema.
-This file will be auto registered.
+## 🧾 Schemas
+Create a sibling file ending with **`.schema.js`**, so it will be auto registered.  
+For example: **hello.js** and **hello.schema.js**  
 
-Schemas:
-- validate inputs
-- generate OpenAPI docs
-- control route options for example (public/private)
+Besides the basic validation fields we can set fields like summary and description,
+which will appear in the docs. Mostly you don't need to write schemas yourself, chat gpt and gemini do it excelently.
 
 
-**`Important - use default export`**
 ```js
 export default {
-	tags: ["Teams"],
-	summary: "Get team",
-	description: "Returns a single team by identifier.",
 
-	params: {
+	tags: ["Test"],
+	summary: "Post hello",
+	description: "Accepts a name and returns a greeting.",
+
+	body: {
 		type: "object",
-		required: ["id"],
+		required: ["name"],
 		properties: {
-			id: {
+			name: {
 				type: "string",
-				minLength: 24,
-				example: "",
 			},
 		},
 	},
 
-	response: {
-		200: {
-			type: "object",
-			properties: {
-				id: {
-					type: "string",
-					example: "507f1f77bcf86cd799439011",
-				},
-				name: { type: "string", example: "Team A" },
-			},
-			required: ["id", "name"],
-		},
-	},
+	...
 };
 ```
 
-<br>
-
-
-## 📚 API Docs
-
-- Open in your browser **`localhost:3000/docs`**
-- OpenAPI JSON: **`/openapi.json`**
+**`‼️ Important use export default`**
 
 <br>
 
+## Route Options
+Though we don't register routes manually, we don't set route options on the register call. If needed, route options can be set on the schema object.
+For example **schema.auth = true** to enable authentication.
+So the schema holds all configs about a root and handlers the pure logic.
 
+<br>
 
+## 📚 API Docs
 
-## 🔐 Authentication (JWT)
+Open in your browser **`localhost:3000/docs`**  
+OpenAPI JSON: **`/openapi.json`**
 
-Enable auth by setting:
+<br>
 
-- `JWT_SECRET`
 
-Behavior:
-- **Private by default**: routes require JWT (cookie or Bearer header)
-- Authenticated user identifier is available as **`req.userId`**
-- Make a route **public** by setting `config.public: true` in its schema
+## 🔐 Authentication
+JWT header and cookie based auth is preconfigured.  
+To enable auth for a route set in it's schema **auth = true**  
+The authenticated user is available as **`req.userId`**
 
 ```js
+// Inside schema
+
 export default {
-	config: { public: true },
-	// ...
+	auth: true
 };
 ```
 
 <br>
 
 ## 🍃 MongoDB
-Define in the env **`MONGODB_URI`** and it will auto-connect at server start and you get:
+Set option **`MONGODB`** your mongodbURI and it will auto-connect at server start and you get:
 
 - global **`db`** (connected database handle)
 - global **`oid(string)`** (string → MongoDB `ObjectId`)
@@ -198,8 +184,19 @@ Define in the env **`MONGODB_URI`** and it will auto-connect at server start and
 | `db` | MongoDB database handle | Use it directly in handlers |
 | `oid(id)` | string → `ObjectId` | Avoid importing `ObjectId` everywhere |
 
+### Example
 
----
+```js
+// Inside route handlers
+
+export default async function (req, res) {
+
+	await db.feedback.insert(...)
+}
+```
+
+
+<br>
 
 ## 🧰 Error Handling
 
@@ -211,9 +208,13 @@ if (!user) throw createError(404, "User not found");
 
 Rule of thumb: make the message something you would want to see at 03:00 in logs.
 
----
+<br>
 
+## About
+- Dependencies: original fastify packages + scalar/fastify-api-reference
+- The source is simple. Everyone can read, understand and modify if needed.
 
+<br>
 
 ## 🛠️ Tips & Tools
 
@@ -230,5 +231,6 @@ In `.vscode/tasks.json`, enable the task with:
 "runOptions": { "runOn": "folderOpen" }
 ```
 
-### 🤖 AI Assistants (Code Style)
-Copy **`RULES.md`** into your AI tool as system context, then ask it to generate routes + schemas.
+### 🤖 AI Assistants
+Copy **`RULES.md`** into your AI tool as system context,  
+then ask it to generate routes + schemas.

package/bin/init.js

@@ -15,17 +15,17 @@ function main() {
 	}
 
 	try {
-		console.log(`🚀 Creating "${projectName}"...`);
+		console.log(`🚀 Setting up "${projectName}"...`);
 		fs.cpSync(templateDir, targetDir, { recursive: true });
 
 		fixDotfiles(targetDir);
 		patchPackageJson(targetDir, projectName);
 
 		process.chdir(targetDir);
-		console.log("📦 Installing maxserver...");
+		console.log("📦 Installing maxserver");
 		execSync("npm install maxserver@latest", { stdio: "inherit" });
 
-		console.log("\n✅ Done! Your project is ready. 😊");
+		console.log(`\n✅ Install complete\n\ncd ${projectName}\nnpm run dev\n`);
 	} catch (err) {
 		console.error("❌ Init failed:", err.message);
 		process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "maxserver",
-	"version": "0.0.15",
+	"version": "0.0.16",
 	"description": "Node server setup based fastify",
 	"author": "Max Matinpalo",
 	"type": "module",

package/src/getAddress.js

@@ -1,29 +1,5 @@
 import os from "node:os";
 
-export function setupGetAddress(app) {
-	app.decorate("getAddress", () => {
-		const addr = app.server?.address();
-		const protocol = app.initialConfig?.https ? "https" : "http";
-
-		if (!addr) return null;
-		if (typeof addr === "string") return addr;
-
-		const isPublicBind = addr.address === "0.0.0.0" || addr.address === "::";
-		const isLoopback = addr.address === "127.0.0.1" || addr.address === "::1";
-
-		const envIp = String(process.env.PUBLIC_IP || "").trim() || null;
-		const detectedIp = envIp || getLanIp();
-
-		const ip = (isPublicBind && !isLoopback)
-			? (detectedIp || addr.address)
-			: "localhost";
-
-		const host = ip.includes(":") ? `[${ip}]` : ip;
-
-		return `${protocol}://${host}:${addr.port}`;
-	});
-}
-
 function getLanIp() {
 	const nets = os.networkInterfaces();
 
@@ -35,3 +11,28 @@ function getLanIp() {
 
 	return null;
 }
+
+
+export function getAddress(app) {
+
+	const addr = app.server?.address();
+	const protocol = app.initialConfig?.https ? "https" : "http";
+
+	if (!addr) return null;
+	if (typeof addr === "string") return addr;
+
+	const isPublicBind = addr.address === "0.0.0.0" || addr.address === "::";
+	const isLoopback = addr.address === "127.0.0.1" || addr.address === "::1";
+
+	const envIp = String(process.env.PUBLIC_IP || "").trim() || null;
+	const detectedIp = envIp || getLanIp();
+
+	const ip = (isPublicBind && !isLoopback)
+		? (detectedIp || addr.address)
+		: "localhost";
+
+	const host = ip.includes(":") ? `[${ip}]` : ip;
+
+	return `${protocol}://${host}:${addr.port}`;
+}
+

package/src/index.js

@@ -12,7 +12,7 @@ import {
 	getHttpsOptions,
 } from "./setup.js";
 
-import { setupGetAddress } from "./getAddress.js";
+import { getAddress } from "./getAddress.js";
 
 
 export default async function maxserver(config = {}) {
@@ -20,47 +20,52 @@ export default async function maxserver(config = {}) {
 	const {
 
 		// maxserver options
+		port = Number(process.env.PORT || 3000),
 		secret = process.env.SECRET,
-		cookieSecret = process.env.COOKIE_SECRET,
-		mongodbUri = process.env.MONGODB_URI,
+		mongodb = process.env.MONGODB,
 		docs = process.env.DOCS !== "false",
-		staticDir = process.env.STATIC_DIR,
-		corsOrigin = process.env.CORS_ORIGIN || "*",
+		cors = process.env.CORS || "*",
+		openapiInfo,
+		static: isStatic = process.env.STATIC,
+		public: isPublic = process.env.PUBLIC === "true",
 
 		// everything else goes straight to Fastify
 		...fastifyOpts
 
 	} = config;
 
-	if (process.env.NODE_ENV == "development") {
-		console.error("Please define secret in env !");
-
-	}
-
-	let maxserverConfig = {
-		secret, mongodbUri, docs, staticDir, corsOrigin
+	const maxserverConfig = {
+		port, secret, mongodb, docs, cors,
+		static: isStatic,
+		public: isPublic
 	};
 
-	process.env.NODE_ENV;
-
-
-
 
-	const app = Fastify({
+	let app;
+	try {
+		app = Fastify({
+			https: getHttpsOptions() || undefined,
+			trustProxy: true,
 
-		https: getHttpsOptions() || undefined,
-		trustProxy: true,
+			// Required to allow adding doc fields on schema
+			ajv: { customOptions: { strictSchema: false } },
+			...fastifyOpts
+		});
+	} catch (err) {
+		console.error("❌ Fastify initialization failed:", err);
+		throw err;
+	}
 
-		// To allow writing example value fields to schemas for doucumentation 
-		ajv: { customOptions: { strictSchema: false } },
-		...fastifyOpts,
-	});
 
 	app.decorate("maxserver", maxserverConfig);
 
+	app.decorate("start", async function () {
+		const port = this.maxserver.port ?? 3000;
+		const host = this.maxserver.public ? '0.0.0.0' : '127.0.0.1';
+		await this.listen({ port, host });
+		console.log('Server running at ', getAddress(this));
+	});
 
-
-	setupGetAddress(app);
 	await setupCookie(app);
 	await setupHelmet(app);
 	await setupCors(app);
@@ -70,13 +75,11 @@ export default async function maxserver(config = {}) {
 	await setupDocs(app);
 	await setupRoutes(app);
 
-
 	global.createError = function (code, message) {
 		const err = new Error(message);
 		err.statusCode = code;
 		return err;
 	};
 
-
 	return app;
 }

package/src/setup.js

@@ -27,18 +27,21 @@ export async function setupHelmet(app) {
 }
 
 
+
+
 export async function setupCors(app) {
 	const isProd = process.env.NODE_ENV === "production";
-	const origin = app.maxserver.corsOrigin ?? true;
+	const origin = app.maxserver.cors ?? "*";
 
-	if (isProd && origin === true) {
-		app.log.warn("CORS origin not set, allowing all origins");
+	if (isProd && origin === "*") {
+		app.log.warn("CORS: allowing all origins (*) in production");
 	}
 
 	await app.register(cors, { origin });
 }
 
 
+
 export function getHttpsOptions() {
 	const { TLS_KEY, TLS_CERT } = process.env;
 	if (!TLS_KEY || !TLS_CERT) return null;
@@ -91,7 +94,7 @@ export async function setupJwt(app) {
 
 
 export async function setupMongo(app) {
-	const url = app.maxserver.mongodbUri;
+	const url = app.maxserver.mongodb;
 	if (!url) return;
 	await app.register(mongodb, { url });
 
@@ -139,7 +142,7 @@ export async function setupDocs(app) {
 
 
 export async function setupStatic(app) {
-	const dir = app.maxserver.staticDir;
+	const dir = app.maxserver.static;
 	if (!dir) return;
 
 	await app.register(fastifyStatic, {

package/templates/env

@@ -1,24 +1,8 @@
-# Environment
-NODE_ENV = development
-
-# Server
-PORT = 3000
-
-# CORS(prod only, ignored in dev)
-# CORS_ORIGIN = https://app.example.com
-
-# JWT;
-# JWT_SECRET = supersecretkey
 
-# MongoDB;
-# MONGODB_URI = mongodb://127.0.0.1:27017/testdb
-
-# Static files
-# STATIC_DIR =./ public
-
-# API Docs in production
-DOCS = 1
+NODE_ENV = development
 
-# Optional HTTPS(direct TLS, no nginx)
-# TLS_KEY = /etc/ssl / private / server.key
-# TLS_CERT = /etc/ssl / certs / server.crt;
+# PORT
+# CORS
+# SECRET
+# MONGODB
+# STATIC 

package/templates/server.js

@@ -1,10 +1,9 @@
 import maxserver from "maxserver";
 
-const server = await maxserver();
-
-await server.listen({
-	port: Number(process.env.PORT || 3000),
+const server = await maxserver({
+	port: 3000,
+	secret: "your_secret"
 });
 
-console.log("Server running at ", server.getAddress());
+await server.start();
 export default server;