Keep the Discord gateway in one process and your product logic in another—without shipping your bot token to every client.
npm create shardwire@latestDiscord bots often grow until one long-lived process is doing everything: gateway traffic, business rules, admin dashboards, and automation. That coupling makes deployments brittle and pushes sensitive capabilities (and sometimes credentials) into places they should not live.
If you have already split “API server + worker” or “control plane + data plane,” the idea will feel familiar. What Shardwire adds is a small, opinionated bridge: a bot-side WebSocket server and a typed client so a separate app process can subscribe to events and send actions with a shared secret—not with your bot user’s full power in the browser.
Scaffold a project, then run the bot and app from the generated README.md:
npm create shardwire@latest
cd your-project
npm install
cp .env.example .env # fill DISCORD_TOKEN, SHARDWIRE_SECRET, optional ids and SHARDWIRE_URL
npm run register # register slash commands (once), if your template includes them
npm run bot # terminal A: bot + bridge
npm run app # terminal B: app client (Express Server) or see template for ViteExpress Server templates also serve GET /health on PORT (default 3000). Adjust URLs and secrets if you change the default listen address.
The React App template instead uses SHARDWIRE_BROWSER_SECRET plus matching VITE_* values so the browser gets a scoped secret rather than a broad internal one.
Cloning only adds source; npm install pulls dependencies like any Node project. When you run a bot or scaffolded app, processes reach Discord and the bridge WebSocket you configure. Keep tokens and bridge secrets in .env or your host’s secret store (templates use names like SHARDWIRE_SECRET or SHARDWIRE_BROWSER_SECRET); never commit real values. To clean up, stop processes and delete the checkout; drop a published dependency from a project with npm uninstall <name>.
Start a new project (recommended):
npm create shardwire@latestUse the libraries in an existing Node or bundler project:
npm install shardwire
# optional dashboards / React controllers
npm install @shardwire/reactPublished packages install on Node.js 18+. The runtime floor depends on which path you use: the Express Server template and any Node app process that calls connectBotBridge still require Node.js 22+, while the React App template follows Vite’s ^20.19.0 || >=22.12.0 support window.
Details — work on this monorepo locally
Clone the repository, then from the repo root:
npm installUseful root scripts:
| Script | Purpose |
|---|---|
npm run build |
Build shardwire, @shardwire/react, and the docs site |
npm run verify |
Lint, tests, typecheck, and builds across published packages and the scaffold |
npm run docs:dev |
Next.js docs + reference dev server |
npm run docs:build / docs:preview |
Static export build and local preview |
Scaffold templates live under packages/create-shardwire/templates/ if you need to read source without generating a project.
- Skim concepts — How it works (bot vs app, secrets, capabilities).
- Scaffold —
npm create shardwire@latest(Express Server or React App). Template sources: express-server, react-vite. - Configure environment —
.envwith Discord credentials and the secret layout your template expects:SHARDWIRE_SECRETfor the Express/Node app path, orSHARDWIRE_BROWSER_SECRETplus matchingVITE_*values for the browser dashboard path. - Register commands (if your template uses slash commands) —
npm run registerin the generated project. - Run bot and app — two processes in development; production layout is your choice (see Keeping it alive).
The bot process owns the Discord gateway session and hosts a bridge server. The app process uses shardwire/client (or @shardwire/react in the browser) to connect over WebSocket, authenticate with the shared secret, and exchange typed events and actions.
Details — repository layout
| Path | Role |
|---|---|
packages/shardwire |
Core bridge + Node client (shardwire, shardwire/client) |
packages/react |
Optional React hooks for app-side UIs |
packages/create-shardwire |
Interactive project scaffold and templates |
apps/website |
Public documentation site (Fumadocs + Next.js) |
Source of truth for APIs and guides is the published documentation, not this file alone.
Details — license and contributing
This monorepo is MIT licensed (LICENSE at the root; packages/shardwire ships its own copy for npm).
Contributions: open an issue or PR on GitHub. Run npm run verify before submitting substantive changes.
Do I have to use React? No. @shardwire/react is optional; Node-only apps use shardwire and shardwire/client.
Can the app run in the browser? Yes for the client side of the bridge; the bot must stay on a server you control. Read the docs for secret handling and deployment constraints.
Where is the changelog? Documentation changelog hub with per-package sections.
See the expanded Contributing note in Reference → Details, and use npm run verify from the repo root.
MIT — see LICENSE.