node-ts starter

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: main
+  pull_request:
+
+jobs:
+  Build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        id: pnpm
+        run: |
+          npm i pnpm@latest -g
+          sed -i '/^use-node-version/s/^/#/' .npmrc
+          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
+          sed -i '/^#use-node-version/s/^#//' .npmrc
+
+      - name: Setup cache
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.pnpm.outputs.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('./pnpm-lock.yaml') }}
+          restore-keys: ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm i -P
+
+      - run: pnpm build

.gitignore

@@ -0,0 +1,8 @@
+# Build output
+/dist/
+
+# Dependencies
+/node_modules/
+
+# Environment variables
+/env.ts

.npmrc

@@ -0,0 +1 @@
+use-node-version=20.11.0

.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["esbenp.prettier-vscode", "biomejs.biome"]
+}

.vscode/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Attach",
+      "port": 9229,
+      "request": "attach",
+      "skipFiles": ["<node_internals>/**"],
+      "type": "node"
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  // #region Editor
+  "editor.codeActionsOnSave": {
+    "quickfix.biome": "explicit",
+    "source.organizeImports.biome": "explicit"
+  },
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  // #endregion
+  // #region Debugger
+  "debug.javascript.autoAttachFilter": "onlyWithFlag",
+  "debug.internalConsoleOptions": "openOnSessionStart"
+  // #endregion
+}

README.md

@@ -0,0 +1,80 @@
+# Node.js + TypeScript Starter
+
+![](../../actions/workflows/ci.yml/badge.svg)
+
+[![](https://railway.app/button.svg)](https://railway.app/template/8AWlL5?referralCode=bonus)
+
+## Key Features
+
+- [<img src="https://user-images.githubusercontent.com/17180392/211619716-8630ae1a-e5ea-424f-87a6-f3188edae821.svg" height=19.2 align=center /> TypeScript](https://www.typescriptlang.org/)
+  - [Typed environment variables](dev.ts)
+  - [TypeScript & JavaScript compatibility](https://www.typescriptlang.org/tsconfig#allowJs)
+  - [ES Modules & CommonJS compatibility](https://esbuild.github.io/api/#format-commonjs)
+- [<img src="https://user-images.githubusercontent.com/124377191/228204788-98a151c8-fc70-4dac-a966-4be6513aafc6.png" height=19.2 align=center /> Node.js](https://nodejs.org/)
+  - [Live Reload](https://nodejs.org/en/blog/release/v18.11.0)
+  - [Debugging](https://nodejs.org/en/docs/guides/debugging-getting-started)
+- [<img src="https://user-images.githubusercontent.com/124377191/228203400-d65b9566-d92e-48b1-9b46-9aa95c05fb21.svg" height=19.2 align=center /> esbuild](https://esbuild.github.io/)
+  - [Fast bundling](https://esbuild.github.io/faq/#benchmark-details)
+  - [Fast transpiling](https://esbuild.github.io/faq/#benchmark-details)
+- [<img src="https://github-production-user-asset-6210df.s3.amazonaws.com/17180392/266780371-74b32ff7-5cc3-45e1-af80-923a05c9f87b.svg" height=19.2 align=center /> Biome](https://biomejs.dev/)
+  - [Fast linting](https://github.com/biomejs/biome/tree/main/benchmark#linting)
+  - [Fast formatting](https://github.com/biomejs/biome/tree/main/benchmark#formatter)
+  - [Import sorting](https://biomejs.dev/analyzer/#imports-sorting)
+- [<img src="https://user-images.githubusercontent.com/124377191/228447757-78408c15-e914-4fb3-9135-f1ff45ee3fce.svg" height=19.2 align=center /> GitHub](https://github.com)
+  - [One click template](https://github.com/dayblox/node-ts/generate)
+  - [Continuous Integration with dependency caching](.github/workflows/ci.yml)
+
+## Prerequisites
+
+- [<img src="https://user-images.githubusercontent.com/124377191/228203877-9975d517-140a-491d-80f5-9cca049143a6.svg" height=19.2 align=center /> pnpm](https://pnpm.io/installation) `>=7.27.0`
+  - [Running multiple scripts in parallel](https://pnpm.io/cli/run#running-multiple-scripts)
+  - [Automatic Node.js version management](https://pnpm.io/npmrc#use-node-version)
+
+## Getting Started
+
+1.  **[Deploy on Railway](https://railway.app/template/8AWlL5?referralCode=bonus)** or **[use this template](https://github.com/dayblox/node-ts/generate)**
+
+2.  **Clone** the repository
+
+3.  **Install** dependencies
+
+    ```sh
+    pnpm i
+    ```
+
+4.  Create environment file `env.ts` at the root
+
+    ```ts
+    export default {
+      PORT: "3000",
+    };
+    ```
+
+    #
+
+    _Optionally_ typecheck environment with `zod`
+
+    ```ts
+    import { z } from "zod";
+
+    z.object({
+      PORT: z.coerce.number(),
+      URL: z.string().url(),
+      UUID: z.string().uuid(),
+      EMAIL: z.string().email().optional(),
+    }).parse(process.env);
+    ```
+
+## Usage
+
+- **Development** mode (**debug**)
+
+  ```sh
+  pnpm dev
+  ```
+
+- **Production** build
+
+  ```sh
+  pnpm build && pnpm start
+  ```

biome.json

@@ -0,0 +1,9 @@
+{
+	"files": { "ignore": [".vscode/*", "dist/*", "node_modules/*"] },
+	"javascript": {
+		"formatter": {
+			"semicolons": "asNeeded"
+		}
+	},
+	"organizeImports": { "enabled": true }
+}

dev.ts

@@ -0,0 +1,11 @@
+import env from "./env"
+
+Object.assign(process.env, env)
+
+type ENV = typeof env
+declare global {
+	namespace NodeJS {
+		// biome-ignore lint/suspicious/noEmptyInterface:
+		interface ProcessEnv extends ENV {}
+	}
+}

package.json

@@ -0,0 +1,23 @@
+{
+  "name": "node-ts",
+  "version": "0.0.0",
+  "author": "dayblox",
+  "description": "Node.js & TypeScript starter",
+  "engines": {
+    "node": ">=18.11",
+    "pnpm": ">=7.27"
+  },
+  "scripts": {
+    "dev": "pnpm /dev:.*/",
+    "dev:build": "esbuild dev.ts ./src --bundle --outdir=dist --packages=external --platform=node --sourcemap --watch",
+    "dev:run": "node --inspect -r ./dist/dev.js --watch dist/src",
+    "build": "esbuild index=./src --bundle --minify --outdir=dist --packages=external --platform=node",
+    "start": "node dist"
+  },
+  "dependencies": {
+    "esbuild": "^0.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19"
+  }
+}