Examples

Spraxium ships with a complete set of real, runnable applications in github.com/spraxium/spraxium/tree/main/apps. Currently, those examples are aligned with the latest APIs, including async component builders, modern interaction patterns, and production-oriented architecture.

This page helps you choose the right starting point for your goal, then gives a practical workflow to run, inspect, and modify examples safely.

App map

Spraxium currently includes 13 official example apps:

1. components-bot
2. context-menu-bot
3. dynamic-bot
4. guard-bot
5. http-bot
6. i18n-bot
7. i18n-components-bot
8. modal-bot
9. sandbox
10. schedule-bot
11. signal-bot
12. slash-bot
13. webhook-bot

upgrade-test-bot was intentionally removed and is not part of the current app set.

What each app teaches

1) slash-bot

Use this first if you want the cleanest entry point.

You will learn:

• Basic slash command registration and execution.
• Handler/module organization with minimal ceremony.
• Core command flow before adding advanced infrastructure.

2) context-menu-bot

Use this if your bot workflow starts from message/user context actions instead of slash commands.

You will learn:

• User and message context menu commands.
• Deferral and response patterns that avoid timeout failures.
• Guard and service composition around interaction handlers.

3) guard-bot

Use this to understand access control and policy layers.

You will learn:

• Guard composition for roles, permissions, and conditions.
• Reusable security checks at module/handler level.
• Patterns for keeping authorization logic out of business code.

4) components-bot

Use this when you need buttons/select menus with richer flows.

You will learn:

• Component V2 usage with await-driven builders.
• Multi-step UI-like interaction flows.
• Mapping component interactions to typed handlers.

5) dynamic-bot

Use this when payload data must travel inside component interactions.

You will learn:

• Dynamic component identity/payload strategies.
• Safer handling of stateful interactions without brittle parsing.
• Migration-friendly structure for evolving component contracts.

6) modal-bot

Use this for form-like input collection.

You will learn:

• Modal opening and submission handlers.
• Validation and error feedback for submitted fields.
• Integration of modal output into command workflows.

7) i18n-bot

Use this when localization is a top requirement.

You will learn:

• Locale detection and translation loading.
• Message composition with language-aware utilities.
• Structuring multilingual command output.

8) i18n-components-bot

Use this to combine localization with complex component flows.

You will learn:

• Localized labels/content in component trees.
• Locale-safe dynamic UI states.
• Practical translation boundaries in interaction-heavy UX.

9) http-bot

Use this when your Discord bot also exposes HTTP endpoints.

You will learn:

• Running bot runtime and HTTP runtime together.
• API endpoint organization around services/modules.
• Basic middleware patterns used by the framework.

10) webhook-bot

Use this when external events should trigger Discord actions.

You will learn:

• Receiving and validating webhook requests.
• Dispatching webhook events to the proper handlers.
• Reliability patterns and explicit error strategy.

11) signal-bot

Use this for event-driven communication patterns.

You will learn:

• Signal/event publishing and consumption.
• Decoupling producers from consumers.
• Scalable internal communication architecture.

12) schedule-bot

Use this for recurring automation.

You will learn:

• Scheduled tasks and cron-like execution flow.
• Safe scheduling boundaries for Discord operations.
• Organizing job logic with observability in mind.

13) sandbox

Use this as your integration laboratory.

You will learn:

• Mixed patterns from many framework features.
• Exception demos and edge-case handling.
• How to prototype quickly before extracting production modules.

Recommended learning paths

Pick one path and follow it sequentially for faster comprehension.

Path A: command fundamentals

1. slash-bot
2. context-menu-bot
3. guard-bot

Path B: interaction-heavy UX

1. components-bot
2. dynamic-bot
3. modal-bot
4. i18n-components-bot

Path C: backend/integration architecture

1. http-bot
2. webhook-bot
3. signal-bot
4. schedule-bot
5. sandbox

Path D: localization-first products

1. i18n-bot
2. i18n-components-bot
3. sandbox

How to run an example

From the workspace root:

pnpm install
pnpm --filter @spraxium/slash-bot build
pnpm --filter @spraxium/slash-bot start

Swap @spraxium/slash-bot for the app package you want to run.

Practical workflow for studying examples

Use this loop when analyzing any app:

1. Read spraxium.config.ts to understand module wiring and runtime hooks.
2. Read src/ handlers first, then services/providers.
3. Run one command/interaction end-to-end and inspect logs.
4. Modify one behavior and re-run immediately.
5. Keep successful experiments, discard noisy experiments quickly.

This keeps your learning focused on execution paths, not just static code reading.

migration notes for example readers

If you used older revisions of the examples, keep these points in mind:

1. Component V2 examples now emphasize async builder usage.
2. Dynamic component flows were modernized to match current payload patterns.
3. HTTP/webhook examples are aligned with latest package interfaces.
4. App manifests were normalized for workspace dependency consistency.

Building your own app from an example

A safe production-oriented approach:

1. Choose the closest example by behavior, not by size.
2. Copy only modules you can explain line-by-line.
3. Replace environment values and secrets first.
4. Add guards, logging, and error handling before adding features.
5. Add tests around your first critical command or interaction flow.

Examples are intended as architecture references, not drop-in production templates.