@wolfstar/create-http-framework

Scaffold a new @wolfstar/http-framework bot in seconds.

Description

A CLI scaffolding tool for creating new WolfStar HTTP Framework bot projects.

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

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, 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
• Auto-install — install dependencies immediately after scaffolding

Options

| Flag | Alias | Description | | ------------------------------------ | ----- | --------------------------------------------------------------------------- | | --overwrite | | Overwrite the target directory if it already exists | | --no-interactive | | Skip all prompts and use defaults / flags | | --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, 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) | | --tunnel / --no-tunnel | | Open a cloudflared quick tunnel in stars dev (dev.tunnel in the config) | | --env <loader> | | varlock: scaffold a .env.schema and derive Env from it | | --install / --no-install | | Enable or disable dependency installation | | --help | -h | Print usage and exit |

Non-interactive / AI agent mode

When the CLI detects an AI agent is running it (via @vercel/detect-agent), it automatically enters non-interactive mode, equivalent to passing --no-interactive. A project name argument is required in this 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                     # The project's commands, layout and rules, for AI coding agents
├── llms.txt                      # The upstream documentation by topic, for AI coding agents
├── stars.config.ts               # The `stars` CLI configuration (build, dev, tunnel)
├── .env                          # Environment variables (DISCORD_TOKEN, DISCORD_PUBLIC_KEY)
├── .gitignore
├── package.json
└── tsconfig.json

• 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 and only describe the features the project was created with. When one already exists and is not this generator's own unedited output (you wrote it, or edited it), a rerun leaves it as it is and says so.
• With a linter, the generated configuration (.oxlintrc.json or eslint.config.mjs) enables the rules of @wolfstar/eslint-plugin-http-framework: decorator order, raw Discord fetches, dynamic translation keys and the other mistakes TypeScript cannot catch.
• --tunnel (or the Dev tunnel feature in the prompt) writes dev: { tunnel: true } to stars.config, so stars dev opens a cloudflared quick tunnel and Discord reaches the bot on your machine. Without it, press t in stars dev to open one on demand.

varlock

--env varlock (or the Environment schema feature in the prompt) sets the project up with varlock, which validates the environment and types it:

• .env.schema declares DISCORD_TOKEN, DISCORD_PUBLIC_KEY, DISCORD_CLIENT_ID, the HTTP port and whatever the other features need (REDIS_URL, SHARDER_CLUSTERS). The values stay in .env.
• varlock is added as a dependency, and @wolfstar/env-utilities loads the schema by itself (it picks varlock when a .env.schema and varlock are there).
• 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 for that file so the project type-checks right away; @generateTsTypes 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.
• Running it against a directory that already has a varlock .env.schema (--ignore) needs no flag: the schema is kept as it is, varlock stays a dependency, and stars.config.ts sets env.loader. An existing .env.schema the generator did not write is never replaced, with or without --env varlock; with the flag it is kept and reported, and Env stays hand-written because that schema may not generate types. A varlock.loadPath in package.json is kept. Rerunning without the flag over a project this generator scaffolded with varlock keeps it on; delete .env.schema to turn it off.

Vite and Nitro

--build vite bundles the bot with Vite into a single dist/main.js, and --build vite-nitro hands it to Nitro, 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/:

pnpm generate:i18n

The CLI runs this script automatically once at the end of scaffolding; re-run it manually whenever you add or edit locale keys so the generated types stay in sync.

Requirements

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