DEV Community: Adam

Adding Codemirror 6 to a React Project

Adam — Sun, 05 Sep 2021 16:51:41 +0000

Codemirror 6 is now a thing! It has been completely rewritten from the bottom up with some improvements. These include: better accessibility, separating functionality into modules and some big performance benefits. An exciting step forward for CodeMirror and, as my go-to text editor package, I felt obliged to give it a whirl. So you are aware, all of the docs are written with vanilla js in mind however, with some slight changes, we can get it up and running for React, which will be the focus of this post.

I'm not going to talk you through setting up the whole dev environment but, I'd recommend running npm init vite@latest in your terminal for a quick Vite project.

Setting up our Editor component

First of all let's create the base of our Editor component:

import React, { useRef } from 'react';

export const Editor = () => {
  const editor = useRef();
  return <div ref={editor}></div>;
};

Here we are rendering a div element and creating a reference to it via useRef. This is so we can attach Codemirror to it later on. For more info on useRef, visit the React docs.

Adding Codemirror

Next, we need to install all of the packages we will need for the basic CodeMirror setup.

npm i @codemirror/state @codemirror/view @codemirror/commands

Notice how everything is split into different modules now. This is one of the big changes in Codemirror 6. Once they have installed, we can import them into our Editor component.

import React, { useRef } from 'react';

import { EditorState } from '@codemirror/state';
import { EditorView, keymap } from '@codemirror/view';
import { defaultKeymap } from '@codemirror/commands';

export const Editor = () => {
  const editor = useRef();
  return <div ref={editor}></div>;
};

We can then initialise CodeMirror and render the text editor in the browser.

import React, { useRef, useEffect } from 'react';

import { EditorState } from '@codemirror/state';
import { EditorView, keymap } from '@codemirror/view';
import { defaultKeymap } from '@codemirror/commands';

export const Editor = () => {
  const editor = useRef();

  useEffect(() => {
    const startState = EditorState.create({
      doc: 'Hello World',
      extensions: [keymap.of(defaultKeymap)],
    });

    const view = new EditorView({ state: startState, parent: editor.current });

    return () => {
      view.destroy();
    };
  }, []);

  return <div ref={editor}></div>;
};

