WelcomeForge

A small Discord onboarding bot built with TypeScript, discord.js, and SQLite. Welcome new members and let them pick community interest roles using persistent buttons.

Demo

Watch the WelcomeForge demo on YouTube

Features

• Custom welcome messages with {user}, {server}, and {count} placeholders.
• Private welcome preview, including the member’s avatar.
• Up to ten self-assignable interest roles; click a button again to remove a role.
• Administrator-only setup, enforced both through command defaults and at runtime.
• Per-server settings saved in SQLite and restored after restarting.
• Role permission and hierarchy validation during setup and on every button click.
• Removed roles stop working on old panels immediately.
• No message-content intent or external database service required.

WelcomeForge is a portfolio/demo project available as a starting point for custom Discord bot commissions.

Requirements

• Node.js 24 or newer.
• A dedicated Discord bot application and a server where you have Administrator permission.
• A persistent writable disk for the SQLite database.

Setup

1. In the Discord Developer Portal, create an application and open its Bot page.
2. Enable Server Members Intent. This is required for welcome events.
3. Copy .env.example to .env, then fill in DISCORD_TOKEN and CLIENT_ID. Use the application ID for CLIENT_ID.
4. Set GUILD_ID to your test server’s ID for immediate server-scoped commands. Enable Developer Mode in Discord to copy IDs. Leave it empty for global registration.
5. Invite your bot with the bot and applications.commands scopes, and View Channels, Send Messages, Embed Links, and Manage Roles permissions. The application’s installation/OAuth2 page can generate the invite URL.
6. In your server’s role list, move the bot’s role above the interest roles it will assign. Create ordinary interest roles without moderation or administration permissions.
7. Install and run:

npm install
npm run deploy
npm run build
npm start

For development, use npm run dev. Register commands again after changing command definitions; startup does not register commands automatically. Registration replaces the command list for this application at the selected scope, so use a dedicated application rather than TicketForge’s application. If switching from server-scoped to global commands, old server-scoped commands remain until removed.

Keep your bot token in .env, never in screenshots, chat, or Git. Do not share it to ask for setup help. .env and database files are ignored by Git.

Configure your server

Run these commands as an administrator (the values after options are examples):

/onboarding welcome channel:#welcome message:Welcome {user} to {server}! You are member #{count}.
/onboarding preview
/onboarding role-add role:@Gaming label:Gaming
/onboarding role-add role:@Music label:Music
/onboarding role-add role:@Coding label:Coding
/onboarding panel channel:#choose-roles
/onboarding status

/onboarding disable disables welcome messages. /onboarding role-remove removes a role from the allowlist without removing it from existing members.

Post a fresh panel after changing role labels or available roles, and delete the old panel manually. Old buttons for roles still on the allowlist keep working after restarts. Buttons for removed roles respond with an explanation instead of assigning them.

Welcome messages skip bot accounts and only run for new joins after configuration. {count} is Discord’s total server member count, including bots. A welcome mentions only the joining member; other mass mentions are suppressed. Preview responses and role-change confirmations are private.

Verify before filming the demo

1. Run npm test and npm run build.
2. Configure a welcome channel and check /onboarding preview.
3. Join the server with a consenting test account and verify the welcome appears in the configured channel.
4. Add three interest roles and post a panel. Toggle each role on and off with a normal member account.
5. Restart the bot. Click the original panel and confirm it still works; check /onboarding status for saved settings.
6. Remove an offered role. Its old button must refuse assignment.
7. Check that a non-administrator cannot configure onboarding.
8. Move an interest role above the bot or give it moderation permissions. Verify assignment is refused, then restore the role.

Portfolio demo outline

Show the welcome preview, a real member join, adding and removing an interest role, and the original panel working after a restart. End on the configuration view. Capture actual Discord screens rather than illustrative mockups.

Suggested portfolio description:

WelcomeForge makes community onboarding easier with personalized welcome messages and self-service interest roles. Administrators configure everything through slash commands, and saved settings and role buttons survive restarts. Built with TypeScript, discord.js, and SQLite.

Hosting and maintenance

Run one bot process against one database. The default file is data/welcomeforge.db; optionally set DATABASE_PATH. Keep that directory on persistent storage and back it up while the bot is stopped. Hosting platforms with ephemeral disks lose settings when restarted or redeployed unless you attach a persistent volume.

Use your hosting provider’s process supervisor to restart the bot if it exits. Discord connectivity and permissions must be tested on the actual host before promising delivery.

Interest roles should grant only the access you intend every member to be able to obtain. The bot rejects common elevated guild permissions, but does not audit channel-specific permission overwrites or determine whether a role unlocks confidential channels. Administrators must review that access before offering a role.

The database stores server IDs, channel IDs, role IDs, role labels, and welcome templates. It does not store message history or member profiles. Configuration persists until removed or the database is deleted.

Project structure

src/
  commands.ts       Slash command definitions
  config.ts         Environment validation
  deploy.ts         Explicit command registration
  index.ts          Discord events and interaction handling
  presentation.ts  Welcome embeds and role buttons
  roles.ts          Role safety and hierarchy checks
  store.ts          SQLite persistence
tests/
  core.test.ts      Persistence, templates, role policy, panel and command checks