htmv 0.0.1

package/README.md

@@ -0,0 +1,112 @@
+# HTMV
+Welcome to HTMV. A simple yet fast web framework currently in work in progress. Installation and usage guide can be found below.
+
+# Precautions
+HTMV was made to be used with [Bun](https://bun.com/). It has not been tested and is not guaranted to work on Node.js. Please ensure you have Bun installed before continuing reading.
+
+# Installation
+## Linking the library
+It's not yet uploaded on NPM so you'll have to link it yourself to your project.
+1. Get the repo
+```bash
+$ git clone https://github.com/Fabrisdev/htmv.git
+```
+2. cd into it
+```bash
+$ cd htmv
+```
+3. Add it to your local registry of packages
+```bash
+$ bun link
+```
+Setup of the library is finished! 🎉 Now onto creating your first **HTMV** project!
+## Creating your first project
+1. Leave that folder and create a new folder for your project
+```bash
+$ cd .. # or cd into wherever you'd like to make your project's folder
+$ mkdir my-first-htmv-project
+```
+2. Create an empty bun project and add HTMV as a dependency
+```bash
+bun init # when prompted for the type, choose EMPTY
+bun link htmv # Adds HTMV dependency
+```
+3. Create two folders. One for routes and the other for views (You can choose any name)
+4. Now in the `index.ts` add this
+```ts
+import path from "node:path";
+import { setup } from "htmv";
+
+const dirPath = import.meta.dir;
+setup({
+	routes: path.join(dirPath, "routes"), // Change to your routes folder name
+	views: path.join(dirPath, "views"), // Change to your views folder name
+	port: 3000,
+});
+```
+5. Let's create your first view! Inside the views folder add a new `example.html` with the contents
+```html
+<h1>Welcome to my blog!</h1>
+<p>{description}</p>
+```
+6. Finally, let's create a route for it. HTMV has file based routing. Every folder inside your `routes` folder indicates a nested route and every `index.ts` is it's entry point. For now, let's keep it simple with just one `index.ts` in it. Create the file and add the next contents
+```ts
+import { type RouteParams, render } from "htmv";
+
+export default async function MyRoute(_params: RouteParams) {
+	return await render("example", {
+		description: "This is my first time using HTMV ❤️",
+	});
+}
+```
+
+## And that's it! We're done. 
+Now let's try it! You can simply start it with `bun run index.ts`. After that, you should now be able to see your page in `http://localhost:3000`.
+
+## Final note
+Did you see how the `{description}` value on our view changed to the one we gave it on our route? Now that's where HTMV gets fun! Just as we now did you could also do more complex stuff like access your DB's data and show it in a nicely form.
+
+# Static files
+Having your views is nice and all... but what about images? videos? or maybe you would like to not have to use `<style>` for CSS and `<script>` for your JS.
+
+To fix this, there's actually a folder we haven't made yet. the `public` folder. Make it and just add it to your `setup`
+```ts
+setup({
+	//... the other folders
+	public: path.join(dirPath, 'public')
+})
+```
+You can add any **static files** onto this folder and they will be automatically served at `/public`. Take that into account when importing them inside your `view`.
+
+# Dynamic routes
+Sometimes you don't know the exact route (this is more common in `APIs`). For example, let's say you want to have a route `/api/user/USER_ID_HERE`. Of course you don't want to have a million folders every single one named with a different user id. That's where dynamic routes come into play.
+
+Let's setup one. Just rename your file to `/api/user/:id`.
+
+That's it! Now you can access it inside your route like this:
+```ts
+import { type RouteParams } from "htmv";
+
+export default function UserEndpoint(routeParams: RouteParams) {
+	const { id } = routeParams.params
+	return `Hello user ${id}!`
+}
+```
+Now when you go to `/api/user/1000` you should see `Hello user 1000!`.
+
+# Hot reloading
+Having to restart the server every time you make a change can be quite tedious. You can instead serve your server with `bun --watch .` to watch for any changes to the folder. Note that this does not include hot reloading in the browser. As of now, you have to refresh the page to see new changes. It doesn't update in real time.
+
+# Recommendations
+Creating a run script is advised. You can easily add it to your `package.json` like this
+```json
+{
+  //...
+  "scripts": {
+    "dev": "bun --watch .",
+		"start": "bun run index.ts"
+  }
+  //...
+}
+```
+Now you can start your server with hot reloading by running `bun dev` or normally by running `bun start`.

package/cli.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+console.log("WIP");

package/index.ts

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import staticPlugin from "@elysiajs/static";
+import { Elysia } from "elysia";
+
+let viewsPath = "";
+
+export async function view(view: string, props: Record<string, unknown>) {
+	if (viewsPath === "")
+		throw new Error(
+			"Views folder path not yet configured. Use `Htmv.setup` before rendering a view.",
+		);
+	const file = Bun.file(path.join(viewsPath, `${view}.html`));
+	const code = await file.text();
+	const replacedCode = code.replace(/{(.+)}/g, (_, propName) => {
+		return props[propName] as string;
+	});
+	return new Response(replacedCode, {
+		headers: { "Content-Type": "text/html; charset=utf-8" },
+	});
+}
+
+export type RouteParams = {
+	query: Record<string, string>;
+	request: Request;
+	params: Record<string, string>;
+};
+
+type Paths = {
+	routes: string;
+	views: string;
+	public: string;
+	port: number;
+};
+export async function setup(paths: Paths) {
+	viewsPath = paths.views;
+	const app = new Elysia().use(
+		staticPlugin({
+			assets: paths.public,
+		}),
+	);
+
+	await registerRoutes(app, paths.routes);
+	app.listen(paths.port);
+	console.log("");
+	console.log(`HTMV running on port ${paths.port}! 🎉`);
+	console.log(`http://localhost:${paths.port}`);
+}
+
+async function registerRoutes(app: Elysia, baseDir: string, prefix = "/") {
+	const entries = await fs.readdir(baseDir, { withFileTypes: true });
+	for (const entry of entries) {
+		const fullPath = path.join(baseDir, entry.name);
+		if (entry.isDirectory()) {
+			await registerRoutes(app, fullPath, path.join(prefix, entry.name));
+			continue;
+		}
+		if (entry.name !== "index.ts" && entry.name !== "index.tsx") continue;
+		const module = (await import(fullPath)) as Record<string, unknown>;
+		const defaultFn = module.default;
+		if (defaultFn && typeof defaultFn === "function") {
+			app.all(prefix, async ({ request, query, params }) => {
+				const result = await defaultFn({ request, query, params });
+				return result;
+			});
+			console.log(`Registered ${fullPath} on ${prefix} route with method all`);
+		}
+		for (const propName in module) {
+			const prop = module[propName];
+			if (typeof prop !== "function") continue;
+			const fn = prop as RouteFn;
+			const name = fn.name.toLowerCase();
+			if (!["get", "post", "put", "patch", "delete"].includes(name)) continue;
+			app[name as "get"](prefix, async ({ request, query, params }) => {
+				const result = await fn({ request, query, params });
+				return result;
+			});
+			console.log(
+				`Registered ${fullPath} on ${prefix} route with method ${name}`,
+			);
+		}
+	}
+}
+
+type RouteFn = (
+	_: RouteParams,
+) => Promise<Response> | Response | Promise<string> | string;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "htmv",
+  "module": "index.ts",
+  "type": "module",
+  "version": "0.0.1",
+  "devDependencies": {
+    "@biomejs/biome": "2.3.3",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@elysiajs/static": "^1.4.6",
+    "elysia": "^1.4.15"
+  },
+  "bin": {
+    "htmv": "./cli.ts"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}