We are using useEffect to initialise CodeMirror once the Editor component has mounted. Notice the [] as useEffects second parameter? This means the "effect" will only run once and not on every re-render. Then, within useEffect, we set up our CodeMirror instance. First, we create our initial state, this includes our text/code and any extensions we want to use (there are some other bits we can add in here too, which I'll show a little later on). Next, we create our view which takes in our initial state and defines the parent. The parent property accepts an element, therefore, we can use the element reference we created earlier in our Editor setup.

Rendering it all

Now rendering it all is as simple as importing the component and using it within your App (or wherever else you want to use it).

import React from 'react';
import './App.css';
import { Editor } from './components/Editor';

function App() {
  return (
    <div className="App">
      <Editor />
    </div>
  );
}

export default App;

That's all you need for a super simple setup, which is great if you want the bare (and I mean bare) minimum. If you play around with the editor though you will notice that presumed functionality such as tabbing, closing brackets and line numbers are missing.

Extending the Basics

Moving on from our super simple setup we can add some more functionality by adding @codemirror/basic-setup. The package is an extension that pulls together a lot of the extensions you expect in a basic editor. To see what extensions the basic setup is using you can check out this section on the reference page. This is what t looks like:

import React, { useRef, useEffect } from 'react';

import { EditorState, basicSetup } from '@codemirror/basic-setup';
import { EditorView, keymap } from '@codemirror/view';
import { defaultKeymap } from '@codemirror/commands';

export const Editor = () => {
  const editor = useRef();

  useEffect(() => {
    const startState = EditorState.create({
      doc: 'Hello World',
      extensions: [basicSetup, keymap.of([defaultKeymap])],
    });

    const view = new EditorView({ state: startState, parent: editor.current });

    return () => {
      view.destroy();
    };
  }, []);

  return <div ref={editor}></div>;
};

We have removed our @codemirror/state import because it's included in the basic setup and included it in our extensions. Playing around with the editor now should feel a little more familiar in terms of functionality and aesthetics. But still, tabbing seems to be missing... you might be thinking "what's the deal? It should be included" but this isn't an oversight and is explained in the tab handling example. Personally, I use the tab to indent, so here's how we can add that functionality.

Adding Tab Functionality

Even though tab indention isn't added as default we can add the command by importing the indentWithTab module and adding it to our keymap.

import React, { useRef, useEffect } from 'react';

import { EditorState, basicSetup } from '@codemirror/basic-setup';
import { EditorView, keymap } from '@codemirror/view';
import { defaultKeymap, indentWithTab } from '@codemirror/commands';

export const Editor = () => {
  const editor = useRef();

  useEffect(() => {
    const startState = EditorState.create({
      doc: 'Hello World',
      extensions: [basicSetup, keymap.of([defaultKeymap, indentWithTab])],
    });

    const view = new EditorView({ state: startState, parent: editor.current });

    return () => {
      view.destroy();
    };
  }, []);

  return <div ref={editor}></div>;
};

Try it out in your editor and it should work a dream. For all of the possible commands, you can add check out the command repo's README.

Adding a Theme

Codemirror has made this easy for us, we can import a theme and add it as an extension when setting up the EditorState. Let's install the one-dark theme, it's my favourite one to use and the one I currently use in VS Code.

npm i @codemirror/theme-one-dark

and then we can import the theme and add it to the array of extensions.

import React, { useRef, useEffect } from 'react';

import { EditorState, basicSetup } from '@codemirror/basic-setup';
import { EditorView, keymap } from '@codemirror/view';
import { defaultKeymap, indentWithTab } from '@codemirror/commands';
import { javascript } from '@codemirror/lang-javascript';
import { oneDark } from '@codemirror/theme-one-dark';

export const Editor = () => {
  const editor = useRef();

  useEffect(() => {
    const startState = EditorState.create({
      doc: 'Hello World',
      extensions: [
        basicSetup,
        keymap.of([defaultKeymap, indentWithTab]),
        oneDark,
      ],
    });

    const view = new EditorView({ state: startState, parent: editor.current });

    return () => {
      view.destroy();
    };
  }, []);

  return <div ref={editor}></div>;
};

And that's it! Your theme has now been added. At present, there only seems to be the one-dark theme on NPM, but check out the Themes section in the docs for how you can create your own or use one-dark as a base.

Adding Syntax Highlighting

You might be wondering after adding the theme why your code/text isn't highlighted. The answer is we haven't told CodeMirror what language we are writing so it can't add the relevant class names to the text editor code. To start seeing some highlighting let's install the javascript language package:

npm i @codemirror/lang-javascript

and then we can import and add it to our extensions:

import React, { useRef, useEffect } from 'react';

import { EditorState, basicSetup } from '@codemirror/basic-setup';
import { EditorView, keymap } from '@codemirror/view';
import { defaultKeymap } from '@codemirror/commands';
import { javascript } from '@codemirror/lang-javascript';
import { oneDark } from '@codemirror/theme-one-dark';

export const Editor = () => {
  const editor = useRef();

  useEffect(() => {
    const startState = EditorState.create({
      doc: 'Hello World',
      extensions: [
        basicSetup,
        keymap.of([defaultKeymap, indentWithTab]),
        oneDark,
        javascript(),
      ],
    });

    const view = new EditorView({ state: startState, parent: editor.current });

    return () => {
      view.destroy();
    };
  }, []);

  return <div ref={editor}></div>;
};

Managing State

Being a React application at some point we will want to hold the code we write in state use elsewhere or manipulate in some shape or form. So how do we create our state from our existing setup? Here's how I did it:

import React, { useRef, useEffect, useState } from 'react';

import { EditorState, basicSetup } from '@codemirror/basic-setup';
import { EditorView, keymap } from '@codemirror/view';
import { defaultKeymap, indentWithTab } from '@codemirror/commands';
import { javascript } from '@codemirror/lang-javascript';
import { oneDark } from '@codemirror/theme-one-dark';

export const Editor = ({ setEditorState }) => {
  const editor = useRef();
  const [code, setCode] = useState('');

  const onUpdate = EditorView.updateListener.of((v) => {
    setCode(v.state.doc.toString());
  });

  useEffect(() => {
    const state = EditorState.create({
      doc: 'Hello World',
      extensions: [
        basicSetup,
        keymap.of([defaultKeymap, indentWithTab]),
        oneDark,
        javascript(),
        onUpdate,
      ],
    });

    const view = new EditorView({ state, parent: editor.current });

    return () => {
      view.destroy();
    };
  }, []);

  return <div ref={editor}></div>;
};

Since we want to manage the state of the editor we need to import useState and create our state const [code, setCode] = useState(""). We can then tackle how we grab the code from CodeMirror and update our state. There seemed to be a few different methods out there, like this CodeSandbox or Cenguidano's gist. I did try Cenguidano's approach originally but it didn't work out and caused an error. After playing around a little and understanding the docs more I realised that we can assign EditorView.updateListener directly rather than creating a function to call it. This means we can treat it as another extension and add it into the extensions array. So now our editor listens for any changes and passes the view object to a callback function. We can then setCode(v.state.doc.toString()) in that callback to update our editor state with the current editor content.

Conclusion

Presently there isn't a lot of content out there on getting CodeMirror 6 set up with React so I hope this article helps. If you come across some other helpful articles send them over in the form below and I will add them to a useful links section.

Additionally, I know I haven't covered updating the editor from manipulated state but thats because I haven't done it myself yet. Once I've done it and I'm happy with the process I will update the post.

Adding an Updated Date to Markdown and Mdx Posts

Adam — Mon, 16 Aug 2021 16:23:00 +0000

The Problem

Unlike a CMS grabbing the modified date for your posts in frameworks like Gatsby and Next can come as a bit of a challenge. In Gatsby for instance you could use the gatsby-transformer-gitinfo plugin which adds a gitPublishedDate field to your GraphQL schema, and this will work perfectly for a lot of cases. However, there is a huge caveat in that approach, which is what I experienced when deploying to Vercel. If your .git directory isn't deployed alongside your repo, then your git logs can't be accessed and no timestamps can be pulled. This is true for a few other approaches I stumbled upon, such as angelos.devs and pragmatic pineapples posts.

Finding a Solution

Luckily I did come across a thread from @monicalent which offered some alternate solutions, and influenced the approach I ended up taking (here is the initial tweet from Lee Robinson and the snippet page it links to). Unlike the previous approaches, it adds the updated date when staging your content to commit rather than pulling the dates at build time. This means you don't need to rely on a .git directory being deployed, with minimal changes to your existing git workflow.

The Approach

The approach that Lee Robinson and Michael Novotny took is to have an existing meta-object in the MDX which is altered via a script. It's a great idea but I want to cater to both Markdown and MDX files and not have to rely on an initial object to exist. Therefore, instead of having a meta-object, which would only be usable in MDX documents, we parse and alter the frontmatter instead. This way we have a common solution which easily integrates into Next and Gatsby projects.

The Node Script

Taking all of this into account, I wrote the below script to satisfy those needs:

/* eslint-disable import/no-extraneous-dependencies */
const fs = require("fs").promises;
const matter = require("gray-matter");

const updateFrontmatter = async () => {
  const [, , ...mdFilePaths] = process.argv;

  mdFilePaths.forEach(async (path) => {
    const file = matter.read(path);
    const { data: currentFrontmatter } = file;

    if (currentFrontmatter.published === true) {
      const updatedFrontmatter = {
        ...currentFrontmatter,
        updatedOn: new Date().toISOString(),
      };
      file.data = updatedFrontmatter;
      const updatedFileContent = matter.stringify(file);
      fs.writeFile(path, updatedFileContent);
    }
  });
};

updateFrontmatter();

Here's what's happening:

We grab the Markdown/MDX file paths
Loop over all of the file paths
Read each file with the gray-matter package which parses the frontmatter for us.
Parse the frontmatter and split it into an object. Take the rest of the content and dump it in a string.

{
  "content": "<h1>Hello world!</h1>",
  "data": {
    "title": "Hello",
    "slug": "home"
  }
}

^ What is returned from gray-matter, data here being the parsed frontmatter content.

If the posts published frontmatter is true we continue, otherwise we do nothing.
Immutably update the object with the new date and assign it to the data property.
Take the newly updated gray-matter object and turn this back into a string
Overwrite the existing content using fs.writeFile

Now you will probably have noticed above that we are grabbing the paths using process.argv. The reason for doing this is we are using Husky and lint-staged to create a git commit hook. What this essentially means is when we make a commit which includes a Markdown or MDX file, we can run a node script and pass the paths as arguments, hence what you saw above.

Setting Up Husky and lint-staged

Install Husky npm i -D husky
Add Husky's git hooks with npx husky install (you will notice it created a .husky directory).
Add your commit hook via npx husky add .husky/pre-commit "npm run lint:staged". This will add a pre-commit file to your .husky directory and within that file, your npm command should exist (if not you can manually add it)
Install lint-staged npm i lint-staged -D
Create a .lintstagedrc file
Add your lint-staged config:

{
  "**/*.{md,mdx}": "node updateFrontmatter"
}

(updateFrontmatter is the filename of your script)

Add the script to your package.json

    "lint:staged": "lint-staged"

Conclusion

Now, whenever you commit either a Markdown or MDX file Husky will run the node script and update/create the updatedOn frontmatter content. No more worrying about the build step and depending on git logs being available. It just works.

Useful Links

gray-matter package
Husky docs - These are worth checking out as V5 is very different to V4
gatsby-transformer-gitinfo - if your .git directory is deployed alongside your repo check out this plugin

Switching from Google Analytics to Umami

Adam — Sat, 07 Aug 2021 21:26:35 +0000

Note: The original post can be found here

For any new site, there is always the tendency to reach out and grab Google Analytics as the "go to" method for collecting and analysing stats about your site and users. I, for one, have been guilty of that in the past but with the growing popularity of open source analytics and cheaper options out there, more and more developers are looking elsewhere.

Why move away?

Personally I am trying to move what I can away from Google's ecosystem but, in the grand scheme of things, I think there is something fundamentally wrong with how easily we open up our sites to Google. I think a lot of the time this comes down to convenience and the perceived best practice of it all, which is totally understandable, and something I can relate to. But, with internet privacy becoming an alarming concern for many people I think it makes sense to explore other options, and keep our visitor information safe.

In addition to this, here are some other benefits I can see:

Analytics is pretty bloated so we should see some performance benefits. Most open source solutions tend to come in at around 2kb, whereas GA comes in at around 40kb which is a huge saving.
No need for the dreaded GDPR cookie banner! Most self-hosted solutions don't set a cookie or track any personal data, so have saved ourselves a job.
Most ad blockers block the GA script. By hosting our own solution we will receive uninterrupted, accurate data.
You'll own the data! Protecting the privacy of your visitors and creating a safer space on the internet.

Note: Before I ventured down the path of self-hosted analytics I researched whether it was possible to set up Google Analytics to be GDPR compliant. At the time of writing this, there was nothing concrete or anything "official". For the amount of developers/site owners that reach for Google Analytics for a new project, I found it interesting and slightly disappointing that there wasn't extensive documentation or guides for this.

Choosing an Analytics solution

It may be a coincidence or it may be fate but as it happens the first open-source analytics solution I digitally stumbled across was in fact Umami! I first discovered it from issue #102 of Kai Brach's Dense Discovery and even though it came out a while back, it still made a big impression on me. In addition to this, thanks to the Twitterverse and "the algorithm", I came across Mike Cao’s (@cauzilla) post How I wrote Umami in 30 days which shared some great insights into the inspiration, why the project came to be and how it was created. I’m still pretty blown away that it only took 30 days from start to *finish. But as fated as this was I did look at a few other solutions:

Ackee - Free Alternative - Probably the most similar solution to Umami and it would have been my second choice. It seems to be pretty popular and well worth checking out.

Fathom - Paid/Free Trial - I came across this solution from one of @brianlovin's tweets so I thought it was worth checking out (as with anything Brian does). For this site, a huge focus isn't put on the data so I wanted a free solution (however, you can try it out for free for 7 days).

Splitbee - Paid/Conversion Focussed - Created by Tobias Lins Splitbee is a paid service with more of a focus on businesses and conversion. It's got a beautiful UI and some great features, but for me (who wants something super simple) it felt a little overkill.

Choosing a Hosting solution

Now I had chosen an analytics solution I needed to decide where it was going to be hosted. As a rule, self-hosting an open-source project can be a bit of a pain with many moving parts. Luckily, Umami's docs give you a few options when it comes to hosting, ranging from all-in-one solutions (DigitalOcean, Railway, Heroku) to set up your frontend and backend separately (Vercel). The biggest thing for me here was finding an easy to use, all-in-one solution so I didn't need to worry about the database and UI layer separately and sign up for two different services. So, as with anything, I did a couple of searches and came across Railway.app via the blogpost Self Hosted Web Analytics.

Railway provided everything I wanted above, a single service that automagically deploys the database and front end for you, and linking them together seamlessly. Having never heard of Railway before I was excited to give it a go.

Note: You could also use Heroku which from what I remember should set up your database and UI layer for you, but I've never been a fan of Heroku so that's why I didn't use it.

Deploying Umami on Railway

I'd like to tell you that it was a complicated process and only really smart people will be able to accomplish this but in reality, it's one of the easiest, friction-free deployment processes I've experienced. Railway provides you with an Umami starter (along with a lot of other starters worth checking out) which automagically deploys your Postgres database and Next frontend for you. To get started you can click the Railway deployment button below.

Note: this can also be found in the official docs and the blogpost I mentioned before

You will be asked to sign in to your Github and give Railway some permissions. This is so railway can create an Umami repo for you which you can fork and apply any updates in the future.
Give your repo a name and add a random string for your HASH_SALT (this can be anything you want) and then click deploy.
Once we have clicked deploy the project will start building. At this point, it's a waiting game until it finishes. I'll admit I just ended up staring at the build logs until it finished (no regrets).
When the deployment has successfully finished we can click the URL in our Project deployments and low and behold you should see the Umami Admin screen.
Sign in with username: admin and password: umami and make sure to change your password. This can be found in Settings > Profile > Change Password.

Configuring our website

So we have Umami up and running on Railway and everything is starting to come together. The only thing left for us to do now is to configure our website in Umami and add the tracking script to our website. So let's do just that:

Head into our settings page in Umami and click add website
Fill in the Name and Domain fields and click save
You should see a </div> button next to our newly created domain. Click it and copy the tracking code
I'm using Next.js so in our _document.jsx file (you may need to create this if you haven't already) we can add the following

