npm package: @getsolara/solara.js
Description: A lightweight and modular Discord bot framework built on discord.js v14, with truly optional feature packages.
Author: getsolara
Latest version: 0.3.4

# ✨ Solara.js ✨

[![Documentation](https://img.shields.io/badge/Documentation-Solara.js.org-blue)](https://solara.js.org)
[![NPM Version](https://img.shields.io/npm/v/@getsolara/solara.js.svg)](https://www.npmjs.com/package/@getsolara/solara.js)
[![Discord Server](https://img.shields.io/discord/1361776049649745931?label=Discord&logo=discord&color=7289DA)](https://discord.gg/mkuh4bPng4)

Hey there! Ever wanted to build a Discord bot without pulling your hair out? Meet **Solara.js**!

Solara.js is a lightweight and **modular** Discord bot framework. Think of it like building with blocks, but for code. It's inspired by the simplicity of function-based scripting and uses the latest `discord.js v14`, making bot creation significantly easier and faster.

Its core is lean, and you can extend its power by adding optional packages for **database, canvas, and voice functionalities** as you need them!

➡️ **Check out our official documentation at [solara.js.org](https://solara.js.org) for comprehensive guides, examples, and the full function list!**

---

**Heads Up!** 🚧

This project is actively developed! While the core is stable and many features are functional, you might (and will) encounter occasional bugs as we continue polishing and improving it, especially within the newer optional packages.

**Key Features:**

*   **Simple Function-Based Syntax:** Write code like `$function[like this]` or just `$function`.
*   **Modern Foundation:** Built on the powerful, up-to-date `discord.js v14`.
*   **Modular Design:**
    *   **Core Package (`@getsolara/solara.js`):** Provides the essential framework and a rich set of core utility functions.
    *   **Optional Packages:** Easily add more specialized features:
        *   `@getsolara/solara.db`: For database integration (uses `quick.db`).
        *   `@getsolara/solara.canvas`: For image manipulation and generation (can use `canvas`, `canvafy`).
        *   `@getsolara/solara.voice`: For voice channel interaction and music playback (uses `@discordjs/voice`, `play-dl`).
*   **Hybrid Commands:** Seamlessly handle both traditional prefix commands (e.g., `!ping`) and modern `/` slash commands (`type: "both"`).
*   **Extensible:** Easily add your *own* custom functions to tailor the bot to your exact needs.
*   **Automatic Responses:** Sending messages and embeds is often automatic, or use explicit functions like `$sendMessage` or `$reply`.
*   **State Management:**
    *   Short-term (in-memory) variables: `$setVar`/`$getVar`.
    *   Persistent data (with `@getsolara/solara.db`): `$setUserVar`, `$getServerVar`, etc.
*   **Control Flow:** Conditional logic (`$if`, `$checkCondition`) and error handling (`$try`/`$catch`).
*   **Rich Function Library:**
    *   The core package comes with **hundreds** of built-in functions for embeds, user/server info, moderation, math, text manipulation, and more!
    *   Optional packages add many more specialized functions (e.g., the DB package adds over 15 database functions, Canvas adds image generation functions, Voice adds playback controls).
*   **Streamlined Setup:** Common Intent/Partial configurations are often handled with sensible defaults, but fully configurable.

**Get It Running:**

1.  **Install the Core:**
    ```bash
    # Make sure you have Node.js (v16.9 or newer!) installed
    npm init -y
    npm install @getsolara/solara.js dotenv discord.js 
    # discord.js is a peer dependency, so it's good practice to install it explicitly
    ```

2.  **Install Optional Packages (As Needed):**
    ```bash
    # If you need database features:
    npm install @getsolara/solara.db quick.db

    # If you need canvas/image generation:
    npm install @getsolara/solara.canvas canvafy canvas # (canvas might have native build steps)

    # If you need voice/music features:
    npm install @getsolara/solara.voice @discordjs/voice play-dl
    # You might also need: ffmpeg-static opusscript libsodium-wrappers (or sodium-native)
    # npm install ffmpeg-static opusscript libsodium-wrappers
    ```

**Quick Start:**

1.  Make your main bot file (e.g., `bot.js`):

    ```javascript
    // Loads environment variables (like your bot token) from a .env file
    require('dotenv').config();
    const { SolaraClient } = require('@getsolara/solara.js');
    const path = require('path'); // Node.js module for working with file paths

    // Set up the bot client
    const bot = new SolaraClient({
        // Define the events your bot needs to listen to
        intents: [ "Guilds", "GuildMessages", "MessageContent", "GuildMembers", "GuildVoiceStates" ],
        // Helps receive events for uncached items
        partials: ["Channel", "Message", "User", "GuildMember"],
        // Solara.js specific options
        solara: {
            prefix: "!", // Your command prefix
            token: process.env.DISCORD_TOKEN, // Your secret bot token (from .env)

            // Enable optional packages if you've installed them:
            db: true,      // Requires @getsolara/solara.db and quick.db
            canvas: true,  // Requires @getsolara/solara.canvas and its deps (canvafy, canvas)
            voice: true,   // Requires @getsolara/solara.voice and its deps (@discordjs/voice, play-dl)

            // Other options:
            triggerOnEdit: true,
            verboseStartupLogging: true
        }
    });

    // Tell Solara where your command files are located
    const commandsPath = path.join(__dirname, 'commands');
    bot.loadCommands(commandsPath);

    // (Optional) Tell Solara where your project-specific custom functions are
    const functionsPath = path.join(__dirname, 'custom_functions');
    bot.loadFunctions(functionsPath);

    // Event listener: Runs when the bot successfully connects to Discord
    bot.on('ready', () => {
        console.log(`${bot.user.tag} is online and ready to go!`);
        // Example: Set a status
        // bot.status({ name: `with Solara!`, type: "PLAYING" });
    });

    // Log the bot into Discord
    bot.login(); // Token is already provided in solara options
    ```

2.  Create command files (e.g., `.js` files) in a `commands/` folder:

    **Example: `commands/ping.js`**
    ```javascript
    module.exports = {
        name: "ping",
        aliases: ["p"],
        description: "Checks the bot's response time.",
        type: "both", // Prefix AND slash command
        code: `Pong! My latency is $ping ms.` 
    };
    ```

3.  **(Optional) Create custom functions** in a `custom_functions/` folder:

    **Example: `custom_functions/greet.js`**
    ```javascript
    module.exports = {
        name: "$greet",
        description: "Greets a user.",
        takesBrackets: true, // Expects $greet[UserName]
        execute: async (context, args) => {
            const userName = args[0] || context.user?.username || "there";
            return `Hello, ${userName}! Welcome.`;
        }
    };
    ```
    You can then use `$greet` in your commands: **code:** `$greet[$username] - Thanks for using $username[$botID]!`

**Function Ecosystem:**

Solara.js provides a comprehensive suite of functions:

*   **Core (`@getsolara/solara.js`):** Hundreds of functions for message handling, embeds, user/server information, moderation tools, text manipulation, math operations, conditional logic, API calls (`$httpRequest`), and much more.
*   **Database (`@getsolara/solara.db`):** Functions like `$setUserVar`, `$getServerVar`, `$getMessageVar`, `$dbGet`, `$dbSet`, `$dbIncrement`, `$dbPush`, `$dbDelete`, `$dbClear`, and more for persistent data storage.
*   **Canvas (`@getsolara/solara.canvas`):** Functions for generating images like welcome cards (`$welcomeCard`), level up cards (`$levelUpCard`), rank cards (`$rankCard`), captchas (`$captchaCard`), Spotify cards (`$spotifyCard`), custom drawing with `$createCanvas`, `$loadImage`, `$registerFont`, etc.
*   **Voice (`@getsolara/solara.voice`):** Functions for voice channel management (`$voiceJoin`, `$voiceLeave`), music playback (`$voicePlay`, `$voiceSkip`, `$voiceStop`, `$voicePause`, `$voiceResume`), queue management (`$voiceQueueAdd`, `$voiceQueueList`, `$voiceQueueClear`, `$voiceQueueRemove`), volume control (`$voiceSetVolume`), and track information (`$voiceNowPlaying`, `$search`, `$lyrics`).

For a complete list of all functions across the core and optional packages, and detailed explanations of how to use them, head over to our official documentation:

➡️ **[Explore the Functions on solara.js.org](https://solara.js.org)**

**Wanna Help?**

Contributions are welcome! Feel free to open an issue or submit a pull request on our GitHub repository. (Contribution guidelines will be detailed soon).

**License**

MIT License - Feel free to use, modify, and distribute! 👍