DEV Community: Geert-Jan Zwiers

Away with your Errors - A Short Tutorial on Running Sentry with Deno

Geert-Jan Zwiers — Tue, 28 Jun 2022 13:03:10 +0000

Cover image credit: Arc'blroth; image link; CC-BY-SA-4.0

Recently, I decided to see if one can run the Sentry SDK for JavaScript on Deno. If you have not heard of Sentry, it is a tool for tracking errors and can be especially useful when working in complex environments such as cloud-native apps with multiple containerized services. Sentry can be used to capture errors and warnings and send them to a centralized dashboard, providing an overview of what might be going awry at any given time.

Although there seems to be no dedicated Sentry module for Deno just yet, Deno comes with the option to run a program in Node compatibility mode. This mode allows running 'hybrid' programs, meaning you can install certain Node packages like you normally would with npm, and then use them alongside code written for Deno. Quite an impressive amount of Node programs can work this way, though not everything. Mostly, it is meant to ease the transition to Deno for Node developers. In this tutorial, I will show how to use Deno's Node compatibility mode to run the Sentry SDK and send an application error to the Sentry dashboard.

Requirements

Deno installed on your machine. You can get it from deno.land.
Node and npm installed on your machine. You can get them from nodejs.org
A Sentry account. They have a free plan available for developers which will do nicely for the purposes of this tutorial. They also have a trial for the more advanced plans in case you're interested in exploring that.

Project Setup

Start by making a new directory for the program. Because we want to use the Node compatibility mode with Deno, we do need to install the npm packages that we want to use, so in the new directory run npm init -y for a default package.json and npm install @sentry/node @sentry/tracing to install the Sentry SDK. You should now have a directory with a package.json, package-lock.json and the node_modules directory containing the node dependencies.

The Code

Create a new file main.mjs. This will be a JavaScript module in which we will test that the Sentry integration works. First, we import Sentry from the npm package like we would in Node:

import * as Sentry from "@sentry/node";

Sentry recommends running Sentry.init as early on as possible in the program, so we will do that next. For this we need to login to Sentry, go to Projects and click Create Project. Choose Node.js as the platform (Deno is not yet listed as an option here) and give a name to the project. On the next page Sentry will show a quickstart, copy the following lines into main.mjs:

Sentry.init({
  dsn: "<my-sentry-dsn>",
  tracesSampleRate: 1.0,
});

Replace <my-sentry-dsn> with the actual Data Source Name (DSN) shown in the quickstart. This string is used by Sentry to figure out where to send events to.

Now we can add some code to generate a test event and see if it is sent to Sentry successfully. Change the contents of main.mjs to the following:

import * as Sentry from "@sentry/node";
import * as log from "https://deno.land/std@0.145.0/log/mod.ts";

Sentry.init({
  dsn: "<my-sentry-dsn>",
  tracesSampleRate: 1.0,
});

async function testEvent() {
  log.info("Sending test event to Sentry.");

  try {
    throw new Error("Nope.");
  } catch (e) {
    Sentry.captureException(e);
    await Sentry.flush();
  }
}

await testEvent();

Notice the log import from the Deno standard library (std).
To understand what is happening, it is important to know that Deno and Node use different systems to resolve JavaScript modules. Node relies heavily on the node_modules directory while Deno utilizes URLs. With Node compatibility mode it is possible to use both 'styles' together in a file.

When you're ready, run the following command from a terminal:

deno run --compat --allow-read --allow-env --allow-net --unstable main.mjs

The important thing here is the --compat option, which enables the Node compatibility mode. If you are interested in how this works behind the scenes, you can find more info on it in the deno manual.

When you run the command, you will probably see a few warning messages in the terminal:

Not implemented: process.on("uncaughtException")
Not implemented: process.on("unhandledRejection")

These are Node methods of the process global that are not available in Deno compatibility mode (yet). This does mean that certain parts of the Sentry SDK are not fully compatible with Deno at the moment, but luckily it does not matter for the example shown in this tutorial. After the program has run, go to the Sentry dashboard, refresh the page (or enable real-time updates) and you should see the error appear:

This short tutorial covered how to use the Sentry SDK for JavaScript in a Deno program and run it in Node compatibility mode. This shows how many Node programs can be re-used in Deno, which is very beneficial to speeding up development until the Deno ecosystem has grown enough that it provides a module of its own.

A Deno-licious Workflow

Geert-Jan Zwiers — Sun, 14 Nov 2021 12:37:28 +0000

If there is one project that has increased my developer happiness, it is probably Deno. One of the best things is the ease at which one can set up a coding workflow and maintain a project with the combination of Deno, Git and the GitHub CLI.

With this workflow, pull requests (PRs) can be made and merged from a terminal, release notes can be generated automatically and releases are made in the blink of an eye. Once you get used to this workflow, it feels about as fluent as coding gets.

Requirements

A GitHub Account
deno installed
gh (GitHub CLI) installed
git installed

Recommended:

an autocompletion tool for your terminal, e.g. oh-my-zsh for the zsh shell or posh-git for PowerShell

Setting up verified commits

As Deno places more emphasis on security, let's begin by creating a key to sign our commits with. This way we can make verified commits that prove we are not some impostor trying to upload a million cat.jpg files or something. In a way, GPG keys are an implementation of 'Just be yourself'!

Read how to generate a GPG key for GitHub here and adding it to your account.

Creating a module

One convention in Deno is to have a file mod.ts as entrypoint and two files deps.ts and dev_deps.ts as places to import other modules for use throughout yours. Note that the filenames have no special meaning in Deno, they are merely a convention. We'd probably like a .gitignore file as well, but I know what you're thinking: Do I really have to make four whole files by hand? No way! Okay, hang on, because there is a solution. Just run mod which is a deno CLI program that scaffolds a basic module for you:

deno install --allow-read --allow-run=git --allow-write --name mod https://deno.land/x/mod/mod.ts

And then run:

mod -n my_deno_project

This makes a directory my_deno_project in the current working directory with the files we just mentioned and runs git init for us. Of course, you can name the directory whatever you like.

Uploading to GitHub

Let's add the code to a remote repository by making a verified commit using our new GPG key. Configure git to require signing commits by running the following command in my_deno_project:

git config commit.gpgsign true

Next, add your files to the working tree and make the first commit:

git add .
git commit -m "initial commit"

At this point you should be prompted to enter your GPG key's password to sign the commit with. Now we can send this code to a remote repository on GitHub with the CLI:

gh repo create

This will let you make a new remote repository interactively, but if you already know what you want you can use something like:

gh repo create my_deno_project --confirm --public

Check that the remote repo was created successfully, then push the local files:

git push -u origin main

Protecting the main branch

Now that the initial code is on GitHub it's time to setup branch protection that ensures we can only merge changes to the main branch via pull requests. The major benefit of doing this is that all changes can be checked and reviewed before being included in any sort of release.

Go to the project on GitHub and go to the Settings tab, then go to Branches. Add a rule with the branch name pattern main and enable the setting "Require a pull request before merging" and also turn on "Include administrators". There is another setting that we want to enable: "Require status checks to pass before merging", but we probably want to have actual checks before enabling it.

We'll add some code and a pipeline soon, but let's do all of that in a new branch:

git checkout -b first_feature

Adding Continuous Integration

When developing modules for Deno there are three steps that can be achieved quite easily using built-in deno subcommands. These are formatting code with deno fmt, linting code with deno lint and running unit and/or integration tests with deno test. Using GitHub Actions we can also include these steps in a Continuous Integration (CI) pipeline that will run anytime we push changes to the remote.

Wait a minute, do we have to add a whole pipeline manually now? Nope! We can use mod to create a basic pipeline for us! In the current working directory (my_deno_project) run:

mod --ci