import Document, { Html, Head, Main, NextScript } from "next/document";

class MyDocument extends Document {
  render() {
    return (
      <Html lang="en">
        <Head>
          {process.env.NODE_ENV === "production" && (
            // the tracking script copied from umami
            <script
              async
              defer
              data-website-id="your-umami-id"
              src="your-umami-src"
            />
            // end of tracking script from umami
          )}
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}

export default MyDocument;

Notice how I have added the process.env.NODE_ENV conditional here to make sure that we are only getting stats sent to umami on production. The conditional could be more complex in my opinion but it works for what I need.

Once your site is deployed with the tracking script you should start to see some stats coming through in Umami.

Conclusion

There we have it! In a relatively short amount of time, you can move your personal site/project away from Google analytics and have the peace of mind that you own the data and a range of other benefits. I want to give a big thanks to Mike Cao (@cauzilla) for creating Umami as without him the project wouldn't exist, and if you do switch over I hope you will send him some love. Also, big claps for railway.app as they have taken the (annoying) problem of self-hosting open-source projects and made the process incredibly easy. What they've built and achieved with this is nothing less than remarkable.

Finally, I do hope you will check out Umami or any of the other listed solutions and migrate away from Google Analytics. I don't think you will regret it.

Useful Tips

Umami works great as a PWA so you can add it to your home screen for quick access (I wouldn't recommend doing this if you feel you would be checking it every 5 minutes).
The URL generated by Railway is a pretty random one so add a browser bookmark so you don't need to dive into your search history from months ago.
Probably the most important when writing for fun: don't let the stats dictate what you write. You'll find yourself losing motivation quickly and writing will feel like a chore.