noblox.js: A JavaScript repository from BIG Games

A Node.js wrapper for interacting with the Roblox API; forked from roblox-js.

About • Prerequisites • Installation • Quickstart • Documentation • Common Issues • YouTube Series • Credits • License

About

noblox.js is an open-source Roblox API wrapper written in JavaScript (with TypeScript compatibility) as a fork from sentanos's roblox-js module.

This NPM package enables operations froms the Roblox website to be executed via NodeJS; many individuals leverage noblox.js along side Roblox's HTTPService to create in-game scripts that interact with the website, i.e. promote users, shout events, and so on, or to create Discord utilities to manage their community.

If you are looking for more information on how to create something like this, check out our sister library, noblox.js-server or our YouTube series. Keep in mind that these resources may not always be up to date, so it is highly encouraged that you learn to use the noblox.js library directly.

Prerequisites

Node.js® v18.18 or later

Installation

With node.js installed simply run:

# Run this to install noblox.js locally to your repository. 
$ npm install noblox.js

# Alternatively, if you are using yarn:
$ yarn add noblox.js

# To use noblox.js anywhere, run this code to install the package globally:
$ npm install noblox.js -g

That's it!

Documentation

You can locate the noblox.js documentation here; keep in mind some internal or legacy methods may not be documented.

Legend

You may notice our documentation utilizes emojis in every function description; they have meanings!

Icon	Description
🔐	Authentication through `setCookie()` is required to use this method.¹
🔓	Authentication through `setCookie()` is required in some use-cases; dependent on the target's privacy settings.
✅	No authentication is required to use this method.

1 : Extended permissions may be required such as edit permissions or account ownership.

Quickstart

Install noblox.js.
Retrieve your .ROBLOSECURITY cookie. Instructions on how to do that can be found here.

Write your code.

Using async/await syntax:

const noblox = require('noblox.js')
async function startApp () {
    // You MUST call setCookie() before using any authenticated methods [marked by 🔐]
    // Replace the parameter in setCookie() with your .ROBLOSECURITY cookie.
    const currentUser = await noblox.setCookie('_|WARNING:-DO-NOT-SHARE-THIS.--Sharing-this-will-allow-someone-to-log-in-as-you-and-to-steal-your-ROBUX-and-items.|_6E6F626C6F782E6A73') 
    console.log(`Logged in as ${currentUser.UserName} [${currentUser.UserID}]`)

    // Do everything else, calling functions and the like.
    const groupInfo = await noblox.getGroup(9997719)
    console.log(groupInfo)
}
startApp()

You are now using noblox.js!

More examples can be found here.

Promises are fundamental to this library; if you are unfamiliar with JavaScript promises, we recommend you check out our tutorial here, and Daniel Shiffman's JavaScript series.

Hiding Your Cookie

It is bad practice to store your .ROBLOSECURITY cookie inside your codebase; it is too easy to accidentally screenshot or push this private key to GitHub. We recommend using a package such as dotenv to store your private information in environmental variables.

We recommend using a secondary account for botting purposes.

Consult their documentation or follow this video.

Invalidating A Cookie

In the event of accidentally exposing your .ROBLOSECURITY cookie, do not panic. Go to Account Settings > Security, select Sign out of all other sessions, then log out of your account. This should invalidate your .ROBLOSECURITY cookie.

Common Issues

Error: You are not logged in.

You may be calling a function before setCookie() is completed; make sure that you are awaiting setCookie() before initializing any event listeners or function calls.

noblox.js is a promise based library, this enables you to run operations concurrently; however if you are not awaiting your promises, this means while setCookie() is validating your cookie, your other functions will continue to run- ~30ms is a long time at the computer scale.

Promises are fundamental to this library; if you are unfamiliar with JavaScript promises, we recommend you check out our tutorial here, and Daniel Shiffman's JavaScript series.

Error: 400 The roleset is invalid or does not exist.

You likely are using a rankId (0 - 255) instead of a rolesetId (>255); a rolesetId is a unique identifier for a role which you can find by calling getRoles(groupId).

Roblox's naming scheme is a fickle beast; similarly, a developerProductId is different than a productId (which appears on the public facing dashboard); use getDeveloperProducts(placeId) to see the developerProductId.

Error: Initialization failed: 401 Authorization has been denied for this request.

First, see the steps for Error: You are not logged in.

If this is unresolved, are you sure the bot has permissions to access this resource? Can you do this operation manually on the website through the bot account?

At the end of the day, a 'bot' is a user account, it cannot magically bypass privacy restrictions or group permissions.

Credits

suufi - Lead maintainer
sentanos - We wouldn't exist without him. 😀
Neztore - Library maintenance and review
alanbixby - Library maintenance
popeeyy - Creation of the documentation.
edward - Helping with the creation of the documentation.

License

MIT

BIG-Games-LLC/noblox.js