create-nolly-template 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to create-nolly-template
+
+Thank you for your interest in contributing to `create-nolly-template`! This project is a CLI tool that provides opinionated templates for various tech stacks, making it easier to bootstrap new projects. We welcome contributions from everyone, whether it's bug fixes, new features, documentation improvements, or adding new templates.
+
+## Table of Contents
+
+- [Contributing to create-nolly-template](#contributing-to-create-nolly-template)
+  - [Table of Contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+  - [Development Setup](#development-setup)
+  - [Project Structure](#project-structure)
+  - [Adding New Templates](#adding-new-templates)
+  - [Coding Guidelines](#coding-guidelines)
+  - [Testing](#testing)
+  - [Submitting Changes](#submitting-changes)
+  - [Reporting Issues](#reporting-issues)
+  - [Code of Conduct](#code-of-conduct)
+  - [License](#license)
+
+## Getting Started
+
+Before you start contributing, please familiarize yourself with the project by reading the [README.md](README.md). It provides an overview of what the tool does, how to install it, and its usage.
+
+## Development Setup
+
+To set up the development environment:
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/thenolle/create-nolly-template.git
+   cd create-nolly-template
+   ```
+
+2. **Install dependencies:**
+   This project uses [pnpm](https://pnpm.io/) for package management. If you don't have pnpm installed, install it first:
+   ```bash
+   npm install -g pnpm
+   ```
+   Then install the dependencies:
+   ```bash
+   pnpm install
+   ```
+
+3. **Run in development mode:**
+   Use the dev script to run the CLI tool directly from source:
+   ```bash
+   pnpm dev
+   ```
+   This uses `tsx` to run TypeScript files without building.
+
+4. **Build the project:**
+   To build the distributable version:
+   ```bash
+   pnpm build
+   ```
+   This compiles TypeScript to JavaScript in the `dist/` folder.
+
+5. **Test the built version:**
+   After building, you can test the CLI:
+   ```bash
+   pnpm start
+   ```
+
+Ensure you have Node.js version 20 or higher installed, as specified in the `engines` field of `package.json`.
+
+## Project Structure
+
+- `src/`: Source code for the CLI tool
+  - `index.ts`: Main entry point
+  - `builder.ts`: Logic for building projects from templates
+  - `paths.ts`: Path utilities
+  - `registry/`: Template registry and types
+- `templates/`: Template directories
+  - `web/backend/fastify/`: Fastify-based backend templates
+- `dist/`: Built JavaScript files (generated)
+- `package.json`: Project configuration
+- `tsconfig.json`: TypeScript configuration
+
+## Adding New Templates
+
+To add a new template:
+
+1. Create a new directory under `templates/` following the structure (e.g., `templates/web/frontend/react/`).
+2. Add the necessary files for the template (e.g., `package.json`, source files).
+3. Update the registry in `src/registry/` to include the new template.
+4. Test the template by running the CLI and selecting it.
+
+Ensure templates are opinionated and follow best practices for the respective tech stack.
+
+## Coding Guidelines
+
+- **TypeScript:** All code is written in TypeScript. Use strict type checking.
+- **Style:** Follow consistent naming conventions and formatting. Use Prettier if available (though not currently configured).
+- **Commits:** Write clear, concise commit messages. Use conventional commits if possible (e.g., `feat: add new template`).
+- **Imports:** Use ES modules (`import/export`) as the project is configured with `"type": "module"`.
+
+## Testing
+
+Currently, there are no automated tests set up. Contributions that add tests (e.g., using Jest or Vitest) are highly encouraged. For now, manually test your changes by:
+
+- Running the CLI in dev mode
+- Building and testing the built version
+- Ensuring templates generate correctly
+
+## Submitting Changes
+
+1. **Fork the repository** on GitHub.
+2. **Create a feature branch** from `main`:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. **Make your changes** and commit them:
+   ```bash
+   git commit -m "feat: description of your changes"
+   ```
+4. **Push to your fork:**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+5. **Open a Pull Request** on GitHub. Provide a clear description of what your changes do and why they're needed.
+
+## Reporting Issues
+
+If you find a bug or have a feature request:
+
+1. Check the [existing issues](https://github.com/thenolle/create-nolly-template/issues) to see if it's already reported.
+2. If not, open a new issue with:
+   - A clear title
+   - Detailed description
+   - Steps to reproduce (for bugs)
+   - Expected vs. actual behavior
+   - Your environment (Node.js version, OS, etc.)
+
+## Code of Conduct
+
+This project follows a code of conduct to ensure a welcoming environment for all contributors. Be respectful, inclusive, and constructive in all interactions.
+
+## License
+
+By contributing to this project, you agree that your contributions will be licensed under the same MIT License as the project. See [LICENSE](LICENSE) for details.
+
+Thank you for contributing! 🚀

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nolly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# 🚀 create-nolly-template
+
+All of my opiniated templates in one place. This is a CLI tool to create a new project based on one of my templates.
+
+## Install
+```bash
+npm i -g create-nolly-template
+# or pnpm i -g create-nolly-template
+```
+
+## Usage
+```bash
+create-nolly-template
+# or npx create-nolly-template
+# or pnpx create-nolly-template
+```
+
+## Templates
+You can see the full list of available templates by running `create-nolly-template --list` or `create-nolly-template -l`.
+
+## Commands
+- `create-nolly-template` - Create a new project based on one of the templates.
+- `create-nolly-template --list` or `create-nolly-template -l` - List all available templates.
+- `create-nolly-template --help` or `create-nolly-template -h` - Show help message.
+- `create-nolly-template --about` or `create-nolly-template -a` - Show information about the project.
+
+## Contributing
+If you want to contribute to this project, feel free to open a pull request or an issue. I would love to see your contributions!  
+See the [CONTRIBUTING](CONTRIBUTING.md) guide for more details.
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.

package/dist/builder.js

@@ -0,0 +1,83 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { TEMPLATES_ROOT } from './paths.js';
+function mergeIntoPackageJson(pkg, dependencies, devDependencies) {
+    if (dependencies)
+        pkg.dependencies = { ...pkg.dependencies, ...dependencies };
+    if (devDependencies)
+        pkg.devDependencies = { ...pkg.devDependencies, ...devDependencies };
+}
+function applyReplacements(content, answers) {
+    let result = content;
+    for (const [key, value] of Object.entries(answers))
+        result = result.replace(new RegExp(`{{${key}}}`, 'g'), value);
+    return result;
+}
+function toRegExp(pattern) {
+    return typeof pattern === 'string' ? new RegExp(pattern, 'g') : pattern;
+}
+function applyPatchOperations(content, operations) {
+    let result = content;
+    for (const op of operations) {
+        const regex = 'pattern' in op ? toRegExp(op.pattern) : undefined;
+        if (op.type === 'replace' && regex) {
+            result = result.replace(regex, op.replacement);
+        }
+        else if (op.type === 'remove' && regex) {
+            result = result.replace(regex, '');
+        }
+        else if (op.type === 'insertBefore' && regex) {
+            result = result.replace(regex, match => `${op.insert}\n${match}`);
+        }
+        else if (op.type === 'insertAfter' && regex) {
+            result = result.replace(regex, match => `${match}\n${op.insert}`);
+        }
+    }
+    return result;
+}
+function applyPatches(fileMap, patches) {
+    for (const patch of patches) {
+        const current = fileMap.get(patch.targetPath);
+        if (!current)
+            continue;
+        const next = applyPatchOperations(current, patch.operations);
+        fileMap.set(patch.targetPath, next);
+    }
+}
+async function loadDirectoryIntoMap(root, baseDir, fileMap) {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    for (const entry of entries) {
+        const absolute = path.join(root, entry.name);
+        const relative = path.relative(baseDir, absolute).replace(/\\/g, '/');
+        if (entry.isDirectory()) {
+            await loadDirectoryIntoMap(absolute, baseDir, fileMap);
+        }
+        else {
+            const content = await fs.readFile(absolute, 'utf-8');
+            fileMap.set(relative, content);
+        }
+    }
+}
+export async function buildProject(template, selectedFeatures, answers, outputDir) {
+    const fileMap = new Map();
+    const baseRoot = path.join(TEMPLATES_ROOT, template.templateRoot);
+    await loadDirectoryIntoMap(baseRoot, baseRoot, fileMap);
+    const pkgRaw = fileMap.get('package.json');
+    const pkg = pkgRaw ? JSON.parse(pkgRaw) : {};
+    mergeIntoPackageJson(pkg, template.dependencies, template.devDependencies);
+    for (const feature of selectedFeatures) {
+        if (feature.templateRoot) {
+            const featureRoot = path.join(TEMPLATES_ROOT, feature.templateRoot);
+            await loadDirectoryIntoMap(featureRoot, featureRoot, fileMap);
+        }
+        mergeIntoPackageJson(pkg, feature.dependencies, feature.devDependencies);
+    }
+    const allPatches = selectedFeatures.flatMap(f => f.patches ?? []);
+    applyPatches(fileMap, allPatches);
+    fileMap.set('package.json', JSON.stringify(pkg, null, 2));
+    await fs.ensureDir(outputDir);
+    for (const [filePath, content] of fileMap.entries()) {
+        const fullPath = path.join(outputDir, filePath);
+        await fs.outputFile(fullPath, applyReplacements(content, answers));
+    }
+}

package/dist/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import prompts from 'prompts';
+import { registry } from './registry/index.js';
+import { buildProject } from './builder.js';
+async function printHelp() {
+    console.log(`
+🚀 create-nolly-template v1.0.0
+
+Usage:
+  create-nolly-template          Interactive wizard
+  create-nolly-template --help   This help
+  create-nolly-template --about  About & credits
+  create-nolly-template --list   List all templates
+
+Examples:
+  pnpx create-nolly-template
+  create-nolly-template -l
+  `);
+    process.exit(0);
+}
+async function printAbout() {
+    console.log(`
+🚀 create-nolly-template
+
+Nolly's templates. Zero-config, TypeScript-first.
+
+Templates: Fastify, WebSocket, Swagger, MongoDB, Prisma, and even more !
+Built with: TypeScript, ESM, fs-extra, prompts, and a lot of ❤️
+
+Made by Nolly, a passionate full-stack developer and open-source enthusiast.
+GitHub: thenolle/create-nolly-template
+License: MIT
+`);
+    process.exit(0);
+}
+async function printList() {
+    console.log('\n📋 Available Templates & Features\n');
+    for (const category of registry) {
+        console.log(`┌─ ${category.name} (${category.key})`);
+        console.log('│');
+        for (const sub of category.subCategories) {
+            console.log(`│  ├─ ${sub.name} (${sub.key})`);
+            console.log('│  │');
+            for (const template of sub.templates) {
+                console.log(`│  │  ├─ ${template.name} (${template.key})`);
+                if (template.features?.length) {
+                    console.log(`│  │  │  Features:`);
+                    template.features.forEach(feat => console.log(`│  │  │    • ${feat.name} - ${feat.description}`));
+                }
+                console.log('│  │');
+            }
+        }
+        console.log('│');
+    }
+    console.log('Run without args for interactive mode.\n');
+    process.exit(0);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help') || args.includes('-h'))
+        return printHelp();
+    if (args.includes('--about') || args.includes('-a'))
+        return printAbout();
+    if (args.includes('--list') || args.includes('-l'))
+        return printList();
+    console.log('\n🚀 Welcome to create-nolly-template!\n');
+    const { category } = await prompts({
+        type: 'select',
+        name: 'category',
+        message: 'Main category',
+        choices: registry.map(category => ({ title: category.name, value: category }))
+    });
+    const { subCategory } = await prompts({
+        type: 'select',
+        name: 'subCategory',
+        message: 'Sub category',
+        choices: category.subCategories.map(subCategory => ({ title: subCategory.name, value: subCategory }))
+    });
+    if (!subCategory)
+        process.exit(0);
+    const { template } = await prompts({
+        type: 'select',
+        name: 'template',
+        message: 'Base template',
+        choices: subCategory.templates.map(template => ({ title: template.name, value: template }))
+    });
+    if (!template)
+        process.exit(0);
+    let selectedFeatures = [];
+    if (template.features && template.features.length > 0) {
+        const { features } = await prompts({
+            type: 'multiselect',
+            name: 'features',
+            message: 'Optional features (space to toggle)',
+            choices: template.features.map((feature) => ({
+                title: feature.name,
+                value: feature,
+                description: feature.description
+            })),
+            hint: '- Space to select. Return to submit'
+        });
+        selectedFeatures = features ?? [];
+    }
+    const answers = await prompts(template.prompts);
+    const { outputDir } = await prompts({
+        type: 'text',
+        name: 'outputDir',
+        message: 'Output directory',
+        initial: `./${answers.name || template.key}`
+    });
+    if (!outputDir)
+        process.exit(0);
+    await buildProject(template, selectedFeatures, answers, outputDir);
+    console.log('\n✅ Project created at', outputDir);
+    console.log('   Base:', template.name);
+    if (selectedFeatures.length > 0)
+        console.log('   Features:', selectedFeatures.map((feature) => feature.name).join(', '));
+    console.log('\n   cd', outputDir, '&& pnpm install\n');
+}
+main().catch(error => {
+    console.error('Error:', error);
+    process.exit(1);
+});

package/dist/paths.js

@@ -0,0 +1,5 @@
+import path from 'path';
+import url from 'url';
+const __filename = url.fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const TEMPLATES_ROOT = path.resolve(__dirname, '../templates');

package/dist/registry/index.js

@@ -0,0 +1,4 @@
+import { webCategory } from './web/index.js';
+export const registry = [
+    webCategory
+];

package/dist/registry/types.js

@@ -0,0 +1 @@
+export {};

package/dist/registry/web/backend/fastify/base.js

@@ -0,0 +1,17 @@
+import { swaggerFeature } from './features/swagger.js';
+import { websocketFeature } from './features/websocket.js';
+import { mongodbFeature } from './features/mongodb.js';
+export const fastifyBase = {
+    key: 'fastify',
+    name: 'Fastify TypeScript',
+    description: 'Fastify with TypeScript, auto-registration, health check',
+    prompts: [
+        { type: 'text', name: 'name', message: 'Project name', initial: 'my-fastify-app' }
+    ],
+    templateRoot: 'web/backend/fastify/base',
+    features: [
+        swaggerFeature,
+        websocketFeature,
+        mongodbFeature
+    ]
+};

package/dist/registry/web/backend/fastify/features/mongodb.js

@@ -0,0 +1,10 @@
+export const mongodbFeature = {
+    key: 'mongodb',
+    name: 'MongoDB support',
+    description: 'Adds MongoDB support',
+    templateRoot: 'web/backend/fastify/mongodb',
+    dependencies: {
+        'fastify-plugin': '^5.1.0',
+        'mongodb': '^7.1.0'
+    }
+};

package/dist/registry/web/backend/fastify/features/swagger.js

@@ -0,0 +1,26 @@
+export const swaggerFeature = {
+    key: 'swagger',
+    name: 'Swagger / OpenAPI docs',
+    description: 'Adds automatic API documentation with Swagger / OpenAPI',
+    dependencies: {
+        '@fastify/swagger': '^9.7.0',
+        '@fastify/swagger-ui': '^5.2.5'
+    },
+    patches: [
+        {
+            targetPath: 'src/app.ts',
+            operations: [
+                {
+                    type: 'insertBefore',
+                    pattern: "import path from 'path'",
+                    insert: "import swagger from '@fastify/swagger'\nimport swaggerUi from '@fastify/swagger-ui'"
+                },
+                {
+                    type: 'insertAfter',
+                    pattern: "app\\.register\\(helmet\\)",
+                    insert: "\tapp.register(swagger, { openapi: { info: { title: '{{name}} API', version: '1.0.0' } } })\n\tawait app.register(swaggerUi, { routePrefix: '/docs' })"
+                }
+            ]
+        }
+    ]
+};

package/dist/registry/web/backend/fastify/features/websocket.js

@@ -0,0 +1,31 @@
+export const websocketFeature = {
+    key: 'websocket',
+    name: 'WebSocket support',
+    description: 'Adds WebSocket support',
+    templateRoot: 'web/backend/fastify/websocket',
+    dependencies: {
+        '@fastify/websocket': '^11.2.0',
+    },
+    patches: [
+        {
+            targetPath: 'src/app.ts',
+            operations: [
+                {
+                    type: 'insertBefore',
+                    pattern: "import path from 'path'",
+                    insert: "import websocket from '@fastify/websocket'"
+                },
+                {
+                    type: 'insertAfter',
+                    pattern: `app\\.register\\(helmet\\)`,
+                    insert: `  app.register(websocket)`
+                },
+                {
+                    type: 'insertAfter',
+                    pattern: `await autoRegister\\(app, 'routes/\\*\\*/\\.routes\\.{ts,js}\\)`,
+                    insert: `  await autoRegister(app, 'routes/**/*.ws.{ts,js}', '/ws')`
+                }
+            ]
+        }
+    ]
+};

package/dist/registry/web/backend/index.js

@@ -0,0 +1,7 @@
+import { fastifyBase } from './fastify/base.js';
+export const backendSubCategory = {
+    key: 'backend',
+    name: 'Backend',
+    description: 'Backend related tools and frameworks',
+    templates: [fastifyBase],
+};

package/dist/registry/web/index.js

@@ -0,0 +1,7 @@
+import { backendSubCategory } from './backend/index.js';
+export const webCategory = {
+    key: 'web',
+    name: 'Web',
+    description: 'Web development templates and tools.',
+    subCategories: [backendSubCategory],
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "create-nolly-template",
+  "version": "1.0.0",
+  "description": "All of my opiniated templates in one place. This is a CLI tool to create a new project based on one of my templates.",
+  "keywords": [
+    "template",
+    "fastify",
+    "react",
+    "next.js",
+    "fullstack",
+    "vite",
+    "swagger",
+    "prisma",
+    "typescript",
+    "cli",
+    "boilerplate"
+  ],
+  "author": "Nolly",
+  "license": "MIT",
+  "bin": {
+    "create-nolly-template": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "dependencies": {
+    "fs-extra": "^11.3.4",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.5.0",
+    "@types/prompts": "^2.4.9",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc --build tsconfig.cli.json",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  }
+}

package/templates/web/backend/fastify/base/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/env": "^5.0.3",
+    "@fastify/helmet": "^13.0.2",
+    "dotenv": "^17.3.1",
+    "fast-glob": "^3.3.3",
+    "fastify": "^5.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "pino-pretty": "^13.1.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/web/backend/fastify/base/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+onlyBuiltDependencies:
+  - esbuild

package/templates/web/backend/fastify/base/src/app.ts

@@ -0,0 +1,53 @@
+import fastify from 'fastify'
+import cors from '@fastify/cors'
+import helmet from '@fastify/helmet'
+import path from 'path'
+import { fileURLToPath, pathToFileURL } from 'url'
+import fg from 'fast-glob'
+import { env } from './utils/env'
+import { sendResponse } from './utils/response'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+async function autoRegister(app: ReturnType<typeof fastify>, pattern: string, prefix: string = '') {
+  const joined = path.join(__dirname, pattern).replace(/\\/g, '/')
+  const files = fg.sync(joined)
+  await Promise.all(files.map(async (file) => {
+    const module = await import(pathToFileURL(file).href)
+    const fn = module.default || module[Object.keys(module)[0]]
+    if (typeof fn === 'function') void app.register(fn, { prefix })
+  }))
+}
+
+export async function buildApp() {
+  const isDev = env.NODE_ENV === 'development'
+  const app = fastify({
+    logger: {
+      level: 'info',
+      transport: isDev ? {
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          translateTime: 'HH:MM:ss',
+          ignore: 'pid,hostname',
+        },
+      } : undefined,
+    },
+  })
+
+  app.register(cors, { origin: true })
+  app.register(helmet)
+
+  await autoRegister(app, 'plugins/**/*.plugin.{ts,js}')
+  await autoRegister(app, 'routes/**/*.routes.{ts,js}')
+
+  app.setNotFoundHandler((_request, reply) => sendResponse(reply, 404, { error: 'Route not found' }))
+  app.setErrorHandler((error: any, _request, reply) => {
+    const statusCode = error?.statusCode ?? 500
+    app.log.error(error)
+    return sendResponse(reply, statusCode, { error: statusCode >= 500 ? 'Internal Server Error' : error.message })
+  })
+
+  return app
+}

package/templates/web/backend/fastify/base/src/controllers/user.controller.ts

@@ -0,0 +1,12 @@
+import { FastifyRequest, FastifyReply } from 'fastify'
+import { z } from 'zod'
+import { sendResponse } from '../utils/response'
+
+const userSchema = z.object({ id: z.uuid() })
+
+export async function getUserHandler(request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) {
+  const parseResult = userSchema.safeParse(request.params)
+  if (!parseResult.success) return sendResponse(reply, 400, { error: 'Invalid user ID' })
+  const user = { id: parseResult.data.id, name: 'Nolly Example' }
+  return sendResponse(reply, 200, user)
+}

package/templates/web/backend/fastify/base/src/index.ts

@@ -0,0 +1,25 @@
+import 'dotenv/config'
+import { buildApp } from './app'
+import { env } from './utils/env'
+
+const PORT = parseInt(env.PORT, 10)
+const HOST = env.HOST
+
+buildApp()
+  .then((app) => {
+    const shutdown = async (signal: string) => {
+      app.log.info(`Received ${signal}, shutting down...`)
+      await app.close()
+      process.exit(0)
+    }
+    process.on('SIGINT', () => shutdown('SIGINT'))
+    process.on('SIGTERM', () => shutdown('SIGTERM'))
+    app.listen({ port: PORT, host: HOST }).catch((error) => {
+      app.log.error('Error starting server:', error)
+      process.exit(1)
+    })
+  })
+  .catch((error) => {
+    console.error('Error building app:', error)
+    process.exit(1)
+  })

package/templates/web/backend/fastify/base/src/plugins/health.plugin.ts

@@ -0,0 +1,6 @@
+import { FastifyInstance } from 'fastify'
+import { sendResponse } from '../utils/response'
+
+export default async function healthPlugin(app: FastifyInstance) {
+  app.get('/health', async (_request, reply) => sendResponse(reply, 200, { status: 'ok', uptime: process.uptime() }))
+}

package/templates/web/backend/fastify/base/src/routes/user.routes.ts

@@ -0,0 +1,6 @@
+import { FastifyInstance } from 'fastify'
+import { getUserHandler } from '../controllers/user.controller'
+
+export default async function userRoutes(app: FastifyInstance) {
+  app.get('/users/:id', getUserHandler)
+}

package/templates/web/backend/fastify/base/src/utils/env.ts

@@ -0,0 +1,17 @@
+import 'dotenv/config'
+import { z } from 'zod'
+
+const envSchema = z.object({
+  PORT: z.string().optional().default('4000'),
+  HOST: z.string().optional().default('0.0.0.0'),
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+})
+
+const result = envSchema.safeParse(process.env)
+if (!result.success) {
+  console.error('❌ Invalid environment variables:')
+  const flattened = z.treeifyError(result.error)
+  console.error(flattened.errors)
+  process.exit(1)
+}
+export const env = result.data

package/templates/web/backend/fastify/base/src/utils/response.ts

@@ -0,0 +1,5 @@
+import { FastifyReply } from 'fastify'
+
+export function sendResponse<T>(reply: FastifyReply, statusCode: number, data: T) {
+  return reply.status(statusCode).send({ success: statusCode < 400, data })
+}

package/templates/web/backend/fastify/base/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": [ "ES2022" ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "skipLibCheck": true
+  },
+  "include": [ "src" ]
+}

package/templates/web/backend/fastify/mongodb/.env

@@ -0,0 +1,2 @@
+MONGO_URI=YOUR_MONGODB_URI
+MONGO_DB=YOUR_DATABASE_NAME

package/templates/web/backend/fastify/mongodb/src/plugins/mongo.plugin.ts

@@ -0,0 +1,53 @@
+import fastifyPlugin from 'fastify-plugin'
+import { MongoClient, Db } from 'mongodb'
+import { FastifyInstance } from 'fastify'
+import path from 'path'
+import { fileURLToPath, pathToFileURL } from 'url'
+import fastGlob from 'fast-glob'
+import { env } from '../utils/env'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+export type ModelFactory = (db: Db, app: FastifyInstance) => any
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    mongo: {
+      client: MongoClient
+      db: Db
+    }
+    models: Record<string, any>
+  }
+}
+
+async function autoLoadModels(app: FastifyInstance, db: Db) {
+  const pattern = path.join(__dirname, '../models/**/*.model.{ts,js}').replace(/\\/g, '/')
+  const files = fastGlob.sync(pattern)
+  const models: Record<string, any> = {}
+  for (const file of files) {
+    const module = await import(pathToFileURL(file).href)
+    const factory: ModelFactory = module.default || module[Object.keys(module)[0]]
+    if (typeof factory !== 'function') continue
+    const model = factory(db, app)
+    if (!model?.name) throw new Error(`Model in ${file} must return { name: string }`)
+    models[model.name] = model
+  }
+  return models
+}
+
+export default fastifyPlugin(async function mongoPlugin(app) {
+  const client = new MongoClient(env.MONGO_URI, { serverSelectionTimeoutMS: 5000 })
+  try {
+    await client.connect()
+  } catch (error: any) {
+    app.log.error('Mongo connection failed:', error)
+    throw error
+  }
+  const db = client.db(env.MONGO_DB)
+  app.decorate('mongo', { client, db })
+  const models = await autoLoadModels(app, db)
+  app.decorate('models', models)
+  app.addHook('onClose', async () => { await client.close() })
+  app.log.info(`📦 Mongo connected: ${env.MONGO_DB}`)
+}, { name: 'mongoPlugin' })

package/templates/web/backend/fastify/websocket/src/routes/chat.ws.ts

@@ -0,0 +1,23 @@
+import { FastifyInstance } from 'fastify'
+import { z } from 'zod'
+import { createWebSocketContext, registerConnection } from '../utils/websocket'
+
+export default async function chat(app: FastifyInstance) {
+  app.get('/chat', { websocket: true }, async (socket, request) => {
+    const options = { auth: false, jwtSecret: 'dev-secret', rateLimit: { max: 10, windowMs: 1000 } }
+    const client = await registerConnection(socket, request, options)
+    const context = createWebSocketContext(client, options)
+    app.log.info(`WS connected: ${context.id} user=${JSON.stringify(context.user)}`)
+    context.on('join', z.object({ room: z.string().min(1) }), ({ room }, context) => {
+      context.join(room)
+      context.send('joined', { room })
+    })
+    context.on('leave', z.object({ room: z.string().min(1) }), ({ room }, context) => {
+      context.leave(room)
+      context.send('left', { room })
+    })
+    context.on('message', z.object({ room: z.string().min(1), message: z.string().min(1) }), ({ room, message }, context) => context.broadcast('message', { from: context.user ?? context.id, message }, room))
+    context.on('broadcast', z.object({ message: z.string().min(1) }), ({ message }, context) => context.broadcast('broadcast', { from: context.user ?? context.id, message }))
+    socket.on('close', () => app.log.info(`WebSocket disconnected: ${context.id}`))
+  })
+}

package/templates/web/backend/fastify/websocket/src/utils/websocket.ts

@@ -0,0 +1,177 @@
+import { WebSocket } from '@fastify/websocket'
+import { z } from 'zod'
+import { createHmac, randomUUID } from 'crypto'
+
+// ----- Protocol -----
+
+const baseSchema = z.object({
+  event: z.string().min(1),
+  data: z.unknown().optional()
+})
+type BaseMessage = z.infer<typeof baseSchema>
+
+// ----- Types -----
+
+export type WebSocketUser = Record<string, any>
+type Client = {
+  id: string
+  socket: WebSocket
+  rooms: Set<string>
+  handlers: Map<string, (data: unknown, context: WebSocketContext) => void>
+  user?: WebSocketUser
+  rate?: {
+    tokens: number
+    last: number
+  }
+}
+const clients = new Map<string, Client>()
+const rooms = new Map<string, Set<string>>()
+
+// ----- Options -----
+
+type WebSocketOptions = {
+  auth?: boolean | ((request: any) => Promise<WebSocketUser | null> | WebSocketUser | null)
+  jwtSecret?: string
+  rateLimit?: {
+    max: number
+    windowMs: number
+  }
+}
+
+// ----- JsonWebSocket -----
+
+function verifyJWT(token: string, secret: string): WebSocketUser | null {
+  try {
+    const [header, payload, signature] = token.split('.')
+    if (!header || !payload || !signature) return null
+    const expected = createHmac('sha256', secret).update(`${header}.${payload}`).digest('base64url')
+    if (expected !== signature) return null
+    const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString())
+    return decoded
+  } catch {
+    return null
+  }
+}
+
+// ----- Core -----
+
+export async function registerConnection(socket: WebSocket, request?: any, options?: WebSocketOptions): Promise<Client> {
+  const id = randomUUID()
+  const client: Client = { id, socket, rooms: new Set(), handlers: new Map() }
+  if (options?.auth) {
+    let user: WebSocketUser | null = null
+    if (typeof options.auth === 'function') {
+      user = await options.auth(request)
+    } else if (options.auth === true) {
+      const header = request?.headers?.authorization
+      const token = header?.replace('Bearer ', '')
+      if (token && options.jwtSecret) user = verifyJWT(token, options.jwtSecret)
+    }
+    if (!user) {
+      socket.send(JSON.stringify({ event: 'error', data: { message: 'Unauthorized' } }))
+      socket.close()
+      throw new Error('Unauthorized WS connection')
+    }
+    client.user = user
+  }
+  if (options?.rateLimit) {
+    client.rate = {
+      tokens: options.rateLimit.max,
+      last: Date.now()
+    }
+  }
+  clients.set(id, client)
+  socket.on('close', () => {
+    for (const room of client.rooms) leaveRoom(id, room)
+    clients.delete(id)
+  })
+  return client
+}
+
+// ----- Rooms -----
+
+function joinRoom(clientId: string, room: string) {
+  const client = clients.get(clientId)
+  if (!client) return
+  if (!rooms.has(room)) rooms.set(room, new Set())
+  rooms.get(room)!.add(clientId)
+  client.rooms.add(room)
+}
+
+function leaveRoom(clientId: string, room: string) {
+  const client = clients.get(clientId)
+  if (!client) return
+  rooms.get(room)?.delete(clientId)
+  client.rooms.delete(room)
+  if (rooms.get(room)?.size === 0) rooms.delete(room)
+}
+
+// ----- Broadcasting -----
+
+function sendRaw(socket: WebSocket, payload: unknown) {
+  socket.send(JSON.stringify(payload))
+}
+
+function broadcast(message: BaseMessage, room?: string) {
+  const payload = JSON.stringify(message)
+  if (room) {
+    const ids = rooms.get(room)
+    if (!ids) return
+    for (const id of ids) clients.get(id)?.socket.send(payload)
+    return
+  }
+  for (const client of clients.values()) client.socket.send(payload)
+}
+
+// ----- Rate Limiting -----
+
+function checkRate(client: Client, options?: WebSocketOptions): boolean {
+  if (!options?.rateLimit || !client.rate) return true
+  const now = Date.now()
+  const elapsed = now - client.rate.last
+  const refill = (elapsed / options.rateLimit.windowMs) * options.rateLimit.max
+  client.rate.tokens = Math.min(options.rateLimit.max, client.rate.tokens + refill)
+  client.rate.last = now
+  if (client.rate.tokens < 1) return false
+  client.rate.tokens -= 1
+  return true
+}
+
+// ----- Context -----
+
+export type WebSocketContext = {
+  id: string
+  user?: WebSocketUser
+  send: (event: string, data?: unknown) => void
+  join: (room: string) => void
+  leave: (room: string) => void
+  broadcast: (event: string, data?: unknown, room?: string) => void
+  on: <T>(event: string, schema: z.ZodType<T>, handler: (data: T, context: WebSocketContext) => void) => void
+}
+
+export function createWebSocketContext(client: Client, options?: WebSocketOptions): WebSocketContext {
+  const context: WebSocketContext = {
+    id: client.id,
+    user: client.user,
+    send: (event, data) => sendRaw(client.socket, { event, data }),
+    join: (room) => joinRoom(client.id, room),
+    leave: (room) => leaveRoom(client.id, room),
+    broadcast: (event, data, room) => broadcast({ event, data }, room),
+    on: (event, schema, handler) => {
+      client.handlers.set(event, (raw, context) => {
+        if (!checkRate(client, options)) return context.send('error', { message: 'Rate limit exceeded' })
+        const parsed = schema.safeParse(raw)
+        if (!parsed.success) return context.send('error', { message: `Invalid payload for ${event}` })
+        handler(parsed.data, context)
+      })
+    }
+  }
+  client.socket.on('message', (raw: any) => {
+    let message: BaseMessage
+    try { message = baseSchema.parse(JSON.parse(raw.toString())) } catch { return context.send('error', { message: 'Invalid message format' }) }
+    const handler = client.handlers.get(message.event)
+    if (!handler) return context.send('error', { message: `Unhandled event: ${message.event}` })
+    handler(message.data, context)
+  })
+  return context
+}