You should now have a .github directory with a workflows subdirectory and a build.yaml file. Note that mod doesn't overwrite existing files (you should see some warnings about that), so we could use it to add these additional files do the project.

If you go into build.yaml, you can see it has a basic pipeline structure for Deno that includes the aforementioned steps. It will format, lint and test the code. Only problem with that is we don't have any code yet! Let's fix that.

Test-Driven Development

To make a high-quality module means having well-tested code, amongst other things. Add the following line to dev_deps.ts:

export { assertEquals } from "https://deno.land/std@0.114.0/testing/asserts.ts";

The idea of Test-Driven Development is to write a test that initially fails, and then writing the minimal amount of code required to make the test pass. For the example project, we'll just be adding a sum function, so create a new file mod.test.ts and add the following code:

import { assertEquals } from "./dev_deps.ts"; 
import { sum } from "./mod.ts";

Deno.test({
  name: "sum",
  fn() {
    assertEquals(sum(1, 2), 3);
  }
});

Also add an empty sum function in mod.ts:

export function sum() {};

If you run deno test you can see the test won't pass. We'll implement a basic sum function here and class it up a bit by allowing it to sum any number of numbers using spread syntax and Array.reduce:

export function sum(...numbers: number[]): number {
    return numbers.reduce((prev, curr) => {
        return prev + curr;
    })
}

If you run the test again you should see it pass. Now, try to run the commands deno fmt and deno lint as well. You can also run deno test --coverage=cov to create a code coverage output directory and then deno coverage cov to view a coverage report on the console (which should be 100% in this case!).

Merging to main

This code looks ready for release, as all checks are passing. We want to include these as requirements for any pull requests. First, create another commit using conventional commit syntax. This style makes it easier to see what type of changes have been made and what sort of version increment would be best. You can read more about the specifications here.

git add .
git commit -m "feat: add sum function"

Now, instead of pushing the code to main, which is protected, let's use the GitHub CLI to make a PR. We can use --fill to autofill the title and body of the PR with the commit info.

gh pr create --fill

Now you don't need to leave the terminal at all with the GitHub CLI. You could keep working on something else, and use gh pr status to check the PR.

When the pipeline has run, edit the branch protection rule on GitHub and tick the "Require status checks to pass before merging" and search for the build job that the pipeline runs, which includes formatting, linting and testing.

If all the checks pass you can merge the changes into main with a (single) squash commit:

gh pr merge --squash

And this is really the core of this workflow. You make changes, create a PR with gh pr create --fill, then check in later and merge with gh pr merge --squash. It takes care of using a consistent format in the code and ensures that good practices are applied by running the linter. It's a very fluent and programmatic way of developing and maintaining a codebase.

Auto-generating release notes.

The great thing about using conventional commits together with GitHub is that you can create release notes and autofill them with your commits. This gives a very nice, concise overview of what sort of fixes and features were made per release. The only downside right now is that it has to be done from GitHub and not the CLI.

To create a release, go to Create a new release on GitHub (right below Releases on the right hand side). As long as your project is unstable, meaning breaking changes can happen at any release and not just major version increments, choose a v0.x.x format for your tag, for example v0.1.0. Click the button "auto-generate release notes" on the top-right of where you can write the release description, and there you go!

Summary

This tutorial showcased a module development workflow for Deno using GitHub. We configured a project to require signing commits with a GPG key. We used the mod CLI to quickly scaffold a module for Deno with a GitHub Actions CI pipeline. Finally, we used the GitHub CLI to create a remote repository, to make pull requests and merge them into a protected branch. This workflow is highly programmatic, with only a few manual steps required on GitHub in the browser, and it greatly reduces the amount of context switching needed while developing.

I hope this tutorial showed you how using Deno and GitHub greatly simplifies the creation of high-quality code, adhering to many good practices and standards (branch protection, commit signing, conventional commits, test-driven development). I recognize that this workflow takes some time to get used to before it starts to become fast and fluent, but it's absolutely worth making the effort as it will take your code quality to the next level.