@wolfstar/create-http-framework 2.5.2 → 2.6.0-next-20260926200949

package/README.md

@@ -34,13 +34,16 @@ The CLI will guide you through the following prompts:
 - **Project name** — an npm-compatible name for your bot
 - **Package manager** — npm, yarn, pnpm, or bun
 - **Language** — TypeScript or JavaScript
-- **Build tool** — tsdown, TypeScript 6, or the TypeScript 7 release candidate
+- **Build tool** — tsdown, Vite, Vite + Nitro, TypeScript 6, or the TypeScript 7 release candidate (Vite and Vite + Nitro are experimental)
 - **Linter and formatter** — Oxlint / ESLint and Oxfmt / Prettier
 - **Port** — the port the HTTP server will listen on (default: `3000`)
 - **Optional features** (multiselect) —
     - **i18n** — add [`@wolfstar/plugin-i18next`](https://github.com/wolfstar-project/stars-components/tree/main/packages/plugin-i18next)
     - **Subcommands** — add an example command that uses subcommands
     - **Testing** — set up Vitest with [`@wolfstar/http-framework-test-utils`](https://github.com/wolfstar-project/stars-components/tree/main/packages/http-framework-test-utils)
+    - **Gateway** — receive gateway events next to the HTTP interactions with [`@wolfstar/plugin-gateway`](https://github.com/wolfstar-project/plugins/tree/main/packages/plugin-gateway)
+    - **Cache** — cache gateway entities with [`@wolfstar/plugin-cache`](https://github.com/wolfstar-project/plugins/tree/main/packages/plugin-cache), in memory or in Redis (asked as a follow-up)
+    - **Sharder** — spread gateway shards across cluster workers with [`@wolfstar/plugin-sharder`](https://github.com/wolfstar-project/plugins/tree/main/packages/plugin-sharder)
 - **Auto-install** — install dependencies immediately after scaffolding
 
 ## Options
@@ -52,13 +55,17 @@ The CLI will guide you through the following prompts:
 | `--interactive`                      | `-i`  | Force interactive prompts even when an AI agent is detected                |
 | `--package-manager <pm>`             |       | Choose npm, yarn, pnpm, or bun                                             |
 | `--language <lang>`                  |       | Choose TypeScript (`ts`) or JavaScript (`js`)                              |
-| `--build <tool>`                     |       | Choose `tsc6`, `tsc7`, or `tsdown` for TypeScript                          |
+| `--build <tool>`                     |       | Choose `tsc6`, `tsc7`, `tsdown`, `vite`, or `vite-nitro` for TypeScript    |
 | `--lint <linter>`                    |       | Choose `none`, `eslint`, or `oxlint`                                       |
 | `--format <formatter>`               |       | Choose `none`, `prettier`, or `oxfmt`                                      |
 | `--port <number>`                    |       | Set the HTTP port (default: `3000`)                                        |
 | `--i18n` / `--no-i18n`               |       | Enable or disable `@wolfstar/plugin-i18next` scaffolding                   |
 | `--subcommands` / `--no-subcommands` |       | Enable or disable the example subcommand command                           |
 | `--testing` / `--no-testing`         |       | Enable or disable the Vitest + `@wolfstar/http-framework-test-utils` setup |
+| `--gateway` / `--no-gateway`         |       | Enable or disable `@wolfstar/plugin-gateway` scaffolding                   |
+| `--cache` / `--no-cache`             |       | Enable or disable `@wolfstar/plugin-cache` (turns `--gateway` on)          |
+| `--redis` / `--no-redis`             |       | Cache in Redis instead of memory (turns `--cache` on)                      |
+| `--sharder` / `--no-sharder`         |       | Enable or disable `@wolfstar/plugin-sharder` (turns `--gateway` on)        |
 | `--install` / `--no-install`         |       | Enable or disable dependency installation                                  |
 | `--help`                             | `-h`  | Print usage and exit                                                       |
 
@@ -82,6 +89,7 @@ my-discord-bot/
 │   │   ├── setup/
 │   │   │   ├── all.ts            # Aggregates setup imports
 │   │   │   └── logger.ts         # Logger configuration
+│   │   ├── cache.ts              # Gateway entity cache (--cache)
 │   │   └── types/
 │   │       └── augments.ts       # Module augmentations (TypeScript only)
 │   ├── locales/
@@ -90,11 +98,13 @@ my-discord-bot/
 │   │           └── ping.json     # Example locale resource (--i18n)
 │   ├── @types/
 │   │   └── i18next.d.ts          # Generated i18next augmentation (--i18n)
+│   ├── shard.ts                  # Gateway client run by each shard worker (--sharder)
 │   └── main.ts                   # Entry point — starts the HTTP server
 ├── tests/
 │   └── ping.test.ts              # Example test (--testing)
 ├── vitest.config.ts              # Vitest configuration (--testing)
 ├── vitest.setup.ts               # Vitest setup file (--testing)
+├── compose.yaml                  # Local Redis server (--redis)
 ├── README.md                     # Generated project README
 ├── .env                          # Environment variables (DISCORD_TOKEN, DISCORD_PUBLIC_KEY)
 ├── .gitignore
@@ -105,8 +115,27 @@ my-discord-bot/
 - `src/locales/en-US/commands/ping.json` and `src/@types/i18next.d.ts` are only generated when **i18n** is enabled.
 - `src/@types/i18next.d.ts` is produced by `@wolfstar/i18next-type-generator`; the CLI runs it automatically at the end of scaffolding, and it can be re-run any time locale files change (see [`generate:i18n`](#i18n-type-generation) below).
 - `src/commands/math.ts` is only generated when **Subcommands** is enabled.
+- `src/lib/cache.ts` is only generated with **Cache**, `src/shard.ts` with **Sharder**, and `compose.yaml` with **Redis**.
 - `tests/ping.test.ts`, `vitest.config.ts`, and `vitest.setup.ts` are only generated when **Testing** is enabled.
 
+### Vite and Nitro
+
+`--build vite` bundles the bot with [Vite](https://vite.dev) into a single `dist/main.js`, and `--build vite-nitro` hands it to [Nitro](https://nitro.build), which writes a deployable `.output/` (the `node-server` preset, pinned in `stars.config.ts`). Both are TypeScript only and turn on `experimental.enableVite` (and `enableNitro`) in the generated `stars.config.ts`.
+
+- A bundle has no `commands` directory to scan, so `src/main.ts` imports and loads the example commands explicitly. Add your own commands there.
+- With Nitro, `src/main.ts` default-exports the client instead of calling `listen()`, and the port comes from `PORT` in `.env`.
+- `main` and `start` are wired to the `node-server` preset's output, `.output/server/index.mjs`. Changing `nitro.preset` to target another platform means deploying that platform's `.output/` instead of running `npm start` — and with `--gateway`, only a preset that keeps a server alive will hold the gateway connection open.
+- Nitro cannot be combined with `--sharder`: the sharder's manager process has no client for Nitro to forward requests to.
+
+### Gateway, cache and sharder
+
+The gateway plugins are for bots that also need gateway events, so they require a long-lived process and Node.js `>=24.17.0`.
+
+- `--gateway` makes `src/main.*` create a `GatewayClient` (it still answers HTTP interactions).
+- `--cache` adds `src/lib/cache.*`, an in-memory cache by default. `--redis` (or the follow-up prompt) swaps it for `ioredis`, adds a `compose.yaml` to start a local Redis, and `REDIS_URL` to `.env`.
+- `--sharder` turns `src/main.*` into the shard manager and adds `src/shard.*`, which runs in every cluster worker (`SHARDER_CLUSTERS` in `.env`).
+- `--cache` and `--sharder` switch `--gateway` on, and `--redis` switches `--cache` on.
+
 ### i18n type generation
 
 When i18n is enabled, the generated `package.json` includes a `generate:i18n` script that (re)generates `src/@types/i18next.d.ts` from the JSON files under `src/locales/`:
@@ -119,4 +148,4 @@ The CLI runs this script automatically once at the end of scaffolding; re-run it
 
 ## Requirements
 
-- Node.js `>=20`
+- Node.js `>=20` (`>=24.17.0` for projects using the gateway)

package/dist/index.js

@@ -45,8 +45,40 @@ const LANGUAGES = ["ts", "js"];
 const BUILD_TOOLS = [
 	"tsc6",
 	"tsc7",
-	"tsdown"
+	"tsdown",
+	"vite",
+	"vite-nitro"
 ];
+/** `vite` and `vite-nitro` both bundle the app with Vite, so pieces are loaded explicitly instead of scanned from disk. */
+function isViteBuild(buildTool) {
+	return buildTool === "vite" || buildTool === "vite-nitro";
+}
+/** `vite-nitro` hands the built client to Nitro, which owns the HTTP server. */
+function isNitroBuild(buildTool) {
+	return buildTool === "vite-nitro";
+}
+/**
+* Applies the dependencies between the gateway features: Redis needs the cache, and the cache and the sharder both
+* need the gateway client. `implied` names the features that were switched on to satisfy another one.
+*/
+function resolveGatewayFeatures(features) {
+	const resolved = { ...features };
+	const implied = [];
+	if (resolved.redis && !resolved.cache) {
+		resolved.cache = true;
+		implied.push("cache");
+	}
+	if ((resolved.cache || resolved.sharder) && !resolved.gateway) {
+		resolved.gateway = true;
+		implied.push("gateway");
+	}
+	return {
+		features: resolved,
+		implied
+	};
+}
+/** The Nitro entry must default-export the HTTP client, which the sharder's manager process never has. */
+const SHARDER_WITH_NITRO_ERROR = "--sharder cannot be combined with --build vite-nitro: Nitro needs a client to forward requests to in every process.";
 const LINTERS = [
 	"none",
 	"eslint",
@@ -74,7 +106,7 @@ async function fetchVersion(packageName) {
 /**
 * Resolves the latest versions of only the packages required by the chosen selections.
 * `ts-node` is intentionally never included. TypeScript 7.0 (tsc7) is pinned to the rc instead
-* of being fetched, because `typescript@latest` resolves to the 6.x line.
+* of being fetched, because `typescript@latest` resolves to the 6.x line. Nitro v3 is still a beta, so callers pin it exactly.
 */
 async function fetchDependencyVersions(selections) {
 	const names = /* @__PURE__ */ new Set([
@@ -88,6 +120,10 @@ async function fetchDependencyVersions(selections) {
 	]);
 	if (selections.i18n) names.add("@wolfstar/plugin-i18next").add("@wolfstar/i18next-type-generator");
 	if (selections.testing) names.add("vitest").add("@wolfstar/http-framework-test-utils");
+	if (selections.gateway) names.add("@wolfstar/plugin-gateway");
+	if (selections.cache) names.add("@wolfstar/plugin-cache");
+	if (selections.redis) names.add("ioredis");
+	if (selections.sharder) names.add("@wolfstar/plugin-sharder");
 	if (selections.language === "ts") {
 		names.add("@types/node");
 		switch (selections.buildTool) {
@@ -95,7 +131,13 @@ async function fetchDependencyVersions(selections) {
 				names.add("typescript");
 				break;
 			case "tsc7": break;
-			case "tsdown": names.add("tsdown").add("typescript");
+			case "tsdown":
+				names.add("tsdown").add("typescript");
+				break;
+			case "vite":
+			case "vite-nitro":
+				names.add("vite").add("typescript");
+				if (isNitroBuild(selections.buildTool)) names.add("nitro");
 		}
 	}
 	if (selections.linter === "eslint") {
@@ -183,12 +225,17 @@ function sortKeys(record) {
 function json(value) {
 	return `${JSON.stringify(value, null, "	")}\n`;
 }
+/** The file `start` runs and `main` points at: sources for JavaScript, the build output for TypeScript. */
+function entryFile(ctx) {
+	if (ctx.language === "js") return "src/main.js";
+	return isNitroBuild(ctx.buildTool) ? ".output/server/index.mjs" : "dist/main.js";
+}
 function buildScripts(ctx) {
 	const scripts = {
 		dev: "stars dev",
-		...ctx.language === "ts" && ctx.buildTool === "tsdown" ? { postinstall: "stars prepare" } : {},
+		...ctx.language === "ts" && (ctx.buildTool === "tsdown" || isViteBuild(ctx.buildTool)) ? { postinstall: "stars prepare" } : {},
 		...ctx.language === "js" ? {} : { build: "stars build" },
-		start: ctx.language === "js" ? "node src/main.js" : "node dist/main.js"
+		start: `node ${entryFile(ctx)}`
 	};
 	if (ctx.linter === "oxlint") {
 		scripts["lint"] = "oxlint src";
@@ -219,6 +266,10 @@ function buildDependencies(ctx) {
 		"gradient-string": caret(v["gradient-string"])
 	};
 	if (ctx.i18n) dependencies["@wolfstar/plugin-i18next"] = caret(v["@wolfstar/plugin-i18next"]);
+	if (ctx.gateway) dependencies["@wolfstar/plugin-gateway"] = caret(v["@wolfstar/plugin-gateway"]);
+	if (ctx.cache) dependencies["@wolfstar/plugin-cache"] = caret(v["@wolfstar/plugin-cache"]);
+	if (ctx.redis) dependencies["ioredis"] = caret(v["ioredis"]);
+	if (ctx.sharder) dependencies["@wolfstar/plugin-sharder"] = caret(v["@wolfstar/plugin-sharder"]);
 	return sortKeys(dependencies);
 }
 function buildDevDependencies(ctx) {
@@ -236,6 +287,12 @@ function buildDevDependencies(ctx) {
 			case "tsdown":
 				dev["tsdown"] = caret(v["tsdown"]);
 				dev["typescript"] = caret(v["typescript"]);
+				break;
+			case "vite":
+			case "vite-nitro":
+				dev["vite"] = caret(v["vite"]);
+				dev["typescript"] = caret(v["typescript"]);
+				if (isNitroBuild(ctx.buildTool)) dev["nitro"] = v["nitro"];
 		}
 	}
 	if (ctx.linter === "eslint") {
@@ -254,7 +311,7 @@ function buildDevDependencies(ctx) {
 }
 function packageJson(ctx) {
 	const devDependencies = buildDevDependencies(ctx);
-	const main = ctx.language === "js" ? "src/main.js" : "dist/main.js";
+	const main = entryFile(ctx);
 	return json({
 		name: ctx.name,
 		version: "1.0.0",
@@ -264,7 +321,7 @@ function packageJson(ctx) {
 		scripts: buildScripts(ctx),
 		dependencies: buildDependencies(ctx),
 		...Object.keys(devDependencies).length > 0 ? { devDependencies } : {},
-		engines: { node: ">=20" }
+		engines: { node: ctx.gateway ? ">=24.17.0" : ">=20" }
 	});
 }
 const sharedCompilerOptions = {
@@ -283,6 +340,19 @@ const sharedCompilerOptions = {
 /** Writes the tsconfig(s). The tsc branches use a composite build so `tsc -b src` resolves `src/tsconfig.json`. */
 function writeTsconfig(targetDir, ctx) {
 	if (ctx.language === "js") return;
+	if (isViteBuild(ctx.buildTool)) {
+		writeFile(join(targetDir, "tsconfig.json"), json({
+			extends: "./.stars/tsconfig.json",
+			compilerOptions: { types: ["node"] },
+			include: ["src/**/*.ts", ".stars/*.d.ts"],
+			exclude: [
+				"node_modules",
+				"dist",
+				".output"
+			]
+		}));
+		return;
+	}
 	if (ctx.buildTool === "tsdown") {
 		writeFile(join(targetDir, "tsconfig.json"), json({
 			extends: "./.stars/tsconfig.json",
@@ -312,14 +382,16 @@ function writeTsconfig(targetDir, ctx) {
 }
 /**
 * Writes the `stars.config.*` file read by the `stars` CLI (`dev`, `build`, `info`, `codegen` scripts). Conventional
-* JavaScript and tsdown projects need no options; an explicit tsc selection is the only generated override.
+* JavaScript and tsdown projects need no options; an explicit tsc, Vite or Nitro selection is the only generated override.
 */
 function writeStarsConfig(targetDir, ctx) {
 	const isJs = ctx.language === "js";
+	let options = !isJs && (ctx.buildTool === "tsc6" || ctx.buildTool === "tsc7") ? "{ build: { tool: 'tsc' } }" : "{}";
+	if (!isJs && isViteBuild(ctx.buildTool)) options = `{ build: { tool: 'vite' }, experimental: { enableVite: true${isNitroBuild(ctx.buildTool) ? ", enableNitro: true, nitro: { preset: 'node-server' }" : ""} } }`;
 	const content = [
 		"import { defineConfig } from '@wolfstar/http-framework/config';",
 		"",
-		`export default defineConfig(${!isJs && ctx.buildTool !== "tsdown" ? "{ build: { tool: 'tsc' } }" : "{}"});`,
+		`export default defineConfig(${options});`,
 		""
 	].join("\n");
 	writeFile(join(targetDir, isJs ? "stars.config.js" : "stars.config.ts"), content);
@@ -421,6 +493,31 @@ function removeI18nDeclaration(outputDir) {
 	const typesDir = dirname(target);
 	if (existsSync(typesDir) && readdirSync(typesDir).length === 0) rmSync(typesDir, { recursive: true });
 }
+/**
+* What the Handlebars sources see: the persisted {@link TemplateContext} plus values derived from it. Deriving at render
+* time keeps the manifest small and lets manifests written before these fields existed still render.
+*/
+function toRenderContext(context) {
+	const typescript = context.language === "ts";
+	const commands = [{
+		className: "PingCommand",
+		file: "ping"
+	}];
+	if (context.subcommandsAdvanced) commands.push({
+		className: "SettingsCommand",
+		file: "settings"
+	});
+	else if (context.subcommands) commands.push({
+		className: "MathCommand",
+		file: "math"
+	});
+	return {
+		...context,
+		vite: typescript && isViteBuild(context.buildTool),
+		nitro: typescript && isNitroBuild(context.buildTool),
+		commands
+	};
+}
 function walkDir(dir) {
 	const entries = readdirSync(dir);
 	const files = [];
@@ -438,6 +535,10 @@ function walkDir(dir) {
 function resolveFeatureDirs(ctx) {
 	const dirs = [];
 	if (ctx.i18n) dirs.push("i18n");
+	if (ctx.gateway) dirs.push("gateway");
+	if (ctx.cache) dirs.push("cache");
+	if (ctx.redis) dirs.push("redis");
+	if (ctx.sharder) dirs.push("sharder");
 	if (ctx.subcommandsAdvanced) dirs.push(ctx.i18n ? "subcommands-advanced-i18n" : "subcommands-advanced");
 	else if (ctx.subcommands) dirs.push(ctx.i18n ? "subcommands-i18n" : "subcommands");
 	if (ctx.testing) {
@@ -464,7 +565,7 @@ function collectOutputPaths(root, language) {
 }
 function renderSource(absoluteSource, context) {
 	const rawContent = readFileSync(absoluteSource, "utf-8");
-	return absoluteSource.endsWith(".hbs") ? Handlebars.compile(rawContent)(context) : rawContent;
+	return absoluteSource.endsWith(".hbs") ? Handlebars.compile(rawContent)(toRenderContext(context)) : rawContent;
 }
 function escapeRegExp(text) {
 	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -483,8 +584,7 @@ function isSimpleInterpolationOnly(rawSource) {
 * existed — every run after this one writes a manifest, closing the gap for good.
 *
 * `null` for files with block helpers (`{{#if}}`, …), which can't be turned into a simple wildcard
-* pattern this way; none currently end up in "stale candidate" position, but this keeps the caller's
-* exact-render fallback available if that changes.
+* pattern this way; the caller compares those against {@link buildLegacyVariantMatchers} instead.
 */
 function buildStaleFileMatcher(absoluteSource) {
 	const rawContent = readFileSync(absoluteSource, "utf-8");
@@ -494,6 +594,33 @@ function buildStaleFileMatcher(absoluteSource) {
 	return new RegExp(`^${literalChunks.join("[\\s\\S]*?")}$`);
 }
 /**
+* Matchers for a source using block helpers (`main.*` is the one that matters), covering exactly the ways the generator
+* that predated the manifest could have written it: `tsdown`, with or without i18n, and none of the later features.
+* Anything older than that renders differently and is preserved rather than cleaned, which is the safe direction to
+* be wrong in. Like {@link buildStaleFileMatcher} it leaves the interpolated name and port as wildcards, by rendering
+* placeholders there.
+*/
+function buildLegacyVariantMatchers(absoluteSource, context) {
+	const placeholder = "\0";
+	const legacy = {
+		...context,
+		name: placeholder,
+		port: placeholder,
+		gateway: false,
+		cache: false,
+		redis: false,
+		sharder: false
+	};
+	return [false, true].map((i18n) => {
+		const rendered = renderSource(absoluteSource, {
+			...legacy,
+			buildTool: "tsdown",
+			i18n
+		});
+		return new RegExp(`^${rendered.split(placeholder).map(escapeRegExp).join("[\\s\\S]*?")}$`);
+	});
+}
+/**
 * Maps every output-relative path `root` could ever produce — for either language — to the source
 * file(s) that render it. Unlike {@link collectOutputPaths} this ignores `context.language`, so it
 * also surfaces paths left behind by a previous run under the *other* language (e.g. `src/main.ts`
@@ -548,7 +675,7 @@ function removeStaleGeneratedFiles(outputDir, context) {
 		const actual = readFileSync(target, "utf-8");
 		if (manifestContext ? sources.some((source) => renderSource(source, manifestContext) === actual) : sources.some((source) => {
 			const matcher = buildStaleFileMatcher(source);
-			return matcher ? matcher.test(actual) : renderSource(source, context) === actual;
+			return (matcher ? [matcher] : buildLegacyVariantMatchers(source, context)).some((candidate) => candidate.test(actual));
 		})) rmSync(target);
 		else preserved.push(path);
 	}
@@ -569,7 +696,7 @@ function processDir(root, outputDir, context) {
 		const rawContent = readFileSync(absoluteSource, "utf-8");
 		const isHandlebars = absoluteSource.endsWith(".hbs");
 		const outputPath = join(outputDir, outputRelative);
-		const content = isHandlebars ? Handlebars.compile(rawContent)(context) : rawContent;
+		const content = isHandlebars ? Handlebars.compile(rawContent)(toRenderContext(context)) : rawContent;
 		writeFile(outputPath, content);
 	}
 }
@@ -608,7 +735,7 @@ Options:
   --interactive, -i            Force interactive prompts even when an AI agent is detected
   --package-manager <pm>       npm | yarn | pnpm | bun (defaults to the detected one)
   --language <lang>            ts | js (default: ts)
-  --build <tool>               tsc6 | tsc7 | tsdown — TypeScript only (default: tsdown)
+  --build <tool>               tsc6 | tsc7 | tsdown | vite | vite-nitro — TypeScript only (default: tsdown)
   --lint <linter>              none | eslint | oxlint (default: oxlint)
   --format <formatter>         none | prettier | oxfmt (default: oxfmt)
   --port <number>              HTTP port (default: 3000)
@@ -616,6 +743,10 @@ Options:
   --subcommands / --no-subcommands  Toggle the subcommands example command (default: off)
   --subcommands-advanced / --no-subcommands-advanced  Toggle the subcommand groups example command (default: off; overrides --subcommands)
   --testing / --no-testing     Toggle the testing setup (vitest) (default: off)
+  --gateway / --no-gateway     Toggle @wolfstar/plugin-gateway, gateway events next to the HTTP interactions (default: off)
+  --cache / --no-cache         Toggle @wolfstar/plugin-cache, the gateway entity cache (default: off; enables --gateway)
+  --redis / --no-redis         Store the cache in Redis instead of memory (default: off; enables --cache)
+  --sharder / --no-sharder     Toggle @wolfstar/plugin-sharder, gateway shards across cluster workers (default: off; enables --gateway)
   --install / --no-install     Toggle dependency installation (default: on)
   --ignore                     Write into an existing, non-empty directory without clearing it
   --help, -h                   Print this message and exit
@@ -670,6 +801,10 @@ async function main() {
 	const cliSubcommands = argv["subcommands"];
 	const cliSubcommandsAdvanced = argv["subcommands-advanced"];
 	const cliTesting = argv["testing"];
+	const cliGateway = argv["gateway"];
+	const cliCache = argv["cache"];
+	const cliRedis = argv["redis"];
+	const cliSharder = argv["sharder"];
 	const cliInstall = argv["install"];
 	const { isAgent, agent } = await determineAgent();
 	const agentMode = isAgent && flagInteractive !== true;
@@ -816,6 +951,14 @@ async function main() {
 					{
 						value: "tsc7",
 						label: "TypeScript 7.0 rc (tsc)"
+					},
+					{
+						value: "vite",
+						label: "Vite (experimental)"
+					},
+					{
+						value: "vite-nitro",
+						label: "Vite + Nitro (experimental)"
 					}
 				],
 				initialValue: "tsdown"
@@ -885,11 +1028,20 @@ async function main() {
 	let wantsSubcommands;
 	let wantsSubcommandsAdvanced;
 	let wantsTesting;
+	let wantsGateway;
+	let wantsCache;
+	let wantsRedis;
+	let wantsSharder;
+	const nitro = language === "ts" && isNitroBuild(buildTool);
 	if (nonInteractive) {
 		wantsI18n = cliI18n ?? false;
 		wantsSubcommands = cliSubcommands ?? false;
 		wantsSubcommandsAdvanced = cliSubcommandsAdvanced ?? false;
 		wantsTesting = cliTesting ?? false;
+		wantsGateway = cliGateway ?? false;
+		wantsCache = cliCache ?? false;
+		wantsRedis = cliRedis ?? false;
+		wantsSharder = cliSharder ?? false;
 	} else {
 		const featuresResult = await multiselect({
 			message: "Which optional features would you like to add?",
@@ -909,7 +1061,19 @@ async function main() {
 				{
 					value: "testing",
 					label: "Testing setup (vitest)"
-				}
+				},
+				{
+					value: "gateway",
+					label: "Gateway events (@wolfstar/plugin-gateway)"
+				},
+				{
+					value: "cache",
+					label: "Gateway entity cache (@wolfstar/plugin-cache)"
+				},
+				...nitro ? [] : [{
+					value: "sharder",
+					label: "Gateway sharding across cluster workers (@wolfstar/plugin-sharder)"
+				}]
 			],
 			initialValues: [],
 			required: false
@@ -923,11 +1087,38 @@ async function main() {
 		wantsSubcommands = features.has("subcommands");
 		wantsSubcommandsAdvanced = features.has("subcommands-advanced");
 		wantsTesting = features.has("testing");
+		wantsGateway = features.has("gateway");
+		wantsCache = features.has("cache");
+		wantsSharder = features.has("sharder");
+		wantsRedis = cliRedis ?? false;
+		if (wantsCache && cliRedis === void 0) {
+			const redisResult = await confirm({
+				message: "Would you like to store the cache in Redis (ioredis) instead of memory?",
+				initialValue: false
+			});
+			if (isCancel(redisResult)) {
+				cancel("Operation cancelled.");
+				process.exit(0);
+			}
+			wantsRedis = Boolean(redisResult);
+		}
 	}
 	if (wantsSubcommands && wantsSubcommandsAdvanced) {
 		log.warn("Both --subcommands and --subcommands-advanced were selected; using the advanced example (with groups).");
 		wantsSubcommands = false;
 	}
+	if (wantsSharder && nitro) {
+		cancel(SHARDER_WITH_NITRO_ERROR);
+		process.exit(1);
+	}
+	const gatewayFeatures = resolveGatewayFeatures({
+		gateway: wantsGateway,
+		cache: wantsCache,
+		redis: wantsRedis,
+		sharder: wantsSharder
+	});
+	if (gatewayFeatures.implied.length > 0) log.warn(`Enabling ${gatewayFeatures.implied.map((feature) => `--${feature}`).join(" and ")}, which the selected features depend on.`);
+	({gateway: wantsGateway, cache: wantsCache, redis: wantsRedis, sharder: wantsSharder} = gatewayFeatures.features);
 	let wantsInstall;
 	if (nonInteractive) wantsInstall = cliInstall;
 	else {
@@ -948,6 +1139,10 @@ async function main() {
 		subcommands: wantsSubcommands,
 		subcommandsAdvanced: wantsSubcommandsAdvanced,
 		testing: wantsTesting,
+		gateway: wantsGateway,
+		cache: wantsCache,
+		redis: wantsRedis,
+		sharder: wantsSharder,
 		language,
 		buildTool,
 		linter,
@@ -962,7 +1157,12 @@ async function main() {
 		i18n: wantsI18n,
 		subcommands: wantsSubcommands,
 		subcommandsAdvanced: wantsSubcommandsAdvanced,
-		testing: wantsTesting
+		testing: wantsTesting,
+		gateway: wantsGateway,
+		cache: wantsCache,
+		redis: wantsRedis,
+		sharder: wantsSharder,
+		buildTool
 	});
 	writeProjectFiles(targetDir, {
 		name: projectName,
@@ -971,6 +1171,10 @@ async function main() {
 		subcommands: wantsSubcommands,
 		subcommandsAdvanced: wantsSubcommandsAdvanced,
 		testing: wantsTesting,
+		gateway: wantsGateway,
+		cache: wantsCache,
+		redis: wantsRedis,
+		sharder: wantsSharder,
 		packageManager,
 		language,
 		buildTool,
@@ -1019,6 +1223,7 @@ async function main() {
 	}
 	const extraNotes = [];
 	if (wantsI18n) extraNotes.push(`  After editing locale files, regenerate i18next types with: ${getRunScript(packageManager, "generate:i18n")}`);
+	if (wantsRedis) extraNotes.push("  Start a local Redis server with: docker compose up -d");
 	if (wantsTesting) extraNotes.push(`  Run the test suite with: ${getRunScript(packageManager, "test")}`);
 	outro(`Done! To get started:\n\n  cd ${projectName}\n${wantsInstall ? "" : `  ${getInstallScript(packageManager)}\n`}  ${getRunScript(packageManager, "dev")}${extraNotes.length ? `\n\n${extraNotes.join("\n")}` : ""}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wolfstar/create-http-framework",
-  "version": "2.5.2",
+  "version": "2.6.0-next-20260926200949",
   "description": "Create a new WolfStar HTTP Framework bot project",
   "keywords": [
     "cli",
@@ -46,11 +46,11 @@
     "@types/handlebars": "^4.1.0",
     "@types/mri": "^1.2.0",
     "@types/node": "22.15.21",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^5.0.0",
     "golar": "^0.1.10",
     "tsdown": "^0.23.0",
     "typescript": "~7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=20"

package/template/base/.env.hbs

@@ -1,6 +1,16 @@
 DISCORD_TOKEN=your_bot_token_here
 DISCORD_PUBLIC_KEY=your_public_key_here
 DISCORD_CLIENT_ID=your_client_id_here
+{{#if nitro}}
+PORT={{port}}
+{{else}}
 HTTP_ADDRESS=0.0.0.0
 HTTP_PORT={{port}}
+{{/if}}
 HTTP_POST_PATH=/
+{{#if redis}}
+REDIS_URL=redis://localhost:6379
+{{/if}}
+{{#if sharder}}
+SHARDER_CLUSTERS=2
+{{/if}}

package/template/base/.gitignore.hbs

@@ -1,5 +1,6 @@
 node_modules/
 dist/
+.output/
 .stars/
 .env
 *.js.map

package/template/base/README.md.hbs

@@ -10,13 +10,38 @@ A Discord bot built with [`@wolfstar/http-framework`](https://www.npmjs.com/pack
 {{#if i18n}}
 3. This project uses [`@wolfstar/plugin-i18next`](https://www.npmjs.com/package/@wolfstar/plugin-i18next). Locale resources live under `src/locales/`; after editing them, regenerate the typed i18next resources with `npm run generate:i18n`.
 {{/if}}
+{{#if gateway}}
+
+This project also connects to the Discord gateway with [`@wolfstar/plugin-gateway`](https://www.npmjs.com/package/@wolfstar/plugin-gateway): `src/main.*` creates a `GatewayClient` that answers HTTP interactions and emits gateway events. It needs a long-lived process and Node.js 24.17 or newer. Add the intents your listeners need to the client options, privileged ones must also be enabled in the Discord Developer Portal.
+{{#if cache}}
+{{#if redis}}
+
+Entities are cached in Redis with [`@wolfstar/plugin-cache`](https://www.npmjs.com/package/@wolfstar/plugin-cache): start a local server with `docker compose up -d` (it listens on `REDIS_URL` from `.env`), or point `REDIS_URL` at your own.
+{{else}}
+
+Entities are cached in memory with [`@wolfstar/plugin-cache`](https://www.npmjs.com/package/@wolfstar/plugin-cache), so nothing outlives the process. Swap `createInMemoryCache` for `createRedisCache` in `src/lib/cache.*` to persist them.
+{{/if}}
+{{/if}}
+{{#if sharder}}
+
+Gateway shards are spread across `SHARDER_CLUSTERS` cluster workers by [`@wolfstar/plugin-sharder`](https://www.npmjs.com/package/@wolfstar/plugin-sharder): `src/main.*` is the manager and `src/shard.*` runs in every worker.
+{{/if}}
+{{/if}}
+{{#if vite}}
+
+The project is bundled with [Vite](https://vite.dev) into a single file, so the commands are loaded explicitly in `src/main.*`: import every new command there and load it with `container.stores.loadPiece`.
+{{/if}}
+{{#if nitro}}
+
+[Nitro](https://nitro.build) serves the bot: `npm run build` writes a deployable `.output/` and `PORT` in `.env` sets the port. `package.json`'s `main` and `start` point at the `node-server` preset's output, `.output/server/index.mjs`, so `npm start` only works on that preset. Targeting another platform means changing `nitro.preset` in `stars.config.ts` and deploying the `.output/` that preset writes, not running it with `npm start`.{{#if gateway}} The gateway connection is held open by the process, so a preset that keeps a server alive is required — the edge presets do not qualify.{{/if}}
+{{/if}}
 
 ## Scripts
 
 The `dev` and `build` scripts are powered by the [`stars`](https://www.npmjs.com/package/@wolfstar/cli) CLI and read the `stars.config` file at the project root.
 
 - `npm run dev` — build, run and restart the bot on changes, with an interactive terminal UI (`npm run dev -- --no-tui` for plain logs).
-- `npm run build` — compile the project (TypeScript projects only).
+- `npm run build` — {{#if nitro}}build the deployable `.output/` directory{{else}}compile the project{{/if}} (TypeScript projects only).
 - `npm start` — run the bot.
 - `npx stars info` — print the resolved configuration.
 {{#if testing}}
@@ -33,4 +58,8 @@ The `dev` and `build` scripts are powered by the [`stars`](https://www.npmjs.com
 - `/settings profile get` / `/settings profile set` / `/settings notifications enable` / `/settings notifications disable` — subcommand groups example.
 {{/if}}
 
+{{#if nitro}}
+The HTTP server listens on `PORT` from `.env` — `{{port}}` by default.
+{{else}}
 The HTTP server listens on `HTTP_ADDRESS`:`HTTP_PORT` from `.env` — `{{port}}` by default.
+{{/if}}

package/template/base/src/lib/types/augments.ts.hbs

@@ -9,5 +9,13 @@ declare module '@wolfstar/env-utilities' {
 		HTTP_ADDRESS: string;
 		HTTP_PORT: IntegerString;
 		HTTP_POST_PATH: string;
+{{#if redis}}
+
+		REDIS_URL: string;
+{{/if}}
+{{#if sharder}}
+
+		SHARDER_CLUSTERS: IntegerString;
+{{/if}}
 	}
 }

package/template/base/src/main.js.hbs

@@ -1,3 +1,6 @@
+{{#if i18n}}
+import '@wolfstar/plugin-i18next/register';
+{{/if}}
 import { setup } from './lib/setup/all.js';
 import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
 import { Client, container } from '@wolfstar/http-framework';
@@ -6,7 +9,12 @@ import { morning } from 'gradient-string';
 
 await setup();
 
-const client = new Client();
+const client = new Client({{#if i18n}}{
+	i18n: {
+		defaultLanguageDirectory: new URL('locales', import.meta.url).pathname,
+		defaultName: 'en-US'
+	}
+}{{/if}});
 await client.load();
 
 const address = envParseString('HTTP_ADDRESS', '0.0.0.0');

package/template/base/src/main.ts.hbs

@@ -1,13 +1,59 @@
+{{#if nitro}}
+{{#if i18n}}
+import { existsSync } from 'node:fs';
+{{/if}}
+{{/if}}
+{{#if i18n}}
+import '@wolfstar/plugin-i18next/register';
+{{/if}}
 import { setup } from './lib/setup/all.js';
+{{#unless nitro}}
 import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
+{{/unless}}
 import { Client, container } from '@wolfstar/http-framework';
+{{#unless nitro}}
 import { createStarsBanner } from '@wolfstar/start-banner';
 import { morning } from 'gradient-string';
+{{/unless}}
+{{#if vite}}
+{{#each commands}}
+import { {{className}} } from './commands/{{file}}.js';
+{{/each}}
+{{/if}}
 
 await setup();
+{{#if nitro}}
+{{#if i18n}}
 
-const client = new Client();
+// Nitro bundles this file into `.output/server`, next to the `.output/locales` copy `stars build` makes; in development
+// it runs from `src`, where the locales sit beside it.
+const bundledLocales = new URL('../locales', import.meta.url);
+const localesDirectory = existsSync(bundledLocales) ? bundledLocales.pathname : new URL('locales', import.meta.url).pathname;
+{{/if}}
+{{/if}}
+
+const client = new Client({{#if i18n}}{
+	i18n: {
+		defaultLanguageDirectory: {{#if nitro}}localesDirectory{{else}}new URL('locales', import.meta.url).pathname{{/if}},
+		defaultName: 'en-US'
+	}
+}{{/if}});
+{{#if vite}}
+
+// The bundle is a single file, so there is no `commands` directory next to it to scan: load the pieces explicitly.
+{{#each commands}}
+await container.stores.loadPiece({ name: '{{file}}', piece: {{className}}, store: 'commands' });
+{{/each}}
+await client.load({ baseUserDirectory: null });
+{{else}}
 await client.load();
+{{/if}}
+{{#if nitro}}
+
+// No `listen()`: the server entry Nitro generates imports this default export and forwards every request to
+// `client.fetch(request)`, which verifies the signature and answers the interaction. Nitro serves on `PORT`.
+export default client;
+{{else}}
 
 const address = envParseString('HTTP_ADDRESS', '0.0.0.0');
 const port = envParseInteger('HTTP_PORT', {{port}});
@@ -28,3 +74,4 @@ console.log(
 );
 
 container.logger.info('Ready');
+{{/if}}

package/template/features/cache/src/lib/cache.js.hbs

@@ -0,0 +1,27 @@
+{{#if redis}}
+import { envParseString } from '@wolfstar/env-utilities';
+{{/if}}
+import { {{#if redis}}createRedisCache{{else}}createInMemoryCache{{/if}} } from '@wolfstar/plugin-cache';
+{{#if redis}}
+import { Redis } from 'ioredis';
+{{/if}}
+
+{{#if redis}}
+/** Caches the gateway's entities in the Redis server at `REDIS_URL`, see `compose.yaml` to start one locally. */
+export function createCache() {
+	return createRedisCache({
+		redis: new Redis(envParseString('REDIS_URL')),
+		// Entries live at `<prefix>:<entity>:<key>`, so several bots can share one database.
+		prefix: '{{name}}'
+	});
+}
+{{else}}
+/**
+ * Keeps the gateway's entities in memory: nothing outlives the process. Swapping the store never changes the call sites,
+ * the gateway client and its managers only see the `Cache` interface (`createRedisCache` is the persistent one).
+ */
+export function createCache() {
+	// Keep the latest 1,000 messages, every other entity is unbounded.
+	return createInMemoryCache({ maxSize: { messages: 1_000 } });
+}
+{{/if}}

package/template/features/cache/src/lib/cache.ts.hbs

@@ -0,0 +1,27 @@
+{{#if redis}}
+import { envParseString } from '@wolfstar/env-utilities';
+{{/if}}
+import { {{#if redis}}createRedisCache{{else}}createInMemoryCache{{/if}}, type Cache } from '@wolfstar/plugin-cache';
+{{#if redis}}
+import { Redis } from 'ioredis';
+{{/if}}
+
+{{#if redis}}
+/** Caches the gateway's entities in the Redis server at `REDIS_URL`, see `compose.yaml` to start one locally. */
+export function createCache(): Cache {
+	return createRedisCache({
+		redis: new Redis(envParseString('REDIS_URL')),
+		// Entries live at `<prefix>:<entity>:<key>`, so several bots can share one database.
+		prefix: '{{name}}'
+	});
+}
+{{else}}
+/**
+ * Keeps the gateway's entities in memory: nothing outlives the process. Swapping the store never changes the call sites,
+ * the gateway client and its managers only see the `Cache` interface (`createRedisCache` is the persistent one).
+ */
+export function createCache(): Cache {
+	// Keep the latest 1,000 messages, every other entity is unbounded.
+	return createInMemoryCache({ maxSize: { messages: 1_000 } });
+}
+{{/if}}

package/template/features/gateway/src/main.js.hbs

@@ -0,0 +1,54 @@
+{{#if i18n}}
+import '@wolfstar/plugin-i18next/register';
+{{/if}}
+import { setup } from './lib/setup/all.js';
+{{#if cache}}
+import { createCache } from './lib/cache.js';
+{{/if}}
+import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
+import { container } from '@wolfstar/http-framework';
+import { GatewayClient } from '@wolfstar/plugin-gateway';
+import { createStarsBanner } from '@wolfstar/start-banner';
+import { GatewayIntentBits } from 'discord-api-types/v10';
+import { morning } from 'gradient-string';
+
+await setup();
+
+const client = new GatewayClient({
+{{#if i18n}}
+	i18n: {
+		defaultLanguageDirectory: new URL('locales', import.meta.url).pathname,
+		defaultName: 'en-US'
+	},
+{{/if}}
+{{#if cache}}
+	// Every dispatch is written into the cache before its event is emitted.
+	cache: createCache(),
+{{/if}}
+	// Add the intents your listeners need, privileged ones (`MessageContent`, `GuildMembers`, `GuildPresences`) must also
+	// be enabled under Bot → Privileged Gateway Intents in the Developer Portal.
+	intents: GatewayIntentBits.Guilds
+});
+
+client.on('error', (error) => container.logger.error(error));
+
+const address = envParseString('HTTP_ADDRESS', '0.0.0.0');
+const port = envParseInteger('HTTP_PORT', {{port}});
+// Loads the pieces, starts the HTTP interactions endpoint, then connects every gateway shard.
+await client.start({ listen: { address, port } });
+
+console.log(
+	morning.multiline(
+		createStarsBanner({
+			name: ['{{name}}'],
+			extra: [
+				'',
+				`Loaded: ${container.stores.get('commands').size} commands`,
+				`      : ${container.stores.get('interaction-handlers').size} interaction handlers`,
+				`Listening: ${address}:${port}`
+			]
+		})
+	)
+);
+
+container.logger.info('Ready');

package/template/features/gateway/src/main.ts.hbs

@@ -0,0 +1,96 @@
+{{#if nitro}}
+{{#if i18n}}
+import { existsSync } from 'node:fs';
+{{/if}}
+{{/if}}
+{{#if i18n}}
+import '@wolfstar/plugin-i18next/register';
+{{/if}}
+import { setup } from './lib/setup/all.js';
+{{#if cache}}
+import { createCache } from './lib/cache.js';
+{{/if}}
+{{#unless nitro}}
+import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
+{{/unless}}
+import { container } from '@wolfstar/http-framework';
+import { GatewayClient } from '@wolfstar/plugin-gateway';
+{{#unless nitro}}
+import { createStarsBanner } from '@wolfstar/start-banner';
+{{/unless}}
+import { GatewayIntentBits } from 'discord-api-types/v10';
+{{#unless nitro}}
+import { morning } from 'gradient-string';
+{{/unless}}
+{{#if vite}}
+{{#each commands}}
+import { {{className}} } from './commands/{{file}}.js';
+{{/each}}
+{{/if}}
+
+await setup();
+{{#if nitro}}
+{{#if i18n}}
+
+// Nitro bundles this file into `.output/server`, next to the `.output/locales` copy `stars build` makes; in development
+// it runs from `src`, where the locales sit beside it.
+const bundledLocales = new URL('../locales', import.meta.url);
+const localesDirectory = existsSync(bundledLocales) ? bundledLocales.pathname : new URL('locales', import.meta.url).pathname;
+{{/if}}
+{{/if}}
+
+const client = new GatewayClient({
+{{#if i18n}}
+	i18n: {
+		defaultLanguageDirectory: {{#if nitro}}localesDirectory{{else}}new URL('locales', import.meta.url).pathname{{/if}},
+		defaultName: 'en-US'
+	},
+{{/if}}
+{{#if cache}}
+	// Every dispatch is written into the cache before its event is emitted.
+	cache: createCache(),
+{{/if}}
+	// Add the intents your listeners need, privileged ones (`MessageContent`, `GuildMembers`, `GuildPresences`) must also
+	// be enabled under Bot → Privileged Gateway Intents in the Developer Portal.
+	intents: GatewayIntentBits.Guilds
+});
+
+client.on('error', (error) => container.logger.error(error));
+{{#if vite}}
+
+// The bundle is a single file, so there is no `commands` directory next to it to scan: load the pieces explicitly.
+{{#each commands}}
+await container.stores.loadPiece({ name: '{{file}}', piece: {{className}}, store: 'commands' });
+{{/each}}
+{{/if}}
+{{#if nitro}}
+
+await client.load({ baseUserDirectory: null });
+// Nitro answers the HTTP interactions (see the default export), the gateway connection stays with this process: run it
+// on a preset that keeps a server alive, such as `node-server`.
+await client.connect();
+
+export default client;
+{{else}}
+
+const address = envParseString('HTTP_ADDRESS', '0.0.0.0');
+const port = envParseInteger('HTTP_PORT', {{port}});
+// Loads the pieces, starts the HTTP interactions endpoint, then connects every gateway shard.
+await client.start({ listen: { address, port }{{#if vite}}, load: { baseUserDirectory: null }{{/if}} });
+
+console.log(
+	morning.multiline(
+		createStarsBanner({
+			name: ['{{name}}'],
+			extra: [
+				'',
+				`Loaded: ${container.stores.get('commands').size} commands`,
+				`      : ${container.stores.get('interaction-handlers').size} interaction handlers`,
+				`Listening: ${address}:${port}`
+			]
+		})
+	)
+);
+
+container.logger.info('Ready');
+{{/if}}

package/template/features/redis/compose.yaml

@@ -0,0 +1,5 @@
+services:
+    redis:
+        image: redis:8-alpine
+        ports:
+            - '6379:6379'

package/template/features/sharder/src/main.js.hbs

@@ -0,0 +1,25 @@
+import { setup } from './lib/setup/all.js';
+import { envParseInteger } from '@wolfstar/env-utilities';
+import { ShardClient, ShardManager } from '@wolfstar/plugin-sharder';
+
+await setup();
+
+// The manager and the shards share this script: `ShardClient.context` is only set in the processes the manager
+// spawned.
+if (ShardClient.context === null) {
+	// Discord's recommended gateway shard count (fetched with `DISCORD_TOKEN`), split across `SHARDER_CLUSTERS`
+	// `node:cluster` workers. Cluster workers share the HTTP port, so Node balances the interactions across them.
+	const manager = new ShardManager({
+		strategy: 'cluster',
+		clusters: envParseInteger('SHARDER_CLUSTERS', 2),
+		// Identifies are paced by the manager across every worker, see `identifyThrottler` in `src/shard.ts`.
+		spawn: { delay: 0 }
+	});
+
+	manager.on('shardReady', (channel) => console.log(`Worker ${channel.id} is ready (gateway shards ${channel.shards.join(', ')})`));
+	manager.on('shardGiveUp', (channel) => console.error(`Worker ${channel.id} keeps crashing, giving up on it`));
+
+	await manager.spawn();
+} else {
+	await import('./shard.js');
+}

package/template/features/sharder/src/main.ts.hbs

@@ -0,0 +1,25 @@
+import { setup } from './lib/setup/all.js';
+import { envParseInteger } from '@wolfstar/env-utilities';
+import { ShardClient, ShardManager } from '@wolfstar/plugin-sharder';
+
+await setup();
+
+// The manager and the shards share this script: `ShardClient.context` is only set in the processes the manager
+// spawned.
+if (ShardClient.context === null) {
+	// Discord's recommended gateway shard count (fetched with `DISCORD_TOKEN`), split across `SHARDER_CLUSTERS`
+	// `node:cluster` workers. Cluster workers share the HTTP port, so Node balances the interactions across them.
+	const manager = new ShardManager({
+		strategy: 'cluster',
+		clusters: envParseInteger('SHARDER_CLUSTERS', 2),
+		// Identifies are paced by the manager across every worker, see `identifyThrottler` in `src/shard.ts`.
+		spawn: { delay: 0 }
+	});
+
+	manager.on('shardReady', (channel) => console.log(`Worker ${channel.id} is ready (gateway shards ${channel.shards.join(', ')})`));
+	manager.on('shardGiveUp', (channel) => console.error(`Worker ${channel.id} keeps crashing, giving up on it`));
+
+	await manager.spawn();
+} else {
+	await import('./shard.js');
+}

package/template/features/sharder/src/shard.js.hbs

@@ -0,0 +1,49 @@
+{{#if i18n}}
+import '@wolfstar/plugin-i18next/register';
+{{/if}}
+{{#if cache}}
+import { createCache } from './lib/cache.js';
+{{/if}}
+import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
+import { container } from '@wolfstar/http-framework';
+import { GatewayClient } from '@wolfstar/plugin-gateway';
+import { ShardClient } from '@wolfstar/plugin-sharder';
+import { GatewayIntentBits } from 'discord-api-types/v10';
+
+const shard = new ShardClient();
+
+const client = new GatewayClient({
+{{#if i18n}}
+	i18n: {
+		defaultLanguageDirectory: new URL('locales', import.meta.url).pathname,
+		defaultName: 'en-US'
+	},
+{{/if}}
+{{#if cache}}
+	cache: createCache(),
+{{/if}}
+	// The gateway shards the manager assigned to this worker, and the total across every worker.
+	...shard.gatewayOptions,
+	// Identifies go through the manager, which grants one per `max_concurrency` bucket across every worker.
+	gateway: { buildIdentifyThrottler: () => shard.identifyThrottler },
+	intents: GatewayIntentBits.Guilds
+});
+
+// Reuse the manager's `GET /gateway/bot` rather than requesting it again from every worker.
+client.gateway.fetchGatewayInformation = () => shard.fetchGatewayInformation();
+client.on('error', (error) => container.logger.error(error));
+
+shard.setCloseHandler(() => client.destroy());
+
+// The worker is ready once every gateway shard it runs is. The manager only starts the next worker once this one
+// reports in, so a worker it assigned no gateway shard to (a layout can hand every shard to one channel of the
+// cluster) reports in right away instead of waiting for a `shardReady` that never fires.
+let pending = shard.shards.length;
+if (pending === 0) void shard.ready();
+client.on('shardReady', () => {
+	if (--pending === 0) void shard.ready();
+});
+
+const address = envParseString('HTTP_ADDRESS', '0.0.0.0');
+const port = envParseInteger('HTTP_PORT', {{port}});
+await client.start({ listen: { address, port } });

package/template/features/sharder/src/shard.ts.hbs

@@ -0,0 +1,61 @@
+{{#if i18n}}
+import '@wolfstar/plugin-i18next/register';
+{{/if}}
+{{#if cache}}
+import { createCache } from './lib/cache.js';
+{{/if}}
+import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
+import { container } from '@wolfstar/http-framework';
+import { GatewayClient } from '@wolfstar/plugin-gateway';
+import { ShardClient } from '@wolfstar/plugin-sharder';
+import { GatewayIntentBits } from 'discord-api-types/v10';
+{{#if vite}}
+{{#each commands}}
+import { {{className}} } from './commands/{{file}}.js';
+{{/each}}
+{{/if}}
+
+const shard = new ShardClient();
+
+const client = new GatewayClient({
+{{#if i18n}}
+	i18n: {
+		defaultLanguageDirectory: new URL('locales', import.meta.url).pathname,
+		defaultName: 'en-US'
+	},
+{{/if}}
+{{#if cache}}
+	cache: createCache(),
+{{/if}}
+	// The gateway shards the manager assigned to this worker, and the total across every worker.
+	...shard.gatewayOptions,
+	// Identifies go through the manager, which grants one per `max_concurrency` bucket across every worker.
+	gateway: { buildIdentifyThrottler: () => shard.identifyThrottler },
+	intents: GatewayIntentBits.Guilds
+});
+
+// Reuse the manager's `GET /gateway/bot` rather than requesting it again from every worker.
+client.gateway.fetchGatewayInformation = () => shard.fetchGatewayInformation();
+client.on('error', (error) => container.logger.error(error));
+
+shard.setCloseHandler(() => client.destroy());
+
+// The worker is ready once every gateway shard it runs is. The manager only starts the next worker once this one
+// reports in, so a worker it assigned no gateway shard to (a layout can hand every shard to one channel of the
+// cluster) reports in right away instead of waiting for a `shardReady` that never fires.
+let pending = shard.shards.length;
+if (pending === 0) void shard.ready();
+client.on('shardReady', () => {
+	if (--pending === 0) void shard.ready();
+});
+{{#if vite}}
+
+// The bundle is a single file, so there is no `commands` directory next to it to scan: load the pieces explicitly.
+{{#each commands}}
+await container.stores.loadPiece({ name: '{{file}}', piece: {{className}}, store: 'commands' });
+{{/each}}
+{{/if}}
+
+const address = envParseString('HTTP_ADDRESS', '0.0.0.0');
+const port = envParseInteger('HTTP_PORT', {{port}});
+await client.start({ listen: { address, port }{{#if vite}}, load: { baseUserDirectory: null }{{/if}} });

package/template/features/i18n/src/main.js.hbs

@@ -1,36 +0,0 @@
-import '@wolfstar/plugin-i18next/register';
-import { setup } from './lib/setup/all.js';
-import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
-import { Client, container } from '@wolfstar/http-framework';
-import { createStarsBanner } from '@wolfstar/start-banner';
-import { morning } from 'gradient-string';
-
-await setup();
-
-const client = new Client({
-	i18n: {
-		defaultLanguageDirectory: new URL('locales', import.meta.url).pathname,
-		defaultName: 'en-US'
-	}
-});
-await client.load();
-
-const address = envParseString('HTTP_ADDRESS', '0.0.0.0');
-const port = envParseInteger('HTTP_PORT', {{port}});
-await client.listen({ address, port });
-
-console.log(
-	morning.multiline(
-		createStarsBanner({
-			name: ['{{name}}'],
-			extra: [
-				'',
-				`Loaded: ${container.stores.get('commands').size} commands`,
-				`      : ${container.stores.get('interaction-handlers').size} interaction handlers`,
-				`Listening: ${address}:${port}`
-			]
-		})
-	)
-);
-
-container.logger.info('Ready');

package/template/features/i18n/src/main.ts.hbs

@@ -1,36 +0,0 @@
-import '@wolfstar/plugin-i18next/register';
-import { setup } from './lib/setup/all.js';
-import { envParseInteger, envParseString } from '@wolfstar/env-utilities';
-import { Client, container } from '@wolfstar/http-framework';
-import { createStarsBanner } from '@wolfstar/start-banner';
-import { morning } from 'gradient-string';
-
-await setup();
-
-const client = new Client({
-	i18n: {
-		defaultLanguageDirectory: new URL('locales', import.meta.url).pathname,
-		defaultName: 'en-US'
-	}
-});
-await client.load();
-
-const address = envParseString('HTTP_ADDRESS', '0.0.0.0');
-const port = envParseInteger('HTTP_PORT', {{port}});
-await client.listen({ address, port });
-
-console.log(
-	morning.multiline(
-		createStarsBanner({
-			name: ['{{name}}'],
-			extra: [
-				'',
-				`Loaded: ${container.stores.get('commands').size} commands`,
-				`      : ${container.stores.get('interaction-handlers').size} interaction handlers`,
-				`Listening: ${address}:${port}`
-			]
-		})
-	)
-);
-
-container.logger.info('Ready');