From your first reply to the bot of your dreams

A Fluxer-native bot SDK for JavaScript, TypeScript and Effect

Home · Docs · Quick start · API reference · Changelog · Examples · FAQ · NeonFlux

npm install @neontechspace/fluxerly

import { runBot } from "@neontechspace/fluxerly"

await runBot({
    token: process.env.FLUXER_BOT_TOKEN,
    commands: {
        prefix: "!",
        commands: { ping: { execute: ({ reply }) => reply("Pong!") } },
    },
})

The same SDK runs large bots. NeonFlux is a real Fluxer bot using it

What Fluxerly includes

Fluxerly is built for developers at every skill level, from a first bot in one file to large bots that need full control

• One-file start: runBot connects, stops cleanly on Ctrl+C and explains a failed startup with a suggested fix
• Visible errors: In the default API, network calls return a Result for expected failures. Check it or return it from a handler so the SDK reports the failure. Logs never contain the token, and FLUXERLY_DEBUG=1 or the logging option changes what they show
• Built-in commands: Prefix commands with typed arguments, guards, cooldowns, command groups and generated help
• Fluxer's features: Messages with embeds, attachments and voice notes, reactions, threads and forum posts, communities and permissions, emoji and stickers, webhooks and OAuth2, with paged history and opt-in caches
• Typed raw access: client.rest.call reaches every route that accepts a bot token with Fluxer's own field names checked at compile time, client.rest.request sends routes newer than the SDK, and raw gateway events carry their documented payload types
• Tests without a token: The /testing and /effect/testing entry points run a bot against an in-memory gateway and HTTP server, and a test clock runs timed work such as a ten-minute reminder without waiting
• Two APIs, one implementation: Start with async/await, or choose the native Effect API, with the same features and behavior in both
• Ready to grow: Automatic sharding, session resume across restarts, a process supervisor, rate limiting that never blindly repeats an uncertain write, and metrics and traces through the observe option
• Agent-ready: fluxerly agents adds the SDK's rules to a project's AGENTS.md, and the docs publish llms.txt

The result is less infrastructure to build, with testing and application structure already in place

Install

Fluxer moves fast, and Fluxerly keeps pace. Choose the channel that fits your bot:

• Stable: Releases that passed every check, for bots that value calm
• Nightly: The newest changes as they land, for bots that want them first

Fluxerly is tested against Node.js 24.15 or newer. JavaScript needs no compiler, and TypeScript typechecking or compilation requires TypeScript 7 and @types/node as a development dependency

npm

npm install @neontechspace/fluxerly

pnpm

pnpm add @neontechspace/fluxerly

Bun

bun add @neontechspace/fluxerly

A committed lockfile records the exact installed version and keeps installs reproducible. Nightly releases can include breaking changes. Install one with npm install --save-exact @neontechspace/fluxerly@nightly, or bun add --exact @neontechspace/fluxerly@nightly with Bun, so a fresh install without a lockfile cannot pick up a newer nightly that breaks the API

Getting started

A bot needs a Fluxer application, its bot token and an invite to a community

Generate a project with a test in the bot's folder with npx @neontechspace/fluxerly init, pnpm dlx @neontechspace/fluxerly init or bunx @neontechspace/fluxerly init, choose JavaScript, TypeScript or Effect, and follow the steps it prints. Adding --template js, --template ts or --template effect skips the question. An existing .env is kept, and missing node_modules and .env lines are added to an existing .gitignore. The quick start also sets up the same project by hand

The generated bot.js replies Pong! to !ping:

import { defineBot, runBot } from "@neontechspace/fluxerly"

// The bot's options without its token, so its test can run them through createTestBot without a token or a network
export const bot = defineBot({
    commands: {
        prefix: "!",
        commands: {
            // Returning the reply reports a failed send to the log
            ping: { execute: ({ reply }) => reply("Pong!") },
        },
    },
})

// Running this file starts the bot, while importing it from a test does not.
// A failure that stops the bot, such as a rejected token, is logged and sets a failing exit code
if (import.meta.main) await runBot({ token: process.env.FLUXER_BOT_TOKEN, ...bot })

Set FLUXER_BOT_TOKEN in .env, check the bot with npm test and start it with npm start, then send !ping in a channel the bot can read. While changing the bot, npm run dev restarts it after each saved change

Choosing an API

JavaScript & TypeScript

Import @neontechspace/fluxerly and use async / await. Check Results for expected failures, and control shutdown with explicit methods and cancellation signals. The default API works with new bots and existing Promise-based applications. JavaScript users do not need TypeScript or Effect setup

Effect

Import @neontechspace/fluxerly/effect and compose work with Effect.gen and yield*. Expected failures stay in the typed error channel. Scopes and interruption control cleanup. Choose this API for an Effect application, or to learn structured concurrency with a real bot

Both entry points provide typed events, prefix commands, embeds, attachments, reactions and collectors. Optional bounded caches keep local lookup separate from remote reads

Why learn Effect?

Bots often grow from one handler into several jobs, listeners and requests that must stop together. Effect describes that work as one program, shares its dependencies and waits for scoped cleanup when it succeeds, fails or is interrupted

For example, a scoped conversation can register a collector, send a question and wait for an answer. If sending fails, the scope releases the collector. Concurrent reads can cancel their unfinished siblings on failure without leaving cleanup to scattered callbacks

Learn the core concepts in the Effect v4 introduction

Installing Effect for a native application

Applications that import Effect directly must declare it as a direct dependency, using a version within the installed SDK's peerDependencies.effect range. Read node_modules/@neontechspace/fluxerly/package.json, or the SDK manifest for this checkout

Fluxerly is tested against the lowest version in that range and against its Effect 4 development version, which can be newer. Later Effect 4 releases are accepted. Do not install Effect 3 or an Effect 4 prerelease. The versioned documentation gives the matching install command

Voice: Waiting for Fluxer's new voice system

Note

Fluxerly waits for Fluxer's new voice system and does not support voice over LiveKit. Fluxer is replacing LiveKit with its own voice system, which should arrive soon, and bot voice will come with it

Fluxerly does not join voice channels or send live audio or video yet. Until then, voice states, member voice controls such as move, mute, deafen and disconnect, voice notes, and audio or video attachments work

Repository activity

Licensed under Apache-2.0