@wolfstar/create-http-framework

npm install @wolfstar/create-http-framework

pnpm add @wolfstar/create-http-framework

yarn add @wolfstar/create-http-framework

bun add @wolfstar/create-http-framework

​

Description

​

Usage

npm create @wolfstar/http-framework@latest my-discord-bot
# or
pnpm create @wolfstar/http-framework my-discord-bot
# or
yarn create @wolfstar/http-framework my-discord-bot
# or
bun create @wolfstar/http-framework my-discord-bot

• Project name — an npm-compatible name for your bot
• Package manager — npm, yarn, pnpm, or bun
• Language — TypeScript or JavaScript
• 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
  • Subcommands — add an example command that uses subcommands
  • Testing — set up Vitest with @wolfstar/http-framework-test-utils
  • Gateway — receive gateway events next to the HTTP interactions with @wolfstar/plugin-gateway
  • Cache — cache gateway entities with @wolfstar/plugin-cache, in memory or in Redis (asked as a follow-up)
  • Sharder — spread gateway shards across cluster workers with @wolfstar/plugin-sharder
  • Dev tunnel — open a cloudflared quick tunnel in stars dev so Discord reaches the bot on your machine (see Dev tunnel)
  • Environment schema — describe the environment in a validated, typed varlock .env.schema (see varlock)
• Auto-install — install dependencies immediately after scaffolding

​

Options

​

Non-interactive / AI agent mode

create-http-framework my-discord-bot --no-interactive

​

Generated project structure

my-discord-bot/
├── src/
│   ├── commands/
│   │   ├── ping.ts               # Example ping command
│   │   └── math.ts               # Example command with subcommands (--subcommands)
│   ├── lib/
│   │   ├── setup/
│   │   │   ├── all.ts            # Aggregates setup imports
│   │   │   └── logger.ts         # Logger configuration
│   │   ├── cache.ts              # Gateway entity cache (--cache)
│   │   └── types/
│   │       └── augments.ts       # Module augmentations (TypeScript only)
│   ├── locales/
│   │   └── en-US/
│   │       └── commands/
│   │           └── 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
├── AGENTS.md                     # Commands, layout, and rules for AI coding agents
├── llms.txt                      # Upstream documentation by topic, for AI coding agents
├── stars.config.ts               # `stars` CLI configuration (build, env, dev tunnel)
├── .env                          # Environment variables (DISCORD_TOKEN, DISCORD_PUBLIC_KEY)
├── .gitignore
├── package.json
└── tsconfig.json             # Root tsconfig (TypeScript only, see TypeScript configuration)

• 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 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.
• AGENTS.md and llms.txt are always generated. They only describe the features the project was created with. See AI agent files.
• With a linter, the generated .oxlintrc.json or eslint.config.mjs enables the rules of @wolfstar/eslint-plugin-http-framework. See Framework lint rules.
• In TypeScript projects built with tsdown or Vite, src/lib/setup/all.ts doesn’t load the environment itself. stars loads .env (the env option in stars.config.ts) before any module of the bot runs. Projects built with tsc, Vite + Nitro, or JavaScript still call setup() from @wolfstar/env-utilities.

​

TypeScript configuration

{
	"files": [],
	"references": [{ "path": "./.stars/tsconfig.app.json" }, { "path": "./.stars/tsconfig.node.json" }]
}

npm run typecheck

​

AI agent files

• AGENTS.md lists the project’s commands, its layout, and the framework rules that are easy to get wrong.
• llms.txt links the upstream documentation, grouped by topic.

​

Framework lint rules

import wolfstar, { recommendedRules } from '@wolfstar/eslint-plugin-http-framework';
import tseslint from 'typescript-eslint';

export default tseslint.config({ ignores: ['dist/**'] }, ...tseslint.configs.recommended, { plugins: { wolfstar }, rules: recommendedRules });

