Fluxerly.js

From your first reply to the bot of your dreams

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

Note

Fluxerly is a prerelease SDK. Start with the temporary docs and review the changelog before upgrading

Issues and pull requests are maintainer-only until the first Stable release. The contribution guide and submission templates are prepared for that release, without opening public access now

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: Network calls return a Result instead of throwing, and logs show every failure in full without the token. FLUXERLY_DEBUG=1 or the logging option changes what the logs show
• Built-in commands: Prefix commands with typed arguments, guards, cooldowns, command groups and generated help
• Tests without a token: The /testing and /effect/testing entry points run a bot against an in-memory gateway and HTTP server
• 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

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. Canary and RC releases can include breaking changes. Install them with --save-exact, or --exact with Bun, so a fresh install without a lockfile cannot pick up a newer Canary or RC that breaks the API

Getting started

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

To start from a generated project with a test, run npx @neontechspace/fluxerly init, pnpm dlx @neontechspace/fluxerly init or bunx @neontechspace/fluxerly init in an empty folder, choose JavaScript, TypeScript or Effect, and follow the steps it prints. Adding --template js, --template ts or --template effect skips the question. To set up the bot by hand instead:

1. Create a folder for the bot containing a package.json file with { "type": "module" }, then install the SDK in that folder as shown above
2. Save the token in a file named .env as FLUXER_BOT_TOKEN=paste-the-token-here, and add .env to .gitignore
3. Save this bot as bot.js. It replies Pong! to !ping

import { runBot } from "@neontechspace/fluxerly"

await runBot({
    token: process.env.FLUXER_BOT_TOKEN,
    events: {
        messageCreate: ({ message, reply }) => {
            if (message.content !== "!ping") return
            return reply("Pong!")
        },
    },
})

4. Run node --env-file=.env bot.js and send !ping in a channel the bot can read

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

The lowest version in that range is the one Fluxerly is tested against. Later Effect 4 releases are accepted. Do not install Effect 3 or an Effect 4 prerelease. The versioned documentation gives the matching install command

Bot voice and media are not supported yet

Bot voice connections and audio/media transport are deferred until after Fluxer's voice update, with SDK implementation and verification still required. Fluxerly does not currently join voice channels or send and receive audio or video

Voice-state observations in communities and member move, disconnect, community mute and community deafen controls are supported for existing participants

Repository activity

Licensed under Apache-2.0