DEV Community: with-heart

Set up our pnpm monorepo

with-heart — Sun, 29 May 2022 19:47:59 +0000

In this post, we'll implement the basic monorepo structure we mentioned at the end of High level technical overview.

As a quick refresher, we'll have three packages:

app
bot
db

We'll only generate a basic package structure for each. Here's what the end structure will look like (with some files/directories excluded to focus on the changes we'll be making):

.
├── app
│  ├── package.json
│  ├── pages
│  ├── public
│  ├── README.md
│  └── tsconfig.json
├── bot
│  ├── package.json
│  ├── src
│  │  └── index.ts
│  └── tsconfig.json
├── db
│  ├── package.json
│  ├── src
│  │  └── index.ts
│  └── tsconfig.json
├── package.json
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
├── README.md
└── tsconfig.json

Additional monorepo setup like using the packages as dependencies of each other, build tooling, etc. will come later.

Create `pnpm` workspace

Since we're using pnpm, monorepo setup doesn't require much setup on our part.

Essentially, we just need to create a pnpm-workspace.yaml file that defines the package directories in our monorepo:

packages:
  - 'app'
  - 'bot'
  - 'db'

With this change, pnpm knows that the app, bot, and db directories are packages in our monorepo.

Now that we have this file in place, we can set up our package directories.

Create the `app` package

Since app is a Next.js app, we'll use create-next-app to generate that package: pnpm create next-app --ts app.

The setup runs as expected and dependencies are added to the root pnpm-lock.yaml file.

We can start our app to test that it works: pnpm --filter app run dev

I just really want to note how cool pnpm is. The --filter flag allows us to zoom in on specific packages to execute our commands. In the above command, we use --filter app to target pnpm run dev to the app directory.

Before we move on, we need to fix an eslint error in the app directory: Parsing error: Cannot find module 'next/babel'.

To resolve that, we need to update app/.eslintrc.json to extend from next/babel:

{
  "extends": ["next/babel", "next/core-web-vitals"]
}

Create the `bot` and `db` packages

Prepare `typescript`

Since bot and db will both be libs and not React apps, we can configure typescript at the root and have both packages extend their configuration from that.

To get started, we'll install a few packages: pnpm i typescript @types/node -w @tsconfig/node16-recommended

The -w flag tells pnpm that we want to install the dependencies at the root.

The @tsconfig/node16-recommended package contains a tsconfig.json file with recommended TypeScript configuration. We'll use that in our root tsconfig.json file:

{
  "extends": "@tsconfig/node16-strictest/tsconfig.json",
  "exclude": ["app"]
}

We also exclude the app directory because Next.js uses its own tsconfig.json file.

Create the `bot` package

bot
├── package.json
├── src
│  └── index.ts
└── tsconfig.json

We'll create the bot folder and a package.json inside of it:

{
  "name": "bot",
  "version": "0.0.0",
  "private": true
}

We'll also create bot/tsconfig.json:

{
  "extends": "../tsconfig.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src"]
}

This configuration includes src in the files TypeScript will compile and the extends option means we reuse the configuration specified in our root tsconfig.json.

Create the `db` package

db
├── package.json
├── src
│  └── index.ts
└── tsconfig.json

To create this package, we'll do everything we did to create the bot package except we replace the word bot with db.

Awesome! We now have a monorepo! This gives us a lot of flexibility and clarity in how we configure and use our packages.

To check out the PR for this post, look here: https://github.com/Developer-DAO/discord-server-info/pull/10

Prepare our repo

with-heart — Sun, 29 May 2022 16:52:58 +0000

Before we start building our application, we need to spend a little time preparing our repo.

In this post, we'll use pnpm to create our package.json file, install prettier, and configure husky and lint-staged to format any changed files with prettier when we commit them. We'll also create a minimal .gitignore file.

Create `package.json`

To generate a package.json file, I ran pnpm init inside our project directory. This created a package.json file with a few defaults:

