Getting Started - Stars Components

Overview

Stars Components is a set of focused TypeScript packages powering the Star Network. The core of it is @wolfstar/http-framework: an HTTP-first framework for Discord applications that answers interactions over a webhook endpoint instead of holding a gateway connection open. Around it sit optional packages for internationalization, environment parsing, logging, metrics, platform helpers, and interaction testing. Adopt one of them on its own, or combine them into a complete bot stack — see Features for the full picture and Why Stars Components for the reasoning behind it.

Prerequisites

Node.js 20 or newer
A Discord application with its token and public key
A public HTTPS endpoint that Discord can use as the application’s interactions endpoint

Adding Stars Components to Your Project

The fastest way to start is the @wolfstar/create-http-framework CLI. It creates the entry point, an example command, environment files, TypeScript or JavaScript configuration, and your preferred quality tools.

pnpm create @wolfstar/http-framework my-discord-bot

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

yarn create @wolfstar/http-framework my-discord-bot

bun create @wolfstar/http-framework my-discord-bot

The interactive wizard lets you select:

TypeScript or JavaScript
tsdown, TypeScript 6, or the TypeScript 7 release candidate for TypeScript builds
Oxlint, ESLint, or no linter
Oxfmt, Prettier, or no formatter
Optional i18n support
HTTP port and package manager

For automation, provide every choice without prompts:

pnpm create @wolfstar/http-framework my-discord-bot \
  --no-interactive \
  --language ts \
  --build tsdown \
  --lint oxlint \
  --format oxfmt \
  --port 3000 \
  --no-i18n

Configuring Credentials

Open the generated .env file and provide the credentials from the Discord developer portal:

DISCORD_TOKEN=your_application_token
DISCORD_PUBLIC_KEY=your_application_public_key

Never commit this file or expose either value in logs.

Writing Your First Command

The generated entry point creates a client, loads commands from src/commands, and starts the HTTP server:

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

const client = new Client();

await client.load();
await client.listen({ port: 3000 });

Commands are regular classes discovered by the store. Head to Build a Command for decorators, options, and subcommands, then to Testing Interactions to exercise them without a network server.

Configuring the Client

client.load() accepts no arguments above: it reads your package.json’s main field (dist/index.js in the generated project) and looks for a commands directory next to it, so there’s no manual path resolution to write — as long as you run the app from the project root (as pnpm start/node . does) and main points at the file you actually run. discordToken and discordPublicKey are picked up from the DISCORD_TOKEN and DISCORD_PUBLIC_KEY environment variables the same way, so you don’t need to pass them to new Client() either. This is the same pattern used in production bots such as wolfstar-project/staryl and wolfstar-project/ring, whose package.json files set main to their built entry point the same way:

const client = new Client({
	api: {
		listenOptions: {
			host: envParseString('API_ADDRESS'),
			port: envParseInteger('API_PORT')
		}
	}
});
await client.load();

If you can’t rely on main — no package.json (e.g. tests), a different working directory, or commands that don’t live in a commands directory next to the entry point — pass baseUserDirectory explicitly. It’s the root directory — client.load() appends the store name (commands, interaction-handlers, …) to it for you, so don’t include commands in the path yourself. For example, if your build puts everything under a bot/ subdirectory next to the entry file (bot/commands, bot/interaction-handlers, …):

import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

await client.load({
	baseUserDirectory: join(dirname(fileURLToPath(import.meta.url)), 'bot')
});

Environment variables get their own guide: Environment Variables.

Examples

Example	Source
Runnable samples	`stars-components/examples`
Production bot — Staryl	`wolfstar-project/staryl`
Production bot — Ring	`wolfstar-project/ring`

Next Steps

Follow Build a Command to understand decorators and interactions.
Configure your public URL as the Discord application’s interactions endpoint.
Add interaction tests before expanding the command set.
Browse the @wolfstar/http-framework package guide and API reference.

​Overview

​Adding Stars Components to Your Project

​Configuring Credentials

​Writing Your First Command

​Configuring the Client

​Examples

​Next Steps

​Community

Overview

Adding Stars Components to Your Project

Configuring Credentials

Writing Your First Command

Configuring the Client

Examples

Next Steps

Community