Discord Widgets Template

An easy-to-customize TypeScript template for Discord profile widgets. It supports multiple Discord apps, dynamic fields, OAuth, and automatic updates.

This template is made for personal widgets and it is not intended for production use.

Warning

This project uses Bun. If you have not used it before, the Bun documentation is a good place to start.

Features

• Multiple Widget Support: Run widgets for multiple Discord apps from the same server.
• Auto Sync: Keep your widgets updated automatically every Sunday.
• Simple Authentication: Start the OAuth flow with only the app ID of the widget you want to use and your user ID.

Sections

• Getting Started - How to set up the project and run it locally.
• Configuration - How to configure your widgets and environment variables.
  • Environment Variables - How to set up your secrets and app details.
  • Widgets - How to configure your widgets and add new fields.
  • Using the OAuth Route - How to authorize your widgets with Discord.
  • Scheduled Sync - How to change the automatic update schedule for your widgets.

Getting Started

Here is the quickest way to get everything running:

1. Create a new repository from the template:

2. Clone the repository:

git clone https://github.com/<your-username>/discord-widgets-template.git
cd discord-widgets-template

3. Install dependencies:

bun install

4. Set up environment variables: Copy .env.example to a new .env file, then fill in your app details and secrets.

5. Configure your widgets: Open src/widgets.ts and replace the example app and user details with your own.

6. Run the project:

bun start

Your OAuth server will now be available at http://localhost:3000 by default.

Configuration

Environment Variables

Check .env.example for the available environment variables and examples.

Secrets can be set for one widget:

WIDGET_<APP_ID>_<VARIABLE_NAME>=your_value

Or shared by every widget:

WIDGET_GLOBAL_<VARIABLE_NAME>=your_value

Use getSecret('VARIABLE_NAME', 'APP_ID') to read a widget secret in your code. Each configured widget needs a BOT_TOKEN and CLIENT_SECRET.

Widgets

You can configure your widgets in the src/widgets.ts file. Each widget should have the following properties:

• appId: The Discord application ID for the widget.
• users: The users who can use the widget. Each user has an id and username.
• fields: The dynamic fields shown in the widget.
• vars: Optional extra values used by your widget logic.

The template includes a sample field for showing a GitHub user's total repositories. You can add your own field types in src/types.ts and handle their values in src/utils/updateWidgets.ts.

Using the OAuth Route

Once the server is running, open this URL with your own IDs:

http://localhost:3000/oauth/authorize?app_id=<WIDGET_APP_ID>&user_id=<YOUR_USER_ID>

You will be sent to Discord to authorize the app of the widget you want to use. After that, the server updates the matching user's widget.

Scheduled Sync

Widgets are updated every Sunday by default. You can change the schedule at the top of src/index.ts if you want them to update at a different time.