{
  "name": "discord-server-info",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

These defaults are weak and don't really fit our use case so I updated the file to contain much more information:

{
  "name": "discord-server-info",
  "private": true,
  "license": "MIT",
  "description": "Explore Discord server data and statistics",
  "keywords": [
    "discord",
    "discord.js",
    "next.js",
    "prisma"
  ],
  "repository": "https://github.com/developer-dao/discord-server-info",
  "readme": "https://github.com/Developer-DAO/discord-server-info#readme",
  "bugs": "https://github.com/Developer-DAO/discord-server-info/issues",
  "scripts": {},
  "dependencies": {}
}

Let's look at some of the changes I made:

removed version
- since I already know that this package.json will eventually serve as the root for our monorepo, it won't have a version
added description, keywords, repository, readme, bugs
- these provide additional context about our package
created empty dependencies
- since this is the root package.json, we'll only use dependencies (because the distinction between dependencies and devDependencies doesn't exist at the root)

Create `.gitignore`

This file will eventually contain many files and folders that we don't want to commit to our repo, but for now we'll just add node_modules:

node_modules/

Create `.prettierrc`

This file contains the options for how prettier formats our files. I mostly use the default option, but I prefer a few overrides:

{
  "proseWrap": "always",
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all"
}

Install `prettier`

To install prettier, I ran pnpm i -D prettier.

This adds prettier to our devDependencies. As mentioned above, we won't be using devDependencies but prettier has to be in this list of the next step to work.

We'll fix that later.

Configure `husky` and `lint-staged`

To install and configure husky and lint-staged, I ran pnpm dlx mrm@2 lint-staged.

This utility detects a number of tools in our repo that lint-staged supports and automatically installs + configures the dependencies we need for them.

In this case, it:

detected prettier and installed husky and lint-staged
added a prepare script which runs husky install so that husky will automatically be installed in each contributor's local environment
installed husky in my local environment (.husky directory)

added a lint-staged configuration block to package.json:

"lint-staged": {
  "*.{js,css,md}": "prettier --write"
}

Since I know ahead of time the types of files we'll be using in this project, I updated the lint-staged configuration to target them:

"lint-staged": {
  "*.{js,ts,tsx,md,json,yml}": "prettier --write"
}

Rename `devDependencies` to `dependencies`

Our final step is to change devDependencies to dependencies in our package.json file:

"dependencies": {
  "husky": "^8.0.1",
  "lint-staged": "^12.4.2",
  "prettier": "^2.6.2"
}

We also need to run pnpm i for this update to take effect.

With all of these changes made, we now have the tooling in place to automatically format the files in our codebase with prettier anytime a contributor commits them.

You can view the PR for these changes here: https://github.com/Developer-DAO/discord-server-info/pull/9

Start with README.md

with-heart — Sun, 29 May 2022 16:20:12 +0000

I firmly believe in Readme Driven Development. This paradigm is simple:

Write your Readme first.

By writing our Readme first, we force ourselves to think through at a high level what it is we'll be building. This serves as an excellent piece of documentation for ourselves and others to remember what the project is, what it's meant to accomplish. and where it's heading.

In keeping with this, writing a high level README.md is how I started discord-server-info!

Let's look at how I structured our README.md:

Heading

Here are the first three lines of the file:

# `discord-server-info`

> Explore Discord server data and statistics

This follows a standard pattern that I tend to follow for any README.md that I create:

the first line is an h1 of the name of the project
- since the name of this project matches the name of the repo, I wrapped it in inline code blocks
the next line is a blockquote with a one-line description of the project

I like this pattern because it immediately establishes two key pieces of information for a reader:

how to refer to this project
whether this project is relevant to them

Readers shouldn't have to read too far into our file to know either of those things.

Introduction

The next section after the heading is Introduction which gives a high level overview of the discord-server-info problem space.

This is essentially a condensed version of the Introduction post from this series.

It allows potential contributors to understand what our project is and why we think it's important.

Technical Overview

The last section is Technical Overview. Where the introduction gives the what and the why, the technical overview gives the how.

This is almost identical to the High level technical overview post from this series.

Since I already have an idea in my head of how we can build this project to accomplish our goals, I've laid out what that looks like at a high level in this section.

