Blurple Canvas Web

Project Blurple

Project Blurple is an annual, week-long, community-run event which celebrates Discord’s anniversary. Part of this is Blurple Canvas where people in participating servers create pixel art on a shared canvas.

Blurple Canvas Web is a web alternative to the existing Discord bot Discord bot, which brings canvas to the web!

If you’d like a bit more context, we have a wiki!

🧚 Features

Viewing canvases

• View canvases. View the current canvas (if/when there is an active event), or view archived canvases from past events. Pick which canvas to view from the dropdown in the navbar.
• Pan and zoom. Pan around the canvas by dragging, and scroll to zoom.
• Live updates. When there’s an ongoing Project Blurple event, the active canvas will update in real time as people place pixels.
• Pixel history. Select a pixel to see what colours have been placed there, and who placed it.

Placing pixels

[!NOTE] Pixel placement is only enabled for active canvases that are part of an ongoing event. Once that event ends, the canvas is locked.

• Sign in with Discord. Anyone can view canvases (no account needed), but you’ll need to sign with Discord to place pixels. (You can also sign out.)
• View colour palette. As you switch between events, see the colours which were/are allowed on that canvas.
• Place pixels. When there is an active Project Blurple event (and you aren’t in cooldown), you can place pixels on the canvas.
  • …Or not. Placing pixels via Blurple Canvas Web can be disabled by unsetting an environment variable when deploying.
• Bot command. When you select a pixel and colour, it’ll show the /place Discord bot command for placing a pixel—along with a button to copy it.
• Partnered colours. Each server partnered with the Project Blurple event gets a unique pixel colour which can only be used from within that server. For these, Blurple Canvas Web gives a link to join the server.

Statistics

• Leaderboard. View the top 10 participants for each canvas, ranked by the number of pixels they’ve placed on that canvas.
• User stats. View your own stats for each canvas, including how you rank against everyone else for that canvas (by pixels placed) and your most frequently used colour—among other details.

🥪 Tech stack & repo structure

This is a monorepo, with three packages:

• @blurple-canvas-web/backend: The Node–Express back-end server
• @blurple-canvas-web/frontend: The Next.js front-end
• @blurple-canvas-web/types: Where TypeScript types shared by the front- and back-end live

All packages are written in TypeScript. backend talks to the same PostgreSQL as the Blurple Canvas Discord bot. Prisma serves as the ORM layer. frontend uses Axios and TanStack Query to query the backend API. Realtime canvas updates are pushed to clients with Socket.IO. Testing is conducted with Vitest. GitHub Actions handles CI.

🌱 Getting started

[!TIP] We suggest opening this project as a Visual Studio Code multi-root workspace: just open the blurple-canvas-web.code-workspace file. The workspace is configured to use the right linter and formatter, and recommends a few extensions. But, you’re welcome to use your preferred editor.

☑️ Prerequisites

[!WARNING] Windows users, these instructions assume you use WSL. You’re welcome to use PowerShell—things still work—but you’ll have to “translate” these steps for yourself.

Install Node Version Manager. If you don’t use Homebrew, see github.com/nvm-sh/nvm for other ways to install.

brew install nvm

Use the appropriate version of Node. You may be prompted to run nvm install. (If for whatever reason you aren’t using nvm, make sure to install and use the Node version specified in /.nvmrc.)

nvm use

Enable Corepack. We use pnpm to manage dependencies. We recommend using Corepack to manage your pnpm version, but if you’d prefer installing pnpm a different way, go ahead.

corepack enable pnpm

Verify pnpm is working. By now the package manager should be good to go. Double check with this command, and make sure it matches the version number specified in the root manifest file.

pnpm --version

🤫 Secrets & environment variables

The backend and frontend packages need to have some environment variables set work correctly (in /packages/backend/.env and /packages/frontend/.env, respectively). Consult the .env.example files in each of those packages to see what variables are needed, and contact one of the contributors if you need any secrets.

🚀 Build & deploy

Install dependencies. Run this from the monorepo root, and it will install dependencies for all packages.

pnpm install

Deploy! With hot-reloading:

pnpm dev

Or without:

pnpm build && pnpm start

If you want to run the front- and back-ends in different terminals[^filter]:

[^filter]: These are shorthand for pnpm --filter @blurple-canvas-web/backend dev and pnpm --filter @blurple-canvas-web/frontend dev.

# Start the back-end
pnpm -F backend dev

# Start the front-end
pnpm -F frontend dev

🤓 Contributors

Blurple Canvas Web started as a SOFTENG 750 project at Waipapa Taumata Rau. We are Team Golden Giraffes.[^teamname]

[^teamname]: Not sure we would’ve chosen this name for ourselves, though…

• Aaron Guo
• Emily Zou
• Henry Wang
• Jasper Lai
• Josh Jeffers
• Samuel Ou

💌 Acknowledgements

Blurple Canvas Web wouldn’t exist without these lovely people and projects. Thanks to:

• Project Blurple and the Project Blurple community, for obvious reasons;
• Rocked03 for creating the Blurple Canvas Discord bot;[^samuel]
• the Place Atlas Initiative for their efforts cataloguing r/Place;
• Josh Wardle and r/Place participants (no introduction needed); and
• you, for your interest in this project!

[^samuel]: Pretty sure Samuel isn’t happy about me putting him on this list. Tough cookies. —Jasper

📜 Licence

The code for Blurple Canvas Web is licensed under the Apache License, Version 2.0.