{
	"jsPlugins": ["@wolfstar/eslint-plugin-http-framework"],
	"rules": {
		"wolfstar/apply-options-decorator-order": "error",
		"wolfstar/require-subcommand-parent": "error",
		"wolfstar/no-raw-discord-fetch": "error",
		"wolfstar/no-dynamic-translation-key": "error",
		"wolfstar/prefer-apply-localized-builder": "error",
		"wolfstar/no-hoisted-plugin-register-import": "error",
		"wolfstar/no-deprecated-i18n-package": "error"
	}
}

​

Dev tunnel

npm create @wolfstar/http-framework@latest my-discord-bot -- --tunnel

import { defineConfig } from '@wolfstar/http-framework/config';

export default defineConfig({ dev: { tunnel: true } });

​

varlock

npm create @wolfstar/http-framework@latest my-discord-bot -- --env varlock

• .env.schema declares DISCORD_TOKEN, DISCORD_PUBLIC_KEY, DISCORD_CLIENT_ID, the HTTP port, HTTP_POST_PATH, and what the other features need (REDIS_URL, SHARDER_CLUSTERS). The values stay in .env.
• varlock is added as a dependency. @wolfstar/env-utilities loads the schema by itself, because it picks varlock when it finds a .env.schema and an installed varlock.
• src/lib/types/augments.ts derives Env from src/@types/env.d.ts with EnvFromVarlock from @wolfstar/env-utilities/varlock, instead of declaring each variable by hand. The scaffold ships a stand-in src/@types/env.d.ts so the project type-checks right away. The schema’s @generateTsTypes directive makes varlock replace it, with the same shape, whenever it loads the schema (npm run dev, or npx varlock load).
• For tsdown and vite projects, stars.config.ts also gets env: { loader: 'varlock' }, so stars dev and stars doctor read the variables the way the bot does. tsc, JavaScript, and Nitro projects load the environment themselves, so they get the schema and the dependency but no env entry.

import type { EnvFromVarlock } from '@wolfstar/env-utilities/varlock';
import type { CoercedEnvSchema } from '../../@types/env.js';

declare module '@wolfstar/env-utilities' {
	interface Env extends EnvFromVarlock<CoercedEnvSchema> {}
}

• With a .env.schema (in src/, the project root, or at varlock.loadPath), the schema is kept as it is, varlock stays a dependency, and stars.config.ts sets env.loader.
• With only a varlock dependency, varlock stays a dependency.
• A varlock.loadPath in package.json is kept.

​

Vite and Nitro

npm create @wolfstar/http-framework@latest my-discord-bot -- --language ts --build vite-nitro

• 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(). The port comes from PORT in .env instead of HTTP_PORT.
• The main field and start script point to the node-server preset’s output, .output/server/index.mjs. If you change nitro.preset to target another platform, deploy that platform’s .output/ instead of running npm start. With --gateway, only a preset that keeps a server alive can hold the gateway connection open.
• Nitro can’t be combined with --sharder. The sharder’s manager process has no client for Nitro to forward requests to, so the CLI exits with an error.

​

Gateway, cache, and sharder

npm create @wolfstar/http-framework@latest my-discord-bot -- --redis --sharder

• --gateway makes src/main.* create a GatewayClient. The bot still answers HTTP interactions.
• --cache adds src/lib/cache.*, an in-memory cache by default.
• --redis (or the follow-up prompt) swaps the in-memory cache for ioredis. It adds a compose.yaml that starts a local Redis server, and adds REDIS_URL=redis://localhost:6379 to .env.
• --sharder turns src/main.* into the shard manager and adds src/shard.*, which runs in every cluster worker. Set the number of workers with SHARDER_CLUSTERS in .env (default: 2).
• Each flag turns on the flags it depends on: --redis turns on --cache, and --cache and --sharder both turn on --gateway.
• When the gateway is enabled, the generated package.json sets engines.node to >=24.17.0.

docker compose up -d

​

i18n type generation

pnpm generate:i18n

​

Requirements

• Node.js >=20 (>=24.17.0 for projects using the gateway)