This will allow potential contributors to understand the direction we're taking and the general structure of the project.

There's a lot more information I could have included in our Readme but didn't, like specific details for how each package should be built or some of the technical pitfalls we'll potentially face.

Instead, we'll treat our Readme like everything else in the repo and iterate on it.

As we reach the point where we're ready to zoom in on one of the packages and implement it, I'll add a high level overview of what that looks like to our Readme.

This allows us to gain the benefits of Readme Driven Development without getting too far ahead of ourselves.

High level technical overview

with-heart — Sun, 29 May 2022 16:14:13 +0000

To build discord-server-info, we'll need a few separate pieces:

bot
db
app

bot will be a Discord bot. This bot reads data from the servers it's connected to and stores it in our database (db).

db is a Prisma database that provides an API for storing and accessing server data.

app is a Next.js application that allows users to authenticate with Discord and explore data from their servers.

If you're wondering why we need this structure rather than having the app read data directly from the Discord API, it's because the Discord API intentionally provides access to very little data. A bot account is required for full access.

The discord-server-info repo will eventually be a monorepo with a package for each piece.

Introduction

with-heart — Sun, 29 May 2022 15:52:41 +0000

Hi!

Welcome to my series on building a discord.js bot with a connected Next.js dashboard.

In this series, we'll be building discord-server-info!

The idea for discord-server-info came from my friend Michelle Bakels. Michelle is attempting to do a major analysis of the Developer DAO Discord server so she can find ways for us to reduce the size and scope of our channels, roles, etc.

Unfortunately, the information provided by Discord Server Insights isn't detailed enough for her to reason about and make informed decisions about our server.

For example, one of the changes she'd like to make to improve access to our existing channels is to require each channel to fill out its description field informing other members of its purpose. How can she create a list of all of our channels currently missing a description?

By hand. glhf Michelle!

This is the type of problem that discord-server-info aims to solve. By enabling server managers to explore more granular server data, discord-server-info can help them analyze, reason about, and better manage their server.

How to scale Excalidraw diagrams for Twitter posts

with-heart — Thu, 19 May 2022 04:42:07 +0000

I've been using Excalidraw to create diagrams that I use in Twitter threads. Unfortunately it's difficult to manually scale diagrams to the correct aspect ratio in Excalidraw.

I finally figured out a solution to this problem, at least for Twitter!

Here's how I did it:

Save this frame image and then import it into Excalidraw (I usually drag the image file onto the canvas)
For each diagram you want to use on Twitter, duplicate the frame and scale your content to fit within its border
When you're ready to export, first set the opacity of the artboard to 0% and then select both the hidden artboard and the content
Add your new image to your Twitter post!

This works because the size of the frame matches the maximum size of Twitter post images, so as long as your content fits in the frame, it will be sized to fit correctly in a Twitter post.

If you followed these steps correctly, here's what the export pane looks like in Excalidraw:

If you followed the steps incorrectly, the export pane of Excalidraw will look like one of the following:

incorrectly scaled: be sure to select the artboard and the content before exporting

black border is in the image: be sure to set the artboard's opacity to 0% before selecting it and the contents for export

You can see the difference in scaling between the first post (correct; using this method) and the second post (incorrect; exporting the content directly):

DEV Community: with-heart

Set up our pnpm monorepo

Create pnpm workspace

Create the app package

Create the bot and db packages

Prepare typescript

Create the bot package

Create the db package

Prepare our repo

Create package.json

Create .gitignore

Create .prettierrc

Install prettier

Configure husky and lint-staged

Rename devDependencies to dependencies

Start with README.md

Heading

Introduction

Technical Overview

High level technical overview

Introduction

How to scale Excalidraw diagrams for Twitter posts

Create `pnpm` workspace

Create the `app` package

Create the `bot` and `db` packages

Prepare `typescript`

Create the `bot` package

Create the `db` package

Create `package.json`

Create `.gitignore`

Create `.prettierrc`

Install `prettier`

Configure `husky` and `lint-staged`

Rename `devDependencies` to `dependencies`