Start a Bot

Before starting, create a Fluxer bot, copy its token when Fluxer shows it and add the bot to a community. Fluxer shows a token only once, and the project below has a file for it. Fluxerly is tested against Node.js 24.15 or newer

Generate the Project

The generator writes into the terminal's current folder. Start in a new folder for the bot:

mkdir my-bot
cd my-bot

Adding --template js, --template ts or --template effect skips the question. The JavaScript and TypeScript templates write the bot shown below. The Effect template writes the Effect starter bot instead. Each template includes a test and an AGENTS.md file, and creates a .env file with an empty token value unless that file already exists. The command then installs the dependencies and prints the remaining steps, or prints installation instructions when installation is skipped or fails

The folder may already hold the .env and .gitignore that the manual setup describes. The command keeps the .env and its token, adds node_modules and .env to the .gitignore when they are missing and leaves the rest of that file as it is. When any other file that the command writes already exists, such as package.json or bot.js, it stops without writing anything

Then set FLUXER_BOT_TOKEN in .env to the token. Check the bot with npm test, pnpm test or bun run test, which runs it against an in-memory Fluxer without the token or a network. Start it with npm start, pnpm start or bun run start and continue with Try it

Set Up the Project by Hand

These steps create the same bot without the generator

1. Install the SDK

Open a terminal in the bot's folder. Create a package.json file in that folder:

{
    "type": "module"
}

This lets the bot use import in Node.js

When a coding agent helps write the bot, copy the SDK's rules for it into the project's AGENTS.md, which many coding agent tools read automatically. Run the same command again after updating the SDK

2. Save the Token

Save the token in a file named .env in the bot's folder:

FLUXER_BOT_TOKEN=paste-the-token-here

Check that the file is named exactly .env. Some editors, such as Notepad, add .txt when saving, and Node.js cannot find .env.txt

Keep that file out of version control by adding this line to .gitignore:

.env

3. Create the Bot

Save this as bot.js. The bot reads its token from FLUXER_BOT_TOKEN in the process environment, so the token never appears in the file

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 })

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 })

The file exports the bot's options as bot. The defineBot function returns them unchanged and keeps the types of command arguments for TypeScript and editors. Running the file starts the bot with these options and the token, while a test can import bot without starting it. Testing a bot shows the test that the generator writes

4. Start It

Start the bot with the token's .env file:

When FLUXER_BOT_TOKEN is already set in the terminal, run the file without --env-file=.env

Try It

Once the bot is online, the terminal shows a line such as Connected to Fluxer as MyBot in 1 community. If it says instead that the bot is not in any community yet, open the link in that line to invite it

Type !ping in a channel the bot can read and reply to. It should answer Pong!

The SDK skips messages from bots by default. The commands option routes a message that starts with the ! prefix and a command name, such as !ping, to that command, and the bot ignores every other message

Press Ctrl+C to stop the bot. The SDK then stops the commands, closes the connection and finishes its cleanup before the program ends

Keep Going

Change ping or Pong! to customize the command or reply. Then choose a task:

• Build a small bot: Combine commands, arguments, an embed, a welcome message, a permission check and a cooldown in one file
• Learn the core concepts: Clients, events, Results, caches and the gateway in plain terms
• Copy an example bot: Complete bots for moderation, reaction roles, welcomes and tickets
• Send messages, embeds and files: Check reply results, edit messages and attach a file
• Add prefix commands to a bot: Register actions with typed arguments and generated help
• React to events and collect replies: Distinguish joins from startup and build a bounded conversation
• Operate a long-running bot: Handle failures, cancellation and shutdown

The client's message methods link to the full API reference for exact inputs and return values

{
    "compilerOptions": {
        "target": "ES2024",
        "module": "NodeNext",
        "types": ["node"],
        "strict": true,
        "noEmit": true,
        "allowImportingTsExtensions": true,
        "verbatimModuleSyntax": true,
        "erasableSyntaxOnly": true
    }
}